Escort Instructions

Oolite contains a lot of commands related to ships with escorts. Not all commands are needed all the times. e.g. when the system adds an escorted ship, all the escorts are already set up.

Adding of mother ship

When a mother ship is added to the universe it is checked if it can have escorts. If yes, the system is examined and a random number of 0, 2, 4 or 6 is subtracted from the maximum escort number. In saver systems it is more likely that escorts are subtracted. When the resulting number is greater than 0 this number of escorts is added as escort with the function setUpEscorts and the escortsAreSetup flag is set.

Adding with setUpEscorts

When the function setUpEscorts is called, it first looks if the escortsAreSetup flag if false. When they were not previously setup, the escorts are set up. They all get an escortAI.plist statemachine and the scanclass and the groupID of the mother.

By default all ships get an escort with role "escort" and only ships with role "police" get an escort with role "wingman".

This default can be overruled by the keys "escort-role" or " escort-ship" in shipData.plist. When a key "escort-role" exist, escorts with this role are chosen and they keep their original role. (this is a bug because the mother will only accept escorts with role "escort"). When a key " escort-ship" exists, a ship with this name is used as escort and they get the role "escort".

When setup is ready they all have a escortAI.plist statemachine and the state itself is set to "FLYING_ESCORT". The initial part in this AI were the escorts are setup is skipped as the escorts are already setup by the system. When you want to give you escorts a custom AI you can redefine this by adding the command: "switchAITo: yourCustomAI.plist" in the ships "launch_actions" in the shipData.plist.

There are two places were a script can use the function setUpEscorts. You can place it in the "launch_actions" of the mothership, or you can put it at the beginning of the ships AI.plist. When you leave it, the system will determine if it will set up the escorts and how many.

Adding escorts from scratch

Also ships that don't belong to the escort group can be assigned as escort. This start with the command scanForFormationLeader. This commands looks for ships with the same scanclass and that don't already have their maximum escorts. If such a ship exist it returns "TARGET_FOUND". When a target is found you can initiate the escort process with: "setTargetToFoundTarget, suggestEscort".

suggestEscort first checks if the target will accept the ship as escort. For getting accepted:

1: The AI stack size of the escort must be lower than 2 
2: It must have a role of escort and the mother must not have the role "escort". 
   (or it must be wingman and the mother police or interceptor)
3: The mother has not yet the maximum numbers of escorts.

When the escort is accepted by the mother it obtains the group ID of the mother, the mother is set as owner and the escort AI receives an "ESCORTING" message. When the escort was clean, it receives the mothers legal status increased with a small random number.

When the escort is rejected the AI gets: "NOT_ESCORTING".

The requirement of having a role of "escort" makes it difficult for a normal ship getting accepted. (Starting with oolite 1.70 you can use the command: "setPrimaryRole: " to change a shiprole with an AI command). Also escorts introduced by the key "escort-role" will have the wrong role for being added afterwards.

Maintaining escort function

Once an escort is set up the command setDesiredRangeTo: sets the follow distance to the leader and the command performEscort will start the real escort job. From here on everything is automated and the escort speeds up to fly into a formation position. To check if everything is still OK the AI should issue the command escortCheckMother in his UPDATE. escortCheckMother does exactly the same as suggestEscort except changing the escorts legal status.

The escortAI.plist

Most escorts fly with this AI and the setUpEscorts function forces the AI to start with the "FLYING_ESCORT" state. When an escort is hit it receives an "ATTACKED" message but will do nothing with it other than giving this message further to the mother. The mother can react in two ways.

1: Issue a "GROUP_ATTACK_TARGET" with the command groupAttackTarget. The escortAI.plist will then as reaction set the AI to interceptAI.plist.

2: Using the command fightOrFleeHostiles. This command will start the command deployEscorts by its own. (The script does not need to call deployEscorts by its own). This deployEscorts will put all escorts into an "interceptAI.plist" with the current mothers target as target.

Getting attacked

For escorts it is essential to have a role of "escort" (or scanclass "CLASS_POLICE"). Only with this role (or scanclass) the system automatically sets the ATTACKED message with the mother when an escort is attacked. With the ATTACKED message the system also sets the "found target" and the "primary aggressor" of the mother to the attacker of the escort.

messageMother

With the command "messageMother: YOUR_MESSAGE", the mother gets "YOUR_MESSAGE" as priority message. You can attach commands to this self defined message like any other system message. The mother immediately reacts to it.

Creating a spreaded group

When the desired range is set at 0.0 with using performEscort the escorts group into a V-shape. With higher values the V-shape is not so clear. You can also create a more spreaded group by giving members a different distance. Se next escort AI were a dice is used to give members different distances and a dice is also used in the FOLLOW_LEADER state to avoid that all ships at once react to a groupAttackTarget message from he mother.

{
GLOBAL = {ENTER = (); EXIT = (); UPDATE = ("pauseAI: 2.0", "setStateTo: ROLL_DICE"); }; 
"ROLL_DICE" = {
     ENTER = ("rollD: 5"); 
     "ROLL_1" = ("setDesiredRangeTo: 100", "setStateTo: FIND_LEADER"); 
     "ROLL_2" = ("setDesiredRangeTo: 600", "setStateTo: FIND_LEADER"); 
     "ROLL_3" = ("setDesiredRangeTo: 1100", "setStateTo: FIND_LEADER"); 
     "ROLL_4" = ("setDesiredRangeTo: 1600", "setStateTo: FIND_LEADER"); 
     "ROLL_5" = ("setDesiredRangeTo: 2100", "setStateTo: FIND_LEADER"); 
     UPDATE = (); 
     EXIT = ();
     }; 
"FIND_LEADER" = {
     ENTER = (); 
     ATTACKED = (setTargetToFoundTarget, "setStateTo: ATTACK_SHIP");
     "TARGET_FOUND" = (setTargetToFoundTarget, "setStateTo: FOLLOW_LEADER"); 
     "NOTHING_FOUND" = ("setStateTo: HEAD_FOR_PLANET"); 
     "INCOMING_MISSILE" = (fightOrFleeMissile, "setStateTo: FLEE"); 
     UPDATE = ("scanForNearestShipWithRole: ups-convoy-l", "pauseAI: 3.0"); 
     EXIT = ();
     }; 
"FOLLOW_LEADER" = {
     ENTER = (performEscort); 
     ATTACKED = (setTargetToFoundTarget,  "setStateTo: ATTACK_SHIP");
     "GROUP_ATTACK_TARGET" = ("rollD: 3");
     "ROLL_1" = (setTargetToFoundTarget, "setStateTo: ATTACK_SHIP"); 
     "INCOMING_MISSILE" = (fightOrFleeMissile, "setStateTo: FLEE"); 
     "NOT_ESCORTING" = ("setStateTo: GLOBAL"); 
     ESCORTING = (performEscort); 
     UPDATE = (escortCheckMother, "pauseAI: 15"); 
     EXIT = ();
     }; 
}

Return to OXP howto AI