Escort Instructions

This seems to be written for the original .plist based AIs - it was last properly edited in 2012 (Oolite v.1.80 with the new AIs came out in 2014).

Adding an escorted "mother" ship

When an escorted "mother" ship is added to the universe it is added with all its escorts as defined in shipData.plist.
Prior to v1.79, for "mother" ships added with the role 'trader', the system is examined and a random number of 0, 2, 4 or 6 is subtracted from the maximum escort number. In safer systems it is more likely that escorts are subtracted. From v1.79 onwards, Oolite allows more flexibility in the type and number of ships escorting the "mother" ship.

Addition of escorts

All escorts are automatically created when the mother is created and get an escortAI.plist statemachine and the scanclass and the groupID of the mother. Only when 'auto_ai' is false, the AI as defined in shipdata.plist is used.

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 their primaryRole is changed to "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 set the auto_ai key to false or add a JS ship-script that sets parameters on addition.

In Oolite 1.65 you had to use the function setUpEscorts to create a ship with escorts, but there is no need to use this function in current Oolite versions.

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 reached the maximum number 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 ship role 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 on creation, the AI is forced 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 spread 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 spread out group by giving members a different distance. See next escortAI where a dice roll is used to give members different distances. A dice roll is also used in the FOLLOW_LEADER state to avoid the situation where all ships at once react to a groupAttackTarget message from the mother.

{
GLOBAL = {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"); 
     }; 
"FIND_LEADER" = {
     ATTACKED = (setTargetToFoundTarget, "setStateTo: ATTACK_SHIP");
     "TARGET_FOUND" = (setTargetToFoundTarget, "setStateTo: FOLLOW_LEADER"); 
     "NOTHING_FOUND" = ("setStateTo: HEAD_FOR_PLANET"); 
     "INCOMING_MISSILE" = (fightOrFleeMissile, "setStateTo: FLEE"); 
     UPDATE = (scanForFormationLeader, "pauseAI: 3.0"); 
     }; 
"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"); 
      }; 
}

Setting custom escort formations

Since Oolite 1.75 we have an even better way to define custom escort positions that can be set dynamically with a function. This is achieved with the coordinatesForEscortPosition ship script event handler, and allows any escort formation to be defined (including escort formations which vary over time, or in response to events). Examples of use can be found in several OXPs - the cruiser of Ixian Ships, the Deep Space Dredger, and the Thargoid Carrier all define a different escort formation to the standard 'V' shape.

Escorting other ships

There are a number of OXP's which feature this activity as a mission for the player - see for example Escort Contracts OXP by Capt Murphy et al. (2011-15), Rescue Stations escort missions by Cim (2011-17) & Oo-Haul escort missions by Dr Nil (2007-9) - broken with newer AI's. Resistance Commander features the player leading a small group of resistance fighters.

Return to OXP howto AI