Elite Wiki - User contributions [en]

Escort Instructions

2008-06-15T22:09:22Z

SimonRaven: /* Creating a spread group */

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 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".

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 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 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 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.

{
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 = (scanForFormationLeader, "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]]
[[Category:Oolite scripting]]

Escort Instructions

2008-06-15T22:07:49Z

SimonRaven: /* Creating a spread group */

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 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".

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 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 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 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 spreaded group by giving members a different distance. See next escortAI 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 the 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 = (scanForFormationLeader, "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]]
[[Category:Oolite scripting]]

Escort Instructions

2008-06-15T22:01:15Z

SimonRaven: /* Adding escorts from scratch */

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 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".

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 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 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. See next escortAI 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 the 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 = (scanForFormationLeader, "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]]
[[Category:Oolite scripting]]

Escort Instructions

2008-06-15T21:41:52Z

SimonRaven: /* Adding of mother ship */

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 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".

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. See next escortAI 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 the 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 = (scanForFormationLeader, "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]]
[[Category:Oolite scripting]]

OXP howto AI

2008-06-15T21:41:11Z

SimonRaven: /* Navigation */ same as other edits today, so far

'''AI Script Format'''

The AI system consists of a [[Stacked AI|stack]] of [[state machine]]s (only the top one of which is active), which respond to game events sent to them as [[Messages|messages]]. They respond by calling a series of [[methods]] which affect the behaviour of the [[entity]] and possibly trigger changes to the '''AI''' by changing the [[state]] or (more drastically) the state machine.

Each state machine (or AI script) is described in a property list in either [[ASCII]] or [[XML]] format, which can be edited with a text editor or with Property List Editor. The structure is of a dictionary containing each of the machine's possible states referenced by an identifying state name. Each state comprises a dictionary of responses to messages the AI might receive, referenced by the message itself. Each response is an array of methods that will be called when the AI receives that message.

The AI function calls within a message handler are separated from each other by a comma. If a function takes a parameter the value is separated from the function name by a colon and a space, and both the function name and value are enclosed in double quotes.

In [[ASCII]] format a simple (two-state) machine looks like this:
{
"STATE_1" = {
"ENTER" = ();
"MESSAGE_A" = ("method1: value", method2, method3);
"MESSAGE_B" = (method4, "setStateTo: STATE_2");
EXIT = ();
UPDATE = ();
};
"STATE_2" = {
"ENTER" = ();
"MESSAGE_A" = ("method1: another_value", method5);
"MESSAGE_B" = (method6, method7, "setStateTo: STATE_1");
EXIT = ();
UPDATE = ();
};
}
The same script in [[twostateXML|XML]].

== AI ==
Messages to the statemachine with a [[State machine|priority]] are displayed in boldface.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''exitAI'''
|Exits current AI and returns to the same state in the old AI that called this AI with a "setAITo:". It returns: "'''RESTARTED'''".
|-
|'''pauseAI:(NSString *)intervalString'''
|Sets next AI update time in seconds. It does not stop the execution of the remainder of the line. It just sets the next UPDATE time to the current time plus the pause time. The pauseAI commands are non-cumulative.
|-
|'''setAITo:(NSString *)aiString'''
|Pauses current AI and switches to anotherAI.plist, this becomes the top AI on the 'AI-stack'.
When anotherAI.plist exits (exitAI), the previousAI becomes topAI again and AI-state is messaged "'''RESTARTED'''".
|-
|'''setStateTo: SOMESTATE'''
|Changes the AI state to SOMESTATE.
|-
|'''switchAITo:(NSString *)aiString'''
|Switches entity AI to another *AI.plist, the previous AI will be exited.
|}

== AI choices ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''fightOrFleeHostiles'''
|Deploys escorts if he has them. If he has enough missiles left he might fire one. Then decides between issue the FIGHTING or FLEEING message. Returns "FIGHTING", "DEPLOYING_ESCORTS" or "FLEEING".
|-
|'''fightOrFleeMissile'''
|Deals with missiles, uses ECM if available, flees if not, marks as offender if police. Returns: "FLEEING" or nothing.
|}

== Perform Action ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''becomeEnergyBlast'''
|Used in the [[Q bomb]].
|-
|'''becomeExplosion'''
|The entity model is replaced by an explosion. If player is docked at exploding station it first launches the player.
|-
|'''becomeLargeExplosion'''
|Used at player entity death, not for use in other instances.
|-
|'''dealEnergyDamageWithinDesiredRange'''
|Needs desiredRange to be set first, then deals [[weaponEnergy]] ([[Shipdata.plist]]) damage within this sphere.
|-
|'''decreaseAlertLevel'''
|Can only be used on stations. Decreases station alertlevel. Returns: "'''CONDITION_YELLOW'''", "'''CONDITION_GREEN'''".
|-
|'''deployEscorts'''
|Sends the mothers primary target to all escorts and sets the statemachine of all the escorts to: interceptAI.plist.
|-
|'''dockEscorts'''
|Gives all existing escorts a dockingAI.plist and sets the state to ABORT so the escorts go to a waiting position for docking.
|-
|'''ejectCargo'''
|Ejects cargo.
|-
|'''enterTargetWormhole'''
|Will locate nearest wormhole, and enter it.
|-
|'''escortCheckMother'''
|Returns "ESCORTING" or "NOT_ESCORTING".
|-
|'''fireECM'''
|Used by stations and hermits to engage ECM.
|-
|'''fireMissile'''
|Fires missiles on selected target. It sends a "'''INCOMING_MISSILE'''" message to the target state machine.
|-
|'''groupAttackTarget'''
|All ships in group will have their targets set to this entity's current target. It will return "'''GROUP_ATTACK_TARGET'''" to the sending ship as well as to all group members.
|-
|'''increaseAlertLevel'''
|Can only be used on stations. Increases station alertlevel. Returns: "'''YELLOW_ALERT'''", "'''RED_ALERT'''".
|-
|'''landOnPlanet'''
|Selects the nearest planet it can find, increments the landed shuttles counter for that planet and 'removes' the entity. Returns: "'''LANDED_ON_PLANET'''"
|-
|'''Launch..''Some''Ship'''
|Launches a ship fron a dockable entity, various types of this method exist. See also [[Station Ships]].
* LaunchDefenseShip
* LaunchEscort
* LaunchMiner
* LaunchPatrol
* LaunchPirateShip
* LaunchPolice
* LaunchScavenger
* LaunchShipWithRole: <Role>
* LaunchShuttle
* LaunchTrader
|-
|'''markTargetForFines'''
|Deals out a fine to target. It returns: "TARGET_MARKED". When the target was no ship it returns: "'''TARGET_LOST'''".
Example:
"markTargetForFines: 100"
Will fine the target 10Cr. N.B. for commercial transactions "awardMoney -$" is a more suitable method.
|-
|'''markTargetForOffence:(NSString*) valueString'''
|Has police mark up the criminal record ([[Legal status]]) of target entity. The value is not added to the criminal record but a bit-wise OR is used between value and criminal record. It returns: "'''TARGET_LOST'''" when the target was no ship.
|-
|'''messageMother:(NSString *)msgString'''
|Sends a AI priority message to the mothership/leader of a group.
Example:
INCOMING_MISSILE = ("messageMother: INCOMING_MISSILE");
The mothership will then behave as if it was targeted by the missile. But you don't have to use standard message names, you can also send self defined message names were the mother can react on.
|-
|'''performAttack'''
|Attacks target.
|-
|'''performCollect'''
|Performs 'collection' of target.
|-
|'''performDocking'''
|NOT YET IMPLEMENTED.
|-
|'''performEscort'''
|Performs escorting. Needs a desired range first. The escorts follow at the desired range. See also [[Escort Instructions]].
|-
|'''performFaceDestination'''
|Has entity face destination. Returns "FACING_DESTINATION" when turn is completed.
|-
|'''performFlee'''
|Sets the caller (AI) to flee from it's primary target at maximum speed. If the caller has a cloaking device, it will be activated. It needs a range to be set first. When the ship outruns the attacker by this distance it returns: "REACHED_SAFETY".
|-
|'''performFlyToRangeFromDestination'''
|With this command the ship can react in two ways. It first looks at the distance to the target. When it is closer to the target than the previously defined desired range, it will fly away from the target, otherwise it will fly toward the target. It stops the ship at the desired range from the destination and than returns: "DESIRED_RANGE_ACHIEVED".
|-
|'''performHold'''
|Performs idleness while tracking a potential target, speed is set to zero. [[frustration]] level is reset.
|-
|'''performHyperSpaceExit'''
|Gets a list of destinations within fuel range, checks if clear of nearby masses, and select one at random. May return "'''WITCHSPACE UNAVAILABLE'''", "'''WITCHSPACE BLOCKED'''" or "'''WITCHSPACE_OKAY'''". It will add a new ship with the same role as the leaving ship at the witchspace entry point.

When the player performs a hyperspace exit or a galactic jump, all NPC ships get the priority message: "'''PLAYER WITCHSPACE'''".
|-
|'''performHyperSpaceExitWithoutReplacing'''
|Gets a list of destinations within fuel range, checks if clear of nearby masses, and select one at random. May return "'''WITCHSPACE UNAVAILABLE'''", "'''WITCHSPACE BLOCKED'''" or "'''WITCHSPACE_OKAY'''". This command will not add a new ship at the witchspace entry point. (available with version 1.70 and higher)
|-
|'''performIdle'''
|Performs idleness. Ship corrects its roll and pitch to 'horizontal' flight, speed is unaffected. [[frustration]] level is reset to zero.
|-
|'''performIntercept'''
|Performs target interception. It needs a range to be set first. When the distance to target becomes less than desired range it returns: "'''DESIRED_RANGE_ACHIEVED'''". When target lost: "'''TARGET_LOST'''". When it hasn't come closer to target for 10 seconds it returns: "'''FRUSTRATED'''"
|-
|'''performMining'''
|Performs mining. (Finds, intercepts and shoots asteroids with [[mining]] laser, if fitted.) It returns: "'''TARGET_LOST'''".
|-
|'''performTumble'''
|Performs random pitch and roll, 'evasive maneuvers'.
|-
|'''setSpeedTo:(NSString *)speedString'''
|Sets desired speed to an absolute value, entity cannot go faster than maxspeed value determined in the [[shipdata.plist]]. If speed is above maxspeed, entity will use fuel injectors if available.
|-
|'''setSpeedFactorTo:(NSString *)speedString'''
|Sets the desired speed to a percentage of maxspeed (0->1=0%->100%). If speedfactor is set above 100%, entity will use fuelinjectors if available.
|-
|'''setUpEscorts'''
|Useful to quickly establish (by name and number the [[Shipdata.plist#escorts|shipdata.plist]] prescribed) escorts, when a ship is introduced to a system. See also [[Escort Instructions]].
|-
|'''suggestEscort'''
|Has an escort seek employment and either gets accepted or rejected by the "mother". See also [[Escort Instructions]].
|-
|'''switchLightsOff'''
|If an entity has lights (or flashers), this command will turn them off. Default state is on. (See [[Shipdata.plist#subentities|shipdata.plist]])
|-
|'''switchLightsOn'''
|Will turn flashers back on.
|-
|'''wormholeEntireGroup'''
|Wormholes ships in this group. Returns '''"ENTER WORMHOLE'''"
|-
|'''wormholeEscorts'''
|Wormholes official escorts. Returns '''"ENTER WORMHOLE'''"
|-
|'''wormholeGroup'''
|Wormholes ships in group of which this is a leader. Returns '''"ENTER WORMHOLE'''"
|}

== Navigation ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''****'''
|The aegis check is part of the system update and messages needs no command to generate them. The following messages are '''only generated''' when the status '''changes'''.
"AEGIS_CLOSE_TO_PLANET": Within 3x planetary radius and not near station.
"AEGIS_IN_DOCKING_RANGE": Within 2x scanner radius of system station.
"AEGIS_LEAVING_DOCKING_RANGE": Has been in docking range but now only close to planet.
"AEGIS_NONE": None of the above three messages is true.
|-
|'''****'''
|The surface check needs no command. It automatically generates messages when a ship passes a border at approximately 1 meter from the main planet surface.
"'''APPROACHING_SURFACE'''": passed the border inward.
"'''LEAVING_SURFACE'''": passed the border outward.
|-
|'''abortDocking'''
|Signal the mother station that the docking is aborted. see [[Docking Instructions]]
|-
|'''getWitchspaceEntryCoordinates'''
|Calculates coordinates at 10 km from the rotation axis of the nearest station it can find, or just fly 10s forward.
|-
|'''recallDockingInstructions'''
|see [[Docking Instructions]]
|-
|'''requestDockingCoordinates'''
|Requests coordinates from the nearest station it can find (which may be a Rock hermit). Returns: "NO_STATION_FOUND", "TRY_AGAIN_LATER", "HOLD_POSITION", "BACK_OFF" , "APPROACH" or "APPROACH_COORDINATES". see also [[Docking Instructions]]
|-
|'''setCoordinates:(NSString *)system_x_y_z'''
|Sets destination coords, see '''[[Methods#Looking_for.2C_and_adding_ships|addShipsAt]]'''. It needs 4 parameters separated with space. When coordinates are set it returns: "APPROACH_COORDINATES". You can even [[setCoordinates_randomizer|randomize]] positive coordinates.
|-
|'''setCourseToPlanet'''
|Selects the nearest planet it can find, sets the coordinates to a point on the ship's side of the surface with a large random spread to avoid all ships flying to the same point. Then it sets the desired range to 50 m (+ its own collision diameter). This short desired range will probably crash normal fast flying ships on the surface but a collision between the planet and a ship with role "shuttle" is interpreted as landing.
|-
|'''setCourseToWitchpoint'''
|Sets destination coords to Witchpoint area and sets "DesiredRange" to 10 km.
|-
|'''setDesiredRangeTo:(NSString *)rangeString'''
|Some methods (such as scanForNearestMerchantmen, checkCourseToDestination, checkDistanceTravelled, etc) require a "desired range" parameter to be set before they can be used.

This method is used to set the desired range. There is only one value for desired range within an instance of the AI. The value of desired range is modified internally by AI methods such as fightOrFleeMissile, setCourseToWitchpoint, and setPlanetPatrolCoordinates.
|-
|'''setDestinationFromCoordinates'''
|Enables the plotting of manual waypoints.
|-
|'''setDestinationToCurrentLocation'''
|This method sets the destination of the current entity to its current location plus a random offset of up to 0.5 metres in the X, Y, and Z coordinates. This can be used to make a ship idle in a small area of space without being completely still.
|-
|'''setDestinationToDockingAbort'''
|DockingAbort coordinates 8000 meter distance from the docking slit.
|-
|'''setDestinationToStationBeacon'''
|Gets station beacon position.
|-
|'''setDestinationToTarget'''
|Sets destination to target coords.
|-
|'''setDestinationToWitchpoint'''
|Sets destination coordinates to WitchspaceExitPosition.
|-
|'''setDestinationWithinTarget'''
|Handy for ramming and racing.
|-
|'''setPlanetPatrolCoordinates'''
|Request coordinates for planet control. Read more in [[setPlanetPatrolCoordinates]].
|-
|'''setSunSkimEndCoordinates'''
|...
|-
|'''setSunSkimExitCoordinates'''
|...
|-
|'''setSunSkimStartCoordinates'''
|...
|-
|'''setTargetToSystemStation'''
|...
|-
|'''setTargetToStation'''
|...
|-
|'''setTakeOffFromPlanet'''
|Selects the nearest planet it can find and calculates a vector perpendicular to the surface and sets a destination range of 10 km. Does nothing if there is no planet to be found.
|}

== Communication ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''******'''
|Hitting a clean ship automatical sends a "'''OFFENCE_COMMITTED'''" to all nearby ships with scanClass equal CLASS_NEUTRAL, CLASS_STATION, CLASS_BUOY, CLASS_POLICE, CLASS_MILITARY, CLASS_PLAYER. Besides this all the ships flying in a group like pirates, police or escorts get an "'''ATTACKED'''" message as when they were attacked themself.
|-
|'''broadcastDistressMessage'''
|Locates all the stations, bounty hunters and police ships in range and tells them that you are under attack. This command resets a previous found target to none at the sending side. It returns: "'''ACCEPT_DISTRESS_MESSAGE'''" in the AI of Stations, Hunters and Police ships and gives them as" Found Target", the "Primary Target" of the sender of the broadcast.
|-
|'''commsMessage:(NSString *)valueString'''
|Broadcasts a general message to player.
Example:
"sendCommsMessage: [thargoid_curses]"
|-
|'''patrolReportIn'''
|This command sets the "last patrol report time" to the current time. Only useful for station patrol.
|-
|'''sendTargetCommsMessage:(NSString*) message'''
|Sends any message to the established (found) target. When the target is not a ship it returns: "'''TARGET_LOST'''"

Example:
"sendTargetCommsMessage: Listen to me!!"
|}

== Locating entities ==

All these methods require a range to be set by setDesiredRange or by <scanner_range> in [[shipdata.plist]], all will return the message TARGET_FOUND or NOTHING_FOUND. The calling entity remembers the found target, but it does not become the current (universal) target. It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.

When you are continuously scanning as in a update event, make sure you add also a pause command. Scanning takes time and in most cases one scan every few seconds is enough. Look also at Oolites internal AI's were this timing is well thought of.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''checkCourseToDestination'''
|Will return "COURSE_OK" when no obstacles on the direct route, else it calculates a little deviated save vector and returns "WAYPOINT_SET". When there is a small ship in his way it also returns: '''HAZARD_CAN_BE_DESTROYED'''
|-
|'''checkDistanceTravelled'''
|First you must define a range with setDesiredRangeTo:. When the total traveled distance since creation is greater than this value it returns: "GONE_BEYOND_RANGE". Used for missiles.
|-
|'''checkGroupOddsVersusTarget'''
|Will return "ODDS_GOOD", "ODDS_LEVEL" or "ODDS_BAD".
|-
|'''checkForFullHold'''
|If entity's cargo capacity is reached, will return "HOLD_FULL".
|-
|'''checkForMotherStation'''
|Will return "STATION_FOUND" or "NOTHING_FOUND".
|-
|'''checkForNormalSpace'''
|Will return "NORMAL_SPACE" or "INTERSTELLAR_SPACE".
|-
|'''checkTargetLegalStatus'''
|Returns "TARGET_CLEAN, "TARGET_MINOR_OFFENDER", "TARGET_OFFENDER", "TARGET_FUGITIVE" or "NO_TARGET".
|-
|'''findNearestPlanet'''
|Will scan for planetentity. Returns nothing. Nearest planet coordinates are placed in destination memory.
|-
|'''scanForFormationLeader'''
|Locates the nearest suitable formation leader in range. Returns: "TARGET_FOUND" or "NOTHING_FOUND". See also [[Escort Instructions]].
|-
|'''scanForHostiles'''
|Locates all the ships in range targeting the receiver and ships with "SCANNCLASS_TARGOID" and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForLoot'''
|Scans for nearest debris in range.
Returns: "HOLD_FULL", "TARGET_FOUND" or "NOTHING_FOUND".
If scanning ship is moving station or has no scoop it always return: "NOTHING_FOUND". If scanning ship has scanClass: "CLASS_POLICE", it only finds slaves and lifepods.
|-
|'''scanForNearestMerchantmen'''
|Scans for ships with role: Trader or Player and selects the nearest. If scanning ship has role Pirate it prefers the player.
Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForNearestShipWithRole:(NSString*) scanRole'''
|Locates all the ships in range and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForNonThargoid'''
|Locates all the non thargoid ships in range and chooses the nearest. It finds everything except cargo and ships with a role starting with: "tharg". If it finds the player it prefers the player. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForOffenders'''
|Locates all the ships in range, subtracts a random value between 0 and 255 from their legal status or bounty and compares the remaining value. It chooses the worst offender. Because of the random value not all ships are found in every scan and the lower the bounty the longer it takes to detect him as offender. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForRandomLoot'''
|Scans for debris in range and selects one at random from the first 16 found.
Returns: "HOLD_FULL", "TARGET_FOUND" or "NOTHING_FOUND"
If scanning ship is station or has no scoop it always return: "NOTHING_FOUND".
|-
|'''scanForRandomMerchantmen'''
|Scans for ships with role: Trader or Player and selects one at random. Returns: "TARGET_FOUND" or "NOTHING_FOUND".
|-
|'''scanForRocks'''
|Scans for nearest boulder in range. When nothing found then scans for nearest asteroid in range. Returns "TARGET_FOUND" or "NOTING_FOUND".
|-
|'''scanForThargoid'''
|Locates all the ships with role "thargoid" in range and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|}

== Targeting ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''requestNewTarget'''
|Locates all the ships in range targeting the mother ship, and chooses the nearest/biggest. Returns: "MOTHER_LOST", "TARGET_FOUND" or "NOTHING_FOUND".
|-
|'''setTargetToFoundTarget'''
|Affirms a TARGET_FOUND by a scanFor- or find-Something-method as the universal target.
|-
|'''setTargetToPrimaryAggressor'''
|This function sets the primary agressor to the primary target. Then in the "performAttack" state, it only has a 25% change of setting the primary agressor to the primary target. The other 75% it will do nothing. This function is designed for used during attack to prevent it will constantly change targets when attacking a group.

primary agressor is set by the system when a ship fires a laser or missile on the other.
|}

== Miscellaneous ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''addFuel:(NSString*) fuel_number'''
|Changes player's fuel level by fuel_number LY's, max to 7.0 min to 0.0.
|-
|'''becomeUncontrolledThargon'''
|Changes ship into cargo with scannClass "CLASS_CARGO" and sets AI to "dumbAI". If also the the cargo type is defined in ShipData.plist it can be picked up like any other cargo.
|-
|'''initialiseTurret'''
|Prepares the turret. As turrets have no statemachine of their own, this function can only be used in the setup_actions of the turrets shipData.
|-
|'''rollD:(NSString*) dice_number'''
|Uses "dice" for random situation use. It returns "'''ROLL_1'''", "'''ROLL_2'''" and so on until dice_number. dice_number is an integer and has no size limit.

Example 1, 3 options in someAI.plist:
GLOBAL = {
ENTER = ("rollD: 3");
"ROLL_1" = (action1);
"ROLL_2" = (action2);
"ROLL_3" = (action3);}

Example 2, 50% chance in [[script.plist]];
[[Script.plist#conditions|conditions]] = ("d100_number lessthan 50");
[[Script.plist#do|do]] = (action1);
[[Script.plist#else|else]] = (action2);
is similar in function.
|-
|'''safeScriptActionOnTarget:(NSString*) action'''
|This will do a script action on the target. For NPC ships as target you can use all the AI commands available that will act as if its own AI used the command. (command introduced with version 1.71)

It will also execute player script commands, like setting mission variables. For this to work it needs a target being set. It doesn't matter witch one.

Example:

"scriptActionOnTarget: set: mission_my_missionvariable TRUE",
"scriptActionOnTarget: awardCredits: 100"
|-
|'''scriptActionOnTarget:(NSString*) action'''
|This will do the same as safeScriptActionOnTarget, but in addition the legacy script engine is started so all installed player scripts are evaluated immediately. Use of this command is discouraged in favour of safeScriptActionOnTarget as it takes a lot of time to evaluate all scripts and in most situations this is also unnecessary.

|-
|'''sendScriptMessage: message'''
|Calls the javaScript function '''message()''' on the ship’s [[Oolite JavaScript Reference: Script|ship script]]. Added in Oolite 1.70. This function opens the whole js power to the AI scripting.

|}

== Role scanning methods ==
Starting with version 1.70 next commands will become available. This info is still preliminary until the actual release.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''scanForNearestShipWithPrimaryRole:(NSString*) role'''
|new (preferred) name for '''scanForNearestShipWithRole:'''.
|-
|'''scanForNearestShipHavingRole:(NSString*) role'''
|scan based on entire role set rather than primary role.
|-
|'''scanForNearestShipWithAnyPrimaryRole:(NSString*) role-list'''
|takes a list of roles (space-separated) and returns the nearest ship with any of them as primary.
|-
|'''scanForNearestShipHavingAnyRole:(NSString*) role-list'''
|takes a list of roles (space-separated) and returns the nearest ship with any of them in its role set.
|-
|'''scanForNearestShipWithScanClass:(NSString*) scanclass'''
|searches for a ship by scan class.
|-
|'''scanForNearestShipWithoutPrimaryRole:(NSString*) role'''
|
|-
|'''scanForNearestShipNotHavingRole:(NSString*) role'''
|
|-
|'''scanForNearestShipWithoutAnyPrimaryRole:(NSString*) role-list'''
|
|-
|'''scanForNearestShipNotHavingAnyRole:(NSString*) role-list'''
|
|-
|'''scanForNearestShipWithoutScanClass:(NSString*) scanclass'''
|
|-
|'''setPrimaryRole:(NSString*) role'''
|Sets the primary role for a ship.
|}
--------------------------------------------------------------------------------
[[Category:Oolite]]
[[Category:Oolite scripting]]

OXP howto AI

2008-06-15T21:35:32Z

SimonRaven: /* Perform Action */

'''AI Script Format'''

The AI system consists of a [[Stacked AI|stack]] of [[state machine]]s (only the top one of which is active), which respond to game events sent to them as [[Messages|messages]]. They respond by calling a series of [[methods]] which affect the behaviour of the [[entity]] and possibly trigger changes to the '''AI''' by changing the [[state]] or (more drastically) the state machine.

Each state machine (or AI script) is described in a property list in either [[ASCII]] or [[XML]] format, which can be edited with a text editor or with Property List Editor. The structure is of a dictionary containing each of the machine's possible states referenced by an identifying state name. Each state comprises a dictionary of responses to messages the AI might receive, referenced by the message itself. Each response is an array of methods that will be called when the AI receives that message.

The AI function calls within a message handler are separated from each other by a comma. If a function takes a parameter the value is separated from the function name by a colon and a space, and both the function name and value are enclosed in double quotes.

In [[ASCII]] format a simple (two-state) machine looks like this:
{
"STATE_1" = {
"ENTER" = ();
"MESSAGE_A" = ("method1: value", method2, method3);
"MESSAGE_B" = (method4, "setStateTo: STATE_2");
EXIT = ();
UPDATE = ();
};
"STATE_2" = {
"ENTER" = ();
"MESSAGE_A" = ("method1: another_value", method5);
"MESSAGE_B" = (method6, method7, "setStateTo: STATE_1");
EXIT = ();
UPDATE = ();
};
}
The same script in [[twostateXML|XML]].

== AI ==
Messages to the statemachine with a [[State machine|priority]] are displayed in boldface.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''exitAI'''
|Exits current AI and returns to the same state in the old AI that called this AI with a "setAITo:". It returns: "'''RESTARTED'''".
|-
|'''pauseAI:(NSString *)intervalString'''
|Sets next AI update time in seconds. It does not stop the execution of the remainder of the line. It just sets the next UPDATE time to the current time plus the pause time. The pauseAI commands are non-cumulative.
|-
|'''setAITo:(NSString *)aiString'''
|Pauses current AI and switches to anotherAI.plist, this becomes the top AI on the 'AI-stack'.
When anotherAI.plist exits (exitAI), the previousAI becomes topAI again and AI-state is messaged "'''RESTARTED'''".
|-
|'''setStateTo: SOMESTATE'''
|Changes the AI state to SOMESTATE.
|-
|'''switchAITo:(NSString *)aiString'''
|Switches entity AI to another *AI.plist, the previous AI will be exited.
|}

== AI choices ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''fightOrFleeHostiles'''
|Deploys escorts if he has them. If he has enough missiles left he might fire one. Then decides between issue the FIGHTING or FLEEING message. Returns "FIGHTING", "DEPLOYING_ESCORTS" or "FLEEING".
|-
|'''fightOrFleeMissile'''
|Deals with missiles, uses ECM if available, flees if not, marks as offender if police. Returns: "FLEEING" or nothing.
|}

== Perform Action ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''becomeEnergyBlast'''
|Used in the [[Q bomb]].
|-
|'''becomeExplosion'''
|The entity model is replaced by an explosion. If player is docked at exploding station it first launches the player.
|-
|'''becomeLargeExplosion'''
|Used at player entity death, not for use in other instances.
|-
|'''dealEnergyDamageWithinDesiredRange'''
|Needs desiredRange to be set first, then deals [[weaponEnergy]] ([[Shipdata.plist]]) damage within this sphere.
|-
|'''decreaseAlertLevel'''
|Can only be used on stations. Decreases station alertlevel. Returns: "'''CONDITION_YELLOW'''", "'''CONDITION_GREEN'''".
|-
|'''deployEscorts'''
|Sends the mothers primary target to all escorts and sets the statemachine of all the escorts to: interceptAI.plist.
|-
|'''dockEscorts'''
|Gives all existing escorts a dockingAI.plist and sets the state to ABORT so the escorts go to a waiting position for docking.
|-
|'''ejectCargo'''
|Ejects cargo.
|-
|'''enterTargetWormhole'''
|Will locate nearest wormhole, and enter it.
|-
|'''escortCheckMother'''
|Returns "ESCORTING" or "NOT_ESCORTING".
|-
|'''fireECM'''
|Used by stations and hermits to engage ECM.
|-
|'''fireMissile'''
|Fires missiles on selected target. It sends a "'''INCOMING_MISSILE'''" message to the target state machine.
|-
|'''groupAttackTarget'''
|All ships in group will have their targets set to this entity's current target. It will return "'''GROUP_ATTACK_TARGET'''" to the sending ship as well as to all group members.
|-
|'''increaseAlertLevel'''
|Can only be used on stations. Increases station alertlevel. Returns: "'''YELLOW_ALERT'''", "'''RED_ALERT'''".
|-
|'''landOnPlanet'''
|Selects the nearest planet it can find, increments the landed shuttles counter for that planet and 'removes' the entity. Returns: "'''LANDED_ON_PLANET'''"
|-
|'''Launch..''Some''Ship'''
|Launches a ship fron a dockable entity, various types of this method exist. See also [[Station Ships]].
* LaunchDefenseShip
* LaunchEscort
* LaunchMiner
* LaunchPatrol
* LaunchPirateShip
* LaunchPolice
* LaunchScavenger
* LaunchShipWithRole: <Role>
* LaunchShuttle
* LaunchTrader
|-
|'''markTargetForFines'''
|Deals out a fine to target. It returns: "TARGET_MARKED". When the target was no ship it returns: "'''TARGET_LOST'''".
Example:
"markTargetForFines: 100"
Will fine the target 10Cr. N.B. for commercial transactions "awardMoney -$" is a more suitable method.
|-
|'''markTargetForOffence:(NSString*) valueString'''
|Has police mark up the criminal record ([[Legal status]]) of target entity. The value is not added to the criminal record but a bit-wise OR is used between value and criminal record. It returns: "'''TARGET_LOST'''" when the target was no ship.
|-
|'''messageMother:(NSString *)msgString'''
|Sends a AI priority message to the mothership/leader of a group.
Example:
INCOMING_MISSILE = ("messageMother: INCOMING_MISSILE");
The mothership will then behave as if it was targeted by the missile. But you don't have to use standard message names, you can also send self defined message names were the mother can react on.
|-
|'''performAttack'''
|Attacks target.
|-
|'''performCollect'''
|Performs 'collection' of target.
|-
|'''performDocking'''
|NOT YET IMPLEMENTED.
|-
|'''performEscort'''
|Performs escorting. Needs a desired range first. The escorts follow at the desired range. See also [[Escort Instructions]].
|-
|'''performFaceDestination'''
|Has entity face destination. Returns "FACING_DESTINATION" when turn is completed.
|-
|'''performFlee'''
|Sets the caller (AI) to flee from it's primary target at maximum speed. If the caller has a cloaking device, it will be activated. It needs a range to be set first. When the ship outruns the attacker by this distance it returns: "REACHED_SAFETY".
|-
|'''performFlyToRangeFromDestination'''
|With this command the ship can react in two ways. It first looks at the distance to the target. When it is closer to the target than the previously defined desired range, it will fly away from the target, otherwise it will fly toward the target. It stops the ship at the desired range from the destination and than returns: "DESIRED_RANGE_ACHIEVED".
|-
|'''performHold'''
|Performs idleness while tracking a potential target, speed is set to zero. [[frustration]] level is reset.
|-
|'''performHyperSpaceExit'''
|Gets a list of destinations within fuel range, checks if clear of nearby masses, and select one at random. May return "'''WITCHSPACE UNAVAILABLE'''", "'''WITCHSPACE BLOCKED'''" or "'''WITCHSPACE_OKAY'''". It will add a new ship with the same role as the leaving ship at the witchspace entry point.

When the player performs a hyperspace exit or a galactic jump, all NPC ships get the priority message: "'''PLAYER WITCHSPACE'''".
|-
|'''performHyperSpaceExitWithoutReplacing'''
|Gets a list of destinations within fuel range, checks if clear of nearby masses, and select one at random. May return "'''WITCHSPACE UNAVAILABLE'''", "'''WITCHSPACE BLOCKED'''" or "'''WITCHSPACE_OKAY'''". This command will not add a new ship at the witchspace entry point. (available with version 1.70 and higher)
|-
|'''performIdle'''
|Performs idleness. Ship corrects its roll and pitch to 'horizontal' flight, speed is unaffected. [[frustration]] level is reset to zero.
|-
|'''performIntercept'''
|Performs target interception. It needs a range to be set first. When the distance to target becomes less than desired range it returns: "'''DESIRED_RANGE_ACHIEVED'''". When target lost: "'''TARGET_LOST'''". When it hasn't come closer to target for 10 seconds it returns: "'''FRUSTRATED'''"
|-
|'''performMining'''
|Performs mining. (Finds, intercepts and shoots asteroids with [[mining]] laser, if fitted.) It returns: "'''TARGET_LOST'''".
|-
|'''performTumble'''
|Performs random pitch and roll, 'evasive maneuvers'.
|-
|'''setSpeedTo:(NSString *)speedString'''
|Sets desired speed to an absolute value, entity cannot go faster than maxspeed value determined in the [[shipdata.plist]]. If speed is above maxspeed, entity will use fuel injectors if available.
|-
|'''setSpeedFactorTo:(NSString *)speedString'''
|Sets the desired speed to a percentage of maxspeed (0->1=0%->100%). If speedfactor is set above 100%, entity will use fuelinjectors if available.
|-
|'''setUpEscorts'''
|Useful to quickly establish (by name and number the [[Shipdata.plist#escorts|shipdata.plist]] prescribed) escorts, when a ship is introduced to a system. See also [[Escort Instructions]].
|-
|'''suggestEscort'''
|Has an escort seek employment and either gets accepted or rejected by the "mother". See also [[Escort Instructions]].
|-
|'''switchLightsOff'''
|If an entity has lights (or flashers), this command will turn them off. Default state is on. (See [[Shipdata.plist#subentities|shipdata.plist]])
|-
|'''switchLightsOn'''
|Will turn flashers back on.
|-
|'''wormholeEntireGroup'''
|Wormholes ships in this group. Returns '''"ENTER WORMHOLE'''"
|-
|'''wormholeEscorts'''
|Wormholes official escorts. Returns '''"ENTER WORMHOLE'''"
|-
|'''wormholeGroup'''
|Wormholes ships in group of which this is a leader. Returns '''"ENTER WORMHOLE'''"
|}

== Navigation ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''****'''
|The aegis check is part of the system update and messages needs no command to generate them. The following messages are '''only generated''' when the status '''changes'''.
"AEGIS_CLOSE_TO_PLANET": Within 3x planetary radius and not near station.
"AEGIS_IN_DOCKING_RANGE": Within 2x scanner radius of system station.
"AEGIS_LEAVING_DOCKING_RANGE": Has been in docking range but now only close to planet.
"AEGIS_NONE": None of the above tree messages is true.
|-
|'''****'''
|The surface check needs no command. It automatically generates messages when a ship passes a border at approximately 1 meter from the main planet surface.
"'''APPROACHING_SURFACE'''": passed the border inward.
"'''LEAVING_SURFACE'''": passed the border outward.
|-
|'''abortDocking'''
|Signal the motherstation that the docking is aborted. see [[Docking Instructions]]
|-
|'''getWitchspaceEntryCoordinates'''
|Calculates coordinates at 10 km from the rotation axis of the nearest station it can find, or just fly 10s forward.
|-
|'''recallDockingInstructions'''
|see [[Docking Instructions]]
|-
|'''requestDockingCoordinates'''
|Requests coordinates from the nearest station it can find (which may be a Rock hermit). Returns: "NO_STATION_FOUND", "TRY_AGAIN_LATER", "HOLD_POSITION", "BACK_OFF" , "APPROACH" or "APPROACH_COORDINATES". see also [[Docking Instructions]]
|-
|'''setCoordinates:(NSString *)system_x_y_z'''
|Sets destination coords, see '''[[Methods#Looking_for.2C_and_adding_ships|addShipsAt]]'''. It needs 4 parameters separated with space. When coordinates are set it returns: "APPROACH_COORDINATES". You can even [[setCoordinates_randomizer|randomize]] positive coordinates.
|-
|'''setCourseToPlanet'''
|Selects the nearest planet it can find, sets the coordinates to a point on the ships side of the surface with a large random spread to avoid all ships flying to the same point. Then it sets the desired range to 50 m (+ its own collision diameter). This short desired range will probably crash normal fast flying ships on the surface but a collission between the planet and a ship with role "shuttle" is interpreted as landing.
|-
|'''setCourseToWitchpoint'''
|Sets destination coords to Witchpoint area and sets "DesiredRange" to 10 km.
|-
|'''setDesiredRangeTo:(NSString *)rangeString'''
|Some methods (such as scanForNearestMerchantmen, checkCourseToDestination, checkDistanceTravelled, etc) require a "desired range" parameter to be set before they can be used.

This method is used to set the desired range. There is only one value for desired range within an instance of the AI. The value of desired range is modified internally by AI methods such as fightOrFleeMissile, setCourseToWitchpoint, and setPlanetPatrolCoordinates.
|-
|'''setDestinationFromCoordinates'''
|Enables the plotting of manual waypoints.
|-
|'''setDestinationToCurrentLocation'''
|This method sets the destination of the current entity to its current location plus a random offset of up to 0.5 metres in the X, Y, and Z coordinates. This can be used to make a ship idle in a small area of space without being completely still.
|-
|'''setDestinationToDockingAbort'''
|DockingAbort coordinates 8000 meter distance from the dockingslit.
|-
|'''setDestinationToStationBeacon'''
|Gets station beacon position.
|-
|'''setDestinationToTarget'''
|Sets destination to target coords.
|-
|'''setDestinationToWitchpoint'''
|Sets destination coordinates to WitchspaceExitPosition.
|-
|'''setDestinationWithinTarget'''
|Handy for ramming and racing.
|-
|'''setPlanetPatrolCoordinates'''
|Request coordinates for planet control. Read more in [[setPlanetPatrolCoordinates]].
|-
|'''setSunSkimEndCoordinates'''
|...
|-
|'''setSunSkimExitCoordinates'''
|...
|-
|'''setSunSkimStartCoordinates'''
|...
|-
|'''setTargetToSystemStation'''
|...
|-
|'''setTargetToStation'''
|...
|-
|'''setTakeOffFromPlanet'''
|Selects the nearest planet it can find and calculates a vector perpendicular to the surface an sets a destinaton range of 10 km. Does nothing if there is no planet to be found.
|}

== Communication ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''******'''
|Hitting a clean ship automatical sends a "'''OFFENCE_COMMITTED'''" to all nearby ships with scanClass equal CLASS_NEUTRAL, CLASS_STATION, CLASS_BUOY, CLASS_POLICE, CLASS_MILITARY, CLASS_PLAYER. Besides this all the ships flying in a group like pirates, police or escorts get an "'''ATTACKED'''" message as when they were attacked themself.
|-
|'''broadcastDistressMessage'''
|Locates all the stations, bounty hunters and police ships in range and tells them that you are under attack. This command resets a previous found target to none at the sending side. It returns: "'''ACCEPT_DISTRESS_MESSAGE'''" in the AI of Stations, Hunters and Police ships and gives them as" Found Target", the "Primary Target" of the sender of the broadcast.
|-
|'''commsMessage:(NSString *)valueString'''
|Broadcasts a general message to player.
Example:
"sendCommsMessage: [thargoid_curses]"
|-
|'''patrolReportIn'''
|This command sets the "last patrol report time" to the current time. Only useful for station patrol.
|-
|'''sendTargetCommsMessage:(NSString*) message'''
|Sends any message to the established (found) target. When the target is not a ship it returns: "'''TARGET_LOST'''"

Example:
"sendTargetCommsMessage: Listen to me!!"
|}

== Locating entities ==

All these methods require a range to be set by setDesiredRange or by <scanner_range> in [[shipdata.plist]], all will return the message TARGET_FOUND or NOTHING_FOUND. The calling entity remembers the found target, but it does not become the current (universal) target. It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.

When you are continuously scanning as in a update event, make sure you add also a pause command. Scanning takes time and in most cases one scan every few seconds is enough. Look also at Oolites internal AI's were this timing is well thought of.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''checkCourseToDestination'''
|Will return "COURSE_OK" when no obstacles on the direct route, else it calculates a little deviated save vector and returns "WAYPOINT_SET". When there is a small ship in his way it also returns: '''HAZARD_CAN_BE_DESTROYED'''
|-
|'''checkDistanceTravelled'''
|First you must define a range with setDesiredRangeTo:. When the total traveled distance since creation is greater than this value it returns: "GONE_BEYOND_RANGE". Used for missiles.
|-
|'''checkGroupOddsVersusTarget'''
|Will return "ODDS_GOOD", "ODDS_LEVEL" or "ODDS_BAD".
|-
|'''checkForFullHold'''
|If entity's cargo capacity is reached, will return "HOLD_FULL".
|-
|'''checkForMotherStation'''
|Will return "STATION_FOUND" or "NOTHING_FOUND".
|-
|'''checkForNormalSpace'''
|Will return "NORMAL_SPACE" or "INTERSTELLAR_SPACE".
|-
|'''checkTargetLegalStatus'''
|Returns "TARGET_CLEAN, "TARGET_MINOR_OFFENDER", "TARGET_OFFENDER", "TARGET_FUGITIVE" or "NO_TARGET".
|-
|'''findNearestPlanet'''
|Will scan for planetentity. Returns nothing. Nearest planet coordinates are placed in destination memory.
|-
|'''scanForFormationLeader'''
|Locates the nearest suitable formation leader in range. Returns: "TARGET_FOUND" or "NOTHING_FOUND". See also [[Escort Instructions]].
|-
|'''scanForHostiles'''
|Locates all the ships in range targeting the receiver and ships with "SCANNCLASS_TARGOID" and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForLoot'''
|Scans for nearest debris in range.
Returns: "HOLD_FULL", "TARGET_FOUND" or "NOTHING_FOUND".
If scanning ship is moving station or has no scoop it always return: "NOTHING_FOUND". If scanning ship has scanClass: "CLASS_POLICE", it only finds slaves and lifepods.
|-
|'''scanForNearestMerchantmen'''
|Scans for ships with role: Trader or Player and selects the nearest. If scanning ship has role Pirate it prefers the player.
Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForNearestShipWithRole:(NSString*) scanRole'''
|Locates all the ships in range and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForNonThargoid'''
|Locates all the non thargoid ships in range and chooses the nearest. It finds everything except cargo and ships with a role starting with: "tharg". If it finds the player it prefers the player. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForOffenders'''
|Locates all the ships in range, subtracts a random value between 0 and 255 from their legal status or bounty and compares the remaining value. It chooses the worst offender. Because of the random value not all ships are found in every scan and the lower the bounty the longer it takes to detect him as offender. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForRandomLoot'''
|Scans for debris in range and selects one at random from the first 16 found.
Returns: "HOLD_FULL", "TARGET_FOUND" or "NOTHING_FOUND"
If scanning ship is station or has no scoop it always return: "NOTHING_FOUND".
|-
|'''scanForRandomMerchantmen'''
|Scans for ships with role: Trader or Player and selects one at random. Returns: "TARGET_FOUND" or "NOTHING_FOUND".
|-
|'''scanForRocks'''
|Scans for nearest boulder in range. When nothing found then scans for nearest asteroid in range. Returns "TARGET_FOUND" or "NOTING_FOUND".
|-
|'''scanForThargoid'''
|Locates all the ships with role "thargoid" in range and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|}

== Targeting ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''requestNewTarget'''
|Locates all the ships in range targeting the mother ship, and chooses the nearest/biggest. Returns: "MOTHER_LOST", "TARGET_FOUND" or "NOTHING_FOUND".
|-
|'''setTargetToFoundTarget'''
|Affirms a TARGET_FOUND by a scanFor- or find-Something-method as the universal target.
|-
|'''setTargetToPrimaryAggressor'''
|This function sets the primary agressor to the primary target. Then in the "performAttack" state, it only has a 25% change of setting the primary agressor to the primary target. The other 75% it will do nothing. This function is designed for used during attack to prevent it will constantly change targets when attacking a group.

primary agressor is set by the system when a ship fires a laser or missile on the other.
|}

== Miscellaneous ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''addFuel:(NSString*) fuel_number'''
|Changes player's fuel level by fuel_number LY's, max to 7.0 min to 0.0.
|-
|'''becomeUncontrolledThargon'''
|Changes ship into cargo with scannClass "CLASS_CARGO" and sets AI to "dumbAI". If also the the cargo type is defined in ShipData.plist it can be picked up like any other cargo.
|-
|'''initialiseTurret'''
|Prepares the turret. As turrets have no statemachine of their own, this function can only be used in the setup_actions of the turrets shipData.
|-
|'''rollD:(NSString*) dice_number'''
|Uses "dice" for random situation use. It returns "'''ROLL_1'''", "'''ROLL_2'''" and so on until dice_number. dice_number is an integer and has no size limit.

Example 1, 3 options in someAI.plist:
GLOBAL = {
ENTER = ("rollD: 3");
"ROLL_1" = (action1);
"ROLL_2" = (action2);
"ROLL_3" = (action3);}

Example 2, 50% chance in [[script.plist]];
[[Script.plist#conditions|conditions]] = ("d100_number lessthan 50");
[[Script.plist#do|do]] = (action1);
[[Script.plist#else|else]] = (action2);
is similar in function.
|-
|'''safeScriptActionOnTarget:(NSString*) action'''
|This will do a script action on the target. For NPC ships as target you can use all the AI commands available that will act as if its own AI used the command. (command introduced with version 1.71)

It will also execute player script commands, like setting mission variables. For this to work it needs a target being set. It doesn't matter witch one.

Example:

"scriptActionOnTarget: set: mission_my_missionvariable TRUE",
"scriptActionOnTarget: awardCredits: 100"
|-
|'''scriptActionOnTarget:(NSString*) action'''
|This will do the same as safeScriptActionOnTarget, but in addition the legacy script engine is started so all installed player scripts are evaluated immediately. Use of this command is discouraged in favour of safeScriptActionOnTarget as it takes a lot of time to evaluate all scripts and in most situations this is also unnecessary.

|-
|'''sendScriptMessage: message'''
|Calls the javaScript function '''message()''' on the ship’s [[Oolite JavaScript Reference: Script|ship script]]. Added in Oolite 1.70. This function opens the whole js power to the AI scripting.

|}

== Role scanning methods ==
Starting with version 1.70 next commands will become available. This info is still preliminary until the actual release.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''scanForNearestShipWithPrimaryRole:(NSString*) role'''
|new (preferred) name for '''scanForNearestShipWithRole:'''.
|-
|'''scanForNearestShipHavingRole:(NSString*) role'''
|scan based on entire role set rather than primary role.
|-
|'''scanForNearestShipWithAnyPrimaryRole:(NSString*) role-list'''
|takes a list of roles (space-separated) and returns the nearest ship with any of them as primary.
|-
|'''scanForNearestShipHavingAnyRole:(NSString*) role-list'''
|takes a list of roles (space-separated) and returns the nearest ship with any of them in its role set.
|-
|'''scanForNearestShipWithScanClass:(NSString*) scanclass'''
|searches for a ship by scan class.
|-
|'''scanForNearestShipWithoutPrimaryRole:(NSString*) role'''
|
|-
|'''scanForNearestShipNotHavingRole:(NSString*) role'''
|
|-
|'''scanForNearestShipWithoutAnyPrimaryRole:(NSString*) role-list'''
|
|-
|'''scanForNearestShipNotHavingAnyRole:(NSString*) role-list'''
|
|-
|'''scanForNearestShipWithoutScanClass:(NSString*) scanclass'''
|
|-
|'''setPrimaryRole:(NSString*) role'''
|Sets the primary role for a ship.
|}
--------------------------------------------------------------------------------
[[Category:Oolite]]
[[Category:Oolite scripting]]

OXP howto AI

2008-06-15T21:33:04Z

SimonRaven: /* Perform Action */ fix typos/bad spelling

'''AI Script Format'''

The AI system consists of a [[Stacked AI|stack]] of [[state machine]]s (only the top one of which is active), which respond to game events sent to them as [[Messages|messages]]. They respond by calling a series of [[methods]] which affect the behaviour of the [[entity]] and possibly trigger changes to the '''AI''' by changing the [[state]] or (more drastically) the state machine.

Each state machine (or AI script) is described in a property list in either [[ASCII]] or [[XML]] format, which can be edited with a text editor or with Property List Editor. The structure is of a dictionary containing each of the machine's possible states referenced by an identifying state name. Each state comprises a dictionary of responses to messages the AI might receive, referenced by the message itself. Each response is an array of methods that will be called when the AI receives that message.

The AI function calls within a message handler are separated from each other by a comma. If a function takes a parameter the value is separated from the function name by a colon and a space, and both the function name and value are enclosed in double quotes.

In [[ASCII]] format a simple (two-state) machine looks like this:
{
"STATE_1" = {
"ENTER" = ();
"MESSAGE_A" = ("method1: value", method2, method3);
"MESSAGE_B" = (method4, "setStateTo: STATE_2");
EXIT = ();
UPDATE = ();
};
"STATE_2" = {
"ENTER" = ();
"MESSAGE_A" = ("method1: another_value", method5);
"MESSAGE_B" = (method6, method7, "setStateTo: STATE_1");
EXIT = ();
UPDATE = ();
};
}
The same script in [[twostateXML|XML]].

== AI ==
Messages to the statemachine with a [[State machine|priority]] are displayed in boldface.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''exitAI'''
|Exits current AI and returns to the same state in the old AI that called this AI with a "setAITo:". It returns: "'''RESTARTED'''".
|-
|'''pauseAI:(NSString *)intervalString'''
|Sets next AI update time in seconds. It does not stop the execution of the remainder of the line. It just sets the next UPDATE time to the current time plus the pause time. The pauseAI commands are non-cumulative.
|-
|'''setAITo:(NSString *)aiString'''
|Pauses current AI and switches to anotherAI.plist, this becomes the top AI on the 'AI-stack'.
When anotherAI.plist exits (exitAI), the previousAI becomes topAI again and AI-state is messaged "'''RESTARTED'''".
|-
|'''setStateTo: SOMESTATE'''
|Changes the AI state to SOMESTATE.
|-
|'''switchAITo:(NSString *)aiString'''
|Switches entity AI to another *AI.plist, the previous AI will be exited.
|}

== AI choices ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''fightOrFleeHostiles'''
|Deploys escorts if he has them. If he has enough missiles left he might fire one. Then decides between issue the FIGHTING or FLEEING message. Returns "FIGHTING", "DEPLOYING_ESCORTS" or "FLEEING".
|-
|'''fightOrFleeMissile'''
|Deals with missiles, uses ECM if available, flees if not, marks as offender if police. Returns: "FLEEING" or nothing.
|}

== Perform Action ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''becomeEnergyBlast'''
|Used in the [[Q bomb]].
|-
|'''becomeExplosion'''
|The entity model is replaced by an explosion. If player is docked at exploding station it first launches the player.
|-
|'''becomeLargeExplosion'''
|Used at player entity death, not for use in other instances.
|-
|'''dealEnergyDamageWithinDesiredRange'''
|Needs desiredRange to be set first, then deals [[weaponEnergy]] ([[Shipdata.plist]]) damage within this sphere.
|-
|'''decreaseAlertLevel'''
|Can only be used on stations. Decreases station alertlevel. Returns: "'''CONDITION_YELLOW'''", "'''CONDITION_GREEN'''".
|-
|'''deployEscorts'''
|Sends the mothers primary target to all escorts and sets the statemachine of all the escorts to: interceptAI.plist.
|-
|'''dockEscorts'''
|Gives all existing escorts a dockingAI.plist and sets the state to ABORT so the escorts go to a waiting position for docking.
|-
|'''ejectCargo'''
|Ejects cargo.
|-
|'''enterTargetWormhole'''
|Will locate nearest wormhole, and enter it.
|-
|'''escortCheckMother'''
|Returns "ESCORTING" or "NOT_ESCORTING".
|-
|'''fireECM'''
|Used by stations and hermits to engage ECM.
|-
|'''fireMissile'''
|Fires missiles on selected target. It sends a "'''INCOMING_MISSILE'''" message to the target state machine.
|-
|'''groupAttackTarget'''
|All ships in group will have their targets set to this entity's current target. It will return "'''GROUP_ATTACK_TARGET'''" to the sending ship as well as to all group members.
|-
|'''increaseAlertLevel'''
|Can only be used on stations. Increases station alertlevel. Returns: "'''YELLOW_ALERT'''", "'''RED_ALERT'''".
|-
|'''landOnPlanet'''
|Selects the nearest planet it can find, increments the landed shuttles counter for that planet and 'removes' the entity. Returns: "'''LANDED_ON_PLANET'''"
|-
|'''Launch..''Some''Ship'''
|Launches a ship fron a dockable entity, various types of this method exist. See also [[Station Ships]].
* LaunchDefenseShip
* LaunchEscort
* LaunchMiner
* LaunchPatrol
* LaunchPirateShip
* LaunchPolice
* LaunchScavenger
* LaunchShipWithRole: <Role>
* LaunchShuttle
* LaunchTrader
|-
|'''markTargetForFines'''
|Deals out a fine to target. It returns: "TARGET_MARKED". When the target was no ship it returns: "'''TARGET_LOST'''".
Example:
"markTargetForFines: 100"
Will fine the target 10Cr. N.B. for commercial transactions "awardMoney -$" is a more suitable method.
|-
|'''markTargetForOffence:(NSString*) valueString'''
|Has police mark up the criminal record ([[Legal status]]) of target entity. The value is not added to the criminal record but a bit-wise OR is used between value and criminal record. It returns: "'''TARGET_LOST'''" when the target was no ship.
|-
|'''messageMother:(NSString *)msgString'''
|Sends a AI priority message to the mothership/leader of a group.
Example:
INCOMING_MISSILE = ("messageMother: INCOMING_MISSILE");
The mothership will then behave as if it was targeted by the missile. But you don't have to use standard message names, you can also send self defined message names were the mother can react on.
|-
|'''performAttack'''
|Attacks target.
|-
|'''performCollect'''
|Performs 'collection' of target.
|-
|'''performDocking'''
|NOT YET IMPLEMENTED.
|-
|'''performEscort'''
|Performs escorting. Needs a desired range first. The escorts follow at the desired range. See also [[Escort Instructions]].
|-
|'''performFaceDestination'''
|Has entity face destination. Returns "FACING_DESTINATION" when turn is completed.
|-
|'''performFlee'''
|Sets the caller (AI) to flee from it's primary target at maximum speed. If the caller has a cloaking device, it will be activated. It needs a range to be set first. When the ship outruns the attacker by this distance it returns: "REACHED_SAFETY".
|-
|'''performFlyToRangeFromDestination'''
|Whit this command the ship can react in two ways. It first looks at the distance to the target. When it is closer to the target than the previously defined desired range, it will fly away from the target, otherwise it will fly toward the target. It stops the ship at the desired range from the destination and than returns: "DESIRED_RANGE_ACHIEVED".
|-
|'''performHold'''
|Performs idleness while tracking a potential target, speed is set to zero. [[frustration]] level is reset.
|-
|'''performHyperSpaceExit'''
|Gets a list of destinations within fuel range, checks if clear of nearby masses, and select one at random. May return "'''WITCHSPACE UNAVAILABLE'''", "'''WITCHSPACE BLOCKED'''" or "'''WITCHSPACE_OKAY'''". It will add a new ship with the same role as the leaving ship at the witchspace entry point.

When the player performs a hyperspace exit or a galactic jump, all NPC ships get the priority message: "'''PLAYER WITCHSPACE'''".
|-
|'''performHyperSpaceExitWithoutReplacing'''
|Gets a list of destinations within fuel range, checks if clear of nearby masses, and select one at random. May return "'''WITCHSPACE UNAVAILABLE'''", "'''WITCHSPACE BLOCKED'''" or "'''WITCHSPACE_OKAY'''". This command will not add a new ship at the witchspace entry point. (available with version 1.70 and higher)
|-
|'''performIdle'''
|Performs idleness. Ship corrects its roll and pitch to 'horizontal' flight, speed is unaffected. [[frustration]] level is reset to zero.
|-
|'''performIntercept'''
|Performs target interception. It needs a range to be set first. When the distance to target becomes less than desired range it returns: "'''DESIRED_RANGE_ACHIEVED'''". When target lost: "'''TARGET_LOST'''". When it hasn't come closer to target for 10 seconds it returns: "'''FRUSTRATED'''"
|-
|'''performMining'''
|Performs mining. (Finds, intercepts and shoots asteroids with [[mining]] laser, if fitted.) It returns: "'''TARGET_LOST'''".
|-
|'''performTumble'''
|Performs random pitch and roll, 'evasive maneuvers'.
|-
|'''setSpeedTo:(NSString *)speedString'''
|Sets desired speed to an absolute value, entity cannot go faster than maxspeed value determined in the [[shipdata.plist]]. If speed is above maxspeed, entity will use fuel injectors if available.
|-
|'''setSpeedFactorTo:(NSString *)speedString'''
|Sets the desired speed to a percentage of maxspeed (0->1=0%->100%). If speedfactor is set above 100%, entity will use fuelinjectors if available.
|-
|'''setUpEscorts'''
|Useful to quickly establish (by name and number the [[Shipdata.plist#escorts|shipdata.plist]] prescribed) escorts, when a ship is introduced to a system. See also [[Escort Instructions]].
|-
|'''suggestEscort'''
|Has an escort seek employment and either gets accepted or rejected by the "mother". See also [[Escort Instructions]].
|-
|'''switchLightsOff'''
|If an entity has lights (or flashers), this command will turn them off. Default state is on. (See [[Shipdata.plist#subentities|shipdata.plist]])
|-
|'''switchLightsOn'''
|Will turn flashers back on.
|-
|'''wormholeEntireGroup'''
|Wormholes ships in this group. Returns '''"ENTER WORMHOLE'''"
|-
|'''wormholeEscorts'''
|Wormholes official escorts. Returns '''"ENTER WORMHOLE'''"
|-
|'''wormholeGroup'''
|Wormholes ships in group of which this is a leader. Returns '''"ENTER WORMHOLE'''"
|}

== Navigation ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''****'''
|The aegis check is part of the system update and messages needs no command to generate them. The following messages are '''only generated''' when the status '''changes'''.
"AEGIS_CLOSE_TO_PLANET": Within 3x planetary radius and not near station.
"AEGIS_IN_DOCKING_RANGE": Within 2x scanner radius of system station.
"AEGIS_LEAVING_DOCKING_RANGE": Has been in docking range but now only close to planet.
"AEGIS_NONE": None of the above tree messages is true.
|-
|'''****'''
|The surface check needs no command. It automatically generates messages when a ship passes a border at approximately 1 meter from the main planet surface.
"'''APPROACHING_SURFACE'''": passed the border inward.
"'''LEAVING_SURFACE'''": passed the border outward.
|-
|'''abortDocking'''
|Signal the motherstation that the docking is aborted. see [[Docking Instructions]]
|-
|'''getWitchspaceEntryCoordinates'''
|Calculates coordinates at 10 km from the rotation axis of the nearest station it can find, or just fly 10s forward.
|-
|'''recallDockingInstructions'''
|see [[Docking Instructions]]
|-
|'''requestDockingCoordinates'''
|Requests coordinates from the nearest station it can find (which may be a Rock hermit). Returns: "NO_STATION_FOUND", "TRY_AGAIN_LATER", "HOLD_POSITION", "BACK_OFF" , "APPROACH" or "APPROACH_COORDINATES". see also [[Docking Instructions]]
|-
|'''setCoordinates:(NSString *)system_x_y_z'''
|Sets destination coords, see '''[[Methods#Looking_for.2C_and_adding_ships|addShipsAt]]'''. It needs 4 parameters separated with space. When coordinates are set it returns: "APPROACH_COORDINATES". You can even [[setCoordinates_randomizer|randomize]] positive coordinates.
|-
|'''setCourseToPlanet'''
|Selects the nearest planet it can find, sets the coordinates to a point on the ships side of the surface with a large random spread to avoid all ships flying to the same point. Then it sets the desired range to 50 m (+ its own collision diameter). This short desired range will probably crash normal fast flying ships on the surface but a collission between the planet and a ship with role "shuttle" is interpreted as landing.
|-
|'''setCourseToWitchpoint'''
|Sets destination coords to Witchpoint area and sets "DesiredRange" to 10 km.
|-
|'''setDesiredRangeTo:(NSString *)rangeString'''
|Some methods (such as scanForNearestMerchantmen, checkCourseToDestination, checkDistanceTravelled, etc) require a "desired range" parameter to be set before they can be used.

This method is used to set the desired range. There is only one value for desired range within an instance of the AI. The value of desired range is modified internally by AI methods such as fightOrFleeMissile, setCourseToWitchpoint, and setPlanetPatrolCoordinates.
|-
|'''setDestinationFromCoordinates'''
|Enables the plotting of manual waypoints.
|-
|'''setDestinationToCurrentLocation'''
|This method sets the destination of the current entity to its current location plus a random offset of up to 0.5 metres in the X, Y, and Z coordinates. This can be used to make a ship idle in a small area of space without being completely still.
|-
|'''setDestinationToDockingAbort'''
|DockingAbort coordinates 8000 meter distance from the dockingslit.
|-
|'''setDestinationToStationBeacon'''
|Gets station beacon position.
|-
|'''setDestinationToTarget'''
|Sets destination to target coords.
|-
|'''setDestinationToWitchpoint'''
|Sets destination coordinates to WitchspaceExitPosition.
|-
|'''setDestinationWithinTarget'''
|Handy for ramming and racing.
|-
|'''setPlanetPatrolCoordinates'''
|Request coordinates for planet control. Read more in [[setPlanetPatrolCoordinates]].
|-
|'''setSunSkimEndCoordinates'''
|...
|-
|'''setSunSkimExitCoordinates'''
|...
|-
|'''setSunSkimStartCoordinates'''
|...
|-
|'''setTargetToSystemStation'''
|...
|-
|'''setTargetToStation'''
|...
|-
|'''setTakeOffFromPlanet'''
|Selects the nearest planet it can find and calculates a vector perpendicular to the surface an sets a destinaton range of 10 km. Does nothing if there is no planet to be found.
|}

== Communication ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''******'''
|Hitting a clean ship automatical sends a "'''OFFENCE_COMMITTED'''" to all nearby ships with scanClass equal CLASS_NEUTRAL, CLASS_STATION, CLASS_BUOY, CLASS_POLICE, CLASS_MILITARY, CLASS_PLAYER. Besides this all the ships flying in a group like pirates, police or escorts get an "'''ATTACKED'''" message as when they were attacked themself.
|-
|'''broadcastDistressMessage'''
|Locates all the stations, bounty hunters and police ships in range and tells them that you are under attack. This command resets a previous found target to none at the sending side. It returns: "'''ACCEPT_DISTRESS_MESSAGE'''" in the AI of Stations, Hunters and Police ships and gives them as" Found Target", the "Primary Target" of the sender of the broadcast.
|-
|'''commsMessage:(NSString *)valueString'''
|Broadcasts a general message to player.
Example:
"sendCommsMessage: [thargoid_curses]"
|-
|'''patrolReportIn'''
|This command sets the "last patrol report time" to the current time. Only useful for station patrol.
|-
|'''sendTargetCommsMessage:(NSString*) message'''
|Sends any message to the established (found) target. When the target is not a ship it returns: "'''TARGET_LOST'''"

Example:
"sendTargetCommsMessage: Listen to me!!"
|}

== Locating entities ==

All these methods require a range to be set by setDesiredRange or by <scanner_range> in [[shipdata.plist]], all will return the message TARGET_FOUND or NOTHING_FOUND. The calling entity remembers the found target, but it does not become the current (universal) target. It can be made the current target by responding to the TARGET_FOUND message with a call to setTargetToFoundTarget.

When you are continuously scanning as in a update event, make sure you add also a pause command. Scanning takes time and in most cases one scan every few seconds is enough. Look also at Oolites internal AI's were this timing is well thought of.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''checkCourseToDestination'''
|Will return "COURSE_OK" when no obstacles on the direct route, else it calculates a little deviated save vector and returns "WAYPOINT_SET". When there is a small ship in his way it also returns: '''HAZARD_CAN_BE_DESTROYED'''
|-
|'''checkDistanceTravelled'''
|First you must define a range with setDesiredRangeTo:. When the total traveled distance since creation is greater than this value it returns: "GONE_BEYOND_RANGE". Used for missiles.
|-
|'''checkGroupOddsVersusTarget'''
|Will return "ODDS_GOOD", "ODDS_LEVEL" or "ODDS_BAD".
|-
|'''checkForFullHold'''
|If entity's cargo capacity is reached, will return "HOLD_FULL".
|-
|'''checkForMotherStation'''
|Will return "STATION_FOUND" or "NOTHING_FOUND".
|-
|'''checkForNormalSpace'''
|Will return "NORMAL_SPACE" or "INTERSTELLAR_SPACE".
|-
|'''checkTargetLegalStatus'''
|Returns "TARGET_CLEAN, "TARGET_MINOR_OFFENDER", "TARGET_OFFENDER", "TARGET_FUGITIVE" or "NO_TARGET".
|-
|'''findNearestPlanet'''
|Will scan for planetentity. Returns nothing. Nearest planet coordinates are placed in destination memory.
|-
|'''scanForFormationLeader'''
|Locates the nearest suitable formation leader in range. Returns: "TARGET_FOUND" or "NOTHING_FOUND". See also [[Escort Instructions]].
|-
|'''scanForHostiles'''
|Locates all the ships in range targeting the receiver and ships with "SCANNCLASS_TARGOID" and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForLoot'''
|Scans for nearest debris in range.
Returns: "HOLD_FULL", "TARGET_FOUND" or "NOTHING_FOUND".
If scanning ship is moving station or has no scoop it always return: "NOTHING_FOUND". If scanning ship has scanClass: "CLASS_POLICE", it only finds slaves and lifepods.
|-
|'''scanForNearestMerchantmen'''
|Scans for ships with role: Trader or Player and selects the nearest. If scanning ship has role Pirate it prefers the player.
Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForNearestShipWithRole:(NSString*) scanRole'''
|Locates all the ships in range and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForNonThargoid'''
|Locates all the non thargoid ships in range and chooses the nearest. It finds everything except cargo and ships with a role starting with: "tharg". If it finds the player it prefers the player. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForOffenders'''
|Locates all the ships in range, subtracts a random value between 0 and 255 from their legal status or bounty and compares the remaining value. It chooses the worst offender. Because of the random value not all ships are found in every scan and the lower the bounty the longer it takes to detect him as offender. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|-
|'''scanForRandomLoot'''
|Scans for debris in range and selects one at random from the first 16 found.
Returns: "HOLD_FULL", "TARGET_FOUND" or "NOTHING_FOUND"
If scanning ship is station or has no scoop it always return: "NOTHING_FOUND".
|-
|'''scanForRandomMerchantmen'''
|Scans for ships with role: Trader or Player and selects one at random. Returns: "TARGET_FOUND" or "NOTHING_FOUND".
|-
|'''scanForRocks'''
|Scans for nearest boulder in range. When nothing found then scans for nearest asteroid in range. Returns "TARGET_FOUND" or "NOTING_FOUND".
|-
|'''scanForThargoid'''
|Locates all the ships with role "thargoid" in range and chooses the nearest. Returns: "TARGET_FOUND" or "NOTHING_FOUND"
|}

== Targeting ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''requestNewTarget'''
|Locates all the ships in range targeting the mother ship, and chooses the nearest/biggest. Returns: "MOTHER_LOST", "TARGET_FOUND" or "NOTHING_FOUND".
|-
|'''setTargetToFoundTarget'''
|Affirms a TARGET_FOUND by a scanFor- or find-Something-method as the universal target.
|-
|'''setTargetToPrimaryAggressor'''
|This function sets the primary agressor to the primary target. Then in the "performAttack" state, it only has a 25% change of setting the primary agressor to the primary target. The other 75% it will do nothing. This function is designed for used during attack to prevent it will constantly change targets when attacking a group.

primary agressor is set by the system when a ship fires a laser or missile on the other.
|}

== Miscellaneous ==

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''addFuel:(NSString*) fuel_number'''
|Changes player's fuel level by fuel_number LY's, max to 7.0 min to 0.0.
|-
|'''becomeUncontrolledThargon'''
|Changes ship into cargo with scannClass "CLASS_CARGO" and sets AI to "dumbAI". If also the the cargo type is defined in ShipData.plist it can be picked up like any other cargo.
|-
|'''initialiseTurret'''
|Prepares the turret. As turrets have no statemachine of their own, this function can only be used in the setup_actions of the turrets shipData.
|-
|'''rollD:(NSString*) dice_number'''
|Uses "dice" for random situation use. It returns "'''ROLL_1'''", "'''ROLL_2'''" and so on until dice_number. dice_number is an integer and has no size limit.

Example 1, 3 options in someAI.plist:
GLOBAL = {
ENTER = ("rollD: 3");
"ROLL_1" = (action1);
"ROLL_2" = (action2);
"ROLL_3" = (action3);}

Example 2, 50% chance in [[script.plist]];
[[Script.plist#conditions|conditions]] = ("d100_number lessthan 50");
[[Script.plist#do|do]] = (action1);
[[Script.plist#else|else]] = (action2);
is similar in function.
|-
|'''safeScriptActionOnTarget:(NSString*) action'''
|This will do a script action on the target. For NPC ships as target you can use all the AI commands available that will act as if its own AI used the command. (command introduced with version 1.71)

It will also execute player script commands, like setting mission variables. For this to work it needs a target being set. It doesn't matter witch one.

Example:

"scriptActionOnTarget: set: mission_my_missionvariable TRUE",
"scriptActionOnTarget: awardCredits: 100"
|-
|'''scriptActionOnTarget:(NSString*) action'''
|This will do the same as safeScriptActionOnTarget, but in addition the legacy script engine is started so all installed player scripts are evaluated immediately. Use of this command is discouraged in favour of safeScriptActionOnTarget as it takes a lot of time to evaluate all scripts and in most situations this is also unnecessary.

|-
|'''sendScriptMessage: message'''
|Calls the javaScript function '''message()''' on the ship’s [[Oolite JavaScript Reference: Script|ship script]]. Added in Oolite 1.70. This function opens the whole js power to the AI scripting.

|}

== Role scanning methods ==
Starting with version 1.70 next commands will become available. This info is still preliminary until the actual release.

{| border="1" cellpadding="5" style="width:100%
!width="225"|Method
!Description
|-
|'''scanForNearestShipWithPrimaryRole:(NSString*) role'''
|new (preferred) name for '''scanForNearestShipWithRole:'''.
|-
|'''scanForNearestShipHavingRole:(NSString*) role'''
|scan based on entire role set rather than primary role.
|-
|'''scanForNearestShipWithAnyPrimaryRole:(NSString*) role-list'''
|takes a list of roles (space-separated) and returns the nearest ship with any of them as primary.
|-
|'''scanForNearestShipHavingAnyRole:(NSString*) role-list'''
|takes a list of roles (space-separated) and returns the nearest ship with any of them in its role set.
|-
|'''scanForNearestShipWithScanClass:(NSString*) scanclass'''
|searches for a ship by scan class.
|-
|'''scanForNearestShipWithoutPrimaryRole:(NSString*) role'''
|
|-
|'''scanForNearestShipNotHavingRole:(NSString*) role'''
|
|-
|'''scanForNearestShipWithoutAnyPrimaryRole:(NSString*) role-list'''
|
|-
|'''scanForNearestShipNotHavingAnyRole:(NSString*) role-list'''
|
|-
|'''scanForNearestShipWithoutScanClass:(NSString*) scanclass'''
|
|-
|'''setPrimaryRole:(NSString*) role'''
|Sets the primary role for a ship.
|}
--------------------------------------------------------------------------------
[[Category:Oolite]]
[[Category:Oolite scripting]]

Methods

2008-06-15T21:13:56Z

SimonRaven: /* Communications */ fix i.e. (which means "that is", not "for example"); fix external link

'''Methods'''

Methods are the actions that are performed when conditions (defined in a script) are met, or when a particular set of actions (like ''[[Shipdata.plist#death_actions|death_actions]]'' or ''[[Shipdata.plist#script_actions|script_actions]]'') are called for, or when an AI calls for a script action to be performed.

All methods are stored in plists as strings (in XML this means between a <string> tag and a </string> closing tag). If they take any parameters then these follow a colon and a space (''': ''') after the 'command' part of the method.

For example: if the ship containing this ''death_actions'' entry is destroyed - the player gets a message and the sun goes Nova two seconds later!

<key>death_actions</key>
<array>
<string>commsMessage: Oh dear [commander_name]!</string>
<string>setSunNovaIn: 2.0</string>
</array>

== The Mission Screen ==

'''setGuiToMissionScreen'''
// opens the mission screen

'''addMissionText: <[[missiontext.plist]] key> '''
// adds text to the mission screen from an entry in [[missiontext.plist]]
// with the given key

'''showShipModel: <role>'''
// shows a rotating model of a ship with the role given
// role refers to a value in one of [[shipdata.plist]]'s entries'
// ''roles'' key value pair

'''setMissionMusic: <filename>'''
// plays the music file given
// if it exists within any OXP's ''Music'' folder

'''setMissionImage: <filename>'''
// displays the picture file given
// if it exists within any OXP's ''Images'' folder

'''setMissionChoices: <[[missiontext.plist]] key>'''
// sets the array of choices presented at the bottom of the mission page to those described in the
// entry in missiontext.plist that corresponds to the key given

'''resetMissionChoice'''
// makes missionChoice ''UNDEFINED''

'''setMissionDescription: <[[missiontext.plist]] key>'''
// sets the short description given on the player's manifest screen

'''clearMissionDescription'''
// clears the short description

Starting with version 1.71 you can also use:
clearMissionScreen
// it clears the image, music and shipmodel in one singlee command.
// same as: setMissionImage: none, showShipModel: none, setMissionMusic: none.
(In 1.70 this command also did clear the mission choices.)

Note that '''setMissionImage:''' displays an image OVER a ship displayed with '''showShipModel:'''.
This means a normal image will cover the ship. To use both, an image must be used with a transparent main page
and all the info must be in the alpha channel of the picture.

'''resetScriptTimer'''
// resets a timer for scripting purposes '''deprecated - do not use''

== Star charts ==

'''addMissionDestination: <pnum>'''
// causes the given planets to be marked on the short and long range star charts
// multiple planet numbers may be supplied separated by spaces

'''removeMissionDestination: <pnum>'''
// causes the given planets to have their marks remove from the short and long range star charts
// multiple planet numbers may be supplied separated by spaces

== Looking for, and adding ships ==

'''checkForShips: <role>'''
// returns the number of ships found in the current system that match the role
// this number can be queried with [[Methods#Results_from_other_methods|'''shipsFound_number''']]

'''addShips: <role> <number>'''
// causes a number of ships matching the given role to appear near the withpoint

'''addSystemShips: <role> <number> <position>'''
// causes a number of ships matching the given role to appear near a point
// on a line from the witchpoint to the planet's station. <position> should be a floating point
// number where 0.0 represents the witchpoint and 1.0 represents the station

'''addShipsAt: <role> <number> <coordinate scheme> <x> <y> <z>'''
// causes a number of ships matching the given role to appear ''near'' a point
// defined by the <coordinate scheme> and the floating point coordinates x,y and z
// <coordinate scheme> consists of a three letter code:
//
// The first letter indicates the feature that is the origin of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
//
// The next letter indicates the feature on the 'z' axis of the coordinate system.
// w => witchpoint
// s => sun
// p => planet
//
// Then the 'y' axis of the system is normal to the plane formed by the planet, sun and witchpoint.
// And the 'x' axis of the system is normal to the y and z axes.
// So:
// ps: z axis = (planet -> sun) y axis = normal to (planet - sun - witchpoint) x axis = normal to y and z axes
// pw: z axis = (planet -> witchpoint) y axis = normal to (planet - witchpoint - sun) x axis = normal to y and z axes
// sp: z axis = (sun -> planet) y axis = normal to (sun - planet - witchpoint) x axis = normal to y and z axes
// sw: z axis = (sun -> witchpoint) y axis = normal to (sun - witchpoint - planet) x axis = normal to y and z axes
// wp: z axis = (witchpoint -> planet) y axis = normal to (witchpoint - planet - sun) x axis = normal to y and z axes
// ws: z axis = (witchpoint -> sun) y axis = normal to (witchpoint - sun - planet) x axis = normal to y and z axes
//
// The third letter denotes the units used:
// m: meters
// p: planetary radii
// s: solar radii
// u: distance between first two features indicated (eg. spu means that u = distance from sun to the planet)
//
// in witchspace (== no sun) coordinates are absolute irrespective of the system used

'''addShipsAtPrecisely: <role> <number> <coordinate scheme> <x> <y> <z>'''
// This adds the ships as close as possible to the specified point

'''addShipsWithinRadius: <role> <number> <coordinate-system> <x> <y> <z> <radius in metres>'''
// Example:
// "addShipsWithinRadius: asteroid 48 wpm 0 0 15000 5000"
// would add a 5km-wide asteroid field with 48 asteroids at a position roughly 15000m towards
// the planet from the witchpoint.

'''spawn: <role> <number>'''
// adds a number of ships matching <role> near the ship
// that's the target of this script (as [[Shipdata.plist#script_actions|script_actions]] or [[Shipdata.plist#death_actions|death_actions]])

'''spawnShip: <[[shipdata.plist]] key>'''
// adds a ship with the unique [[shipdata.plist]] key given
// the position and facing of the ship are determined by a ''spawn'' dictionary in the
// ship's shipdata.plist entry with ''position'' and ''facing_position'' as strings describing
// coordinates according to one of the schemes above

== Changing the universe ==

'''setSunNovaIn: <seconds>'''
// Sets the sun to go nova after the given time in seconds

'''sendAllShipsAway'''
// Makes all the ships in the system hyperspace away

'''setPlanetinfo: <key>=<value>'''
// sets an override to the [[planetinfo.plist]] entry for the current system
// the value for the given key is set to match the value
// (see [[planetinfo.plist]])
//
// eg '''setPlanetinfo: description=a very dull planet'''
// (Note the '=' is required)

'''setSpecificPlanetInfo: <gnum>=<pnum>=<key>=<value>
// sets an override to the [[planetinfo.plist]] entry for the system
// specified by galaxy gnum and planet pnum
//
// eg '''setSpecificPlanetInfo: 0=7=description=Lave is not a very dull planet'''
// (Note the '=' is required between all 4 values)

'''addPlanet: <[[planetinfo.plist]] key>'''
// adds a planet to the universe from data in [[planetinfo.plist]].

'''addMoon: <[[planetinfo.plist]] key>'''
// adds a moon to the universe from data in [[planetinfo.plist]].
// (Moons do not get an atmosphere or clouds like planets).

'''blowUpStation'''
// blows up the main station. If there are more stations, the nearest becomes the main station were you can save files.
// the removal of the station is stored in the save-file

== Mission Variables ==

As of 1.65? these methods can also be used with script local variables by suppling a
"local_" variable rather than a "mission_" varaible. The difference is that "mission_" variables are stored within a save file and "local_" variables are not saved with the game and are only valid localy, within a mission script.

'''set: [[mission_variable]] <value>'''
// sets the [[mission_variable]] to the value given
// the value can be a particular string or numeric value,
// or a queriable state

'''reset: [[mission_variable]] <value>'''
// sets the [[mission_variable]] to be ''UNDEFINED''

'''increment: [[mission_variable]]'''
// increases the mission variable's value by 1.0

'''decrement: [[mission_variable]]'''
// decreases the mission variable's value by 1.0

'''add: [[mission_variable]] <value>'''
// adds the value given to the [[mission_variable]]
// the value can be a number or a queriable state
// like ''shipsFound_number''

'''subtract: [[mission_variable]] <value>'''
// subtracts the value given from the [[mission_variable]]
// the value can be a number or a queriable state
// like ''shipsFound_number''

Be aware that increment and decrement result in values with integer representation like "1", "2" and that "add" and "subtract" result in valus with a real representation like "1.000000" and "2.000000".
This is important by comparing values with an equal statement.

== Player rewards and penalties==
These methods work on the player, not any other ship.

'''awardCredits: <number>'''
// awards number of credits.

'''awardShipKills: <number>'''
// Adds to the number of kills accredited to the player

'''setLegalStatus: <number>'''
// Sets the bounty on the player's head.

'''setFuelLeak: <amount>'''
// removes this amount from the fuel tank every second
// until the tanks drain and self-seal

'''awardFuel: <amount>'''
// The amount can be positive or negative, expressed in LY of range
// the fuel level is adjusted to a maximum of 7.0LY and minimum of 0.0.

=== Equipment ===

'''awardEquipment: <equipment key>'''
// if the player doesn't have the equipment already
// and their ship can be equipped witth it then this fits the
// player's ship with the equipment given
// valid keys can be found in [[equipment.plist]] (they all begin '''EQ_'''):-
// EQ_FUEL
// EQ_MISSILE
// EQ_CARGO_BAY
// EQ_ECM
// EQ_FUEL_SCOOPS
// EQ_ESCAPE_POD
// EQ_ENERGY_BOMB
// EQ_ENERGY_UNIT
// EQ_NAVAL_ENERGY_UNIT
// EQ_DOCK_COMP
// EQ_GAL_DRIVE
// EQ_CLOAKING_DEVICE
// EQ_PASSENGER_BERTH
// EQ_HARDENED_MISSILE
// EQ_FUEL_INJECTION
// EQ_SCANNER_SHOW_MISSILE_TARGET
// EQ_MULTI_TARGET
// EQ_ADVANCED_COMPASS
// EQ_QC_MINE
// EQ_SHIELD_BOOSTER
// EQ_NAVAL_SHIELD_BOOSTER
// EQ_WEAPON_TWIN_PLASMA_CANNON
// EQ_MILITARY_JAMMER
// EQ_MILITARY_SCANNER_FILTER

'''removeEquipment: <equipment key>'''
// removes the indicated equipment from the player's ship

'''testForEquipment: <equipment key>'''
// tests whether the player ship has a piece of equipment installed
// returns the result in [[Methods#Results_from_other_methods|'''foundEquipment_bool''']]

=== Cargo ===

'''awardCargo: <amount> <[[Commodities|Commodity]] name>'''
// awards a quantity of the cargo named
// the cargo name must match the name in [[commodities.plist]] exactly
// only positive numbers are allowed.

'''removeAllCargo'''
// removes all cargo from the hold with no compensation to the player
// any special cargo is also removed (see below) restoring use of the cargo bay
// Gold, Platinum, and Gemstones are unaffected (they're in the cabin safe).

'''useSpecialCargo: <description of cargo>'''
// fills the cargo bay withthe cargo described, effectively
// disabling the use of the cargo bay until the cargo is removed.

=== Special ===

'''ejectItem: <[[shipdata.plist]] key>'''
// Creates a ship or other entity from [[shipdata.plist]] and ejects from
// the ship's aft hatch

'''launchFromStation'''
// forces the player ship to launch
// STATUS_LAUNCHING is skipped, so no script action on that moment.

== Communications ==

'''commsMessage: ''message'' '''
// sends the player a message in the form of a text string.
// if the message contains elements enclosed in square brackets ''[like_this]''
// that corresponds to a [[mission_variable]] or keys in [[misc plists|descriptions.plist]]
// or to special expansions like [commander_name] then these are expanded
// and substituted into the original message
//
'''consoleMessage3s: ''message'' '''
'''consoleMessage6s: ''message'' '''
// sends the player a message in the form of a text string with 3 or 6 second duration.
// if the message contains elements enclosed in square brackets ''[like_this]''
// that corresponds to a [[mission_variable]] or keys in [[misc plists|descriptions.plist]]
// or to special expansions like [commander_name] then these are expanded
// and substituted into the original message
// difference with commsMessage is that it is not stored in the comms file and can not be recalled by the player.
//
'''Special Expansions'''
//As well as [commander_name] the following are available;
//[commander_shipname] - Displays the name of the players ship, as specified by [[shipdata.plist]].
//{commander_rank] - Displays the players Elite rating.
//[commander_legal_status] - Displays the players current legal status.
//[Thanks-for-assist] - Err, thanks the player for their assistance.
//[Thargoid_curses] - Random Thargoid curses.
//[police_attack_warning] - Random warning of immediate(?) attack.
//%H - Will display the current system name; e.g., Isinor.
//%I - Displays the current system name with "ian" attached; e.g., Isinorian.
//%R - Random word.
// An (incomplete) excell sheet detailing the default [http://home.tiscali.nl/arexack/descriptions%20array.xls descriptions.plist]
//
//
//custom variable texts can be created by creating an array in a custom descriptions.plist,
//these can then be referenced like the above examples.
//Example of descriptions.plist entry:
//<key>beg-for-mercy</key>
// <array>
// <string>No!</string>
// <string>Help! Anyone!</string>
// <string>etc, etc</string>
// </array>

== Querying states ==

=== Player status ===

// '''mission_string'''
// returns the key for the current mission

// '''status_string'''
// returns one of:
// ''STATUS_AUTOPILOT_ENGAGED''
// ''STATUS_DEAD''
// ''STATUS_DEMO''
// ''STATUS_DOCKING''
// ''STATUS_DOCKED''
// ''STATUS_EFFECT''
// ''STATUS_ENTERING_WITCHSPACE''
// ''STATUS_ESCAPE_SEQUENCE''
// ''STATUS_EXITING_WITCHSPACE''
// ''STATUS_EXPERIMENTAL''
// ''STATUS_IN_FLIGHT''
// ''STATUS_IN_HOLD''
// ''STATUS_INACTIVE''
// ''STATUS_LAUNCHING''
// ''STATUS_TEST''
// ''STATUS_WITCHSPACE_COUNTDOWN''
// ''UNDEFINED''

// '''gui_screen_string'''
// returns one of:
// ''GUI_SCREEN_EQUIP_SHIP''
// ''GUI_SCREEN_INTRO1''
// ''GUI_SCREEN_INTRO2''
// ''GUI_SCREEN_INVENTORY''
// ''GUI_SCREEN_LONG_RANGE_CHART''
// ''GUI_SCREEN_MAIN''
// ''GUI_SCREEN_MANIFEST''
// ''GUI_SCREEN_MARKET'' //doesnt work (v1.69.1)
// ''GUI_SCREEN_CONTRACTS''
// ''GUI_SCREEN_MISSION''
// ''GUI_SCREEN_OPTIONS''
// ''GUI_SCREEN_SHORT_RANGE_CHART''
// ''GUI_SCREEN_STATUS''
// ''GUI_SCREEN_SYSTEM_DATA''
// ''GUI_SCREEN_SHIPYARD''
// ''UNDEFINED''

// '''galaxy_number'''
// returns a value between 0 and 7

// '''planet_number'''
// returns a value between 0 and 255

// '''score_number'''
// returns the number of the player's current ship kills

// '''credits_number'''
// returns the player's credits x10

// '''legalStatus_number'''
// returns the bounty on the players head

// '''fuel_level_number'''
// returns the fuel level in LY

// '''dockedAtMainStation_bool'''
// returns ''YES'' if docked at a systems main station, ''NO'' otherwise

// '''dockedStationName_string'''
// returns ''NONE'' if the player isn't docked, the name of the station (from [[shipdata.plist]]) if it is, ''UNKNOWN'' otherwise

=== Results from other methods ===

// '''shipsFound_number'''
// returns the number of ships found by ''checkForShips:''

// '''foundEquipment_bool'''
// returns the result of the last ''testForEquipment''
// returns ''YES'' if the equipment was found, ''NO'' otherwise

// '''missionChoice_string'''
// returns the result of the player's selection from a list of missionChoices
// returns ''UNDEFINED'' or the key for the chosen option

=== Random numbers ===

// '''d100_number'''
// returns a random value from 0 to 99

// '''pseudoFixedD100_number'''
// returns a random number from 0 to 99 that will always be the same for a certain system.

Starting with version 1.69 you can also use d256 numbers:
// '''d256_number'''
// returns a random value from 0 to 255

// '''pseudoFixedD256_number'''
// returns a random number from 0 to 255 that will always be the same for a certain system.

=== Time ===

// '''clock_number'''
// returns the game time in seconds
// '''clock_secs_number'''
// returns the game time in seconds
// '''clock_mins_number'''
// returns the game time in minutes
// '''clock_hours_number'''
// returns the game time in hours
// '''clock_days_number'''
// returns the game time in days

=== System states ===

// '''sunWillGoNova_bool'''
// returns whether the sun is going to go nova, either ''YES'' or ''NO''

// '''sunGoneNova_bool'''
// returns whether the sun has gone nova, either ''YES'' or ''NO''

// '''systemGovernment_string'''
// returns one of:-
// ''Anarchy''
// ''Feudal''
// ''Multi-Government''
// ''Dictatorship''
// ''Communist''
// ''Confederacy''
// ''Democracy''
// ''Corporate State''

// '''systemGovernment_number'''
// returns a value from 0 to 7

// '''systemEconomy_number'''
// returns a value from 0 to 7

// '''systemTechLevel_number'''
// returns a value from 0 to 14

// '''systemPopulation_number'''
// returns a value representing the system's population

// '''systemProductivity_number'''
// returns a value representing the system's productivity

// '''scriptTimer_number'''
// returns the script timer's current value in seconds. It resets on a witchspace jump '''(deprecated - do not use)'''

== Debugging scripts ==

'''debugOn'''
// sends script debugging messages to the console.

'''debugOff'''
// cancels script debugging messages

'''debugMessage: <message>'''
// sends the given message to the console. The message is written to the console regardless
// of whether debugOn has been performed or not. For GNUstep versions of Oolite, the console
// is a file called stderr.txt located in the game's installation directory. Mission variables
// and queriable states may be included in the message, eg:
//
// ''debugMessage: current galaxy is [galaxy_number]''

'''debug keys'''
// pause game to enable debug keys.
// press d for full debug-mode.
// press b for collision debug-mode.
// press c for octree debug-mode.
// press o for an object dump.
// a full list: [[Debug_Keys]]

== AI ==

Note that although most of these methods affect the player, some can also be utilised by an AI.
*[[OXP howto AI]].

[[Category:Oolite]]
[[Category:Oolite scripting]]

Talk:Realistic Shipyards

2008-05-15T16:16:41Z

SimonRaven: /* Issues and Requests */

== Issues and Requests ==

Due to the presence of the "hires" textures, my running oolite process bloats to around
800 MB virtual memory (ram + swap) in about 45 minutes of play, whereas without them, it stays
around 400-600 after 2-4 hours' play, including witchspace jumps.

Could there be one that has just the "lowres" or older textures, or at least a place where we can
drop them into Textures/ and Images/ ? My base is a Debian (Linux-based) box, 512 MB RAM,
radeon 9000 agp video.

[[User:SimonRaven|SimonRaven]] 07:42, 30 April 2008 (BST)

Update: turns out it was an error on my part, I thought I'd removed the System Redux from AddOns, but I hadn't.
Still had an issue with the "hires" textures from the ships, bloating the thing a bit too much to my
taste (but I get nitpicky about such things, so if I complain too much, just ignore the extra complaining hehe).

[[User:SimonRaven|SimonRaven]] 17:16, 15 May 2008 (BST)

Docking Computers

2008-05-04T19:42:48Z

SimonRaven: /* Use */ clarify keys a bit, and correct spelling of "queue"

By the time most [[Jameson]]s have acquired enough credits to afford this piece of equipment, they have learnt to dock manually with their optical recievers obscured (or were scraped from a dockingbay by auto-shovels). Nevertheless, this is a useful piece of AI to install in your vessel if you do not have a copilot, who can take over the helm should you feel an urgent need to visit the captains recreational cubicle. (Be advised that voiding the ships sanitation tanks while in dock or in the process of docking is prohibited and will be fined according to GalCop Art.2, sec.4a "unsanitary behaviour" and Art.1,sec.5 "vandalism of GalCop property" - punishments include cleaning the docking area of such noisome jetsam.)

Back to: [[Oolite Equipment]]

== Specification ==
The SinCorn RemLock D&A System is a sophisticated and expensive piece of gadgetry. It comes with MemmSomn Pilot Interaction to induce hi-cram sleep during the maneuvre.

== Use ==
Press '''c''' ("c") on your control console to activate, and to deactivate.
Autopilot will approach the station, ask for clearance and line up in the queue at the docking beacon and eventually dock.

Docking computers can save on minor collisions and accidents which cost Commanders money. A tired Commander can easily make a minor mistake that will not destroy the ship but may damage valuable ship systems.

=== Advanced Options ===
A soothing ancient melody will be replayed while activated as most space veterans get agitated at the slow and deliberate method of docking the AI uses, this can be switched on and off by pressing '''s''' ("s").

Holding '''shift''' and pressing '''d''' ("D") activates a hypnotic sleep inducer (MemmSomn Pilot Interaction) at the same time as the docking computers - this allows the pilot to sleep while the ship docks and awake refreshed when docking procedures are complete. This allows Commanders to devote more concentration on important commercial decisions once docked.

Holding '''shift''' and pressing '''c''' (˝C") contacts the targeted ship or station rather than the main station, permitting auto-docking with large vessels and non-standard space-stations.

== Availability ==
Pricetag: 1500.0 Cr.
Techlevel: 9

== Links ==
Back to: [[Oolite Equipment]]

[[Category:Oolite]]

Talk:Realistic Shipyards

2008-04-30T06:42:35Z

SimonRaven: New page: == Issues and Requests == Due to the presence of the "hires" textures, my running oolite process bloats to around 800 MB virtual memory (ram + swap) in about 45 minutes of play, whereas w...

Woma

2008-04-12T19:54:08Z

SimonRaven: /* Security */

{{Infobox ShipStats Oolite| title= Woma Fuel Transport
|image = [[Image:Oolite-woma.png|250px]]
|dimensions = 60 x 24 x 142
|capacity = N/A
|gunmounts = N/A
|maxspeed = 0.1 LM
|maneuverability = Roll: 0.4<br />Pitch: 0.8
|energybanks = N/A
|milshields = N/A
|shieldboost = N/A
|hyperspace = Yes
|isoxp = OXP
|isplayer = No
}}
== Overview ==

An unlikely sighting in poor and hazardous systems, this large mass of metal that is the Woma Fuel Transport Service moves a great deal of [[Quirium]] between systems of commerce, keeping stations in constant supply. Completing this task is usually done at notoriously slow pace as these are some of the most sluggish movers in populated space, and Woma pilots do not get paid by the hour.

==Security==

As pirates consider them an awkward beast, providing for Woma protection has
been something of a dilemma for [[FuelCorp]]. Since they will never be found
transporting anything of value other than the two silos containing fuel, which
may only be accessed with the apropriate, exclusive machinery, it is practically
a rule among pirates to ignore them.

[[Image:Womasep.png|thumb|280px|left|A Fuel Silo is dispatched]]

Considering this they are surprisingly often prone to vicious and futile, fatal
attacks. This is presumably carried out by vandals who do it just to see a big explosion.
Any other motive is hard to imagine.

Having counted the costs of years of indecision, FuelCorp has recently swallowed the
bitter pill, and has upped the level of protection with a fleet of dedicated
[[Sidewinder (Oolite)|Sidewinder]] escorts.

== Download ==

The [http://oosat.alioth.net/node/22 transports.oxp] containing the Woma.