AI Development Guide and M27AI v34 Devlog

Following the recent Supreme Computer Cup I was inspired to have a go at developing a basic AI for FAF. As I had zero experience of coding in Lua, I thought at the same time I would write down things as I learnt them to have both a guide for other people interested in getting started in developing an AI, and a dev log for the creation of my AI.

See below for a link to the current AI development guide and devlog:
https://docs.google.com/document/d/1uQlEoN-kti7G2MnhwD60uaaHwVevPNYH/edit?usp=sharing&ouid=100973959280546778272&rtpof=true&sd=true

You can also access the mod on Github:
https://github.com/maudlin27/M27AI

I've copied the current overview from the guide below:

This document is intended to do 3 things at once (meaning it does none of them very well!):
• Act as a guide to people new to FAF AI development, including collating any other useful resources out there on AI development
• Be a sort of dev log of my thought process and development steps for creating my first FAF AI, with extracts of code thrown in
• Form my main ‘todo’ list for further developments of my AI
If you see any errors, or have any comments or suggestions (in particular any AI developers who read this since you’ll probably know better/easier ways of doing things than the methods I’ve chosen) let me know and I can update the guide where relevant.

If you’re here for useful resources and/or details of how to write AI and don’t care about the dev log aspect then just skip to section 2) Setup and background and section 5) Index of useful functions, and/or browse the index for points that may be of interest.

Latest changes (v34 summary)
v34 - Dynamic firebases

• M27 will in some scenarios build firebases, including T2 artillery. These will be built in response to what the enemy does for now, although a future update is likely to introduce pre-planned firebases at chokepoints.

• Improved T3 arti protection with shield assist logic.

• 15 Bug fixes, including an issue that stopped torpedo bombers working (they'd only attack enemies that got near them previously), and an error that would happen when building experimentals if the enemy had an experimental

• 33 misc changes, including improving ecoing ability slightly by trying to always have something upgrading (sometimes this can hurt it though)

Key areas of focus by version (history):
v1-3: Release
v4 - Intel and threat detection
v5 - Use of ACU and hotfix
v7 - Engineers and building upgrades
v9 - Air
v10 - Anti-Turtle
v11-v12 - Pathfinding and misc changes
v13 - Anti-navy
v14 - ACU and mobile shields
v15-v18 - CPU optimisation and hotfixes
v19 - Rally points and air domination strategy
v20 - Late game
v21-23 - Eco management
v24 - Bombers
v25 - Misc
v26 - Nukes
v27 - T3 Arti
v28 - Game options/compatibility
v29 - Optimisation and TMD
v30 - Czar, Soulripper and Defences
v31 - Bombers (again) and TML
v32-33 - Plateaus
v34 - Firebases (part 1)

1. Overview 32
   1.1) AI goals 32
   1.2) Background 33
   1.3) Approach 33
2. Setup and background 34
   2.1) Lua editors 34
   2.1.1) Intellij IDEA 34
   2.2) Other guides which include a section on AI: 35
   2.2.1) General information: 35
   2.2.2) How AI in FAF works 35
   2.2.3) AI markers and how AI uses them: 37
   2.2.4) Hooking (e.g. replacing/appending existing game code) 37
   2.2.5) Creating custom scripts for Sorian AI: 37
   2.2.6) Pathfinding 37
   2.2.7) How platoons work 37
   2.2.8) AI Research (non-FAF related) 37
   2.3) Lua coding 37
   2.3.1) How to code in Lua 37
   2.3.2) Stand alone Lua code testing 37
   2.3.3) Lua optimisation 38
   2.3.4) Common causes of errors for non-Lua coders 38
   2.4) Debugging in FAF 38
   2.4.1) Console 38
   2.4.2) Cheats 39
   2.4.3) Log window and error messages 39
   2.4.4) Debug window and shortcuts 39
   2.4.5) Platoon names for debugging 40
   2.4.6) Function hooks and identifying infinite loops 40
   2.4.7) Fast speed 40
   2.4.8) In-game tools and information 41
   2.4.9) Other shortcuts and game startup options 42
   2.4.10) Suggested shortcut 44
   2.4.11) Using FAF Develop 44
   2.4.12) Error handling 45
   2.4.13) Optimisation – benchmarks and monitoring 46
   2.4.14) Debugging via replay 47
   2.5) AI development discord 48
   2.6) Core FAF Lua files 49
   2.6.1) Accessing core Lua code 49
   2.6.2) Other built in functions 49
   2.6.3) Unit blueprints 50
   2.7) Testing AI against other AI 50
   2.7.1) Simple offline testing 50
   2.7.2) Mass offline AI testing 51
   2.8) Getting started – using a simple AI template as a starting point 52
   2.9) Downloading and setting up MicroAI 52
   2.10) Giving the AI mod your own name 52
   2.11) General - Hooks, and getting the code to recognise if it’s running your AI 53
   2.11.1) Hooking – Unit callbacks/events – applied example 53
   2.12) Github 57
   2.12.1) Github advantages and Github desktop 57
   2.12.2) Linking Github with a local repo via creating your own init file 58
   2.12.3) Pro Git ebook 58
   2.12.4) Git commit messages 58
   2.13) Uploading your AI to FAF 58
   2.13.1) Pre-upload checklist 58
   2.13.2) FAF rules on uploading mods 58
   2.13.3) Uploading to FAF 58
   2.14) Other AI documentation 59
3. AI changes 59
   3.1) Build order - Changing the initial build order 59
   3.1.1) Adding/removing buildings 59
   3.1.2) Change build order based on map resource positions 59
   3.1.3) Build order conditions 60
   3.2) Build order – ACU builds without moving at start 60
   3.2.1) BaseTemplate 61
   3.3) Build factory and power to benefit from adjacency 62
   3.3.1) Record all mexes on the map, and reference this information 62
   3.3.2) Determine com start position 63
   3.3.3) Identify mexes near to start 63
   3.3.4) Hook onto the core code relating to building a structure at a location 64
   3.3.5) Call build order from custom aiBrain function, to edit how things are built 65
   3.3.6) Adjust build template based on mex location - conditions 65
   3.3.7) Adjust build template based on mex location – build location adjustment 66
   3.3.8) Build initial PGens by existing factory 67
   3.3.9) Adjacency bonus where ACU is away from start location 69
   3.3.10) Referencing unit blueprints for information such as unit size 71
   3.4) Platoons and sending engineers to reclaim 73
   3.4.1) How platoons work 73
   3.4.2) Send the first engineer on reclaim duty 78
   3.4.3) Determine where to send the engineer to reclaim 79
   3.4.4) Identifying reclaim mass value 80
   3.4.5) Find out if a location is accessible by ground: 80
   3.4.6) Mapping reclaim locations and assigning preferred location to an engineer 82
   3.4.7) Don’t send early reclaiming engi if there’s minimal starting reclaim 82
   3.4.8) Issue new reclaim command if engineer becomes idle 83
   3.4.9) Send more engineers to reclaim later (as lower priority) based on the reclaim currently on the map 83
   3.4.10) Send 5 engineers at the start to reclaim and build mexes 84
   3.4.11) Reclaiming trees when no main mass left 84
   3.5) Building and assisting hydro 84
   3.5.1) Check if hydro near start area and have engineer build hydro 84
   3.5.2) Have ACU assist engineer with hydro 85
   3.5.3) Get ACU to continue build order after hydro complete 86
   3.5.4) Subsequent build order changes 87
   3.6) Attack force composition changes and check of AI performance 87
   3.6.1) Build Moar Tanks 87
   3.7) Pre-v1: AI Progress check 88
   3.7.1) Land factory buildings and other build order refinements 89
   3.8) Raiding AI 90
   3.8.1) Raiding behaviour - overview 90
   3.8.2) Queue up move commands for mexes 91
   3.8.3) Identify mexes to target 91
   3.8.4) Locating mexes near to an existing pathing route 94
   3.8.5) Determine when raiders need new targets 94
   3.8.6) Handling complications (stuck units, move orders built on, platoon units dying) 95
   3.8.7) Change factory rally point so units are assigned orders sooner 96
   3.8.8) Making use of platoon names for debugging 99
   3.8.9) Ensure 1 land scout included in each platoon 99
   3.8.10) Use microbots before switching to tanks 100
   3.8.11) Have scouts stay with the platoon 102
   3.8.12) AI scouting, threat detection, and identifying nearby enemy units 102
   3.8.13) Attack engineers en-route: Overview 105
   3.8.14) Tracking when have reached movement points 106
   3.8.15) Determining the platoon minimum range 106
   3.8.16) Identifying nearby enemy units and assessing their threat 108
   3.8.17) Actions based on enemy threat 109
   3.8.18) Avoid attacking enemy mexes for small platoons 110
   3.8.19) Other issues – cheating, walls and min range 111
   3.8.20) Larger raiding platoons 112
   3.9) Large attack wave 113
   3.9.1) Checking when to form a large attack wave 113
   3.9.2) Generalising raider AI 113
   3.9.3) Creating separate platoon AI for the large attack force 114
   3.9.4) Run nearer to base when outnumbered 114
   3.9.5) Recalling nearby raiders to join attack force 115
   3.9.6) Updating threat assessment for ACU health and upgrades 116
   3.9.7) Don’t chase small numbers of faster units 118
   3.9.8) Switch to hunt and kill enemies once reached destination 119
   3.10) Pre-v1: AI Progress check 120
   3.10.1) Summer duel 120
   3.10.2) Theta passage 120
   3.10.3) New issues 120
   3.11) Platoon AI – Generalised approach and further enhancements 121
   3.11.1) Embracing the table 121
   3.11.2) Moving units when shots blocked by cliffs 124
   3.11.3) Anti-stuttering protection 125
   3.11.4) Large attack AI – Rally point for merged units 125
   3.11.5) Raiders assume small numbers of enemies are engis/scouts 125
   3.11.6) T1 Artillery specifically target structures, and spread-attack units 125
   3.11.7) Keep scouts at back of platoon 127
   3.11.8) Platoons with non-Seraphim T1 artillery and no tanks don’t run unless against slower enemy 127
   3.11.9) Factor in nearby platoons when faced with enemies 127
   3.11.10) More T1 arti in platoons once reached certain level of tanks 128
   3.11.11) Don’t treat AA as a direct fire unit when forming a platoon 128
   3.11.12) Build hydro where it’s far away from base 128
   3.12) Expansion bases 129
   3.12.1) Background – expansions and the main base 129
   3.12.2) Having all units treated as available for platoons 129
   3.13) Upgrade ACU with gun and attack 130
   3.13.1) How to upgrade an ACU 130
   3.13.2) Get enough energy to support guncom 131
   3.13.3) Upgrade ACU’s gun once have enough energy 131
   3.13.4) Attack with ACU once upgrade finished 132
   3.13.5) ACU overcharge 133
   3.14) V1-3 release incl AI progress check 133
   3.14.1) Performance – v1-3 of M27AI 133
   3.14.2) Issues and planned improvements from testing 134
   3.14.3) Debug issues and other bug fixes 135
   3.14.4) Attack lauched as soon as ACU gun ready 139
   3.14.5) Default attack-move direct fire units at enemy (attack-move if platoon scattered) 139
   3.14.6) Limit of 1 microbot per early raider platoon, and tank defenders 140
   3.14.7) Skip move location if are closer to the next move location than the first one 140
   3.14.8) Build more engineers if are close to overflowing mass 141
   3.14.9) Add energy storage requirements to ACU initial land factory build order 142
   3.14.10) ACU and Engineers will move near mex to build 142
   3.14.11) Other minor misc changes 144
   3.15) On demand basic pathfinding 145
   3.15.1) Revised approach 145
   3.15.2) Mex raiding path optimisations 146
   3.15.3) Useful maps for testing map based logic 146
   3.15.4) Move to build structure – check pathing 147
   3.15.5) Platoon Merge location – have it check no pathing issues in nearby segments 147
   3.16) AI Overseer - responding to enemy attacks 147
   3.16.1) Overview 147
   3.16.2) Planned initial logic 148
   3.16.3) Run overseer on AI creation 148
   3.16.4) Assigning units to defender platoons 149
   3.16.5) Recording enemy threats 150
   3.16.6) Sending units to deal with enemy threats 152
   3.16.7) Sorting a multi-dimensional table 152
   3.16.8) Disbanded units return to base 154
   3.16.9) Intercepting platoons should leave at least 1 scout when removing spare units 154
   3.16.10) Don’t remove units when in combat 155
   3.16.11) Platoon and other build conditions 155
   3.16.12) Limit number of mobile AA in an intercepting defending platoon 156
   3.16.13) Remove ACU from defender platoon once the threat is dealt with 156
   3.16.14) Don’t have ACU join a platoon if its upgrading 156
   3.16.15) Disabling sorian base manager distress logic 157
   3.17) AI Overseer – Intel and ACU managers 157
   3.17.1) Intel manager - overview 157
   3.17.2) Planned logic – 1-off 157
   3.17.3) Planned logic – recurring 158
   3.17.4) Scout localised platoon AI 159
   3.17.5) ACU manager 160
   3.18) V4 release (incl AI progress check) 161
   3.18.1) Pre-release checklist 162
   3.18.2) AI performance results 163
   3.18.3) Notable issues noted from performance 163
   3.18.4) Resolution of immediate issues/bugs post-release 164
   3.19) ACU –aggression, support and micro enhancements 169
   3.19.1) ACU custom platoon - overview 169
   3.19.2) ACU expansion – choice of location 170
   3.19.3) Platoon completion actions 172
   3.19.4) Expanding more than once 173
   3.19.5) Getting nearby reclaim and/or unclaimed mexes while moving 174
   3.19.6) Assisting hydro construction (reworked) 176
   3.19.7) ACU defender platoon refinements 177
   3.19.8) ACU Scout helper and general scout build order 178
   3.19.9) ACU MAA helper and general behaviour 180
   3.19.10) Air threat assessment and MAA to build (initial) 181
   3.19.11) Large platoon scout and MAA helpers 181
   3.19.12) ACU attacks independently to large attack platoon 181
   3.19.13) ACU Build order tweaks 181
   3.19.14) Aeon ACU gets both gun upgrades 182
   3.19.15) ACU retreat 182
   3.19.16) ACU kiting 182
   3.19.17) Have ACU attack-move if kiting doesn’t return any action 183
   3.19.18) Manual overcharge 184
   3.19.19) Other misc changes/refinements 187
   3.20) V5 release (incl AI progress check) 187
   3.20.1) Pre-release checklist 187
   3.20.2) AI performance results 188
   3.20.3) Resolution of immediate issues/bugs 189
   3.21) V6 - Refinements, basic water based actions, v6 hotfix 189
   3.21.1) Misc refinements pre v6 189
   3.21.2) ACU water based actions – reclaim and move to shore 190
   3.21.3) V6 hotfix 191
   3.21.4) Error fixes subsequent to v6 191
   3.22) V7 - Custom build orders and platoon formers 194
   3.22.1) Proof of concept 194
   3.22.2) Initial complications – LABs and no valid units 196
   3.22.3) Related changes – scout conditions; tracking construction orders 196
   3.22.4) Linking production with threat detection overseer 196
   3.22.5) Increasing indirect fire units based on enemy PD usage 197
   3.22.6) Assign MAA similarly to how scouts are assigned 197
   3.22.7) Platoon former – manually assigning platoons based on threat distance 197
   3.22.8) Try to save raider scouts 198
   3.22.9) Not got enough units for a platoon – send spare units to intel path 198
   3.22.10) Call the platoon former if disband a platoon containing combat units 198
   3.22.11) Platoon merger – Periodically combining attack platoons where they’re nearby 198
   3.22.12) Delayed platoon formation 199
   3.22.13) Factories away from main base or with nearby enemies don’t build engineers 200
   3.23) V7 - Engineer overseer 200
   3.23.1) Overview 200
   3.23.2) Spare engineer action logic 200
   3.23.3) Nearby enemy logic 201
   3.23.4) Unclaimed mex logic 201
   3.23.5) Threat detector – adjust distance calculation and record 201
   3.23.6) Update engineer names to reflect their action 202
   3.23.7) Clear unit actions if factory idle (unexpected bug workaround) 202
   3.23.8) Have ACU assist assigned hydro builder and build land factory 202
   3.23.9) Retain existing engineer assignments in favour of nearest engineer 203
   3.23.10) Power assignment – longer term requirement check 204
   3.23.11) Optimisations and rollbacks 204
   3.23.12) Adjacency refinements 204
   3.23.13) Misc changes 205
   3.23.14) If an engineer changes its action and its being guarded, clear the current action and commands of the guards so they can be reassigned 205
   3.23.15) Consider engineer actions as soon as a factory finishes construction 206
   3.23.16) Constructing building – first check if part-complete similar building 206
   3.23.17) Building more engineers 206
   3.23.18) Engineers take into account ACU expansion path 207
   3.23.19) Initial engineers keep building mexes until they die or half the map is covered 207
   3.23.20) Have engineers queue up nearby unclaimed mexes and multiple T1 power 207
   3.23.21) Build a second power at the same time 208
   3.23.22) Build more energy storage based on power income 208
   3.24) V7 - Building Upgrade overseer 208
   3.24.1) Overview 208
   3.24.2) Refinements 209
   3.24.3) Have engineer overseer switch to assisting an upgrade instead of building a land factory 209
   3.24.4) Pause upgrade if low on resources (and track so can resume later) 209
   3.24.5) Mass stall – pause factories over mexes 210
   3.25) V7 - Idle platoon 210
   3.25.1) Army pool platoon and new idle platoon 210
   3.25.2) Approach 211
   3.26) v7 - Misc changes 211
   3.26.1) ACU is removed from defender platoons when allocating new threats 211
   3.26.2) Allocating overseers to different ticks 211
   3.26.3) Have defender platoons move in formation 212
   3.26.4) State of game log 212
   3.26.5) Intel path – allow scouts to move +/- 1 path 212
   3.26.6) ACU shots blocked 212
   3.26.7) Enemy ACU threat increase 213
   3.27) V7+V8 release (incl AI progress check) 213
   3.27.1) V7 - Minor enhancements to overseers due to testing (pre-release) 213
   3.27.2) Tracking revision 213
   3.27.3) Choosing nearby engineers based on mex location 214
   3.27.4) Pre-release check results 214
   3.27.5) V8 Hotfix – crash 215
   3.27.6) Other bugs – fixed in v9 215
   3.27.7) Other misc changes for v9 219
   3.28) V9 - Air scouting 220
   3.28.1) Determining when we last scouted an area 220
   3.28.2) How often we want to scout areas 221
   3.28.3) Deciding on nearest mex targets 222
   3.28.4) Deciding which area to scout first 222
   3.28.5) Adding via points to journey 223
   3.28.6) Take a detour if a scout has died 223
   3.28.7) Produce air factory 223
   3.28.8) Ignore locations too far away 224
   3.28.9) Number of air scouts wanted: 224
   3.28.10) Air factory unit builder 224
   3.28.11) Available scouts – factor in fuel and make use of air staging 224
   3.29) V9 - Air overseer – Bombers and Inties 225
   3.29.1) Generalised scout/air unit management 225
   3.29.2) Find targets for bombers 225
   3.29.3) Determine available bombers 225
   3.29.4) Assign targets to bombers 225
   3.29.5) Bomber production 226
   3.29.6) Make mexes nearer enemy base high priority scout target if idle scout and bomber 226
   3.29.7) Target power if no other targets 226
   3.29.8) Interceptor basic logic: 226
   3.29.9) Interceptor tracking: 227
   3.29.10) Inties built if not enough to meet current air threats 227
   3.29.11) Don’t build bombers if last 3 that died were ineffective 227
   3.30) V9 Release 228
   3.30.1) Pre-release checklist 228
   3.30.2) Post-release bug fixes 228
   3.30.3) Misc tweaks 229
   3.30.4) Initial build order done via my code 230
   3.31) V10 - Air overseer – minor enhancements 231
   3.31.1) Air scouts clear current target if it’s already been scouted recently 231
   3.31.2) Stop inties chasing enemy air to other side of map 231
   3.31.3) Send idle air units to refuel if they have <70% fuel or <80% health 231
   3.31.4) Surplus bomber attack 231
   3.32) V10 - Indirect fire units 232
   3.32.1) Indirect fire overseer/enhancements to threat detection 232
   3.32.2) Prioritise shields and TMD if near current target and wouldn’t cause us to come within range of an enemy PD 235
   3.32.3) Instead of using the average position of a platoon, use the position of the front units 236
   3.32.4) Improved ACU protection logic 236
   3.32.5) Raider/large related attack/run logic 237
   3.32.6) Pathfinding issues 238
   3.32.7) Disband indirect defenders if their current threat group is all dead 238
   3.32.8) Don’t issue override orders from the overseer if a platoon is attacking or running 238
   3.32.9) Syncronised attacks 239
   3.32.10) Include nearby defensive type structures when assessing PD threat 239
   3.32.11) Minor refinements 239
   3.32.12) Escort expanding engineers with 1 tank 240
   3.32.13) Remove escorts if too many 240
   3.32.14) Target upgrading ACU 241
   3.33) V10 - Strategic choices – switching to eco 241
   3.33.1) Stop building tanks and upgrade sooner if have map control 241
   3.33.2) Switch to eco if we have no core platoons we want tanks for 241
   3.33.3) Eco strategy – focus on defence with minimal raiders 241
   3.33.4) Upgrade factories to non hq factories once we have an hq 241
   3.33.5) Switch to eco if mex income not increased recently 242
   3.33.6) Don’t upgrade buildings near the frontline 242
   3.33.7) After upgrading a factory, build an engineer and power as a high priority 242
   3.33.8) Have spare combat units patrol around the mex on our side nearest the midpoint if in eco mode 242
   3.33.9) Keep building tanks in eco mode if we have high mass 243
   3.34) V10 Release 243
   3.34.1) Pre release checks 243
   3.34.2) AI Tournament performance 243
   3.34.3) Bug fixes 244
   3.34.4) Minor enhancements 246
   3.35) V11 - Pathfinding 3rd attempt 247
   3.35.1) Background 247
   3.35.2) Information wanted from pathfinding 248
   3.35.3) Can we path from A to B 248
   3.35.4) Pathing results 255
   3.35.5) Amphibious pathfinding 258
   3.35.6) Naval pathfinding 262
   3.35.7) Summary of time taken to generate level 1 pathing 263
   3.35.8) Optimisation – function integration 263
   3.35.9) Update existing code to make use of new logic in place of CanPathTo 264
   3.35.10) Update intel logic to determine intel paths at start of game 264
   3.35.11) Further changes – v11-v12 264
   3.35.12) V13 Issues – Serenity Desert 265
   3.35.13) V13 - Double-check all mex positions are pathable 265
   3.35.14) Manual height adjustment 267
   3.36) V11-v12 Releases – Mass storage, Anti-Nuke, Misc 267
   3.36.1) Further bug fixes 267
   3.36.2) Basic Anti-experimental and nuke logic 268
   3.36.3) Cap mexes with mass storage 269
   3.36.4) Factor in energy income before having engineers upgrade 269
   3.36.5) Other misc changes 269
   3.36.6) V12 release: Pre release checks 270
   3.36.7) Bug fixes 271
   3.36.8) Misc changes for v13 272
   3.37) V13 - Anti-Navy logic 273
   3.37.1) Navy threat detection overseer 273
   3.37.2) Build more air factories if significant shortfall in air units wanted 274
   3.37.3) Build radar at base once we have enough power 274
   3.37.4) Only produce amphibious land units if we can’t path to the enemy base 275
   3.38) V13 Release 275
   3.38.1) Post release bug fixes 275
   3.38.2) Misc changes 278
   3.39) V14 - ACU Upgrades 280
   3.39.1) Issuing an upgrade 280
   3.39.2) ACU requests help when damaged 280
   3.39.3) Mid-tier ACU upgrades 281
   3.39.4) Only upgrading if we can attack approaching enemy units 281
   3.39.5) Spare engineers don’t assist anything if ACU upgrading and we have low mass 281
   3.39.6) Disable reclaim and building functionality if ACU has big gun (sera+cybran) 281
   3.39.7) ACU won’t get slow upgrades unless it’s closer to our base than the enemy 281
   3.40) V14 - Mobile shields 282
   3.40.1) Shield platoon 282
   3.40.2) Shield production: 282
   3.40.3) Assign mobile shields to T2+ mexes if TML detected 283
   3.40.4) Other platoon changes 283
   3.40.5) Misc changes 283
   3.41) V14 - Assign land scouts to mexes 284
   3.41.1) Assign scouts to mexes and adjust upgrade logic 284
   3.41.2) Build scouts based on numbers needed 284
   3.41.3) Create new platoon logic for guarding a mex 284
   3.41.4) Only upgrade mexes if they are close to base or have intel coverage 284
   3.42) V14 - Anti-bomber logic 285
   3.42.1) Micro to dodge bombers 285
   3.42.2) Working out the position a unit is facing, and how that compares to another location 285
   3.43) V14 - All-in attack on ACU 287
   3.43.1) Deciding whether to launch an all-in attack 287
   3.43.2) Platoon and unit actions 287
   3.43.3) Production and upgrade logic 288
   3.43.4) Platoon formation 288
   3.43.5) Misc refinements 288
   3.44) V14 Release 289
   3.44.1) Pre-release checks 289
   3.44.2) Bug fixes post release 289
   3.44.3) Misc changes/tweaks 291
   3.45) V15 - Profiler 293
   3.45.1) Profiler 293
   3.45.2) Function count and time per tick 294
   3.45.3) Initial results (with no optimisation) 294
   3.45.4) Softles profiler 301
   3.45.5) Conclusion – functions to focus on 303
   3.45.6) Optimisation: Reclaim 303
   3.45.7) Optimisation: GetIntelCoverageOfPosition 303
   3.45.8) Optimisation – high usage functions 304
   3.45.9) Optimisation: GetNearestEnemyIndex 305
   3.45.10) Optimisation: AddNearbyUnitsToThreatGroup 306
   3.45.11) Optimisation – moving near a target and initial optimisation results 306
   3.45.12) Optimisation – GetPriorityExpansionMovementPath (part 2) 307
   3.45.13) Results of optimisation to date and reclaim adjustments 308
   3.45.14) Summary of time taken by different logic areas 313
   3.46) V15 - New reclaim logic 313
   3.46.1) Shortlist of reclaim locations 313
   3.46.2) Assignment 315
   3.46.3) Localised reclaim logic 315
   3.46.4) Reclaim tracking and checks 316
   3.46.5) Other Reclaim functions 316
   3.46.6) Further optimisation 317
   3.47) V15 Release, and v16-18 Hotfix releases 318
   3.47.1) Pre-V16 release bug fixes 319
   3.47.2) Pre-V16 release misc changes 319
   3.47.3) Intel path rewrite 319
   3.47.4) V16 Hotfix release 320
   3.47.5) Pre-v17 hotfix release bug fixes 320
   3.47.6) Pre-V17 hotfix release - Other misc changes 321
   3.47.7) V17 Hotfix Pre-release checks 322
   3.47.8) V18 Hotfix 323
   3.47.9) Post v18 bugfixes 323
   3.47.10) Misc changes 324
   3.48) V19 - Rally points 325
   3.48.1) Choice of rally point 325
   3.48.2) Use of rally points 326
   3.48.3) ACU Anti-TML Logic – retreat to rally point 327
   3.49) V19 - Air dominance strategy and bomber changes 328
   3.49.1) Conditions for switching to air dominance 328
   3.49.2) Production and upgrade changes 328
   3.49.3) Air AA targeting changes 329
   3.49.4) Bomber targeting changes 329
   3.49.5) Initial build order changes 329
   3.49.6) Bomber – ‘hard to hit’ target logic 330
   3.49.7) Other bomber changes 330
   3.50) V19 Release 331
   3.50.1) Pre-release checks 331
   3.50.2) Post-release bugfixes 332
   3.50.3) Misc fixes 333
   3.51) V20 - Experimentals 333
   3.51.1) First experimentals 333
   3.51.2) V20 Pre-release checks 334
   3.51.3) Progress assessment 335
   3.51.4) Post-release bug fixes: 336
   3.51.5) Post release misc changes: 337
   3.52) V21 - Improved ecoing 339
   3.52.1) Build order and eco adjustments 339
   3.52.2) Powerstall management 339
   3.52.3) Reclaiming redundant buildings 340
   3.52.4) Ctrl-K mexes 341
   3.52.5) Other engineer and upgrade improvements 341
   3.52.6) Tracking eco performance progress 342
   3.53) V21 - ACU protection strategy and v21-v23 release 343
   3.53.1) SML ACU protection logic 343
   3.53.2) Dedicated ACU protection mode 343
   3.53.3) V21 Pre-release checks 344
   3.53.4) Post-release changes: Bugfixes 344
   3.53.5) Post-release changes: Misc 345
   3.53.6) V22 Pre-release checks 347
   3.53.7) Post-release bugfixes 348
   3.53.8) Post-release misc changes 349
   3.54) V24 - Early T3 bomber 349
   3.54.1) Prioritise airHQ if enemy is vulnerable to strat bombers 349
   3.54.2) Assisting HQ upgrades 349
   3.54.3) Initial engineers 350
   3.54.4) Scouting 350
   3.54.5) Factoring in bomber success to air factories wanted 350
   3.54.6) Prioritising power over HQs sometimes 350
   3.54.7) Minor eco improvements 350
   3.54.8) Best bomb location 351
   3.54.9) Clear path for bomber 352
   3.54.10) AirAA Support adjustments 352
   3.54.11) Targeting shielded units 353
   3.54.12) Other bomber and air changes 353
   3.55) v25 – Misc issues 355
   3.55.1) Bug fixes 355
   3.55.2) Initial build order changes 356
   3.55.3) Land combat and ACU related 357
   3.55.4) Intel related 358
   3.55.5) Engineer related 359
   3.55.6) Factory production related 360
   3.55.7) Threat response 360
   3.55.8) Air related 360
   3.55.9) Economy upgrade related 362
   3.55.10) Optimisations 362
   3.55.11) Misc/General logic changes 363
   3.55.12) V25 pre-release checks 363
   3.56) V26 – Nukes, shields and novax 364
   3.56.1) Bugfixes (post v25 release) 364
   3.56.2) Misc changes (post v25 release) 365
   3.56.3) When to start a late game unit 367
   3.56.4) Impact on normal build logic 367
   3.56.5) What experimental unit to build: 367
   3.56.6) Nuke launcher construction logic 368
   3.56.7) Nuke launcher targeting logic 368
   3.56.8) Fixed Shield generators 368
   3.56.9) Novax – decision to construct 369
   3.56.10) Novax - Usage 369
   3.56.11) Pre release checks 371
   3.57) V27 – T3 Arti 371
   3.57.1) Bug fixes 371
   3.57.2) Misc changes 373
   3.57.3) Revised overcharge logic 375
   3.57.4) Failed optimisation attempt 376
   3.57.5) UEF remaining late game logic 380
   3.57.6) Pre release checks 381
   3.58) v28 – Compatibility/game options 382
   3.58.1) Bugfixes 382
   3.58.2) Misc changes 383
   3.58.3) Improved nuke logic 384
   3.58.4) Improved logic where we can’t path to the enemy base 384
   3.58.5) Changing focus when an enemy is nearly defeated 385
   3.58.6) Scenario info settings – non-assassination game modes 386
   Other game setting – Unit restrictions 387
   Extra support for mods 388
   Other game setting support – Norush timer 389
   3.58.7) Pre-release checks 390
   3.59) V29 – Optimisation (again) and TMD 391
   3.59.1) Bug fixes 391
   3.59.2) Misc changes 391
   3.59.3) Identifying sim mods 392
   3.59.4) Random optimisation – GetBlueprint and GetUnitId 392
   3.59.5) Reclaim optimisation (again) 394
   3.59.6) NewMovementPath optimisation 398
   3.59.7) Optimisation – engineer logic – Initial changes 398
   3.59.8) New basic profiling check – total game time 401
   3.59.9) Optimisation - Idle engineers 402
   3.59.10) New optimisation feature – showing the ms at a point in time 403
   3.59.11) Platoon raiding 403
   3.59.12) Anti-Mercy logic 405
   3.59.13) TMD 405
   3.59.14) Pre-release checks 409
   3.60) V30 – Czar, Soulripper and defence 409
   3.60.1) Bug fixes 409
   3.60.2) Misc changes 410
   3.60.3) Enemy cloaked com 411
   3.60.4) Fatboy logic enhancements 411
   3.60.5) Reclaim tweaks 412
   3.60.6) ACU running from enemy experimental threats 413
   3.60.7) Non-UEF choice of experimental 413
   3.60.8) Cybran experimental gunship logic 413
   3.60.9) Czar 414
   3.60.10) Further tweaks to czar and soulripper logic 414
   3.60.11) Building SAMs 415
   3.60.12) Building PD 415
   3.60.13) Pre-release checks 416
   3.61) V31 – Bombers, TML and late-game 417
   3.61.1) Bug fixes 417
   3.61.2) Misc changes 419
   3.61.3) Misc improvements to late game 421
   3.61.4) New bomber logic: Initial bombers 422
   3.61.5) New bomber logic: T1 bombers (general) 423
   3.61.6) New bomber target logic: T2 bomber 423
   3.61.7) New bomber target logic: T3 bomber: 423
   3.61.8) Other air changes 425
   3.61.9) T4 bomber targeting and usage 429
   3.61.10) New Logic for land experimental attacks 430
   3.61.11) Co-ordinated T3 arti and novax targeting 430
   3.61.12) TML 431
   3.61.13) Pre-release notes 432
   3.62) V32 – Plateaus 433
   3.62.1) Bug fixes 433
   3.62.2) Misc changes 434
   3.62.3) Transports 436
   3.62.4) Identifying plateaus of interest 436
   3.62.5) Building engineers and transports 437
   3.62.6) Managing transports 437
   3.62.7) Plateau logic - engineers 438
   3.62.8) Plateau logic - factories 438
   3.62.9) Plateau platoon logic 439
   3.62.10) Plateau logic – other 440
   3.62.11) Pre-release checks 440
   3.63) V33 – Hotfix 441
   3.63.1) Bug fixes 441
   3.63.2) Misc changes 443
   3.63.3) Pre-release checks 444
   3.64) V34 – Firebase and shield assisting 445
   3.64.1) Bug fixes 445
   3.64.2) Misc changes 446
   3.64.3) Dynamic Firebases 448
   3.64.4) Shield assisting/Arti war enhancements 450
   3.64.5) Pre-release checks 451
   3.64.6) Acknowledgements 452
4. Future possible changes 452
5. Index of useful functions 523
   5.1) Map, game setup and general aiBrain information 524
   5.1.1) aiBrain - general 524
   5.1.2) AI Brain – Economy 526
   5.1.3) Map Markers and start positions 527
   5.1.4) Map size and playable area 528
   5.1.5) Terrain info 528
   5.2) Getting a list of units by category, location, or other method 529
   5.2.1) All units that meet a particular category 529
   5.2.2) Units at/near a location 530
   5.3) Unit information 531
   5.3.1) Units on radar 531
   5.3.2) Blueprints and unit categories 531
   5.3.3) Unit upgrades (enhancements) 532
   5.3.4) See 5.4.10) Other unit commands 533
   5.3.5) Location and pathfinding 533
   5.3.6) Unit’s ai Brain owner 533
   5.3.7) Unit’s current commands and whether it’s alive 533
   5.3.8) Unit bones 533
   5.3.9) Shields 534
   5.3.10) Units with missiles/anti-nukes 534
   5.3.11) Unit resource usage 534
   5.4) Unit and platoon commands 535
   5.4.1) Building 535
   5.4.2) Assisting 535
   5.4.3) Pausing 535
   5.4.4) Reclaim 536
   5.4.5) Factory specific commands 536
   5.4.6) Movement and attack-move 536
   5.4.7) Transport 537
   5.4.8) Combat related 537
   5.4.9) Stopping 538
   5.4.10) Other unit commands 538
   5.4.11) Upgrades and enhancements 538
   5.4.12) Current commands and targets 538
   5.4.13) Unit status 539
   5.4.14) Change a unit’s name 540
   5.5) Platoon additional functions 540
   5.5.1) Units platoon handle 540
   5.5.2) Get AIBrain 540
   5.5.3) Get units in a platoon 541
   5.5.4) Disband 541
   5.5.5) Platoon exists 541
   5.5.6) Platoon position 541
   5.5.7) Get all platoons 541
   5.5.8) Platoon ai plan name 541
   5.5.9) Add units to a platoon 541
   5.5.10) Army pool and removing units from a platoon 542
   5.5.11) Create a platoon 542
   5.5.12) Change or reset an AI plan 542
   5.5.13) Platoon movement formation 542
   5.6) Weapon information 542
   5.6.1) Get a unit’s weapon 542
   5.6.2) Get information on that weapon 543
   5.7) Time and thread related 543
   5.7.1) Game time 543
   5.7.2) System time 543
   5.7.3) Wait/delay the code 544
   5.7.4) Fork thread (run independently) 544
   5.8) Events 544
   5.8.1) Creating custom events 546
   5.9) Other 547
   5.9.1) Visual changes – Draw Circles and Lines 547
   5.9.2) On Intel Change 547

Not exactly an AI comment, but you wanna have things right, right?

"Lua" (pronounced LOO-ah) means "Moon" in Portuguese. As such, it is neither an acronym nor an abbreviation, but a noun. More specifically, "Lua" is a name, the name of the Earth's moon and the name of the language. Like most names, it should be written in lower case with an initial capital, that is, "Lua". Please do not write it as "LUA", which is both ugly and confusing, because then it becomes an acronym with different meanings for different people. So, please, write "Lua" right!

Thanks, I'll reflect the correct case usage of Lua in the next version of the guide (I'll probably update it whenever I release an AI update so the two are in sync)

So I decided I might actually post something more relevant

Full stops vs colons – continuing the above example, oUnit.GetUnitId() will return an error, but oUnit:GetUnitId() won’t.

It's maybe worth mentioning why that happens. oUnit:GetUnitId() is syntactic sugar for oUnit.GetUnitId(self). So if you wanna you the version with . you have to pass self as first arg.

F9 opens up the debug window (you may want to change the game resolution to windowed to more easily access this).

That's a log window, not debug. You can open the debugger with Ctrl+F9 or /debug and that's way better for debugging then trying to print things into the log. Since it works as any debugger you are used to, pauses the execution on the line you seleceted and lets you see whats inside global and local variables.

The below link also appears to give a list of core/global functions that can be used (I’ve not tested these to see if they all work, or even if they’re for FAF rather than SupCom2):
https://supcom.fandom.com/wiki/LUADOC_1.5.3599

It is for FA, some of these functions are documented here https://github.com/FAForever/fa/tree/deploy/fafdevelop/engine

I’m not using Github since I’m working on this on my own, and since I doubt I can get the same ease of use I currently have with changing something offline and instantly seeing the results in-game after a Ctrl+F10 restart. However, Github is used by a number of the AI developers so there’s likely some significant benefits to it.

Git is very useful even if you're working alone, as you have history of changes and you can easily switch to previous versions if something breaks. The game can use files from any location, so for my development, it uses files from my local git repo. It's just a matter of setting your own init file https://github.com/FAForever/fa#running-the-game-with-your-changes

To keep things simple (as I couldn’t get more complex builderconditions{} with multiple variables to work, despite seeing it being used in other AIs people have done)

So build conditions are defined in a table

BuildConditions = {
    {BMBC, 'BaseEngineersEnabled', {self.BaseName}},
    {BMBC, 'BaseBuildingEngineers', {self.BaseName}},
    {BMBC, 'HighestFactoryLevel', {i, self.BaseName}},
    {BMBC, 'FactoryCountAndNeed', {i, j, pType, self.BaseName}},
    {BMBC, 'BaseActive', {self.BaseName}},
},

so here, you have 5 build conditions, each in it's own table.

local BMBC = '/lua/editor/BaseManagerBuildConditions.lua'

first value ( BMBC) in the table is thr path the file you wanna use
second one ('BaseEngineersEnabled') is name of the function in that file to use
third ({self.BaseName}) is table of arguments to pass into that function
AI brain is always passed as first argument, and then all other that you specify in the table

So you could rewrite your example to this:

-- Inside the builder
BuilderConditions = {
    {MIBC, 'Is1NearbyMex', {11}}
},


-- Inside MiscBuildConditions.lua
function Is1NearbyMex(aiBrain, distance)
    local iNearbyMex = MapInfo.RecordMexNearStartPosition(Utilities.GetAIBrainArmyNumber(aiBrain), distance, true)
    if iNearbyMex == 1 then
        return true
    end
    return false
end

This way you can already specify the distance for chehcking the nearby mexes.

Determine com start position

This function should do the trick
brain:GetArmyStartPos()

To help with this, I first wanted to understand what the various variables feeding into it were, so made use of the log function for each variable in turn; where it returned an error due to being a table value that I was trying to put into the log

Best would be to use the debugger to see whats what, as you can open the tables.
But if you really wanna dump the table into the log you have to use LOG(repr(table))

@speed2
Thanks, in particular for the debug window - I expect using that would've drastically cut my debugging time! I'll update for your comments in the latest version.

Unfortunately I can't get the debug window to work for me (I just get an error message) and some other people have had the same problem. Asking in the AI discord Jip thought that you need to do an install from the cd version of the game not steam but that you may know the exact procedure?

Error message below in case it helps:

unpack this https://mega.nz/file/VlRCXajY#UMsAx9IR1dIOqX72bPpOYytR6FS3zO1DGVPT2AhSPAY
into \THQ\Gas Powered Games\Supreme Commander - Forged Alliance\coderes\Engine

@speed2
Don't think I've got that folder with the steam install, I've got the following:
C:\Program Files (x86)\Steam\steamapps\common\Supreme Commander Forged Alliance
(this doesn't have a coderecs folder, and adding one in doesnt resolve the issue)

I've also got the FAF location:
C:\ProgramData\FAForever
same issue as with the steamapps folder

(just in case I also tried the \Documents\My Games\Gas Powered Games\Supreme Commander Forged Alliance folder but no luck).

Is there anywhere else I may have missed for a steam version?

Although I'd hoped I'd got the CDs for both as well, checking I've only got the CD for the original supcom so cant try a fresh install via disc.

It belong to the game instalation folders, and fast few ppl having this issue resolved it by creating those folders

@maudlin27

I am not finished reading your guide, but excellent work so far!

v4 changes (in reality v2, but when I uploaded the mod on its first release I had to rush out a couple of hotfixes where I'd forgotten to remove debug logic and accidently introduced a bug that affected all games!)

• Fixed various bugs (see 3.14.3)
• Slightly improved pathfinding performance (see 3.15)
• New AI logic which will detect enemy threats and send units to deal with them (see 3.16)
• New AI logic which attempts to maintain intel over the map to stop surprise attacks (see 3.17)

I've also updated the guide to reflect speed2's comments (as well as a couple of other minor points/sections, such as a bit on uploading a mod and some tests that I now run before uploading)

I am stunned.

Really good work, maudlin27!

v5 changes - these were mostly about the ACU, making it more aggressive and less suicidal

• Fixed various bugs and improved some error handling (see 3.18.4)
  ACU improvements (see 3.19):
• ACU will try to expand to high reclaim or mex locations, while building on mexes it comes across and reclaiming
• ACU will have scout and MAA support
• ACU tries to kite enemies it comes across
• ACU uses manual overcharge to overcharge optimal targets

Also updated the guide slightly to add details of the AI development discord channel in FAF (separate to the main AI development discord), and a couple of common hard crash errors

v6 Hotfix - My AI broke with the recent FAF patch, so this is primarily to fix that. I was in the middle of more extensive changes so my AI is less stable than I'd like but I figured it's better than a broken one! I've also held off on updating the dev log for this release.

Main changes made:

• ACU performs better underwater (reclaims units, tries to move to nearby land when it cant shoot)
• Improvements to ACU overcharge behaviour (it should OC when retreating, and also positions better against enemy PD)
• Switch to new error handling approach (orange messages now appear in the log with more detail; this also happens when any ACU dies)

Issues currently present I'm aware of (which shouldnt have a noticeably detrimental impact on performance, but will be noticeable to anyone looking at the log):

• 'MergeLocations' error message on certain maps - should just mean larger platoons dont regroup at a midpoint before attacking
• 'MexRaider' warning about the final waypoint - in most cases just affects which mexes are targetted (in rare cases might cause a delay in the platoon doing anything)
• 'Stuttering'/delays in performance on certain maps (e.g. open palms)

V7 Update - T2 is now here! My changes were focused on creating my own engineer and platoon formation functionality (which took far far longer than I was expecting due to various difficult bugs - a lot of work for not much benefit), but at the end I threw in some basic upgrade logic so my AI now gets T2.

Various bug fixes. More notable ones are that the AI should work better on adaptive maps that 'hide' some of their mexes, and should be less likely to try and build on unpathable mexes
Custom platoon formation and engineer functionality. A couple of more notable features of this are that engineers now work together to build 1 building (e.g. power) rather than independently try and build 5 at once, and factor in what mexes theyre already planning to build on when choosing where to expand
Building upgrade logic - AI will now upgrade mexes and land factories (meaning for the first time T2 units can hit the battlefield!)
Load spreading of functionality to help counter the CPU performance hit of these changes
I've also updated the guide for a couple of points (e.g. including a section on events)

As before, much more detail on the changes/my thought process as I went about implementing them is in the dev log.

v8 Hotfix - Fixed a game crash that could happen if the AI lost an upgrading building (thanks to relent0r for for flagging there was a crash), along with a couple of other minor bug fixes.

v9 Reintroduced air units:

• Air scouts are built to periodically scout locations of interest
• Interceptors are used to help defend against enemy air attacks
• Bombers should target enemy units of interest.
• Air factory should be built early if there's enough power (and by a hydro if one is available)
• Various bug fixes and small tweaks to behaviour - refer to 3.27.6 - 3.27.7 of the guide

I admire the guide / developers log that you are keeping

V10 - Implemented anti-turtle logic:

• Use of T2+T3 MMLs and mobile arti to break firebases
• Ecoing (not very well, but better than before)
• Reduced turtle feeding

Misc changes:

• Large bomber attack for if we end up with lots of spare bombers
• T3 air factories can be built/upgraded
• Support factories will be built/upgraded instead of HQs
• Higher tier power is built sooner
• Engineers can request guards
• Various bug fixes (see section 3.30.2 of the guide)
• Updated the guide with details on how to run in FAF Develop offline

My AI also has a new icon

For anyone that's interested in the background to the last 5 versions/2 months - back at v5 I was crushed by gunner1069 (I usually get them to play a match every couple of weeks against the latest AI version) with a simple turtle strategy on Theta Passage - they didnt bother getting any mexes and instead just rushed T2 PD with their ACU and my AI had no answer despite having 4x the mass income. My primary focus in all the versions since then has been coming up with the logic that will give my AI a chance in that scenario.

Unfortunately, a relatively simple plan for a human (dont send units single-file into PD, upgrade mexes and then attack with MMLs) required a bunch of different bits of logic:

• Checking for PD and running away from it (so the enemy isn't fed kills/mass), without running away when we're already in range of it and able to beat it (I had some frustrating to watch games where my AI would charge in at a firebase, overwhelm the shields, be about to destroy everything, before deciding to run and turning a winning position into a loss)
• Realising there's PD when it kills our land scouts without being picked up by their radar
• Making use of air scouts to reveal 'hidden' PD to avoid suiciding units and the ACU into the PD
• Quickly expanding to uncontested mexes (including on enemy side of the map)
• Focusing on maintaining map control and ecoing if faced with a turtle rather than trying to break them immediately, which in turn requires various logic for identifying if we're against a turtle, upgrading mexes, building T2+ buildings, upgrading factories, making use of support factories, etc. (I've still not got basic things done like capping mexes with mass storage)
• Using indirect fire units to attack PD/long range enemy units while both protecting them from enemy mobile attacks, and not suiciding our own units trying to protect them

These changes also mean my AI will be worse in other situations - e.g. against a non-turtle it might choose to eco when it would be able to finish the game by pressing the attack, and it's also still poor at the mid-T2+ stage so extending the game via ecoing means it's more likely to snatch defeat from the jaws of victory. Long term though it needed to happen as a 'T1 or die' strategy only has a decent chance on 5v5 maps.

@maudlin27 Nice list of g
Changes of updates for you Ai mod, I'd like to extend you the offer it have this in a more of a cleaner formate over on the new faf wiki, if this is somtbing your interested in please send me a pm here or on the faf discord and I can set you up with a page