Scripts within shipdata

Shipdata.plist scripts

Ships can have 4 different scripts that are executed on creation or disapearing of the ship
(Starting with Oolite 1.71 ships can also have a "script" entry that points to a JS script inside the scripts folder. When a js script is defined, none of the legacy scripts mentioned below will be used.)

setup_actions

setup_actions is executed very early in ship creation and is used for e.g. starting turrets.

<key>setup_actions</key>
<array>
    <string>initialiseTurret</string>
</array>

launch_actions

launch_actions is executed just before introducing by launching or addShips commands. The location is not yet defined, so a "spawn: my_ship 1" in launch_actions will still place a ship near the whitchspace point and not near the future appearing point of the ship. Escorts always get an esortAI.plist if added as escort, even if an other AI was defined in ai_type. You can overwrite it again to your AI with a setAITo: command in launch_actions.

<key>launch_actions</key>
<array>
    <string>switchAITo: my_escortAI.plist</string>
</array>

The same is valid for other default roles like trader, pirate, hunter, police, sunskim-trader. If added by the System Populator, a trader gets a route1traderAI and a pirate gets a pirateAI etc. If you want you ship to be added in one of the default roles but with your own AI you can redefine it here. (Only redefining the AI of ships with role "trader" will have the problem that traders are also launched by stations, but in that case with an exitingTraderAI.plist or a route2sunskimAI.plist. Launching can not be detected by the new custom AI, as the "LAUNCHED OKAY" message is released before the launch_actions are executed).

Setting the AI to a new one in launch_actions is replaced by the auto_ai key. Specially since 1.73 where also the System Populator will look at the auto_ai key. When you want escorts, traders, pirates or other standard roles to keep their custom AI it is enough to set auto_ai to false.

death_actions

The name death_actions is self explaining. It is executed on destruction of the ship. You can use it to set mission variables on destruction or release other items from the shipdata.plist

<key>death_actions</key>
<array>
    <string>set: mission_my_mission: DESTROYED</string>
    <string>spawn: my_items 5</string>
</array>

script_actions

script_actions is executed on disapearing of a ship from the system by docking or by being scoopped.

<key>script_actions</key>
<array>
    <string>awardCargo: 3 computers</string>
    <string>commsMessage: scooped 3 computers</string>
</array>

commands to use

Almost all normal script commands can be used and will always be executed as in the normal script. This can however give unpredictable results under ceirtain circumstances. Always be aware on who the script should act. Take for instance the scooping of items. If you use an awardCredits and the player scoops the item he gets the credits. If a NPC ship scoops the item the NPC ship should get the credits. This is unwanted as NPC ships can't have credits. So oolite explicit checks with some commands on whom the script acts. If it does not act on the player the script returns doing nothing. The following commands only work in scoopable items with script_actions that are scooped by the player and do nothing in death_actions or on scooping by NPC ships.

awardCredits:
awardShipKills:
awardEquipment:
removeEquipment:
awardCargo:
removeAllCargo

All other commands are executed under all circumstances and always set player parameters. e.g. setting mission_variables, awardFuel or using a consoleMessage3s will also be executed if a item is scooped by a NPC ship, even if the player is docked. A commsMessage is also always executed but within that command there is a check if the player is in scannerrange.

This can give very unwanted results. e.g. a NPC ship could scoop a barrel and set an mission_varriable as if the player did scoop it. In the old legacy script there is no explicit check who scoops a barrel. In javaSript this will be made possible.

The only way to figure out on who the script acts from within the script is to make use of the fact that some commands only act on the player. e.g. the awardCredits. If the credits change it is the player, if not it is a NPC ship.

<key>script_actions</key>
<array>
   <string>set: local_my_credits [credits_number]</string>
   <string>awardCredits: 1</string>
   <string>subtract: local_my_credits [credits_number]</string>
   <dict>
       <key>conditions</key>
       <array>
           <string>local_my_credits lessthan 0</string>
       </array>
       <key>do</key>
       <array>
           <string>awardCredits: -1</string>
           <string>"your stuff if scooped by player"</string>
       </array>
       <key>else</key>
       <array>
           <string>"your stuff if scooped by NPC ship"</string>
       </array>
   </dict>
</array>

Take note that Oolite legacy script does not allow you to compare two variables directly against eachother. So we need the subtraction command to compare the difference against the constant 0

Return to shipdata.plist