AI script editing help

It doesn't seem THAT hard to do, so I wonder why there's no tutorial out about it yet. And since it isn't, I need the help of some people to explain stuff to me about what exactly I'm doing when I try to edit the scripts through notepad.

We'll break it down with an example from the MPQ.//

============================================================================
// Orc 05 -- light blue player -- AI Script
//============================================================================

globals
player user = Player(3)
endglobals

Translation: I don't know. This script controls player 10, and the human player is player 4, not 3. So why is 3 the player user?

//============================================================================
// main
//============================================================================

function main takes nothing returns nothing
call CampaignAI(MOON_WELL,null)
call SetReplacements(2,2,4)

Translation: No clue.

// don't harvest immediately
set campaign_wood_peons = 0

call SetBuildUnit( 1, WISP )
call SetBuildUnit( 1, ELF_ALTAR )
call SetBuildUnit( 1, HUNTERS_HALL )
call SetBuildUnit( 8, WISP )

call SetBuildUnitEx( 3,3,3, ANCIENT_PROTECT )

call CampaignDefender( EASY, 3, ARCHER )
call CampaignDefender( EASY, 2, HUNTRESS )

call SetBuildUpgrEx( 0,0,1, UPG_BLESSING )

Translation: I assume this gives the initial build for the player... a wisp, altar, huntress hall, 8 more wisps, 3 APs, 3 archers and 2 huntresses (if on easy), and a nature's blessing upgrade if playing on hard.

I'm assuming that something like "call SetBuildUnit( 1, HUNTERS_HALL )" means build one hunter's hall. I'm assuming that something like call SetBuildUnit( x,y,z, ARCHER ) means that you'd build x archers on easy, y on medium, and z on hard.

// wait to start harvesting
call WaitForSignal()
set campaign_wood_peons = 0

// wait to start attack waves
call WaitForSignal()

Translation: No clue... obviously, the titles of each section tells you what each script does, but I don't know exactly how the script works.

//*** WAVE 1 ***
call InitAssaultGroup()
call CampaignAttackerEx( 3,3,5, ARCHER )
call CampaignAttackerEx( 1,1,1, ANCIENT_PROTECT )
call SuicideOnPlayerEx(M6,M6,M6,user)

call SetBuildUpgrEx( 0,0,1, UPG_STR_MOON )
call SetBuildUpgrEx( 1,1,1, UPG_ULTRAVISION )

Translation: Make an attack group, and add either 3 or 5 archers (depending which thing is chosen) and one ancient protector. Then attack with those on the player (but what does M6 mean?)... then upgrade Ultravision and moon strength if on hard.

//*** WAVE 2 ***
call InitAssaultGroup()
call CampaignAttackerEx( 3,3,4, ARCHER )
call CampaignAttackerEx( 2,2,3, ANCIENT_PROTECT )
call SuicideOnPlayerEx(M8,M8,M7,user)

call SetBuildUpgrEx( 0,0,1, UPG_MOON_ARMOR )
call SetBuildUpgrEx( 0,0,1, UPG_GLAIVE )

Translation: By now, it's all routine. Build an attack group with 3 archers (4 on hard), 2 APs (3 on hard), and attack... M8? M7? What do those mean?

So.. as you can see, it's really not that difficult, but I'm having trouble figuring out how exactly some things work.

I realize there's a lot more I can do with these scripts.. but that's for another day. Basically, my goal right now is to edit this one to make a functional attack script for my campaign. But some of the units.. I don't have names for. Like how do I enter a Druid of the Claw into the script? Druid_of_claw? Where can I find all of these?

globals
player user = Player(3)
endglobals

Translation: I don't know. This script controls player 10, and the human player is player 4, not 3. So why is 3 the player user?

Often in programming, the indexing of a list object (in this case, a list of players) will start with 0. I assume that Players(0) would be equal to the human user (Player 1) if this is indeed the case. It seems like it would be possible to write an AI script for the human player to run as well.

globals
player user = Player(3)
endglobals

Player(3) is Player 4 in game. Player(0) is Player 1, etc...

function main takes nothing returns nothing
call CampaignAI(MOON_WELL,null)
call SetReplacements(2,2,4)

I don't know what SetReplacements does, but CampaignAI tells the computer to build moon wells when it needs more food, and sets some default variables (See common.ai for more info)


// don't harvest immediately
set campaign_wood_peons = 0

call SetBuildUnit( 1, WISP )
call SetBuildUnit( 1, ELF_ALTAR )
call SetBuildUnit( 1, HUNTERS_HALL )
call SetBuildUnit( 8, WISP )

call SetBuildUnitEx( 3,3,3, ANCIENT_PROTECT )

call CampaignDefender( EASY, 3, ARCHER )
call CampaignDefender( EASY, 2, HUNTRESS )

call SetBuildUpgrEx( 0,0,1, UPG_BLESSING )


Exactly as you said, these tell the computer to build stuff.


call WaitForSignal()
set campaign_wood_peons = 0

// wait to start attack waves
call WaitForSignal()

These are a little more interesting... The AI waits for the actual map to send an AI Command (It's in the triggers somewhere). Guess it's used to keep the ai from doing stuff until it's supposed to.


call InitAssaultGroup()
call CampaignAttackerEx( 3,3,5, ARCHER )
call CampaignAttackerEx( 1,1,1, ANCIENT_PROTECT )
call SuicideOnPlayerEx(M6,M6,M6,user)

call SetBuildUpgrEx( 0,0,1, UPG_STR_MOON )
call SetBuildUpgrEx( 1,1,1, UPG_ULTRAVISION )


Yes, this tells them to attack and get upgrades. M6 is defined in comman.ai as 60*6 i think. I think it means attack in 6 minutes or attack every 6 minutes.

Hope this helps. I'll see if i can write a good example ai and i'll post it.

One more hint: The "Ex" at some commands means the command is for levels with different difficulties. If "Ex" is removed (i.e. CallCampaignAttacker vs. CallCampaignAttackerEx), then the number and use of the following variables differ (see common.ai and the ais for human lvl 7).