AI Development Guide and M27AI v20 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:

As of v13 I'm now using github so you can also access the mod here:

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 (v20 summary)
v20 - Late game
This version improves some of the AI's late game ability, both fixing an issue that led to severe underutilisation of T3 mobile artillery in some cases, and having it build experimental units.

  • Experimental units will now sometimes be built late game
  • Improved use of T3 mobile artillery
  • Better use of heavily upgraded ACUs (including bugfix that caused Cybran ACUs to do nothing)
  • Tweaks to Engineer management
  • Other minor bugfixes

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

M27AI developer; Devlog and more general AI development guide:

  1. Overview 25
    1.1) AI goals 25
    1.2) Background 26
    1.3) Approach 26
  2. Setup and background 27
    2.1) Lua editors 27
    2.1.1) Intellij IDEA 27
    2.2) Other guides which include a section on AI: 28
    2.2.1) General information: 28
    2.2.2) How AI in FAF works 28
    2.2.3) AI markers and how AI uses them: 29
    2.2.4) Hooking (e.g. replacing/appending existing game code) 29
    2.2.5) Creating custom scripts for Sorian AI: 29
    2.2.6) Pathfinding 29
    2.2.7) How platoons work 29
    2.2.8) AI Research (non-FAF related) 29
    2.3) Lua coding 30
    2.3.1) How to code in Lua 30
    2.3.2) Stand alone Lua code testing 30
    2.3.3) Lua optimisation 30
    2.3.4) Common causes of errors for non-Lua coders 30
    2.4) Debugging in FAF 31
    2.4.1) Console 31
    2.4.2) Cheats 31
    2.4.3) Log window and error messages 31
    2.4.4) Debug window and shortcuts 32
    2.4.5) Platoon names for debugging 32
    2.4.6) Fast speed 32
    2.4.7) Other shortcuts and game startup options 32
    2.4.8) Suggested shortcut 34
    2.4.9) Using FAF Develop 34
    2.4.10) Error handling 35
    2.4.11) Optimisation – benchmarks and monitoring 36
    2.4.12) Debugging via replay 38
    2.5) AI development discord 39
    2.6) Core FAF Lua files 39
    2.6.1) Accessing core Lua code 39
    2.6.2) Other built in functions 40
    2.6.3) Unit blueprints 40
    2.7) Testing AI against other AI 40
    2.7.1) Simple offline testing 40
    2.7.2) Mass offline AI testing 41
    2.8) Getting started – using a simple AI template as a starting point 41
    2.9) Downloading and setting up MicroAI 41
    2.10) Giving the AI mod your own name 42
    2.11) General - Hooks, and getting the code to recognise if it’s running your AI 42
    2.12) Github 43
    2.12.1) Github advantages and Github desktop 43
    2.12.2) Linking Github with a local repo via creating your own init file 43
    2.12.3) Pro Git ebook 44
    2.12.4) Git commit messages 44
    2.13) Uploading your AI to FAF 44
    2.13.1) Pre-upload checklist 44
    2.13.2) FAF rules on uploading mods 44
    2.13.3) Uploading to FAF 44
    2.14) Other AI documentation 45
  3. AI changes 45
    3.1) Build order - Changing the initial build order 45
    3.1.1) Adding/removing buildings 45
    3.1.2) Change build order based on map resource positions 45
    3.1.3) Build order conditions 46
    3.2) Build order – ACU builds without moving at start 46
    3.2.1) BaseTemplate 46
    3.3) Build factory and power to benefit from adjacency 48
    3.3.1) Record all mexes on the map, and reference this information 48
    3.3.2) Determine com start position 49
    3.3.3) Identify mexes near to start 49
    3.3.4) Hook onto the core code relating to building a structure at a location 50
    3.3.5) Call build order from custom aiBrain function, to edit how things are built 50
    3.3.6) Adjust build template based on mex location - conditions 51
    3.3.7) Adjust build template based on mex location – build location adjustment 52
    3.3.8) Build initial PGens by existing factory 52
    3.3.9) Adjacency bonus where ACU is away from start location 54
    3.3.10) Referencing unit blueprints for information such as unit size 56
    3.4) Platoons and sending engineers to reclaim 58
    3.4.1) How platoons work 58
    3.4.2) Send the first engineer on reclaim duty 64
    3.4.3) Determine where to send the engineer to reclaim 65
    3.4.4) Identifying reclaim mass value 65
    3.4.5) Find out if a location is accessible by ground: 66
    3.4.6) Mapping reclaim locations and assigning preferred location to an engineer 67
    3.4.7) Don’t send early reclaiming engi if there’s minimal starting reclaim 68
    3.4.8) Issue new reclaim command if engineer becomes idle 68
    3.4.9) Send more engineers to reclaim later (as lower priority) based on the reclaim currently on the map 69
    3.4.10) Send 5 engineers at the start to reclaim and build mexes 70
    3.4.11) Reclaiming trees when no main mass left 70
    3.5) Building and assisting hydro 70
    3.5.1) Check if hydro near start area and have engineer build hydro 70
    3.5.2) Have ACU assist engineer with hydro 71
    3.5.3) Get ACU to continue build order after hydro complete 72
    3.5.4) Subsequent build order changes 73
    3.6) Attack force composition changes and check of AI performance 73
    3.6.1) Build Moar Tanks 73
    3.7) Pre-v1: AI Progress check 74
    3.7.1) Land factory buildings and other build order refinements 74
    3.8) Raiding AI 76
    3.8.1) Raiding behaviour - overview 76
    3.8.2) Queue up move commands for mexes 77
    3.8.3) Identify mexes to target 77
    3.8.4) Locating mexes near to an existing pathing route 80
    3.8.5) Determine when raiders need new targets 80
    3.8.6) Handling complications (stuck units, move orders built on, platoon units dying) 81
    3.8.7) Change factory rally point so units are assigned orders sooner 82
    3.8.8) Making use of platoon names for debugging 84
    3.8.9) Ensure 1 land scout included in each platoon 85
    3.8.10) Use microbots before switching to tanks 86
    3.8.11) Have scouts stay with the platoon 88
    3.8.12) AI scouting, threat detection, and identifying nearby enemy units 88
    3.8.13) Attack engineers en-route: Overview 91
    3.8.14) Tracking when have reached movement points 91
    3.8.15) Determining the platoon minimum range 92
    3.8.16) Identifying nearby enemy units and assessing their threat 93
    3.8.17) Actions based on enemy threat 95
    3.8.18) Avoid attacking enemy mexes for small platoons 96
    3.8.19) Other issues – cheating, walls and min range 97
    3.8.20) Larger raiding platoons 98
    3.9) Large attack wave 99
    3.9.1) Checking when to form a large attack wave 99
    3.9.2) Generalising raider AI 99
    3.9.3) Creating separate platoon AI for the large attack force 100
    3.9.4) Run nearer to base when outnumbered 100
    3.9.5) Recalling nearby raiders to join attack force 101
    3.9.6) Updating threat assessment for ACU health and upgrades 102
    3.9.7) Don’t chase small numbers of faster units 104
    3.9.8) Switch to hunt and kill enemies once reached destination 105
    3.10) Pre-v1: AI Progress check 105
    3.10.1) Summer duel 106
    3.10.2) Theta passage 106
    3.10.3) New issues 106
    3.11) Platoon AI – Generalised approach and further enhancements 107
    3.11.1) Embracing the table 107
    3.11.2) Moving units when shots blocked by cliffs 110
    3.11.3) Anti-stuttering protection 110
    3.11.4) Large attack AI – Rally point for merged units 110
    3.11.5) Raiders assume small numbers of enemies are engis/scouts 111
    3.11.6) T1 Artillery specifically target structures, and spread-attack units 111
    3.11.7) Keep scouts at back of platoon 112
    3.11.8) Platoons with non-Seraphim T1 artillery and no tanks don’t run unless against slower enemy 113
    3.11.9) Factor in nearby platoons when faced with enemies 113
    3.11.10) More T1 arti in platoons once reached certain level of tanks 114
    3.11.11) Don’t treat AA as a direct fire unit when forming a platoon 114
    3.11.12) Build hydro where it’s far away from base 114
    3.12) Expansion bases 115
    3.12.1) Background – expansions and the main base 115
    3.12.2) Having all units treated as available for platoons 115
    3.13) Upgrade ACU with gun and attack 116
    3.13.1) How to upgrade an ACU 116
    3.13.2) Get enough energy to support guncom 116
    3.13.3) Upgrade ACU’s gun once have enough energy 117
    3.13.4) Attack with ACU once upgrade finished 118
    3.13.5) ACU overcharge 118
    3.14) V1-3 release incl AI progress check 119
    3.14.1) Performance – v1-3 of M27AI 119
    3.14.2) Issues and planned improvements from testing 119
    3.14.3) Debug issues and other bug fixes 120
    3.14.4) Attack lauched as soon as ACU gun ready 125
    3.14.5) Default attack-move direct fire units at enemy (attack-move if platoon scattered) 125
    3.14.6) Limit of 1 microbot per early raider platoon, and tank defenders 126
    3.14.7) Skip move location if are closer to the next move location than the first one 126
    3.14.8) Build more engineers if are close to overflowing mass 127
    3.14.9) Add energy storage requirements to ACU initial land factory build order 128
    3.14.10) ACU and Engineers will move near mex to build 128
    3.14.11) Other minor misc changes 130
    3.15) On demand basic pathfinding 130
    3.15.1) Revised approach 130
    3.15.2) Mex raiding path optimisations 132
    3.15.3) Useful maps for testing map based logic 132
    3.15.4) Move to build structure – check pathing 133
    3.15.5) Platoon Merge location – have it check no pathing issues in nearby segments 133
    3.16) AI Overseer - responding to enemy attacks 133
    3.16.1) Overview 133
    3.16.2) Planned initial logic 133
    3.16.3) Run overseer on AI creation 134
    3.16.4) Assigning units to defender platoons 135
    3.16.5) Recording enemy threats 136
    3.16.6) Sending units to deal with enemy threats 138
    3.16.7) Sorting a multi-dimensional table 138
    3.16.8) Disbanded units return to base 140
    3.16.9) Intercepting platoons should leave at least 1 scout when removing spare units 140
    3.16.10) Don’t remove units when in combat 141
    3.16.11) Platoon and other build conditions 141
    3.16.12) Limit number of mobile AA in an intercepting defending platoon 142
    3.16.13) Remove ACU from defender platoon once the threat is dealt with 142
    3.16.14) Don’t have ACU join a platoon if its upgrading 142
    3.16.15) Disabling sorian base manager distress logic 143
    3.17) AI Overseer – Intel and ACU managers 143
    3.17.1) Intel manager - overview 143
    3.17.2) Planned logic – 1-off 143
    3.17.3) Planned logic – recurring 144
    3.17.4) Scout localised platoon AI 145
    3.17.5) ACU manager 146
    3.18) V4 release (incl AI progress check) 147
    3.18.1) Pre-release checklist 148
    3.18.2) AI performance results 149
    3.18.3) Notable issues noted from performance 149
    3.18.4) Resolution of immediate issues/bugs post-release 150
    3.19) ACU –aggression, support and micro enhancements 155
    3.19.1) ACU custom platoon - overview 155
    3.19.2) ACU expansion – choice of location 156
    3.19.3) Platoon completion actions 158
    3.19.4) Expanding more than once 159
    3.19.5) Getting nearby reclaim and/or unclaimed mexes while moving 160
    3.19.6) Assisting hydro construction (reworked) 162
    3.19.7) ACU defender platoon refinements 163
    3.19.8) ACU Scout helper and general scout build order 164
    3.19.9) ACU MAA helper and general behaviour 166
    3.19.10) Air threat assessment and MAA to build (initial) 167
    3.19.11) Large platoon scout and MAA helpers 167
    3.19.12) ACU attacks independently to large attack platoon 167
    3.19.13) ACU Build order tweaks 167
    3.19.14) Aeon ACU gets both gun upgrades 168
    3.19.15) ACU retreat 168
    3.19.16) ACU kiting 168
    3.19.17) Have ACU attack-move if kiting doesn’t return any action 169
    3.19.18) Manual overcharge 170
    3.19.19) Other misc changes/refinements 173
    3.20) V5 release (incl AI progress check) 173
    3.20.1) Pre-release checklist 173
    3.20.2) AI performance results 174
    3.20.3) Resolution of immediate issues/bugs 175
    3.21) Refinements, basic water based actions, v6 hotfix 175
    3.21.1) Misc refinements pre v6 175
    3.21.2) ACU water based actions – reclaim and move to shore 176
    3.21.3) V6 hotfix 177
    3.21.4) Error fixes subsequent to v6 177
    3.22) Custom build orders and platoon formers 180
    3.22.1) Proof of concept 180
    3.22.2) Initial complications – LABs and no valid units 182
    3.22.3) Related changes – scout conditions; tracking construction orders 182
    3.22.4) Linking production with threat detection overseer 182
    3.22.5) Increasing indirect fire units based on enemy PD usage 183
    3.22.6) Assign MAA similarly to how scouts are assigned 183
    3.22.7) Platoon former – manually assigning platoons based on threat distance 183
    3.22.8) Try to save raider scouts 184
    3.22.9) Not got enough units for a platoon – send spare units to intel path 184
    3.22.10) Call the platoon former if disband a platoon containing combat units 184
    3.22.11) Platoon merger – Periodically combining attack platoons where they’re nearby 184
    3.22.12) Delayed platoon formation 185
    3.22.13) Factories away from main base or with nearby enemies don’t build engineers 186
    3.23) Engineer overseer 186
    3.23.1) Overview 186
    3.23.2) Spare engineer action logic 186
    3.23.3) Nearby enemy logic 187
    3.23.4) Unclaimed mex logic 187
    3.23.5) Threat detector – adjust distance calculation and record 187
    3.23.6) Update engineer names to reflect their action 188
    3.23.7) Clear unit actions if factory idle (unexpected bug workaround) 188
    3.23.8) Have ACU assist assigned hydro builder and build land factory 188
    3.23.9) Retain existing engineer assignments in favour of nearest engineer 189
    3.23.10) Power assignment – longer term requirement check 190
    3.23.11) Optimisations and rollbacks 190
    3.23.12) Adjacency refinements 190
    3.23.13) Misc changes 191
    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 191
    3.23.15) Consider engineer actions as soon as a factory finishes construction 192
    3.23.16) Constructing building – first check if part-complete similar building 192
    3.23.17) Building more engineers 192
    3.23.18) Engineers take into account ACU expansion path 193
    3.23.19) Initial engineers keep building mexes until they die or half the map is covered 193
    3.23.20) Have engineers queue up nearby unclaimed mexes and multiple T1 power 193
    3.23.21) Build a second power at the same time 194
    3.23.22) Build more energy storage based on power income 194
    3.24) Building Upgrade overseer 194
    3.24.1) Overview 194
    3.24.2) Refinements 195
    3.24.3) Have engineer overseer switch to assisting an upgrade instead of building a land factory 195
    3.24.4) Pause upgrade if low on resources (and track so can resume later) 195
    3.24.5) Mass stall – pause factories over mexes 196
    3.25) Idle platoon 196
    3.25.1) Army pool platoon and new idle platoon 196
    3.25.2) Approach 197
    3.26) Misc changes 197
    3.26.1) ACU is removed from defender platoons when allocating new threats 197
    3.26.2) Allocating overseers to different ticks 197
    3.26.3) Have defender platoons move in formation 198
    3.26.4) State of game log 198
    3.26.5) Intel path – allow scouts to move +/- 1 path 198
    3.26.6) ACU shots blocked 198
    3.26.7) Enemy ACU threat increase 199
    3.27) V7+V8 release (incl AI progress check) 199
    3.27.1) V7 - Minor enhancements to overseers due to testing (pre-release) 199
    3.27.2) Tracking revision 199
    3.27.3) Choosing nearby engineers based on mex location 200
    3.27.4) Pre-release check results 200
    3.27.5) V8 Hotfix – crash 201
    3.27.6) Other bugs – fixed in v9 201
    3.27.7) Other misc changes for v9 205
    3.28) Air scouting 206
    3.28.1) Determining when we last scouted an area 206
    3.28.2) How often we want to scout areas 207
    3.28.3) Deciding on nearest mex targets 208
    3.28.4) Deciding which area to scout first 208
    3.28.5) Adding via points to journey 209
    3.28.6) Take a detour if a scout has died 209
    3.28.7) Produce air factory 209
    3.28.8) Ignore locations too far away 210
    3.28.9) Number of air scouts wanted: 210
    3.28.10) Air factory unit builder 210
    3.28.11) Available scouts – factor in fuel and make use of air staging 210
    3.29) Air overseer – Bombers and Inties 211
    3.29.1) Generalised scout/air unit management 211
    3.29.2) Find targets for bombers 211
    3.29.3) Determine available bombers 211
    3.29.4) Assign targets to bombers 211
    3.29.5) Bomber production 212
    3.29.6) Make mexes nearer enemy base high priority scout target if idle scout and bomber 212
    3.29.7) Target power if no other targets 212
    3.29.8) Interceptor basic logic: 212
    3.29.9) Interceptor tracking: 213
    3.29.10) Inties built if not enough to meet current air threats 213
    3.29.11) Don’t build bombers if last 3 that died were ineffective 213
    3.30) V9 Release 214
    3.30.1) Pre-release checklist 214
    3.30.2) Post-release bug fixes 214
    3.30.3) Misc tweaks 215
    3.30.4) Initial build order done via my code 216
    3.31) Air overseer – minor enhancements 217
    3.31.1) Air scouts clear current target if it’s already been scouted recently 217
    3.31.2) Stop inties chasing enemy air to other side of map 217
    3.31.3) Send idle air units to refuel if they have <70% fuel or <80% health 217
    3.31.4) Surplus bomber attack 217
    3.32) Indirect fire units 218
    3.32.1) Indirect fire overseer/enhancements to threat detection 218
    3.32.2) Prioritise shields and TMD if near current target and wouldn’t cause us to come within range of an enemy PD 221
    3.32.3) Instead of using the average position of a platoon, use the position of the front units 222
    3.32.4) Improved ACU protection logic 222
    3.32.5) Raider/large related attack/run logic 223
    3.32.6) Pathfinding issues 224
    3.32.7) Disband indirect defenders if their current threat group is all dead 224
    3.32.8) Don’t issue override orders from the overseer if a platoon is attacking or running 224
    3.32.9) Syncronised attacks 225
    3.32.10) Include nearby defensive type structures when assessing PD threat 225
    3.32.11) Minor refinements 225
    3.32.12) Escort expanding engineers with 1 tank 226
    3.32.13) Remove escorts if too many 226
    3.32.14) Target upgrading ACU 227
    3.33) Strategic choices – switching to eco 227
    3.33.1) Stop building tanks and upgrade sooner if have map control 227
    3.33.2) Switch to eco if we have no core platoons we want tanks for 227
    3.33.3) Eco strategy – focus on defence with minimal raiders 227
    3.33.4) Upgrade factories to non hq factories once we have an hq 227
    3.33.5) Switch to eco if mex income not increased recently 228
    3.33.6) Don’t upgrade buildings near the frontline 228
    3.33.7) After upgrading a factory, build an engineer and power as a high priority 228
    3.33.8) Have spare combat units patrol around the mex on our side nearest the midpoint if in eco mode 228
    3.33.9) Keep building tanks in eco mode if we have high mass 229
    3.34) V10 Release 229
    3.34.1) Pre release checks 229
    3.34.2) AI Tournament performance 229
    3.34.3) Bug fixes 230
    3.34.4) Minor enhancements 232
    3.35) Pathfinding 3rd attempt 233
    3.35.1) Background 233
    3.35.2) Information wanted from pathfinding 234
    3.35.3) Can we path from A to B 234
    3.35.4) Pathing results 241
    3.35.5) Amphibious pathfinding 244
    3.35.6) Naval pathfinding 248
    3.35.7) Summary of time taken to generate level 1 pathing 249
    3.35.8) Optimisation – function integration 249
    3.35.9) Update existing code to make use of new logic in place of CanPathTo 250
    3.35.10) Update intel logic to determine intel paths at start of game 250
    3.35.11) Further changes – v11-v12 250
    3.35.12) V13 Issues – Serenity Desert 251
    3.35.13) V13 - Double-check all mex positions are pathable 251
    3.35.14) Manual height adjustment 253
    3.36) V11-v12 Releases 253
    3.36.1) Further bug fixes 253
    3.36.2) Basic Anti-experimental and nuke logic 254
    3.36.3) Cap mexes with mass storage 255
    3.36.4) Factor in energy income before having engineers upgrade 255
    3.36.5) Other misc changes 255
    3.36.6) V12 release: Pre release checks 256
    3.36.7) Bug fixes 257
    3.36.8) Misc changes for v13 258
    3.37) Anti-Navy logic 259
    3.37.1) Navy threat detection overseer 259
    3.37.2) Build more air factories if significant shortfall in air units wanted 260
    3.37.3) Build radar at base once we have enough power 260
    3.37.4) Only produce amphibious land units if we can’t path to the enemy base 261
    3.38) V13 Release 261
    3.38.1) Post release bug fixes 261
    3.38.2) Misc changes 264
    3.39) ACU Upgrades 266
    3.39.1) Issuing an upgrade 266
    3.39.2) ACU requests help when damaged 266
    3.39.3) Mid-tier ACU upgrades 267
    3.39.4) Only upgrading if we can attack approaching enemy units 267
    3.39.5) Spare engineers don’t assist anything if ACU upgrading and we have low mass 267
    3.39.6) Disable reclaim and building functionality if ACU has big gun (sera+cybran) 267
    3.39.7) ACU won’t get slow upgrades unless it’s closer to our base than the enemy 267
    3.40) Mobile shields 268
    3.40.1) Shield platoon 268
    3.40.2) Shield production: 268
    3.40.3) Assign mobile shields to T2+ mexes if TML detected 269
    3.40.4) Other platoon changes 269
    3.40.5) Misc changes 269
    3.41) Assign land scouts to mexes 270
    3.41.1) Assign scouts to mexes and adjust upgrade logic 270
    3.41.2) Build scouts based on numbers needed 270
    3.41.3) Create new platoon logic for guarding a mex 270
    3.41.4) Only upgrade mexes if they are close to base or have intel coverage 270
    3.42) Anti-bomber logic 271
    3.42.1) Micro to dodge bombers 271
    3.42.2) Working out the position a unit is facing, and how that compares to another location 271
    3.43) All-in attack on ACU 273
    3.43.1) Deciding whether to launch an all-in attack 273
    3.43.2) Platoon and unit actions 273
    3.43.3) Production and upgrade logic 274
    3.43.4) Platoon formation 274
    3.43.5) Misc refinements 274
    3.44) V14 Release 275
    3.44.1) Pre-release checks 275
    3.44.2) Bug fixes post release 275
    3.44.3) Misc changes/tweaks 277
    3.45) Profiler 279
    3.45.1) Profiler 279
    3.45.2) Function count and time per tick 280
    3.45.3) Initial results (with no optimisation) 280
    3.45.4) Softles profiler 287
    3.45.5) Conclusion – functions to focus on 289
    3.45.6) Optimisation: Reclaim 289
    3.45.7) Optimisation: GetIntelCoverageOfPosition 289
    3.45.8) Optimisation – high usage functions 290
    3.45.9) Optimisation: GetNearestEnemyIndex 291
    3.45.10) Optimisation: AddNearbyUnitsToThreatGroup 292
    3.45.11) Optimisation – moving near a target and initial optimisation results 292
    3.45.12) Optimisation – GetPriorityExpansionMovementPath (part 2) 293
    3.45.13) Results of optimisation to date and reclaim adjustments 294
    3.45.14) Summary of time taken by different logic areas 299
    3.46) New reclaim logic 299
    3.46.1) Shortlist of reclaim locations 299
    3.46.2) Assignment 301
    3.46.3) Localised reclaim logic 301
    3.46.4) Reclaim tracking and checks 302
    3.46.5) Other Reclaim functions 302
    3.46.6) Further optimisation 303
    3.47) V15 Release, and v16-18 Hotfix releases 304
    3.47.1) Pre-V16 release bug fixes 305
    3.47.2) Pre-V16 release misc changes 305
    3.47.3) Intel path rewrite 305
    3.47.4) V16 Hotfix release 306
    3.47.5) Pre-v17 hotfix release bug fixes 306
    3.47.6) Pre-V17 hotfix release - Other misc changes 307
    3.47.7) V17 Hotfix Pre-release checks 308
    3.47.8) V18 Hotfix 309
    3.47.9) Post v18 bugfixes 309
    3.47.10) Misc changes 310
    3.48) Rally points 311
    3.48.1) Choice of rally point 311
    3.48.2) Use of rally points 312
    3.48.3) ACU Anti-TML Logic – retreat to rally point 313
    3.49) Air dominance strategy and bomber changes 314
    3.49.1) Conditions for switching to air dominance 314
    3.49.2) Production and upgrade changes 314
    3.49.3) Air AA targeting changes 315
    3.49.4) Bomber targeting changes 315
    3.49.5) Initial build order changes 315
    3.49.6) Bomber – ‘hard to hit’ target logic 316
    3.49.7) Other bomber changes 316
    3.50) V19 Release 317
    3.50.1) Pre-release checks 317
    3.50.2) Post-release bugfixes 318
    3.50.3) Misc fixes 319
    3.51) Experimentals and v20 Release 319
    3.51.1) First experimentals 319
    3.51.2) V20 Pre-release checks 320
  4. Future possible changes 321
  5. Index of useful functions 372
    5.1) Map, game setup and general aiBrain information 374
    5.1.1) aiBrain - general 374
    5.1.2) AI Brain – Economy 375
    5.1.3) Map Markers and start positions 376
    5.1.4) Map size and playable area 376
    5.1.5) Terrain info 377
    5.2) Getting a list of units by category, location, or other method 377
    5.2.1) All units that meet a particular category 377
    5.2.2) Units at/near a location 379
    5.3) Unit information 379
    5.3.1) Units on radar 379
    5.3.2) Blueprints and unit categories 380
    5.3.3) Unit upgrades (enhancements) 381
    5.3.4) Location and pathfinding 381
    5.3.5) Unit’s ai Brain owner 381
    5.3.6) Unit’s current commands and whether it’s alive 382
    5.3.7) Unit bones 382
    5.3.8) Shields 382
    5.3.9) Units with missiles/anti-nukes 382
    5.4) Unit and platoon commands 383
    5.4.1) Building 383
    5.4.2) Assisting 383
    5.4.3) Pausing 383
    5.4.4) Reclaim 384
    5.4.5) Factory specific commands 384
    5.4.6) Movement and attack-move 384
    5.4.7) Transport 385
    5.4.8) Combat related 385
    5.4.9) Stopping 386
    5.4.10) Upgrades and enhancements 386
    5.4.11) Current commands and targets 386
    5.4.12) Unit status 386
    5.4.13) Change a unit’s name 388
    5.5) Platoon additional functions 388
    5.5.1) Units platoon handle 388
    5.5.2) Get AIBrain 388
    5.5.3) Get units in a platoon 388
    5.5.4) Disband 388
    5.5.5) Platoon exists 388
    5.5.6) Platoon position 389
    5.5.7) Get all platoons 389
    5.5.8) Platoon ai plan name 389
    5.5.9) Add units to a platoon 389
    5.5.10) Army pool and removing units from a platoon 389
    5.5.11) Create a platoon 390
    5.5.12) Change or reset an AI plan 390
    5.5.13) Platoon movement formation 390
    5.6) Weapon information 390
    5.6.1) Get a unit’s weapon 390
    5.6.2) Get information on that weapon 390
    5.7) Time and thread related 391
    5.7.1) Game time 391
    5.7.2) System time 391
    5.7.3) Wait/delay the code 391
    5.7.4) Fork thread (run independently) 391
    5.8) Events 392
    5.8.1) Creating custom events 394
    5.9) Other 394
    5.9.1) Visual changes – Draw Circles and Lines 394
    5.9.2) On Intel Change 395

M27AI developer; Devlog and more general AI development guide:


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)

M27AI developer; Devlog and more general AI development guide:


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):

It is for FA, some of these functions are documented here

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

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
    return false

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

Determine com start position

This function should do the trick 🙂

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))


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:

M27AI developer; Devlog and more general AI development guide:


unpack this
into \THQ\Gas Powered Games\Supreme Commander - Forged Alliance\coderes\Engine


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:
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.

M27AI developer; Devlog and more general AI development guide:


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



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)

M27AI developer; Devlog and more general AI development guide:


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

M27AI developer; Devlog and more general AI development guide:


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)

M27AI developer; Devlog and more general AI development guide:


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.

M27AI developer; Devlog and more general AI development guide:


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.

M27AI developer; Devlog and more general AI development guide:


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

M27AI developer; Devlog and more general AI development guide:


I admire the guide / developers log that you are keeping 🙂

A work of art is never finished, merely abandoned


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.

M27AI developer; Devlog and more general AI development guide:


@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 😀

"The needs of the many outweigh the needs of the few" - Spock