ScriptAIGoals

gtw 6-17-05

Lua functions for scripting the AI in the mission scripts:

*******************************************************************************
- ClearAIGoals( team )

Removes all previous AI goals for this team.  You should call this before you set the first goals for a team, since teams 1, 2, and 3
start out with a default Conquest goal.

for example:
ClearAIGoals( 1 )


*******************************************************************************
- DeleteAIGoal( goalHandle )

Remove the specified goal.  goalHandle is the handle returned by AddAIGoal.

for example:
DeleteAIGoal( handle )


*******************************************************************************
int AddAIGoal( team, goaltype, weight )
int AddAIGoal( team, goaltype, weight, target1 )
int AddAIGoal( team, goaltype, weight, target1, target2 )

Add an AI goal for this team.  Returns a handle to the new goal.


goaltype can be one of these:

 "Conquest" - plays like BF1 on the command posts
                      AddAIGoal( team, "Conquest", weight );

 "Deathmatch" - just kill everyone
                      AddAIGoal( team, "Deathmatch", weight );

 "Destroy" - destroy the target (a gameobject pointer, or a character index)
                     AddAIGoal( team, "Destroy", weight, gameObjectPtr );
                     AddAIGoal( team, "Destroy", weight, integerChrIdx );

 "Defend" - defend the target (a gameobject pointer, or a character index)
                     AddAIGoal( team, "Defend", weight, gameObjectPtr );
                     AddAIGoal( team, "Defend", weight, integerChrIdx );

 "CTFOffense" - try to get the specified flag and bring it back to the specified region
                     AddAIGoal( team, "CTFOffense", weight, regionName );
                     AddAIGoal( team, "CTFOffense", weight, regionName, flagPtr );

 "CTFDefense" - protect the specified flag, and hunt down and return it when its stolen
                     AddAIGoal( team, "CTFDefense", weight );
                     AddAIGoal( team, "CTFDefense", weight, flagPtr );

 "Follow" - follow around the target (like defend, but uses a tight follow)
                     AddAIGoal( team, "Follow", weight, gameObjectPtr);


Weight is a relative weight for this goal.  Since you can specify more than one goal for a team at a time, this specifies how the guys are divided. 
A goal with weight 2 will get twice as many guys as the goal with weight 1. 
The size of the numbers doesn't matter and they don't have to add up to 100 or anything.
 
The goals for Conquest and Deathmatch don't require a target, since they figure that out automatically. 
When you give a Defend, Destroy or CTF goal, it has to know what object you want to atttack or protect.

for example:

 ClearAIGoals( 1 )
 AddAIGoal( 1, "CTFOffense", 50, GetRegionName(team1captureregion) )
 AddAIGoal( 1, "CTFDefense", 50 )
 ClearAIGoals( 2 )
 AddAIGoal( 2, "CTFOffense", 25, GetRegionName(team2captureregion) )
 AddAIGoal( 2, "CTFDefense", 50 )
 AddAIGoal( 2, "Destroy", 25, sheldBunkerObjPtr )

This will set up a CTF game with half of team 1's guys on offense and half on defense. 
Team 2 will have half their guys on defense, a quarter on offense, and a quarter trying to destroy the shield bunker (a GameObject).  Once they kill that it will automatically rebalance the remaining goals so that 1/3 of the guys are on ctf offense and 2/3 are on ctf defense.


Or you can specify flags:

 ClearAIGoals( 1 )
 AddAIGoal( 1, "CTFOffense", 30, GetRegionName(team1captureregion), team2FlagAPtr )
 AddAIGoal( 1, "CTFOffense", 30, GetRegionName(team1captureregion), team2FlagBPtr )
 AddAIGoal( 1, "CTFDefense", 40, team1FlagCPtr )

This will send some guys to get 'FlagA' and return it to 'team1captureregion', some other guys to get 'FlagB' and return it there, and the other 40% will defend their own flagC.


Destroy and Defend can specify GameObjects or Character indices:

 ClearAIGoals( 1 )
 AddAIGoal( 1, "Defend", 100, 0 )
 ClearAIGoals( 2 )
 AddAIGoal( 2, "Destroy", 50, 0 )
 AddAIGoal( 2, "Destroy", 50, atatPtr )
 
This sets up all of team 1 to defend Character(0), which is the player. 
Here you could also put the index of a special character (ie Leia or anyone) you spawn in somewhere. 
Team 2 is set to kill Character(0) (the player again) and also destroy the ATAT specified by atatPtr.