-
Notifications
You must be signed in to change notification settings - Fork 111
ai_scripting_system_specs
\
AI Scripting System Specs:
\
\
1 Overview of scripting system 1
3.2 Special Operation Commands 5
5 Scaling the Number of Ships 7
6 Other Scripting System Details 7
6.1 Detecting Ships In a Volume 7
6.2 Debug Prints From the Script 7
\
\
This document specs out a number of elements of the AI scripting system to be used in Homeworld’s single player missions. Here is how the scripting system will work, as I understand it:
\
-
Groups of ships are laid out in the Mission Editor and assigned Team ID’s.
-
There is a master script for the entire mission. Inside this script are includes which tell the master script which individual script files to use for each Team ID.
-
Each Team ID script file is a finite state machine which works as follows:
-
High-level commands are used to issue intelligent orders to the team. These commands ‘bundle’ significant AI with them – e.g. an attack command could use all sorts of low-level moves and tactics, but the script only calls “Attack.” This allows the script to stay fairly high-level (and manageable) and puts the burden on the computer player AI to be smart about how the orders are carried out.
-
Each command is given one or more parameters. These parameters are often things specified in the mission layout such as AI points or volumes, but can also be script-only values like distances and attack modifiers (see Falko’s Mission Modifiers).
-
Essentially, while executing a command, the script has relinquished control of the team to the computer player AI.
-
A number of “out conditions” are defined in the script which tell the computer player under what circumstances to transfer control back to the script.
-
Once an out condition is hit the script tells the team what to do next.
-
In addition to the states and commands, the scripting system supports messaging between scripts so that teams can ‘communicate’ intelligently in a mission.
-
When a script is finished it can be restarted using various conditions in the master script and ships that are built by the computer player during the level.
\
This section talks about all the things we need to do in the Master Script. This is the script that essentially ‘controls’ the entire mission.
\
The master script will use an #include command to tell the game where to look for the separate AI scripts used in a mission.
\
Example:
\
<PatrolTeam1> #include "PatrolTeam1.script"
\
Here PatrolTeam1 is the team ID and PatrolTeam1.script is the script file being included (duh ).
\
Since the time required to create, tune, and debug the AI scripts will probably be fairly long, we would like to get as much use out of them as possible. What this means for a mission is that we would like the ability to restart an AI script that has become dormant (because that team has been totally destroyed). This would mean that the computer player would inject new ships built during the mission into the AI script and the script would be restarted.
\
However to make this restarting behavior more intelligent, we would like the ability to define the conditions for how each script is restarted. Most likely, this would be defined in the ‘master’ script for the entire mission. Here are some examples of restarting conditions:
\
-
Script inactivity for a certain amount of time (e.g. script has been dormant for >5 mins)
-
Player has/hasn’t entered a certain volume
-
Whether another script has started/ended
\
We would also like the ability to combine these conditions – i.e. “Script <Alpha9> inactive 5mins AND Volume12 NotPenetrated.”
\
In addition to simply restarting an AI script we would like to be able to set some modifiers on how that script is restarted – this way we can do things like make a patrol more belligerent the second time it’s restarted (like a player might do who’s angry at losing his patrol). A simple way to do this might be to globally increment the MModifier setting on all commands in the script when it is restarted.
\
To tell the computer player which ships to restart a script with, we will use the GetShips command with the alternative ship type parameter. This lets us tell the computer player what ship types we would like used in the script (and weight them!), but also give it alternatives if the first choice is not available.
\
The master script seems like the most likely place to define the ‘win conditions’ for the mission. These are the conditions that the player has to satisfy to win the mission and move on.
\
In addition to simply setting the win conditions, we also have to be able to check to see if these conditions have been satisfied and if they are, let the game know so the game can let the player know that he/she has satisfied a condition. The way this will happen is via a text display detailed in the upcoming single player design update.
\
At this point in time we don’t know all of the win conditions we will want in the final game. Some basic ones we do know are:
\
<Team ID> dies
\
A specific team has died (e.g. <Carrier1> dies). Lets us designate specific targets for the player to take out as mission objectives.
Countships <,>,= <x>%
Counts the ships in the world to see if they are <, > or = to a specified % of the original ships in the world.
\
Some missions may have a timer or other “lose conditions” whereby the player loses the mission if they are satisfied. Thus the script will have to check for these and communicate with the game if these conditions are fulfilled, just like the win conditions.
\
The individual team scripts will set a level of difficulty for themselves (see section 3.1 at the bottom of the table), but the master script will also set a level of difficulty for any ships built by the computer AI player and not used by any teams. In other words, any ships controlled by the computer AI player and not by a script will use the global difficulty level set in the master script.
\
This table lists the high-level commands that can be called in the scripts, along with the parameters and out conditions.
\
Command
Description & Parameters
Out Conditions
Reconnaissance
Descr: See Falko’s computer player doc
\
Parameters:
-
AI points, path, or volumeto perform the reconnaissance around/along/in
-
Radius or Volume around each point
-
“Success rate” modifier – how good the recon ship is at finding enemies.
\
-
Finds ships (returns a result)
-
Timer expires
-
Fuel conditions
Recon <AI point/Path/Volume> <Radius> <Success rate> <MModifier>^^1^^
Recon_Harass
Descr: See Falko’s computer player doc. In addition, recon_harass should attack armed ships.
\
Parameters:
-
AI points, path, or volumeto perform the recon_harass around/along/in
-
Radius or Volume around each point
-
“Success rate” modifier – how good the recon ship is at finding enemies.
\
-
Combat conditions
-
Timer expires
-
Fuel conditions
Recon_Harass <AI point/Path/Volume> <Radius> <Success rate> <MModifier>
Guard
Descr: See Falko’s computer player doc
\
Parameters:
- ShipID to be guarded
\
-
Combat conditions
-
Fuel conditions
-
Guard ship gets destroyed
Guard <ShipID> <Mmodifier>
Patrol
Descr: See Falko’s computer player doc
\
Parameters:
-
Path to patrol along
-
Radius to attack within while patrolling
\
-
Combat conditions
-
Fuel conditions
-
Timer expires
Patrol <Path> <Radius> <MModifier>
Harass
Descr: See Falko’s computer player doc
\
Parameters:
- ShipID to be harassed
\
-
Combat conditions
-
Fuel conditions
Harass <ShipID> <Mmodifier>
Attack
Descr: See Falko’s computer player doc
\
Parameters:
- ShipID to be attacked
\
-
Combat conditions
-
Fuel conditions
Attack <ShipID> <Mmodifier>
Defend
Descr: See Falko’s computer player doc
\
Parameters:
-
ShipID or Volume to be defended
-
Combat conditions
-
Fuel conditions
-
Timer expires
Defend <ShipID/Volume> <MModifier>
Retreat
Descr: Ship(s) retreat either to a fixed AI point OR to a certain distance away from their current location, using an AI point as a heading. Also, multiple AI points can be specified for the latter condition – the AI will choose randomly among these for a more varied heading. Any support ships in the group will automatically heal/refuel wounded ships or ships that are low on fuel.
\
It should be noted that the AI point could be outside the game world. This would allow us to have missions where the player’s win conditions are such that they don’t have to kill every guy on the map. Remaining enemies could retreat to a location outside the game world and be purged. To allow for some more interesting retreating, a parameter of % derelict is supported so that a certain % of the team can be left behind, derelict, for the player to salvage/capture.
\
Parameters:
-
AI pointto retreat to
-
Distanceto move away & *AI point(s)*for heading
-
% Derelict - % of ships to leave behind
\
-
Retreat point is reached (can further specify the % of ships that have to arrive to meet this condition)
-
Retreat point is not reached (can also specify the % of ships)
-
Timer expires
-
Fuel condition
Retreat <AI Point/Distance + AI Point(s)> <MModifier>
Harvest
Descr: Command given to a resource collector.
\
Parameters:
-
Resource ID to harvest
-
Volumeto harvest in
-
ShipID to dock with when full
-
Pathto move along between resources and dropoff point.
\
- All resources are harvested
Harvest <ResourceID/Volume> <Path> <ShipID>
Support
Descr: Command given to a support ship. Tells the support ship to rendezvous with a specific team and repair and refuel that team’s ships.
\
We pass the support ship the ID(s) of the teams to be supported. The ships to be supported receive a message to move to meet the support ship. We pass the teams to be supported an AI point to fly to. The support ships meets them at this point. OR, we pass them a distance to fly away from their current location, using one or more AI points as a heading (a la Retreat command). If the latter is used, the Support ship knows where their destination is and meets them there.
\
Parameters:
-
ShipIDto support**
-
AI Pointto rendezvous at
-
Distanceto move away & *AI point(s)*for heading
-
Teams to be supported have died (all must die – support will still occur if one guy is alive)
-
Support successful: all teams are repaired and refueled.
-
Support ship doesn’t reach the destination.
-
Teams to be supported don’t reach the destination.
-
Teams to be supported run out of fuel along the way.
-
Timer expires
Support <ShipID> <AI Point/Distance + AI Point(s)> <MModifier>
Reinforce
Descr: This command takes ships and sends them to reinforce ships in battle. Let’s take an example using Group A as the ships already in combat and Group B as the reinforcements. Group B receives a message to reinforce Group A. They proceed to Group A’s current destination and are given attack orders against Group A’s current targets.
\
Parameters:
-
ShipID to reinforce
-
Combat conditions
-
Fuel conditions (Group B)
-
Timer expires en route
-
Group B fails to engage the enemy (for whatever reason)
Reinforce <ShipID> <MModifier>
Move
Descr: This command tells a team to move to an AI point along a path, or to another ship (using the MoveNearTo command already in the game). It includes a modifier to maxvelocity so that we can tell ships to move slower than they normally would.
\
Parameters:
-
AI Point or Path or Ship ID
-
% Modifier to maxvelocity
-
Timer expires
-
Team reaches destination
Move <AI Point/Path> <%MaxVelocity> <MModifier>
Dock
Descr: Dock with a specified ship
\
Parameters:
- Ship ID
\
-
Timer expires
-
Team completes docking
Dock <Ship ID> <MModifier>
\
\
\
\
\
\
\
Command
Description & Parameters
Out Conditions
This section will be filled in later when all the special operations are spec’d out (design update on this subject due by the end of M13).
\
\
RGB Values
Descr: This sets the RGB values for the base and stripe colour for the team ID controlled by the script.
\
Parameters:
- RGB values
\
- N/A
Set BaseColour = <R>, <G>, <B>
Set StripeColour = <R>, <G>, <B>
Difficulty level
Descr: Sets the difficulty level for the team ID controlled by the script.
\
Parameters:
-
Difficulty level
-
N/A
Set Difficulty = <Difficulty level>
Timers
Descr: Sets (or checks) a timer.
\
Parameters:
-
Timer name
-
Timer value
-
N/A
-
SetTimer <Timer Name> <Timer Value>
-
TimerDone <Timer Name>
Volume Checking
Descr: Checks to see if a volume has been penetrated. See section 6.1 for more details on volume checking.
\
Parameters:
-
Volume name
-
Volume timer
-
Expansion volume radius
\
- N/A
-
CkVolume <Volume Name> <Volume Timer>
-
CkVolume <Volume Name> <Volume Radius>
Scaling Weighting
Descr: Sets the weighting which determines what % of ships this team ID will receive if the ships in the mission are scaled up to account for a larger player fleet. This command is built into the include function.
\
See section 5 for more details on scaling.
\
Parameters:
- % weight
\
- N/A
<Team ID> #include <% weight>, <”Filename.script”>
Win Condition
Descr: Sets the win conditions
\
Parameters:
-
# - specifies the number of the win condition, since there can be more than one.
-
Win condition (this may vary widely based on the requirements of the mission. For now, we only have 2 – see section 2.3).
\
- N/A
Set WinCondition<#> = <Win condition>
Wait
Descr: Waits forever
\
Parameters: None
\
- N/A
Wait
\
\
\
\
\
\
\
\
\
There is a series of generic out conditions specifically related to combat and just about every script file will require these conditions at one time or another.
\
-
Destroy all targets (i.e. the player)
-
100% of the team is destroyed
-
A certain percentage of the team is destroyed
-
A certain percentage of the team is damaged (i.e. there are five ships, all alive but down to 60% of collective health)
-
Enemies retreat
-
Enemy fleet is at a certain percentage of its original size
-
Timer expires
\
All the ships in a team check their health and fuel levels. When the fuel reaches a critical level on any of the ships in the team, say 20%, they will exit the command.
This checks the distance from the team of ships to the item used in the command (e.g. the enemies to attack or the AI point to move to) and prevents the ships from travelling too far. The distance condition can provide an immediate out, prior to any other action being performed in the script.
\
It should be noted that the timer condition here in section 4.4 differs from the timer used in 4.1 - Combat Conditions. The rationale for having two timers is this: certain commands embody multiple actions, including movement and combat (such as the Recon_Harass command). For these commands, we want to be able to set a timer for the first action (the move) as well as for the combat.
\
Since the size of the player’s fleet is unknown to the designers at every point in the game, the AI must account for a fleet which could be larger than anticipated. The way this is handled in the scripting and mission layout is as follows:
\
-
In the mission layout, extra ship ‘slots’ are made (AI points) next to every group of ships that is placed.
-
The AI dynamically scales the number of enemy ships up based on the size of the player’s fleet. There will probably be some equation for this in the AI?
-
The master script contains relative weighting values for each enemy team which tell the AI what percentage of new ships to dump into that group if the ships are being scaled. This lets us do things like add fewer ships to a patrol group and more ships to a reinforcement group.
-
Each group receives only the same type of ships that are already there. Thus a patrol group of Heavy Interceptors will receive only Heavy Interceptors.
\
The AI scripts will often be checking volumes as triggers for various behaviors. However since the player will have numerous ships, detecting a volume penetration is a bit of a tricky business. To handle this, we propose a couple solutions:
\
-
When a volume is penetrated the AI waits for a certain amount of time (timer) and then picks everyone in that volume as the “penetrators.”
-
When a volume is penetrated the AI takes the first penetrator and looks for ships in a volume around him, defined by a tunable radius. This is Darren’s idea, a modification on the original idea of expanding the initial volume.
\
\
Another feature that I have found very useful in writing AI scripts is the ability to perform a print to the debug window. This helps immensely in debugging the scripts and can also let us check to see if various parts of the mission are working without playing through the whole thing. It might also be useful to have a command line switch to turn off the AI script debug prints so that the coders don’t have an extra hard time seeing their own debug messages.
\
1 This is the mission modifier defined in Falko’s document: aggressive, neutral, evasive, suicidal, etc.