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

The current AI has been uploaded as a mod, and the files can also be accessed from the below:
https://drive.google.com/drive/folders/1jnLd67CVIpBB-ulXPlJP_GSS5QPZjK0R?usp=sharing

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 4) Index of useful functions, and/or browse the index for points that may be of interest.

In terms of the dev log section, if you start seeing lots of yellow highlighting/square brackets you’ve reached the end of the dev log part and the start of my todo list of things I’m planning on working on next.

Latest changes (v7) summary:
T2 is now here! My changes were focused on creating my own engineer and platoon formation functionality, 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)

Key areas of focus by version (history):
v1-3: Release
v4 - Intel and threat detection
v5 - Use of ACU
v6 - Hotfix for patch
v7 - Engineers and building upgrades
v8 - Hotfix (fixed crash)

Having only started following the FAF forums and news the start of this year I'd not come across the PC election before, but one thing that's surprised me is just how long the process has gone on for. To summarise the timings for the PC election that's almost now finished:

• 6 May 21 - election announced, candidates requested
• 30 May - Signups closed (includes 1 week extension to accommodate further debate following disqualification of certain candidates/clarification of conditions to apply)
• 6 June - voting begins
• 6 July - voting ends

So essentially, 3 months taken up with the PC election.

Regardless of whoever wins the current election, I'd suggest shortening this period significantly, as 1/4 of the PC's time will potentially be in 'election mode'.

I'd therefore suggest allowing 3 weeks for candidates, and then 3 weeks for voting, to halve the time involved overall, for next year's election, while still giving enough of a period to allow most people who might be on holiday at some point in that time to be able to stand and/or vote, without having the election go on for so long.

I'd also be curious if anyone has stats on the timeframe of when votes were cast, as I suspect they will be weighted significantly towards the start of the voting period (which would give further support for there not being a need for a whole month to vote). If this isn't the case and votes tend to be evenly spread over the time period (or even weighted more towards the end of the voting period) then it may still be worth retaining 4 weeks for voting.

1. Overview 15
   1.1) AI goals 15
   1.2) Background 16
   1.3) Approach 16
2. Setup and background 17
   2.1) Lua editors 17
   2.1.1) Intellij IDEA 17
   2.2) Other guides which include a section on AI: 18
   2.2.1) General information: 18
   2.2.2) How AI in FAF works 18
   2.2.3) AI markers and how AI uses them: 19
   2.2.4) Hooking (e.g. replacing/appending existing game code) 19
   2.2.5) Creating custom scripts for Sorian AI: 19
   2.2.6) Pathfinding 19
   2.2.7) How platoons work 19
   2.3) Lua coding 20
   2.3.1) How to code in Lua 20
   2.3.2) Stand alone Lua code testing 20
   2.3.3) Lua optimisation 20
   2.3.4) Common causes of errors for non-Lua coders 20
   2.4) Debugging in FAF 21
   2.4.1) Console 21
   2.4.2) Cheats 21
   2.4.3) Log window and error messages 21
   2.4.4) Debug window and shortcuts 21
   2.4.5) Platoon names for debugging 22
   2.4.6) Fast speed 22
   2.4.7) Other shortcuts and game startup options 22
   2.4.8) Error handling 23
   2.4.9) Optimisation – benchmarks and monitoring 24
   2.4.10) Debugging via replay 26
   2.5) AI development discord 26
   2.6) Core FAF Lua files 26
   2.6.1) Accessing core Lua code 26
   2.6.2) Other built in functions 27
   2.6.3) Unit blueprints 27
   2.7) Testing AI against other AI 27
   2.7.1) Simple offline testing 27
   2.7.2) Mass offline AI testing 27
   2.8) Getting started – using a simple AI template as a starting point 28
   2.9) Downloading and setting up MicroAI 28
   2.10) Giving the AI mod your own name 28
   2.11) General - Hooks, and getting the code to recognise if it’s running your AI 29
   2.12) Github 29
   2.12.1) Linking Github with a local repo via creating your own init file 30
   2.12.2) Pro Git ebook 30
   2.12.3) Git commit messages 30
   2.13) Uploading your AI to FAF 30
   2.13.1) Pre-upload checklist 30
   2.13.2) FAF rules on uploading mods 30
   2.13.3) Uploading to FAF 30
   2.14) Other AI documentation 31
3. AI changes 31
   3.1) Build order - Changing the initial build order 31
   3.1.1) Adding/removing buildings 31
   3.1.2) Change build order based on map resource positions 31
   3.1.3) Build order conditions 32
   3.2) Build order – ACU builds without moving at start 32
   3.2.1) BaseTemplate 32
   3.3) Build factory and power to benefit from adjacency 34
   3.3.1) Record all mexes on the map, and reference this information 34
   3.3.2) Determine com start position 35
   3.3.3) Identify mexes near to start 35
   3.3.4) Hook onto the core code relating to building a structure at a location 36
   3.3.5) Call build order from custom aiBrain function, to edit how things are built 36
   3.3.6) Adjust build template based on mex location - conditions 37
   3.3.7) Adjust build template based on mex location – build location adjustment 38
   3.3.8) Build initial PGens by existing factory 38
   3.3.9) Adjacency bonus where ACU is away from start location 40
   3.3.10) Referencing unit blueprints for information such as unit size 42
   3.4) Platoons and sending engineers to reclaim 44
   3.4.1) How platoons work 44
   3.4.2) Send the first engineer on reclaim duty 49
   3.4.3) Determine where to send the engineer to reclaim 51
   3.4.4) Identifying reclaim mass value 51
   3.4.5) Find out if a location is accessible by ground: 51
   3.4.6) Mapping reclaim locations and assigning preferred location to an engineer 53
   3.4.7) Don’t send early reclaiming engi if there’s minimal starting reclaim 54
   3.4.8) Issue new reclaim command if engineer becomes idle 54
   3.4.9) Send more engineers to reclaim later (as lower priority) based on the reclaim currently on the map 54
   3.4.10) Send 5 engineers at the start to reclaim and build mexes 55
   3.4.11) Reclaiming trees when no main mass left 56
   3.5) Building and assisting hydro 56
   3.5.1) Check if hydro near start area and have engineer build hydro 56
   3.5.2) Have ACU assist engineer with hydro 57
   3.5.3) Get ACU to continue build order after hydro complete 58
   3.5.4) Subsequent build order changes 59
   3.6) Attack force composition changes and check of AI performance 59
   3.6.1) Build Moar Tanks 59
   3.7) Pre-v1: AI Progress check 60
   3.7.1) Land factory buildings and other build order refinements 60
   3.8) Raiding AI 62
   3.8.1) Raiding behaviour - overview 62
   3.8.2) Queue up move commands for mexes 62
   3.8.3) Identify mexes to target 63
   3.8.4) Locating mexes near to an existing pathing route 66
   3.8.5) Determine when raiders need new targets 66
   3.8.6) Handling complications (stuck units, move orders built on, platoon units dying) 66
   3.8.7) Change factory rally point so units are assigned orders sooner 68
   3.8.8) Making use of platoon names for debugging 70
   3.8.9) Ensure 1 land scout included in each platoon 71
   3.8.10) Use microbots before switching to tanks 72
   3.8.11) Have scouts stay with the platoon 74
   3.8.12) AI scouting, threat detection, and identifying nearby enemy units 74
   3.8.13) Attack engineers en-route: Overview 77
   3.8.14) Tracking when have reached movement points 77
   3.8.15) Determining the platoon minimum range 78
   3.8.16) Identifying nearby enemy units and assessing their threat 79
   3.8.17) Actions based on enemy threat 81
   3.8.18) Avoid attacking enemy mexes for small platoons 82
   3.8.19) Other issues – cheating, walls and min range 83
   3.8.20) Larger raiding platoons 84
   3.9) Large attack wave 85
   3.9.1) Checking when to form a large attack wave 85
   3.9.2) Generalising raider AI 85
   3.9.3) Creating separate platoon AI for the large attack force 86
   3.9.4) Run nearer to base when outnumbered 86
   3.9.5) Recalling nearby raiders to join attack force 87
   3.9.6) Updating threat assessment for ACU health and upgrades 88
   3.9.7) Don’t chase small numbers of faster units 90
   3.9.8) Switch to hunt and kill enemies once reached destination 91
   3.10) Pre-v1: AI Progress check 91
   3.10.1) Summer duel 92
   3.10.2) Theta passage 92
   3.10.3) New issues 92
   3.11) Platoon AI – Generalised approach and further enhancements 93
   3.11.1) Embracing the table 93
   3.11.2) Moving units when shots blocked by cliffs 96
   3.11.3) Anti-stuttering protection 96
   3.11.4) Large attack AI – Rally point for merged units 96
   3.11.5) Raiders assume small numbers of enemies are engis/scouts 97
   3.11.6) T1 Artillery specifically target structures, and spread-attack units 97
   3.11.7) Keep scouts at back of platoon 98
   3.11.8) Platoons with non-Seraphim T1 artillery and no tanks don’t run unless against slower enemy 99
   3.11.9) Factor in nearby platoons when faced with enemies 99
   3.11.10) More T1 arti in platoons once reached certain level of tanks 100
   3.11.11) Don’t treat AA as a direct fire unit when forming a platoon 100
   3.11.12) Build hydro where it’s far away from base 100
   3.12) Expansion bases 101
   3.12.1) Background – expansions and the main base 101
   3.12.2) Having all units treated as available for platoons 101
   3.13) Upgrade ACU with gun and attack 102
   3.13.1) How to upgrade an ACU 102
   3.13.2) Get enough energy to support guncom 102
   3.13.3) Upgrade ACU’s gun once have enough energy 103
   3.13.4) Attack with ACU once upgrade finished 104
   3.13.5) ACU overcharge 104
   3.14) V1-3 release incl AI progress check 105
   3.14.1) Performance – v1-3 of M27AI 105
   3.14.2) Issues and planned improvements from testing 105
   3.14.3) Debug issues and other bug fixes 106
   3.14.4) Attack lauched as soon as ACU gun ready 111
   3.14.5) Default attack-move direct fire units at enemy (attack-move if platoon scattered) 111
   3.14.6) Limit of 1 microbot per early raider platoon, and tank defenders 112
   3.14.7) Skip move location if are closer to the next move location than the first one 112
   3.14.8) Build more engineers if are close to overflowing mass 113
   3.14.9) Add energy storage requirements to ACU initial land factory build order 114
   3.14.10) ACU and Engineers will move near mex to build 114
   3.14.11) Other minor misc changes 116
   3.15) On demand basic pathfinding 116
   3.15.1) Revised approach 116
   3.15.2) Mex raiding path optimisations 118
   3.15.3) Useful maps for testing map based logic 118
   3.15.4) Move to build structure – check pathing 119
   3.15.5) Platoon Merge location – have it check no pathing issues in nearby segments 119
   3.16) AI Overseer - responding to enemy attacks 119
   3.16.1) Overview 119
   3.16.2) Planned initial logic 119
   3.16.3) Run overseer on AI creation 120
   3.16.4) Assigning units to defender platoons 121
   3.16.5) Recording enemy threats 122
   3.16.6) Sending units to deal with enemy threats 124
   3.16.7) Sorting a multi-dimensional table 124
   3.16.8) Disbanded units return to base 126
   3.16.9) Intercepting platoons should leave at least 1 scout when removing spare units 126
   3.16.10) Don’t remove units when in combat 127
   3.16.11) Platoon and other build conditions 127
   3.16.12) Limit number of mobile AA in an intercepting defending platoon 128
   3.16.13) Remove ACU from defender platoon once the threat is dealt with 128
   3.16.14) Don’t have ACU join a platoon if its upgrading 128
   3.16.15) Disabling sorian base manager distress logic 129
   3.17) AI Overseer – Intel and ACU managers 129
   3.17.1) Intel manager - overview 129
   3.17.2) Planned logic – 1-off 129
   3.17.3) Planned logic – recurring 130
   3.17.4) Scout localised platoon AI 131
   3.17.5) ACU manager 132
   3.18) V4 release (incl AI progress check) 133
   3.18.1) Pre-release checklist 134
   3.18.2) AI performance results 134
   3.18.3) Notable issues noted from performance 135
   3.18.4) Resolution of immediate issues/bugs post-release 136
   3.19) ACU –aggression, support and micro enhancements 141
   3.19.1) ACU custom platoon - overview 141
   3.19.2) ACU expansion – choice of location 142
   3.19.3) Platoon completion actions 144
   3.19.4) Expanding more than once 145
   3.19.5) Getting nearby reclaim and/or unclaimed mexes while moving 146
   3.19.6) Assisting hydro construction (reworked) 148
   3.19.7) ACU defender platoon refinements 149
   3.19.8) ACU Scout helper and general scout build order 149
   3.19.9) ACU MAA helper and general behaviour 152
   3.19.10) Air threat assessment and MAA to build (initial) 152
   3.19.11) Large platoon scout and MAA helpers 153
   3.19.12) ACU attacks independently to large attack platoon 153
   3.19.13) ACU Build order tweaks 153
   3.19.14) Aeon ACU gets both gun upgrades 154
   3.19.15) ACU retreat 154
   3.19.16) ACU kiting 154
   3.19.17) Have ACU attack-move if kiting doesn’t return any action 155
   3.19.18) Manual overcharge 155
   3.19.19) Other misc changes/refinements 159
   3.20) V5 release (incl AI progress check) 159
   3.20.1) Pre-release checklist 159
   3.20.2) AI performance results 159
   3.20.3) Resolution of immediate issues/bugs 160
   3.21) Refinements, basic water based actions, v6 hotfix 161
   3.21.1) Misc refinements pre v6 161
   3.21.2) ACU water based actions – reclaim and move to shore 161
   3.21.3) V6 hotfix 162
   3.21.4) Error fixes subsequent to v6 163
   3.22) Custom build orders and platoon formers 166
   3.22.1) Proof of concept 166
   3.22.2) Initial complications – LABs and no valid units 167
   3.22.3) Related changes – scout conditions; tracking construction orders 168
   3.22.4) Linking production with threat detection overseer 168
   3.22.5) Increasing indirect fire units based on enemy PD usage 168
   3.22.6) Assign MAA similarly to how scouts are assigned 169
   3.22.7) Platoon former – manually assigning platoons based on threat distance 169
   3.22.8) Try to save raider scouts 170
   3.22.9) Not got enough units for a platoon – send spare units to intel path 170
   3.22.10) Call the platoon former if disband a platoon containing combat units 170
   3.22.11) Platoon merger – Periodically combining attack platoons where they’re nearby 170
   3.22.12) Delayed platoon formation 170
   3.22.13) Factories away from main base or with nearby enemies don’t build engineers 172
   3.23) Engineer overseer 172
   3.23.1) Overview 172
   3.23.2) Spare engineer action logic 172
   3.23.3) Nearby enemy logic 172
   3.23.4) Unclaimed mex logic 173
   3.23.5) Threat detector – adjust distance calculation and record 173
   3.23.6) Update engineer names to reflect their action 173
   3.23.7) Clear unit actions if factory idle (unexpected bug workaround) 173
   3.23.8) Have ACU assist assigned hydro builder and build land factory 174
   3.23.9) Retain existing engineer assignments in favour of nearest engineer 175
   3.23.10) Power assignment – longer term requirement check 175
   3.23.11) Optimisations and rollbacks 176
   3.23.12) Adjacency refinements 176
   3.23.13) Misc changes 177
   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 177
   3.23.15) Consider engineer actions as soon as a factory finishes construction 178
   3.23.16) Constructing building – first check if part-complete similar building 178
   3.23.17) Building more engineers 178
   3.23.18) Engineers take into account ACU expansion path 178
   3.23.19) Initial engineers keep building mexes until they die or half the map is covered 179
   3.23.20) Have engineers queue up nearby unclaimed mexes and multiple T1 power 179
   3.23.21) Build a second power at the same time 179
   3.23.22) Build more energy storage based on power income 180
   3.24) Building Upgrade overseer 180
   3.24.1) Overview 180
   3.24.2) Refinements 181
   3.24.3) Have engineer overseer switch to assisting an upgrade instead of building a land factory 181
   3.24.4) Pause upgrade if low on resources (and track so can resume later) 181
   3.24.5) Mass stall – pause factories over mexes 182
   3.25) Idle platoon 182
   3.25.1) Army pool platoon and new idle platoon 182
   3.25.2) Approach 182
   3.26) Misc changes 183
   3.26.1) ACU is removed from defender platoons when allocating new threats 183
   3.26.2) Allocating overseers to different ticks 183
   3.26.3) Have defender platoons move in formation 183
   3.26.4) State of game log 183
   3.26.5) Intel path – allow scouts to move +/- 1 path 184
   3.26.6) ACU shots blocked 184
   3.26.7) Enemy ACU threat increase 184
   3.27) V7 release (incl AI progress check) 184
   3.27.1) Minor enhancements to overseers due to testing (pre-release) 184
   3.27.2) Tracking revision 185
   3.27.3) Choosing nearby engineers based on mex location 186
   3.27.4) Pre-release check results 186
4. Future likely planned changes 186
   4.1) Misc changes (not yet organised) 186
   4.1.1) Idle units run from enemies 186
   4.1.2) ACU Upgrader 187
   4.1.3) Only build MMLs if T2 PD detected 187
   4.1.4) Pause gun upgrade when power stalling 187
   4.1.5) Review overseer threat assignment 187
   4.1.6) Extra energy storage 187
   4.1.7) Second Power queue 187
   4.1.8) Pre-empt future FAF patch error 188
   4.1.9) ACU Mobile assisters still try going into water when ACU makes it back to land 188
   4.1.10) Mex raider target error 188
   4.1.11) ACU factors in part-complete buildings 188
   4.1.12) MAA build order 188
   4.1.13) ACU upgrade logic and support requests 188
   4.1.14) Spare unit overseer 188
   4.1.15) ACU should ignore enemy ACU if its underwater 188
   4.1.16) Overcharge further refinements – enemy ACU position and low health PD 188
   4.1.17) Engineer reclaim target selection 189
   4.1.18) Adjust number of mex raiders based on mexes on map outside enemy bases 189
   4.1.19) Have the first intel path really close to our base 189
   4.1.20) Have large attack platoons attack out of formation if ACU in combat against high threat 189
   4.1.21) Adjacency priority 189
   4.1.22) Setons Clutch – Fix the ACU going on a scenic tour of the seabed 189
   4.1.23) Artillery only attack platoon? 190
   4.1.24) Other changes 190
   4.2) Air scouting 190
   4.3) Air overseer 190
   4.4) Anti-turtle overseer and ecoing 190
   4.5) Replace remaining build order and platoon former logic 190
   4.5.1) Air factory build order via overseer 190
   4.5.2) ACU gun upgrades via overseer 190
   4.5.3) ACU initial build order via overseer 190
   4.5.4) See if can remove core game functionality 191
   4.6) CPU performance optimisation/benchmarking 191
   4.6.1) Platoon rewrite? 191
   4.7) AI Overseer – Other changes 191
   4.7.1) Fix AI assisters when ACU goes into water 191
   4.7.2) Initial raiders head straight to enemy mex 191
   4.7.3) Stop initial raiders standing by power plants theyre attacking 191
   4.7.4) Air threat overseer sends MAA to intercept (if not too far away) 191
   4.7.5) Update intercept location for defenders 191
   4.7.6) Limit the range of the defender logic? 192
   4.7.7) Determine when an enemy threat is killed/disband defenders earlier 192
   4.7.8) T2 range adjustments 192
   4.7.9) Split up a large platoon to chase small units 192
   4.7.10) Attack with all land units once ACU near enemy main base 193
   4.7.11) Point defence included in ACU threat? 193
   4.7.12) Platoon composition manager and/or PD hunters 193
   4.7.13) Air threat MAA intercept 193
   4.7.14) Choice of reclaim target – factor in engineers assigned to nearby location 194
   4.7.15) Queue up multiple mexes and power 194
   4.7.16) Performance optimisations 195
   4.7.17) Interupted buildings are compelted by assisting engineers 195
   4.7.18) Intel pathing – use land based pathing 196
   4.7.19) Intel pathing – have scouts advance independently if no threats 196
   4.7.20) Initial movement path for defenders based on intel 196
   4.7.21) Platoon completion – next action based on intel coverage 196
   4.7.22) Backup logic for unforeseen errors – idle ACU 196
   4.7.23) Backup logic for unforeseen errors – idle units 197
   4.7.24) ACU treated as building on initial mexes 197
   4.7.25) Upgrade overseer - Refine the logic for upgrading to allow for T3 and mass storage 197
   4.7.26) Upgrade overseer – don’t upgrade if in range of T2 artillery 197
   4.7.27) Other (TBC) 197
   4.8) More micro improvements and other enhancements 197
   4.8.1) Assist building being constructed instead of building new one 197
   4.8.2) Engineer assist AI will assist factories 198
   4.8.3) ACU and small platoons move if under attack from artillery 198
   4.8.4) ACU/General platoon target prioritisation 198
   4.8.5) Initial raider build order tweaks 199
   4.8.6) Factory builder – instance count bug 199
   4.8.7) Indirect fire units near the ACU when its upgrading? 199
   4.8.8) Attack platoons merge with larger attack platoons they come near 199
   4.8.9) Support platoon units run away from enemies nearest them 199
   4.8.10) T1 Arti composition based on PD 200
   4.8.11) Platoon merge path when attacking? 200
   4.8.12) Aeon T1 tanks kiting 200
   4.8.13) Indirect fire structure targeting 200
   4.8.14) ACU new land factory/adjacency bonus – target nearest mexes first? 200
   4.8.15) Target low health units (small platoon sizes) 200
   4.8.16) Anti-capture protection 200
   4.8.17) Advanced reclaim prioritisation 200
   4.8.18) Air factory adjacency 201
   4.8.19) Engineer management – combine to construct a single building instead of 2 separate ones 201
   4.8.20) Engineers attack-move to nearby enemies 201
   4.8.21) Improved blip threat detection 201
   4.8.22) Protecting engineers 201
   4.8.23) Saving scouts when a platoon is dying 201
   4.8.24) Replace existing construction orders if closer 201
   4.8.25) Factory adjacency location - Build land factories nearer our base if not near base 202
   4.8.26) Integrate IsShotBlocked into wider unit stuck and targeting logic 202
   4.8.27) Advanced Kiting – Com vs Com 202
   4.8.28) Overcharge further refinements 202
   4.9) Resource stall and overflow 202
   4.9.1) Mass stall – pause non-mex production 202
   4.9.2) Energy stall – pause non-PGen production 202
   4.9.3) Mass overflow – upgrade a mex 202
   4.10) T2 upgrades and anti-turtle tactics 202
   4.11) Enhanced pathfinding information – how long to path 203
   4.12) AI scouting, threat detection, and safe paths 203
   4.12.1) General discussion on scouting and threat detection 203
   4.12.2) Naval pathfinding 206
   4.12.3) Determining a safe path for raiders 206
   4.12.4) Engineer mex selection – calculating safe paths 207
   4.12.5) Basic air scouting 207
   4.13) Other enhancements 207
   4.13.1) Fix guide hyperlinks 207
   4.13.2) What to do if early hydro is destroyed 207
   4.13.3) Transports 207
   4.14) Optimisations 208
   4.14.1) Base game removal - Consumption values 208
   4.14.2) Determining nearest enemy start position every 10s instead of on the fly 209
   4.15) Lower priority enhancements to earlier code 209
   4.15.1) Enhancements flagged earlier 209
   4.15.2) Per-unit micro to win early exchanges 209
   4.15.3) ACU building land factory – link to engineer overseer 209
   4.15.4) If control >50% of mexes then consider upgrading to T2 mexes and land 209
   4.15.5) Overseer and full share 209
   4.15.6) Free for all and multiple opponents 209
   4.15.7) Enemy ACU upgrade 209
   4.15.8) Extra energy storage and power build decision – Factor in enemy tech level 209
   4.15.9) Improve intel pathing choice based on enemy threats 210
5. Index of useful functions 210
   5.1) Map, game setup and general aiBrain information 211
   5.1.1) aiBrain - general 211
   5.1.2) AI Brain – Economy 212
   5.1.3) Map Markers and start positions 213
   5.1.4) Map size 213
   5.1.5) Terrain info 214
   5.2) Getting a list of units by category, location, or other method 214
   5.2.1) All units that meet a particular category 214
   5.2.2) Units at/near a location 215
   5.3) Unit information 216
   5.3.1) Units on radar 216
   5.3.2) Blueprints 216
   5.3.3) Unit upgrades 217
   5.3.4) Whether a blueprint matches category conditions 217
   5.3.5) Location and pathfinding 217
   5.3.6) Unit’s ai Brain owner 218
   5.3.7) Unit’s current commands and whether it’s alive 218
   5.3.8) Unit bones 218
   5.4) Unit and platoon commands 218
   5.4.1) Building 218
   5.4.2) Assisting 219
   5.4.3) Pausing 219
   5.4.4) Reclaim 219
   Note: The core AI functionality appears to run ProcessBuildCommand on a unit given an issuereclaim order (even if that unit is in a custom platoon) and will then disband that platoon (meaning less than 1 second after the reclaim order is given, the unit stops reclaim and is disbanded). 219
   One solution is to add extra code to ProcessBuildCommand to not disband the platoon is the unit is reclaiming. 219
   5.4.5) Factory specific commands 219
   5.4.6) Movement and attack-move 220
   5.4.7) Transport 220
   5.4.8) Combat related 220
   5.4.9) Stopping 221
   5.4.10) Upgrades 221
   5.4.11) Current commands and targets 221
   5.4.12) Unit status 221
   5.4.13) Change a unit’s name 223
   5.5) Platoon additional functions 223
   5.5.1) Units platoon handle 223
   5.5.2) Get AIBrain 223
   5.5.3) Get units in a platoon 223
   5.5.4) Disband 223
   5.5.5) Platoon exists 223
   5.5.6) Platoon position 224
   5.5.7) Get all platoons 224
   5.5.8) Platoon ai plan name 224
   5.5.9) Add units to a platoon 224
   5.5.10) Army pool and removing units from a platoon 224
   5.5.11) Create a platoon 225
   5.5.12) Change or reset an AI plan 225
   5.5.13) Platoon movement formation 225
   5.6) Time and thread related 225
   5.6.1) Game time 225
   5.6.2) Wait/delay the code 225
   5.6.3) Fork thread (run independently) 225
   5.7) Events 226
   5.8) Other 228
   5.8.1) Visual changes – Draw Circles and Lines 228
   5.8.2) On Intel Change 228

I’d suggest highlighting the point about being able to join multiple queues in the news post when its released (and possibly even the game loading tooltips)-I doubt I’m the only one who assumed you could only be in one queue at a time.

@BlackYps
I fail to see how anyone could argue astro craters is like sim city with a straight face, even allowing for the way in which many people here (as shown on this thread amongst others) seem to look down with disdain on those of us that play such maps (even though they appear to be the most popular types of maps on FAF, at least for custom games). There's more variety in the gameplay on astro than the majority of 1v1 maps on ladder for those not in the highest ratings , where in most cases for ladder it's a case of 'T1 land spam or die' (with having a good APM being far more significant than making good strategic decisions). Perhaps you've just not played enough astro games to appreciate the range of strategies on it (since if you're using your main profile you don't appear to have any games on the map).

I'd have also thought a focus on "the kind of players that faf wants to attract" (in the context of not wanting to attract people who don't like high APM play) very shortsighted. The more people who play faf (in a non-toxic way) the better its longevity/future prospects. Just using myself as an example, while I may play mostly astro I also sometimes play some 1v1 ladder. I doubt I'm the only person who has a favourite style of map such as astro/gap/setons but who also likes to sometimes play other maps or game modes. If all such players were to leave faf because we're 'not the kind of players that faf wants to attract' you get fewer people playing those maps/game mods you approve of such as 1v1 matchmaker.

I also don't understand the logic proposed both here and in the PC election thread for removing the global ranking system. If you had a team of rank 1500s on astro or dual gap against a team of rank 500s (global rating), almost every time the 1500 ranks would crush the 500 ranks. While you may have a greater variance in ability (especially at lower ratings) than with a 1v1 rating, the rating is still a far far better guide to how well someone will play than having no rating at all. Removing the rating just seems like a way of punishing people who are playing maps that don't meet the personal preferences of those suggesting its removal, especially given how bad opti-balance is at balancing a game when you have newer players. As for manually balancing based on knowledge of players, the majority of my games have been from where I've hosted an all welcome lobby, but on average I won't recognise the names of the majority of people who join, and even of those whose names I recognise I'll only know how well some of them play/favoured strategies (there's probably only 4-5 people I could think of off the top of my head where I know how they tend to play and how good that style of play is).

Going back to the OP, while I'd like the idea of an option to play 'lower APM' 1v1 maps (as opposed to currently where I can be given a 1v1 map on a map that's normally seen in the custom lobby as a 3v3 or 4v4 map), and think it would be a more gentle introduction to newer players, if implemented it'd need to be as an option on the existing matchmaker (e.g. you check the box for if you want to play 'new player friendly only' maps, and/or if you're open to playing the full map pool), or else you dilute the number of people on matchmaker even further.

Since as I understand it something a bit like this is meant to happen (I don't think it's working well if it is though), it may be easier to just improve the current system of starting with a small map pool and then adding more complex maps as rating rises.

The 'stone age' mode also sounds like an interesting idea for teaching the gameplay style that's required for 1v1, although I'm not sure how best it would be implemented (if as an option, people may just not choose it and/or it splits the pool of people queuing too much and makes finding games harder; if its as a tutorial mode with AI then people may not be aware of it and/or the AI may not offer enough of a challenge; if it's forced for the first x games then it could put off people who want to experience the full range of options and not be limited to the first tier).

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.

I thought it was a valid tactic to ctrl k to kill the enemy com-it stops them gaining vet from killing you and surviving, and from being able to run away from you if they have some spam to block you. I’ve done it myself a number of times and would feel very aggrieved to be banned for it (until now id presumed it would count as a draw). If the actual issue can be fixed then great, but if not it shouldn’t be punishable because it should be a legitimate tactic to obtain a draw instead of a loss. Id be happy with a punishment that just involved a manual rating change as well since that would just be an awkward way of fixing the issue.

One query though-some have suggested pausing and offering a draw. how do you get a draw? One game my opponent had to leave so we agreed to have our coms shoot each other to death to draw; is there a better/easier way?

With a larger player base I'd be in favour of such a matchmaking idea. My concern though is that you'll only end up with a small number of people queuing at a time (except for very busy periods) similar to the existing matchmakers, and you'll inevitably have some people who are very good at whatever custom mode is highlighted compared to a new player.

That said, one of the biggest issues I have with both the 1v1 and 2v2 matchmakers is that the maps are too much like hard work. That is, if I get a 1v1 map there's a good chance it's some large sprawling map with mexes everywhere that requires me to do a crazy amount of actions a minute to keep up with t1 land spam being mandatory (except on huge maps or naval ones), which ends up being stressful not fun. In 2v2 from what little I've played it's similar, but with the added pressure of a teammate who will be angry that I don't perform as well as they'd like.

I think this is a large part of the reason games like gap, astro, dual gap, pass etc. are popular - you dont have to focus on as many areas of the map at once, and so there's more chance to just have fun, and it's alot easier to get into as a new player. Even setons and isis mirror this to a large extent (ignoring the players who will make your life miserable if you don't conform to the expected way of doing things when starting in a particular slot).

Therefore I like the idea of having lots of different 'fun'/different types of modes that will make a change in gamestyle from the standard 1v1, especially if they include vs AI challenges, I'm just not sure how to solve the issue of too few new players wanting to do it leading to those that do try getting crushed by pros. One possibility might be to showcase it on the news page (e.g. you have a different mode each week, and the news page features it prominently).

After the recent AI tournament I was inspired to have a go at experimenting with AI development to see if I could come up with anything remotely functional, and figured I'd also document some of the steps in doing it to help anyone else who is interested in starting out (assuming I make enough progress for such documentation to be of any use).

Unfortunately I feel I've failed already at a basic first hurdle, and wondered if any of the AI developers might take pity and help me out?

I thought I'd start simple, and just try and adapt an AI's initial build order. I used the MicroAI as a starting point since I understand it's intended for public use for such a purpose:
https://github.com/HardlySoftly/MicroAI

My presumption with how the AI relating to the intial build order worked from looking through the files is as follows:

• AIBaseTemplates\MicroAI.lua lists the various custom builder functions to be used by the AI, including 'MicroAICommanderBuilder'
• AI/AIBuilders/MicroBuilders.lua then sets out what each of these builder functions does. 'MicroAICommanderBuilder' is the top priority, and appears to contain the initial build order in the section beginning BuildStructures = { 'T1LandFactory', 'T1EnergyProduction', 'T1EnergyProduction', .... }

So, as a simple test to check if I was right, I changed it so the first item listed was 'T1EnergyProduction', followed by 'T1AirFactory'. However, on loading up the AI on an (offline) custom game, it would still start by building a T1 land factory.

Other changes I made seemed to have some sort of impact (e.g. to try and change the attacks the AI was sending I started messing around with the "MicroAILandBuilder" part of this file, along with the PlatoonTemplates\MicroAITemplates/lua file, which resulted in the AI massing an army of land scouts to attack with - not quite what I was after but at least a noticeable change! So I don't think the issue is with the changes I'm making failing to be reflected in the mod I then load in the offline FAF skirmish)

Searching for articles that might give some basics of how the AI works I found the below which has a section on AI scripting (in the context of custom missions) and a separate guide which gives an overview/diagram of how the AI works:
https://wiki.faforever.com/index.php?title=Mission_Scripting
https://wiki.faforever.com/index.php?title=AI_Modding
I've also been able to locate the core game files that are part of FAF (i.e. the Lua file within Supreme Commander Forged Alliance\gamedata), but I couldn't find anything else from a skim of these forums and Discord.

Is anyone able to help either with my query, or alternatively if there's any material aimed at beginners getting into FAF AI development that might explain some of the basics?

Edit: Thanks for the help everyone - now resolved the issue

Edit2: See my more recent forum post for a link to the current version of the guide:
https://forum.faforever.com/topic/2373/ai-development-guide-and-m27ai-v1-devlog

I’d suggest taking a screenshot and making a report whenever you come across this so they can be banned/suspended.

On a related note I’m happy to volunteer to go through reports if it would help such issues (and other breaches of faf rules) be dealt with quicker/if you (faf moderation team) need more resource to deal with reports.

@scout_more_often You misunderstood me-you can eco by just building sera sacus with no mass fabs. IIRC its something like half as efficient as a RAS sacu but more than twice the combat effectiveness, when adjusting for build cost.

The sera sacu can also be used to eco. It’s worse than a ras sacu at eco but much better for combat, so gives a useful ‘jack of all trades’ option

If it doesnt happen already (I dont really understand how the rating system works) what about increasing the amount that your rating changes based on consecutive wins/losses? I.e. your 3rd loss in a row loses you more than the 2nd loss, and so on (and if it already does this then possibly increasing the extent to which it does it slightly).
That way you dont have to sit through as many unbalanced matches where your team gets mad at you because you're far worse than your rank suggests, hopefully improving the experience for everyone.

I'm assuming from the screenshots in the linked thread that the league system is just intended for matchmakers not custom/global rank, in which case while it would help to some extent it wouldn't solve the issue for global (or are there plans for a league system for global as well?)

To clarify, if you ctrl-k your com in a scenario where it makes sense (if the exploit didnt exist) is that considered abuse of an exploit?

Eg your com is about to die and/or lose range of enemy com (with you in a non-winning situation) but enemy com is low enough health that ctrl-k will kill it. Regardless of if the exploit existed ctrl-k is or could reasonably be thought to be the best move. Is that considered abuse of an exploit?

If yes I see that as a serious issue because you’re potentially banning someone for playing the game properly (ie they would play that way whether or not the exploit existed). If it isn’t then I’m confused what scenario would be considered abuse of an exploit.

Another example would be deliberately going for a draw by charging your acu into an acu fight but again that is a legitimate strategy if you don’t think you’ll come out on top long term.

I had no idea until I saw this thread that nukes were at different speeds (and thats after >600 games I think), so i expect there are a significant number of other players who also arent aware and hence dont factor it into their choice of faction.
Its also different to other buildings that are universal across factions but different rather than just outright worse-eg artillery have different aoes and accuracy; tmd have different ranges but can also handle different numbers of units etc; finally if anything it runs counter to the aeon theme of having units specialised for particular roles (that are better at that specific role than more generalised faction counterparts).

If factional differences were wanted an alternative could be to change the build power of silos to compensate for the launch time so they both launch in the same time but require slightly more resources for a slightly shorter period to build the missile

If no changes are wanted then instead adjust the tooltip about 5m for a nuke and 4m for smd to also note some factions nukes take longer to launch than others

A few other ideas:
Fall back

Get AA/TMD/smd

Please can I have an engi of faction [x]

reclaim here (ping)
move your units as theyre blocking me (ping/map note)

Im going to: eco/make {experimental}/go air/go navy/rush nuke/rush arti etc

I need aa cover (ping)

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.

What if instead of showing people's CPU scores, you instead show a warning flag if they're likely to have too low a CPU for the map in question, similar to how you get a ping warning if someone's ping goes over 500?

It'd be impossible to get a perfect measure, but I'd have thought you could still have a reasonable approximation by considering the map size, and the number of players available on the map, coming up with an approximate CPU score that you'd want to play that map late game without significant slowdown, and then showing a player's CPU score only if they exceed that level.

So for example a 3v3 on a 10x10 map might show a warning if they're about 400 CPU, while a 4v4 on a 20x20 map might show a warning around >200 CPU (testing could be done to come up with better thresholds - I just picked these numbers out of thin air).

This way the person with the bad CPU knows by staying in the game lobby they're at risk of being kicked, while they also dont have to worry about being kicked based on their CPU if they've got a good enough CPU for the map and the host just likes going over the top with CPU scores.

An alternative would be making it a rule that you can't kick someone due to CPU/Country/Ranking/Grey status if you host an "All welcome" game (and reporting and punishing people who break the rule) but my understanding is there's already a large backlog of moderation reports so that's probably a non-starter as an option.

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.

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)