Difference between revisions of "Escort Instructions"

From Elite Wiki
(Creating a spread group)
(Incorporated ML's suggestions, tweak)
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
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 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.<br>
 +
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==
==Adding of mother ship==
+
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.
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 safer 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".
 
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".
+
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 redefine this by adding the command: "'''switchAITo: yourCustomAI.plist'''" in  the ships "launch_actions" in the shipData.plist.
+
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.
  
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.
+
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==
 
==Adding escorts from scratch==
Line 36: Line 34:
  
 
==The escortAI.plist==
 
==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.  
+
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.
 
1: Issue a "GROUP_ATTACK_TARGET" with the command '''groupAttackTarget'''. The escortAI.plist will then as reaction set the  AI to interceptAI.plist.
Line 50: Line 48:
 
==Creating a spread group==
 
==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 die roll is used to give members different distances. A die 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.
+
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 = {ENTER = (); EXIT = (); UPDATE = ("pauseAI: 2.0", "setStateTo: ROLL_DICE"); };  
+
  GLOBAL = {UPDATE = ("pauseAI: 2.0", "setStateTo: ROLL_DICE"); };  
 
  "ROLL_DICE" = {
 
  "ROLL_DICE" = {
 
       ENTER = ("rollD: 5");  
 
       ENTER = ("rollD: 5");  
Line 61: Line 59:
 
       "ROLL_4" = ("setDesiredRangeTo: 1600", "setStateTo: FIND_LEADER");  
 
       "ROLL_4" = ("setDesiredRangeTo: 1600", "setStateTo: FIND_LEADER");  
 
       "ROLL_5" = ("setDesiredRangeTo: 2100", "setStateTo: FIND_LEADER");  
 
       "ROLL_5" = ("setDesiredRangeTo: 2100", "setStateTo: FIND_LEADER");  
      UPDATE = ();
 
      EXIT = ();
 
 
       };  
 
       };  
 
  "FIND_LEADER" = {
 
  "FIND_LEADER" = {
      ENTER = ();
 
 
       ATTACKED = (setTargetToFoundTarget, "setStateTo: ATTACK_SHIP");
 
       ATTACKED = (setTargetToFoundTarget, "setStateTo: ATTACK_SHIP");
 
       "TARGET_FOUND" = (setTargetToFoundTarget, "setStateTo: FOLLOW_LEADER");  
 
       "TARGET_FOUND" = (setTargetToFoundTarget, "setStateTo: FOLLOW_LEADER");  
Line 71: Line 66:
 
       "INCOMING_MISSILE" = (fightOrFleeMissile, "setStateTo: FLEE");  
 
       "INCOMING_MISSILE" = (fightOrFleeMissile, "setStateTo: FLEE");  
 
       UPDATE = (scanForFormationLeader, "pauseAI: 3.0");  
 
       UPDATE = (scanForFormationLeader, "pauseAI: 3.0");  
      EXIT = ();
 
 
       };  
 
       };  
 
  "FOLLOW_LEADER" = {
 
  "FOLLOW_LEADER" = {
Line 82: Line 76:
 
       ESCORTING = (performEscort);  
 
       ESCORTING = (performEscort);  
 
       UPDATE = (escortCheckMother, "pauseAI: 15");  
 
       UPDATE = (escortCheckMother, "pauseAI: 15");  
      EXIT = ();
+
      };  
      };  
 
 
  }
 
  }
 +
 +
== 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 [[Oolite JavaScript Reference: Ship script event handlers#coordinatesForEscortPosition|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]]
 
Return to [[OXP howto AI]]
 
[[Category:Oolite scripting]]
 
[[Category:Oolite scripting]]

Latest revision as of 19:46, 20 October 2022

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