AI Development Guide and M27AI v20 Devlog


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


v11-v12 update:
The big thing I've been working on in these 2 updates is an alternative approach to pathfinding to replace my use of CanPathTo with a manual method that I can run at the start of the game and then lookup the pre-recorded results later in the game (rather than calculating pathfinding on the fly), since I figured this should be much faster.
Unfortunately I failed to factor in the consequential change this would have on other parts of my code, and while my replacement 'canpathto' check itself is much faster (especially on 81x81km maps), my overall AI is significantly slower! Since my new approach is based on terrain height differences, it will also be less accurate, so I've managed to achieve the worst of both worlds! However, it should at least be easier to get some CPU performance gains in the future, even if my first attempt has failed.

Various misc changes:

  • Significant improvement in ecoing speed, including the ability to build mass storage
  • MAA and Engineers shouldn't be overproduced as much, and certain T3 MAA shouldn't be treated as land attack units
  • Mobile artillery should attack enemies (instead of changing their mind every second)
  • Surplus engineers should reassess what they do periodically instead of assisting the same factory
  • Minor improvements to building and upgrade decisions to deal with mass overflow and power stall
  • SMD can now be built in response to a nuke threat
  • AI will now stop ecoing if it detects certain experimental threats
  • Various other bug fixes and smaller tweaks to the AI

See 3.34.3 - 3.36.6 for details of the changes and the journey I went through getting an alternative pathfinding logic to work.

M27AI developer; Devlog and more general AI development guide:


v13 Update:
My AI should finally have a chance (albeit a small one) on water based maps. Previously, it would ignore naval units (meaning they'd only die if they happened to get within firing range of a unit). It'd also assume it could send land units to attack the enemy base meaning on island maps it'd produce way too many tanks that would do nothing.

Now, it should try and deal with enemy naval threats, while also focusing on building amphibious and hover land units (although it still doesn't try to build any naval units).

Various misc changes and bug fixes, including:

  • Fixed hard-crash when sera sniper bots were built
  • Improved engineer logic for nearby enemies
  • Slightly less suicidal ACU behaviour (but only when it feels life has meaning)
  • Engineers are less likely to block units in the base when they have nothing left to do
  • Introduced fixes for the pathfinding on several maps where the new logic was giving incorrect results.

M27AI developer; Devlog and more general AI development guide:


Gave this AI a try and it's quite a challenge! It still tends to overextend a bit with its com and also seems to clump up its tanks, but if this is how it is now then I'm excited to see how it will be in the next few updates.


Thanks for the feedback, and glad it's providing a challenge! Do you have a replay that shows the tank clumping issue? It's probably just its normal behaviour but figured it'd be good to confirm (depends how bad the clumping was/what units).

New version will be up once an issue with the client preventing uploads is resolved, but I double-down on the ACU focused gameplay so will probably still suffer with ACU overextending (it just wont be as suicidal to do in the mid-game in the next version)

M27AI developer; Devlog and more general AI development guide:


v14 Update:
I decided to take on board feedback from a number of people that the AI is too aggressive with the ACU and builds lots of land scouts, and so this version my ACU is even more aggressive and builds even more land scouts!
Also introduced a new suicide function (congrats if you manage to trigger this without looking at the code - the AI gives its first voice message if you make it commit suicide).

Summary of changes:

  • ACU will now sometimes get upgrades other than gun
  • New 'all-in' strategy where my ACU charges at the enemy
  • Mobile shields will now be built and used
  • More land scouts built
  • Improved logic for dealing with enemy bombers
  • ACU will now consider Ctrl-King itself
  • Various bug fixes and tweaks

M27AI developer; Devlog and more general AI development guide:


@maudlin27 said in AI Development Guide and M27AI v14 Devlog:

ACU will now consider Ctrl-King itself

How does it evaluate this in practice? 🙂

edit: I just noticed the text above that it is a 'secret'.

A work of art is never finished, merely abandoned


Really interesting document. I look forward to seeing this grow.

A couple of things I didnt find (I may have missed):

  1. Do you have any data on what % of (a typical) AI's time is spent in Pathfinding, Build Conditions etc?

Theres a fair bit of talk of CPU performance but I didnt see any direct evidence of what causes the slowness. While its great to have optimal functions knowing where to direct attention (low hanging fruit!) is a good idea.

  1. Do you intend to test non standard game settings e.g 5/10 minute no rush or disabled units?

1 - Re % of an AI's time taken on different areas, It will vary depending on the AI and the approach taken, although at a high level I'd expect pathfinding to take up a lot of time at the start of game, and build conditions to take up minimal time throughout the game.

For example with pathfinding, for a while my AI would calculate if it could path somewhere as and when it needed to (and then record the result so it could refer to later), but more recently it will do the calculations up-front, which is consistent with the approach of the other AI I'm aware. Times taken can vary dramatically - e.g. when Balthazar was testing their pathfinding logic, I think the slowest time they came across was on Alaska (which I'm guessing was an 81km map) where it took more than 5m. Softles mentioned their pathfinding after optimisation is down to 0.4s on smallest maps. Map size has a big impact though, since an 81x81km map is 262 times the size of a 5km map, so if you do things to the same level of accuracy the time taken will skyrocket.

Therefore pathfinding is largely a 1-off cost at the start of the game (where it's more acceptable to have a slight delay before the game actually starts), although there'll still be some overhead later on (e.g. if trying to calculate a safe path to use - I dont use this logic at the moment so can't comment on how much time it takes).

The most useful function for working out the CPU performance impact is GetSystemTimeSecondsOnlyForProfileUse()
If you compare the result before and after a 'heavy duty' function you can get an indication of how long that function takes (although the figure isn't that reliable).

In the latest version I'm working on I'll be including lots of comments and profiler outputs from some profiling I did of my own AI in an effort to improve its CPU performance, and the code for this as well as code Softles recently helpfully shared on the AI discord for profiling will be included as part of the AI.

As a very rough guide though, anything that is running >10k times in a single tick needs to be streamlined to avoid a performance impact. Simple checks like if a variable is true or false take up no noticeable time (you'd need to be checking millions of times in a tick I'd have thought to impact things), while more involved checks such as getting all units of a particular category within a certain distance of a point on the map will take far longer.

Examples of things that can end up overloading a tick could be carrying out logic on every part of the map (e.g. calculating reclaim), or recursive logic (e.g. in v14 and earlier I'd recursively look for units around an existing unit, and then units around those, and so on, in order to group them into an 'army' to be dealt with).

To give a rough idea of the relative weightings for M27 (other AI will be different) for different aspects of the AI, the following benchmarks are for the total time taken in the first 10m of a 3v3 M27AI game on a 10km map (WIP v15):

  • Determining pathing at the start of the game c.4.5s
  • telling platoons what to do 8.5s
  • threat detection logic (identify enemy threats, selecting units to deal with the threat) 3.7s
  • checking reclaim on the map 3.3s
  • managing air units 2.6s
  • managing engineers (build conditions and orders including reclaim) 1.7s
  • Deciding what to build for factories 0.1s.
    As part of this, I have a function called 200k times that took 0.000s in total, and another function called 165 times that took 0.36s.

The times are a relative guide, not absolute, as the GetSystemTimeSecondsOnlyForProfileUse() isn't that accurate, and depending on how its used it won't factor in time taken by the wider game engine as a consequence of the AI's code.

2 - Not in the immediate future, but probably once I've achieved some other goals. I think Softles may be planning an AI tournament with norush at some point so that might prompt me to have a look at it!

M27AI developer; Devlog and more general AI development guide:


v15 Update:
Focus of this release was (CPU) optimisation, so the major changes are 'behind the scenes'. It also means in some areas (primarily threat detection) my ACU unfortunately is a bit more stupid than before, as I didn't feel I could justify the increased CPU load caused by a more accurate method.

  • Implemented new profilers (both my own, and one Softles kindly provided) to help identify high usage functions
  • Rewrote most of the reclaim logic to improve performance (significant reduction in game stuttering, although still worse than I'd like)
  • Optimisation of a number of other functions to significantly reduce time taken
  • Improved SMD logic (including fixing a bug that meant SMD was never built) - AI is now much more likely to have a loaded SMD ready before a nuke hits.
  • Tweaks to how much power and energy storage is built to reduce tendency to over-build power and to ensure the ACU can deal 15k damage with overcharge late-game
  • Various bugfixes (notable ones being a bug with ACU escorts that would result in lots of errors appearing in the log, and an issue that caused escorts/assisting platoons to sometimes go to the wrong location)

M27AI developer; Devlog and more general AI development guide:


@maudlin27 said in AI Development Guide and M27AI v15 Devlog:

Rewrote most of the reclaim logic to improve performance (significant reduction in game stuttering, although still worse than I'd like)

I'm not sure if it will help but I recently re-wrote AutoReclaim (dwm) as "AutoReclaim (splitice)" for more performant reclaims (for T!-3 engineering type towers).


I also tried a 2v2 (far slots) on Burial Mounds and noted many issues (including a general lack of awareness of the no unit paths and lack of serious economic growth). This was on v14. I think I'll re-asses though when this gets more mature.