How to: Creating custom unit scripts for Sorian AI

[Uveso]

Hello Modders!

Creating scripts for the Sorian AI is very simple.
You only need to create a textfile filled with an Array. Thats all.


First we need to create a new folder and .lua file inside your mod:

Create a new directory inside you modfolder named "lua".
Inside the Lua folder create a new directory named "customunits".

Now create an empty textfile inside "customunits" and name it "test.lua".

The new file (test.lua) should now be in this location:

Code: Select all

C:\Users\YOURNAME\Documents\My Games\Gas Powered Games\Supreme Commander Forged Alliance\Mods\YOURMOD\lua\CustomUnits\test.lua

Now we need to fill this test.lua file with an Array that is holding the unit ID with Buildplatoon.

Let's say we have a new Tech 1 GroundDefense with the Unit ID "ueb0815" and we want a 30% build chance.

Then the Array will look like this:

Code: Select all

UnitList = {

   T1GroundDefense = {
      UEF = {'ueb0815', 30},
   },

}

UnitList is the mainarray for all units. (Ingame and customunits)
T1GroundDefense means, if the AI will build a Tech 1 Grounddefense it will use all units saved inside the subarray "T1GroundDefense ". (Ingame and customunits)
UEF = {'ueb0815', 30}, This unit can only be build from UEF, has the unitID "ueb0815", and 30% of all T1GroundDefense builded by AI will be unit "ueb0815".
If you set 30 to 100, then the AI will only build unit "ueb0815" as T1GroundDefense.


You can fill up the test.lua file with several builodplatoons and units. First a list, what you should not do:

This won't work: ( 2 or more units in a buildplatoon for the same faction)

Code: Select all

UnitList = {
    T1GroundDefense = {
        Cybran = {'brmt1expdt2', 50}, -- Name: Pen mk2 (Experimental Point Defense)
        Cybran = {'brpt1pd', 50}, -- Name: Hethula-Uttaus (Heavy Point Defense)
        Cybran = {'brnt2pd2', 50}, -- Name: Ace mk.2 (Heavy Point Defense)
    },
}


This won't work: (more then one unique buildplatoon (like 2 x T1GroundDefense) in the same file)

Code: Select all

UnitList = {
    T1GroundDefense = {
        Cybran = {'brmt1expdt2', 50}, -- Name: Pen mk2 (Experimental Point Defense)
        Seraphim = {'brpt1pd', 50}, -- Name: Hethula-Uttaus (Heavy Point Defense)
    },
    T1GroundDefense = {
        UEF = {'brnt2pd2', 50}, -- Name: Ace mk.2 (Heavy Point Defense)
        Cybran = {'brmt2pd', 50}, -- Name: Sabertooth (Heavy Point Defense)
    },
}


But if you use different platoons, you can fill up the file as much as you want:

Code: Select all

UnitList = {
    T1GroundDefense = {
        Cybran = {'brmt1expdt2', 50}, -- Name: Pen mk2 (Experimental Point Defense)
        Aeon = {'brot1hpd', 50}, -- Name: Zpyker (Heavy Point Defense)
        Seraphim = {'brpt1pd', 50}, -- Name: Hethula-Uttaus (Heavy Point Defense)
    },
    T1LandDFTank = {
        UEF = {'brnt1htt3', 50}, -- Name: Predator mk.3 (Heavy Tank)
        Cybran = {'brmt1at', 50}, -- Name: Roach (Assault Tank)
        Aeon = {'brot1mt', 50}, -- Name: Lintea (Medium Tank)
        Seraphim = {'brpt1asta', 50}, -- Name: Hethistle-ve (Assault Tank)
    },
    T2ShieldDefense = {
        Cybran = {'qrb4208', 30}, -- ED6: Gilmore (Village Shield Generator)
    },
    T3ShieldDefense = {
        UEF = {'qeb4408', 55}, -- UHSD Puls: Cochran (Village Shield Generator)
        Aeon = {'qab4408', 55}, -- Cashton (Village Shield Generator)
        Seraphim = {'qsb4408', 55}, -- Atha Ythisioz (Village Shield Generator)
    },
}


And you can put up to 5 units in each platoon. For every faction one Unit:

Code: Select all

UnitList = {
    T4LandExperimental2 = {
        UEF = {'qeb4410', 50}, -- EXHSD Puls: Bucksport (Metropolis Shield Generator)
        Cybran = {'qrb4410', 50}, -- ED8: Bovill (Metropolis Shield Generator)
        Aeon = {'qab4410', 50}, -- Jenks (Metropolis Shield Generator)
        Seraphim = {'qsb4410', 50}, -- Athayii Ythisioz (Metropolis Shield Generator)
        Nomads = {'qnb4410', 50}, -- Wagos (Metropolis Shield Generator)
    },
}


And these are all buildplatoons that will work with sorian and normal AI:

Code: Select all

MassStorage
EnergyStorage
Wall

T1LandFactory
T1SeaFactory
T1AirFactory
T1AirFighter
T1AirBomber
T1Gunship
T1AirTransport
T1EnergyProduction
T1MassCreation
T1Resource
T1Radar
T1HydroCarbon
T1AADefense
T1GroundDefense
T1NavalDefense
T1Sonar
T1SeaSub
T1SeaFrigate

T2LandFactory
T2SeaFactory
T2AirFactory
T2FighterBomber
T2AirGunship
T2AirTorpedoBomber
T2AirTransport
T2StrategicMissile
T2ShieldDefense
T2RadarJammer
T2EngineerSupport
T2MissileDefense
T2GroundDefense
T2AADefense
T2Artillery
T2ShieldDefense
T2Radar
T2RadarJammer
T2Resource
T2EnergyProduction
T2AirStagingPlatform
T2NavalDefense
T2Sonar
T2SeaDestroyer
T2SeaCruiser
T2SubKiller
T2ShieldBoat
T2CounterIntelBoat

T3LandFactory
T3AirFactory
T3AirFighter
T3AirBomber
T3AirGunship
T3TorpedoBomber
T3AirTransport
T3QuantumGate
T3SeaFactory
T3SeaBattleship
T3SeaNukeSub
T3SeaCarrier
T3MissileBoat
T3SubKiller
T3Battlecruiser
T3MassCreation
T3Artillery
T3RapidArtillery
T3EnergyProduction
T3AADefense
T3GroundDefense
T3StrategicMissile
T3StrategicMissileDefense
T3MassExtraction
T3ShieldDefense
T3Radar
T3NavalDefense
T3Sonar
T3Optics

T4LandExperimental1
T4LandExperimental2
T4LandExperimental3 (only cybran)
T4AirExperimental1
T4SeaExperimental1
T4EconExperimental (only aeon)
T4SatelliteExperimental (only UEF)
T4Artillery


To create those Buildplatoon arrays you can use my private unit debugger mod.
If you load the game with the debuggermod and your unitmod; simply press [SHIFT]+[a] ingame.
You will see a list of all units (in copy+paste ready array style) inside the debugwindow [F9] or the game.log.

It will look like this:

Code: Select all

INFO: Uveso Debugger: [UnitDebug.lua 714] - Unit UEB0001 veryfied, has Icon but no AI Support. Name:(Hammer) (Tech 1 Power Defence)
INFO: T1GroundDefense = {
INFO:         UEF = {'UEB0001', 50}, -- Name: Hammer(Tech 1 Power Defence)
INFO: },

Remove the "INFO: ", then you can copy this to your "customunits\test.lua"

You can use as filename what you want. The game will load all .lua files from the "customunits" folder.

Download debuggermod:
http://faforever.uveso.de/forum/UvesoDebuggerV49.zip

Greetings, Uveso.

[HUSSAR]

does anyone know how to tell AI to upgrade existing FA buildings into new modded units? E.g. ExMex mod adds T4 mex extractors but AI does not build T4 mex from T3 mex extractors even though human player can upgrade them.

[Sprouto]

Without getting too detailed, you'd likely have to hook the unit that is going to be upgraded into your new unit, so that the original unit is aware that it can be upgraded into your new unit. The kind of additional data required can be found in any of the units which can already be upgraded into something else. The new unit may also require some additional data in the form of the UpgradesFrom field.

Secondly, with Sorian, you'll need to have a custom builder that will;

a) Detect that there are un-upgraded units in the pool. (Done with an appropriate builder condition)
b) Issue the necessary upgrade command to them.

As I recall, Sorian manages extractor upgrades thru this kind of mechanism. You can use that as an example of how it's done.

[Resin_Smoker]

This is cool and all but all you can do is modify the existing Buildplatoon's. While this "should" work, in my experience it can lead to some strange results especially if more than one mod attempts to overwrite the same Buildplatoon values. What is needed is a way to "add" new Buildplatoon types that can coexist with the types currently in play. Back in the day, Domino had written scripts that allowed just that and more. Too bad no one ever used it but me.

[Uveso]

Here is an example how to make AI BuilderGroups and StructureUpgradeTemplates for the Black Ops Hydrocarbon Power Plants:

https://github.com/aeoncleanse/Mods/pull/255/files

[Resin_Smoker]

Here is an example how to make AI BuilderGroups and StructureUpgradeTemplates for the Black Ops Hydrocarbon Power Plants:

https://github.com/aeoncleanse/Mods/pull/255/files

I realize... did this at one time for 4DC.
My prior comment was more of a why this is not done.

Note: Aeoncleanse made a few units for use with 4DC about the same time the he created the script for that mod.

[Uveso]

I guess i know what you mean.

The next version will inject the "BuilderGroupName" directly into the AIBase-Templates.

So you can add comlete new builders to "All" base templates without changing any of them.

[Edit]
This will be done by hooking the function AddGlobalBaseTemplate inside AIAddBuilderTable.lua
(coming soon )

[Uveso]

This is the hook to add a Platoon builder to the AIBaseTemplates (like SorianMainRush etc.)
(Can be used by multiple mods, the hook is non destructive)

AIAddBuilderTable.lua

Code: Select all

local OLDAddGlobalBaseTemplate = AddGlobalBaseTemplate
function AddGlobalBaseTemplate(aiBrain, locationType, baseBuilderName)
    AddGlobalBuilderGroup(aiBrain, locationType, 'NuclearRepulsorShields')
    OLDAddGlobalBaseTemplate(aiBrain, locationType, baseBuilderName)
end


In this case the builder "NuclearRepulsorShields" will be added to the base template.
Also if the game starts a new location manager, this hook will also add the builder to any expansion base template.