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 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 a escort is set up 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.

Return to OXP howto AI