Shipdata.plist

shipdata.plist will provide Oolite with all the definitions necessary to include it as an entity in the game, be it ship, station, freak object or sub-entity (extra). The following (property) entries are, for order's sake, listed alphabetically:

accuracy

Used with missiles it has influence on tracking of target. Allowed values with missiles are between 0.0 and 10.0. When not defined, the system assings to the missile the accuracy value of 0.0, which corresponds to the standard missile tracking behaviour.

Used with NPC ships it enlarges the chance of shooting at greater distances. Value with NPC ships is between -5 and 10.

Example:

"accuracy" = 8;

aft_eject_position

Determines the XYZ point on the model from which cargo is ejected.

Example:

"aft_eject_position" = "0.0 -4.5 -23.0";

aft_weapon_type

Assigns the ship's laser. Any weapon type from the equipment.plist can be used (and WEAPON_NONE).

Example:

"aft_weapon_type" = "WEAPON_BEAM_LASER";

ai_type

Assigns an AI to the entity. This may be a previously existing AI, or one custom made for the occasion.

Example:

"ai_type" = "pirateAI.plist";

allows_auto_docking

This property was added in Oolite test release 1.75.
When set false for a station, this station will not allow the use of a docking computer. Default value in "yes".

Example:

allows_auto_docking = "no";

allows_fast_docking

This property was added in Oolite test release 1.75.
When set true for a station, this station will allow fast docking with the docking computer. Default value in "no".

Example:

allows_fast_docking = "yes";

auto_ai

This will autoswitch the ai to the appropriate one if a ship was added in one of its standard roles like trader or pirate. (true by default). See also the comment in the autoAIMap.plist inside Oolite. Defining auto_ai is only necessary when using one of the standard roles mentioned in the autoAIMap.plist for your ship. auto_ai does nothing for ships with custom roles. Example:

"auto_ai" = yes;

This auto_ai switch is also used for bounties. When auto_ai is false the ship will keep the bounty as defined for the ship but, when true and the ship is added in one of the populator roles, the ship will get the default bounty for that role.

beacon

A special feature for beacons and navigation aids. The string can be anything - the first letter is what's displayed in the advanced space compass.

Example:

"beacon" = "X-code";

The following characters are known to be used as identifiers for stations and other fixed objects (listed with their respective OXPs):

A = Astromine (Commies)
B = Black Monk Monastery (Black Monks)
    A Seedy Space Bar (Random Hits)
    Nemeanian Military Base (Assassins)
C = CoachWhip hOopy Casino (Hoopy Casino)
    Pi-42 Con Store (Your Ad Here)
F = Collective Zero-G Factory (Commies)
    Collective SLAPU (Commies)
    Imperial AstroFactory (Dictators)
G = Griff Research Ltd Orbital Base (Assassins)
    GRS Buoy Factory (GRS Buoy Repair)
H = Hacker Outpost (Anarchies)
    Deep Space Hoopy Hotel : Hades Branch (Assassins)
L = The Link Base (Ionics)
    Deep Space Hoopy Hotel : Lernean Branch (Assassins)
N = Main Station Beacon
P = Tianve Pulsar Monitoring Station (Tianve)
R = Rock Hermit (Rock Hermit Locator)
    Augeaian Orbital Repair Facility (Assassins)
    Rebel Outpost (Assassins)
Q = Hesperides Wiseguy Way-Station (Assassins)
S = Navy SecCom Station (Galactic Navy)
    Special Branch Orbital Headquarters (Assassins)
T = Taranis Corporation HQ (Taranis)
W = Witchpoint Buoy
Z = Free Trade Zone (Free Trade Zone)

The following characters are known to be used for non-station objects that may appear anywhere:

H = Homing Beacon (ett Homing Beacon)

The following characters should not be assigned easily to stations or ships that are supposed to appear anywhere, because they are likely to be used for ships in other OXPs:

M = Mark
T = Target
V = Victim
X = general marker
+ = general marker

Starting with Oolite 1.73 we can also use custom icons with the compass. For that you must define a key in descriptions.plist with the same name as one of the roles of the ship with beacon. Than define the icon in the same way as missile icons. (An array of x/y-coordinates that will be connected by lines)

"fuelStation_location" =  (1, 2, -3, 2, -3, -4, 3, -4, 3, 4,  -3, 4, -3, 3, 2, 3, 2, -3, 1, -3 );

bounty

Sets a Cr. reward on the NPC's head, and is bound to give it trouble with the law . This bounty setting is overruled when adding ships in one of the populator roles like pirate, trader etc. Pirates are default added with a small bounty and traders are added clean. However, like the player, also the npc bounty can raise when attacking other clean ships or police vessels.

Example:

"bounty" = 50;

cargo_carried

Determines the type of cargo carried as described in commodities and commodities.plist. Only one type can be specified. This key can be used for both ships and barrels.

Example:

"cargo_carried" = "Gold";

When used for barrels, it is also possible to add several units in a pod by preceding the commodity name with a space separated number. Adding more than a ton in a pod is not possible. Defining a quantity for ships is not possible this way.
Since Oolite 1.74 it will also be possible to define a mix of random cargo for ships by using the string "SCARCE_GOODS" or "PLENTIFUL_GOODS", instead of a commodity name. The first selects random goods that are scarce at the main station, the second selects goods that are plentiful present at the main station. (Populator added traders heading toward the station always have scarce goods while traders heading from the main station always have plentiful goods on board. It would be wise to stick to this rule with custom ships.)
To make cargo_carried working for ships, the cargo_type must be "CARGO_NOT_CARGO" to define the ship not being cargo itself. (see below)

cargo_type

Determines if object is indeed cargo (CARGO_RANDOM, CARGO_SLAVES, CARGO_THARGOID, CARGO_ALLOY, CARGO_MINERALS, CARGO_CARRIED) or a ship, as below, which is not cargo. Works since Oolite 1.71 also for pods spawn by a script. CARGO_CARRIED needs in addition an second key cargo_carried that specifies the cargo. (see below)

Example:

"cargo_type" = "CARGO_RANDOM";

More control of contents of barrels is available through the CARGO_CARRIED string.

Example:

"cargo_type" = "CARGO_CARRIED";
"cargo_carried" = "4 Gold";

You can also specify the cargo of a ship. use "cargo_type" = CARGO_NOT_CARGO and define the contents of the barrels it will give with "cargo_carried". In that case there must be no quantity defined, only the type of commodity.

Example:

"cargo_type" =  "CARGO_NOT_CARGO";
"cargo_carried" = "Computers";

Another notable type of cargo is the scripted item CARGO_SCRIPTED_ITEM, as examplified by the cloacking device. When CARGO_SCRIPTED_ITEM is defined, the barrels will trigger scooping events for the ship-scripts. Other barrels don't trigger scooping events.
Until 1.74 such scripted barrels were removed from the system after scooping. Starting with 1.74 the barrels are stored in the ships hold like normal barrels when a cargo was defined for them with the JS method "setCargo". Scripted cargo works with any object that can be scooped. When you have scripted escape pods that must be preserved, fill it with one ton of Slaves.

cloak_passive

When true, any firing of laser will deactivate the cloak. (False by default)

Example:

"cloak_passive" = yes;

conditions

Whit this option you can include an array of extra conditions when to add a ship. When the conditions are not met, the ship does not appear in a selection list by role. Useful when you have a standard ship like a trader that should only be added in certain systems.

Example:

"conditions" = ("systemGovernment_number equal 3",
                "systemEconomy_number lessthan 4"
               );

custom_views

Will add the ability to display custom POVs of the player ship, in game toggled by pressing v.

This is an array with any number of entries, one for each view, each with:

• a view_description - giving a textual description of the view.
• a view_position - relative to the origin of the ship model.
• a view_orientation - this is a quaternion expressing a rotation from directly forwards.
• a weapon_facing - FORWARD, AFT, PORT or STARBOARD. The weapon that will fire when that view is selected.

The view_position is best chosen by selecting a facet, line or point in Wings and copying down the coordinates.

For the view_orientation you will probably need a calculator but the basic method is to choose a unit vector (x y z) as the axis for a rotation then calculate the four values W X Y and Z for the quaternion as follows:

W = the cosine of half the angle rotated about the axis xyz
X = the sine of half the angle rotated about xyz, multiplied by x
Y = the sine of half the angle rotated about xyz, multiplied by y
Z = the sine of half the angle rotated about xyz, multiplied by z

Four decimal places are probably enough accuracy for these values.

Example:

 custom_views =
(
    {
        view_description = "Front View";
        view_orientation = "0.0 0.0 1.0 0.0";
        view_position = "0.0 30.0 200.0";
        weapon_facing = "FORWARD";
    }
);

death_actions

Gives an opportunity to have a ship's death trigger one or a set of script_actions. It contains an array of legacy script expressions.

Example:

"death_actions" = ("spawn: explosive_shrapnel 1");

debris_role

Specifies the kind of debris an asteroid or boulder generates. When not defined they default to generating 'ships' with role "boulder" or "splinter". (Key added with Oolite 1.74)

Example:

"debris_role" = "my_boulder_foo";

defense_ship

Gives an oportunity to designate a particular ship by name that will defend a station/carrier. When launched from a carrier the scanclass becomes that of the carrier.

Example:

<key>defense_ship</key>
<string>my_defender</string>

defense_ship_role

Gives an oportunity to designate a particular (group of) ships that will defend a station/carrier. This has to be specified in the roles of the ship(s) that are assigned to defend. When launched from a carrier the scanclass becomes that of the carrier.

Example:

<key>defense_ship_role</key>
<string>carrier_defenders</string>

density

This real value is used to calculate a ships total mass. Default is 1.0

Example:

<key>density</key>
<real>1.5</real>

display_name

States the model's name as it will be known to the ID computer. By default this is the same as "name". Added for multilingual oolite.

Example:

<key>display_name</key>
<string>ExampleShip Mark IX</string>

docking_pattern_model

The name of the .dat file that is used for displaying the docking pattern for this station only. Default is ring.dat. (Introduced in version 1.74)

Example:

<key>docking_pattern_model</key>
<string>ring.dat</string>

energy_recharge_rate

The rate at which energy is replenished. Stations are at 100, Adders at 2. (Default value: 1)

Example:

<key>energy_recharge_rate</key>
<real>3.5</real>

escape_pod_model

With this entry ships can have custom escape pods. (starting from version 1.65) You have to specify the role of your custom escape pod (not its entry-name).

Example:

<key>escape_pod_model</key>
<string>custom_pod</string>

escorts

Determines how many escorts an NPC shall have. Maximum is 16. In save systems Oolite may randomly decide to subtract escorts from the defined value.

Example:

<key>escorts</key>
<integer>4</integer>

Warning: Ships with scanClass = CLASS_POLICE should always have escorts set to zero. Oolite will set this value here and add wingmans instead of escorts. Without special scripting escorts won't escort a mother with CLASS_POLICE.

escort-role

Assigns the specific ship type to be the escort, by the ship's role. (Starting with Oolite 1.74 also the name "escort_role" is accepted.)

Example:

<key>escort-role</key> 
<string>my_custom_escort_role</string>

Warning: Only usable since Oolite 1.71. It will use the AI file defined in shipdata for this escort and will not use any default escortAI. So make sure the summoned escort has an AI defined in its entry that is capable of supporting escorting.

escort-ship

Assigns the specific ship type to be the escort, by the ship's name. (Starting with Oolite 1.74 also the name "escort_ship" is accepted.)

Example:

<key>escort-ship</key>
<string>cobramk1</string>

equipment_price_factor

Equipment price mask for dockables.

Example:

<key>equipment_price_factor</key>
<real>4.5</real>

equivalent_tech_level

Sets shipyard tech level for dockables, different to the local system techlevel.

Example:

<key>equivalent_tech_level</key>
<integer>1</integer>

exhaust

The XYZ position(s) of exhaust plume(s), and the XYZ of the plume shape, ergo

x y z width height length

x y z is the position relative to the origin of the main model.

width in meters, how wide a plume is on x axis. (x radius)

height in meters, how tall a plume is on y axis. (y radius)

length in meters, how long a plume is on z axis. (This value is in current Oolite versions ignored. Length is now derived from the ships speed)

Below are 2 assigned plumes at coords 5, 0, -25 and -5, 0, -25, and each plume is 6 m wide and 4 m tall. (length info is ignored)

Example:

<key>exhaust</key>
<array>
    <string>5 0.0 -25 6.0 4.0 10.0</string>
    <string>-5 0.0 -25 6.0 4.0 10.0</string>
</array>

extra_cargo

Cargobay extension size can now be customised. This is the amount the cargo capacity increases when an extra cargobay is installed. Default value is 15. It is only used with player ships.

Example:

<key>extra_cargo</key>
<integer>value</integer>

forward_weapon_type

Assigns the ship's laser. Any weapon type from the equipment.plist can be used (and WEAPON_NONE).

Example:

<key>forward_weapon_type</key>
<string>WEAPON_BEAM_LASER</string>

frangible

Determines if eventual sub-entities are "loose". By default any given object is already frangible, so the use of this line must be to negate that. If set to false, the object plus subentities will be regarded as a single object. If set to true, sub entities can be destroyed seperately from the main object. Frangible sub-entities can have a max_energy and an energy_recharge_rate that is independently set from the main entity.

Example:

<key>frangible</key>
<false/>

fragment_chance

Determines if a ship breaks apart into fragments and generates parts with role "wreckage". By chance factor, or true/false. Default is 90% chance. The amount of wreckage is based on the ships mass with a maximum of 3. Wreckage is scaled to match the ships size but is very short living. (0.25s -> 1.25s)

Example:

<key>fragment_chance</key>
<false/>

fuel

Determines an NPC ship's fuel storage, which will affect how it uses its Fuel Injectors.

Example:

<key>fuel</key>
<integer>70</integer>

has_cloaking_device

Determines if a ship has a cloacking device installed. By chance factor, or true/false.

Example:

<key>has_cloaking_device</key>
<real>0.5</real>

has_ecm

Determines if a ship has the E.C.M system installed. By chance factor, or true/false.

Example:

<key>has_ecm</key>
<real>0.5</real>

or

<key>has_ecm</key>
<false/>

has_energy_bomb

Determines if a ship has an energy bomb. If it has one, it might launch a mine with role "energy_bomb" as part of his fleeing behavior. currently the only build-in mine with this role is the q-bomb.
A ship will only deploy the bomb when it has also fuel-injectors and some fuel left to avoid getting killed by its own bomb. On average it will try to deploy the bomb once every 100 seconds during fleeing.

Example:

<key>has_energy_bomb</key>
<false/>

has_escape_pod

Determines if a ship has an escape pod. Can be either a boolean value, or a number from 0 to 1 expressing the likelihood of the equipment being present. Starting with version 1.65 ships can have multiple escape pods. To specify more than one escape pod, has_escape_pod must be set to a numeric value corresponding to the escape pods present on board.

Examples:

has_escape_pod = no;
has_escape_pod = 0.75;
has_escape_pod = 3;

XML example:

<key>has_escape_pod</key>
<false/>

has_fuel_injection

Determines if a ship has the witchdrive fuel injector.

Example:

<key>has_fuel_injection</key>
<real>0.99</real>

has_military_jammer

Determines if a ship has a military jammer. Ships equipped with this item become invisible on the radar. Example:

<key>has_military_jammer</key>
<real>0.75</real>

has_military_scanner_filter

Determines if a ship has a military jammer filter. Ships equipped with this item can see ships equipped with a military jammer on the radar. Example:

<key>has_military_scanner_filter</key>
<real>0.50</real>

has_npc_traffic

Determines if a station has NPC traffic (carriers are treated as stations, too). Default is "YES", when set to NO the station will not launch random traders.

Example:

<key>has_npc_traffic</key>
<true/>

has_scoop

Determines if a ship has a fuel/cargo scoop.

Example:

<key>has_scoop</key>
<false/>

has_scoop_message

A key for cargo. Determines if a barrel generates a default scoop message when scooped. Default is true, but setting it to false suppresses any messages, so a scripts can generate its custom messages on scooping. (Added with Oolite 1.74)

Example:

<key>has_scoop_message</key>
<false/>

has_shield_booster

Determines if a ship has the shield booster. (enlarges max energy with 256)

Example:

<key>has_shield_booster</key>
<real>0.80</real>

has_shield_enhancer

Determines if a ship has the coveted shield enhancer. (enlarges max energy with 256 and raises energy recharge rate with 50%)

Example:

<key>has_shield_enhancer</key>
<real>0.45</real>

has_shipyard

Determines if a station or carrier has a shipyard. By chance factor as number between 0 and 1, but it can also be an array of conditions. (Name is valid starting with Oolite 1.74. Before it was called "hasShipyard".)

Example:

<key>has_shipyard</key>
<real>0.75<real/>

heat_insulation

This real number gives the amount of heat insulation of a ship. Default is 1.0 Only for NPC ships. Playes ships can have the equipment EQ_HEAT_SHIELDING with gives the player than a heat_insulation of 2.0

Example:

<key>heat_insulation</key>
<real>2.0</real>

hud

Used for a playership, to assign another HUD than the default one.

Example:

<key>hud</key>
<string>specialhud.plist</string>

hyperspace_motor

If set to false / NO, it will stop ships from executing normal hyperspace jump (player ships will still be able to execute galactic jumps). Default = true / YES. (Planned for Oolite 1.75)

Examples:

<key>hyperspace_motor</key>
<false/>

hyperspace_motor=NO;

hyperspace_motor_spin_time

Used to modify jump countdown time. Default = 15.

Examples:

<key>hyperspace_motor_spin_time</key>
<integer>15</integer>

hyperspace_motor_spin_time=15;

is_carrier

Added as a tag for making the model be considered a carrier or station. An alternative to including carrier or station among the roles. When present this key even overrules station/carrier settings with roles. (Name is valid starting with Oolite 1.74. Before it was called "isCarrier".)

Example:

<key>is_carrier</key>
<true/>

is_submunition

Key added for missiles with multiple warheads. When this key is set and the entity is spawn or fired by a missile, it inherits its parent as owner. This key must be set so the player will be awarded for a kill by submunition.

Example:

<key>is_submunition</key>
<true/>

is_template

Set this to yes/<true/> for ships which are only used through like_ships and are not intended to be used directly. If your (otherwise working) OXP generates warnings about ships with no roles or model attribute, you probably need this.

Example:

<key>is_template</key>
<true/>

laser_color

Determines a ship's laser colour.

In Oolite 1.69 and later, this is any colour specifier. In earlier versions, it must be a named colour. Also as of 1.69, the game requires laser colours to be reasonably bright; if the brightest colour component is less than 0.5, the colour will be brightened.

Example:

<key>laser_color</key>
<string>cyanColor</string>

launch_actions

Triggers a script on the entity just after setup, also when called by spawn and addShip methods. Can be used to change to a custom AI, when a ship is generated by standard role. script_actions

Example:
"role = trader"
<key>launch_actions</key>
 <array>
  <string>setAITo: pirateAI.plist</string>
 </array>

like_ship

Allows a shipdata entry (of a ship with many matching characteristics to another) to be short and sweet. With like_ship you can reference to another existing shipdata entry, and then only specify the differences to the 'original'. It takes the unique entry-identifier as argument. Of course you have to make sure that the 'original' you are referring to actually exists, or Oolite won't be able to create your ship.

Works well together with the is_template-key.

Example:

<key>like_ship</key>
<string>adder</string>
<key>max_flight_speed</key>
<real>700</real>
<key>name</key>
<string>Freak Turbo Adder</string>

likely_cargo

This is only used for ships with role asteroid and pirate. With asteroids it gives the likely number of boulders it breaks into. With pirates added by the System Populator: when lower than 16 it is the cargo, when higher than 15, it is changed in a random value between 0 and 15. This value is overridden by the actual scooped cargo if the pirate had scooped something.

Example:

<key>likely_cargo</key>
<integer>2</integer>

market

Key that sets the market for stations and carriers. The name defines the key in commodities.plist that will be used as local market. Without a market key, the stations primaryRole is used as market. Added with test release 1.74

Example:

<key>market</key>
<string>none</string>

materials

See Materials in Oolite.

max_cargo

Sets the ship's cargo limit. On explosion of trader ships added by the System Populator, 10% of this value is used as likely cargo. When the result is lower than 16 it is the cargo, when higher than 15, it is changed in a random value between 0 and 15.

Example:

<key>max_cargo</key>
<integer>5</integer>

max_defense_ships

Designates how many ships a dockable entity (station, carrier) can launch in defense. See also Station Ships

Example:

<key>max_defense_ships</key>
<integer>10</integer>

max_energy

Sets the ship's energy value. (Default value: 200)

Example:

<key>max_energy</key>
<real>300</real>

max_flight_pitch

Sets pitch factor. Will usually range from a sluggish 0.6 to a very sensitive 3.0

Example:

<key>max_flight_pitch</key>
<real>2.2</real>

max_flight_roll

Sets roll factor. Will usually range from 0.8 to 4.6.

Example:

<key>max_flight_roll</key>
<real>4.2000000000000002</real>

max_flight_speed

Sets the model's top speed. Interceptors fly at 520 (0.52 LM), Shuttles at 80.

Example:

<key>max_flight_speed</key>
<real>320</real>

max_flight_yaw

Sets yaw factor. Will usually range from a sluggish 0.6 to a very sensitive 3.0 When no value is defined it will use the same value as max_flight_pitch

Example:

<key>max_flight_yaw</key>
<real>2.2</real>

max_missiles

Sets a ship's missile limit. Maximum allowable value for the player is 16 and for npc ships 32. When not defined, the value with "missiles" is used as max_missiles. When defining more than a few missiles, it could be wise to also define value for "missile_load_time" to avoid massive missile launches. npc ships are more likely to fire missiles the more they carry.

Example:

<key>max_missiles</key>
<integer>1</integer>

max_police

Designates how many police or patrol ships a dockable entity (station, carrier) can launch. See also Station Ships

Example:

<key>max_police </key>
<integer>10</integer>

max_scavengers

Designates how many scavengers or miners a dockable entity (station, carrier) can launch. See also Station Ships

Example:

<key>max_scavengers</key>
<integer>10</integer>

missile_launch_position

Determines the XYZ point on the model from which a missile is launched.

Example:

<key>missile_launch_position</key>
<string>0.0 -2.25 10.0</string>

missile_load_time

Defines the time in seconds before a new missile is ready to fire after one is fired. Mainly useful for npc ships that have many missiles. Added with test release 1.74

Example:

<key>missile_load_time</key>
<string>2.1</string>

missiles

Sets a ship's probable number of missiles.

Example:

<key>missiles</key>
<integer>0</integer>

missile_role

Defines the entity that is launched as missile. Can specify a certain missile-type or any other ship-entity by role. Only applies to NPC's, player-ship dependacies must be defined in the shipyard.plist. If no missile_role is defined and a NPC ship launches a missile he most often chooses the default missile but sometimes chooses one at random from all ships with role missile inside one of the installed OXP's.

Example:

<key>missile_role</key>
<string>thargon</string>

model

Assigns the entity's corresponding .dat file that will be found with the exact same name in the Models folder.

Example:

<key>model</key>
<string>example_ship.dat</string>

name

States the model's name as it will be known to the ID computer.

Example:

<key>name</key>
<string>ExampleShip Mark IX</string>

no_boulders

With older versions, scripted asteroids had no boulders by default. Starting with 1.70 all asteroids produce boulders when hit by a mining laser. no_boulders can overwrite this to emulate the old situation. By chance factor, or true/false.

Example:

<key>no_boulders</key>
<true/>

pilot

Gives the ship a predefined pilot, defined in characters.plist. Can eject in pod, if available, and be captured.
By default every object starts with a pilot except buoys, missiles, cargo and rocks. By defining a specific pilot, any default pilot is replaced or a pilot is added to previously unpiloted objects.

Example:

<key>pilot</key>
<string>constrictor-mission-thief</string>

port_dimensions

Defines the size of the docking port and takes 3 numbers, separated by "x". This key is generally of little use and can be skipped as it becomes overwritten by the actual size of the bounding box of the dock subentity when a correct dock subentity is defined.

Example:

<key>port_dimensions</key>
<string>65x30x500</string>

Size of Oolites main-station dock is: 64.00 x 192.00 x 250.00 while the dimension of a rock-hermit dock is: 138.001 x 138.001 x 250.12 (W x H x L)
These sizes may be relevant for ship dimensions as since Oolite 1.75 ships must fit in these docks to be allowed docking or launching.

port_radius

Defines the size of the docking port radius. Or more precise, this is the distance from the station centre to the port location. Default value is 500. This key is generally of little use and can be skipped as it will be overwritten by the real position of the dock subentity.

Example:

<key>port_radius</key>
<string>500</string>

requires_docking_clearance

Sets the requirement for docking clearance. Default is false. See also DockingClearance

Example:

<key>requires_docking_clearance</key>
</true>

roles

Assigns which role(s) the entity should have, that can correspond to one specific, exclusive use, or several.

The game engine constantly calls for generic roles to populate the universe. In the example below the ship in question will be considered twice as often (2.0) when a trader is called for, only one quarter as often (0.25) when looking for a hunter, and as often as any other pirate ships when looking for a pirate.

NB: If the ship cannot be docked to, extra care should be taken to avoid using the words station or carrier as part of any of the ship's role names. When either of these words are inside the roles key, the ship is automatically given station attributes. Other ships might even fruitless try to dock with it, and it will affect how some ships / entities are shown on the scanner.

Example:

<key>roles</key>
<string>hunter(0.25) trader(2.0) pirate</string>

or an exclusive role, simply:

<key>roles</key>
<string>uniquely_named_role</string>

This has the benefit of being the only ship to be selected when a script calls for the uniquely_named_role ship.

An item from the commodities can also be named as a role, for when that commodity is floating in space and called upon, to be represented by a particular model.

Example:

<key>roles</key> 
<string>Gold</string>

Some roles are used by the game engine to populate systems, detect and define properties. (see also the System Populator) Such roles include 'thargoid', 'missile' and 'energybomb'. Externally used equipment also needs specific mention of role, for example EQ_*_MINE and EQ_*_MISSILE.

rotating

Given to a station when rotation is desired.

Example:

<key>rotating</key>
<true/>

rotational_velocity

May be applied to a sub-entity, like the following entry to the subentity spines of the Weeviloid Hunter. Takes the form of quaternions. The following example enables rotation around the Z-axis.

Example:

<key>rotational_velocity</key>
<string>0.707 0.0 0.0 0.707</string>

scan_class

Will alter the model's appearance on the IFF system. If this line is omitted, it will become by default a standard ship entity, appearing as yellow flag on the radar. There are other options.

• CLASS_BUOY
• CLASS_CARGO
• CLASS_MILITARY
• CLASS_MISSILE
• CLASS_POLICE
• CLASS_ROCK
• CLASS_STATION
• CLASS_THARGOID
• CLASS_NO_DRAW

(Name is valid starting with Oolite 1.74. Before it was called "scanClass". Also starting with 1.74 is that scripts can define custom colours for ships on the IFF system so ships might have an other scan_class as is seams.)

Developer Note

Oolite uses scan_class internally to determine the behaviour of some ships (particularly with regard to who may shoot whom without incurring legal penalties). Bear this in mind and don't allocate CLASS_POLICE or CLASS_THARGOID to ships lightly!

Example:

<key>scan_class</key>
<string>CLASS_ROCK</string>

scanner_range

Sets a custom scanner range. Standard is 25.6 km, thargoids have 50 km. Only applies to NPCs. However, at least since oolite 1.65 all defined scanner ranges are limited to 25.6 km, even for thargoids. This means it only makes sense defining shorter ranges than the maximum range.

scoop_position

Determines the XYZ point on the model from which cargo is scooped. (default is 0,0,0)

Example:

<key>scoop_position</key>
<string>0.0 -4.5 -23.0</string>

script

Specifies a JavaScript script to attach to the ship. Ship scripts were introduced with Oolite test release 1.70, and are the preferred approach to scripting ships in new versions of Oolite.

script_info

A property list whose contents are available to JavaScript scripts, for whatever use they desire. It is exposed to JavaScript as the scriptInfo property of Ship objects.
Take note that when using an ascii plist, the JS engine will read in all entries as strings. When you need an entry as number, you might need to explicit convert it to a number. This is specially true for booleans as a "NO" string will be read as true. For all normal keys its Oolite that does the conversion for you.

script_actions

Gives an oportunity to insert events such as in script.plist, to involve a specific shipdata entity. As seen in the following example, this particular object checks if Player has a cloaking device, and if not, will award it. Should Player already have it, the gift will be in gold. See also scripts within shipdata for more detailled info.

Example:

<key>script_actions</key>
<array>
    <string>debugOn</string>
    <string>testForEquipment: EQ_CLOAKING_DEVICE</string>
    <dict>
       <key>conditions</key>
       <array>
          <string>foundEquipment_bool equal NO</string>
       </array>
       <key>do</key>
       <array>
          <string>awardEquipment: EQ_CLOAKING_DEVICE</string>
       </array>
       <key>else</key>
       <array>
          <string>awardCargo: 100 Gold</string>
       </array>
    </dict>
    <string>debugOff</string>
</array>

setup_actions

Arranges a process that may be necessary for some objects, like ball turrets.

Example:

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

shaders

The shaders dictionary has the same structure as the materials dictionary. When shaders are available, the contents of the shaders dictionary are used in preference to those in materials. If shaders are not available, the shaders dictionary is ignored.

smooth

Determines if the model will use glLightModel(GL_FLAT) or glLightModel(GL_SMOOTH).

If true, then lighting effects will be interpolated across the polygons of the model, giving a more 'rounded' effect.

Asteroids, Boulders and Splinters use this effect as do some other models.

Example:

<key>smooth</key>
<true/>

spawn

The spawn directory is only used when a ship is added with the command: "spawnShip: shipname". This command only allows to add one ship by name (not role!). The position and orientation are taken from a spawn directory that describes the position it is placed and the position it is looking at.

Example

<key>spawn</key>
<dict>
      <key>facing_position</key>
      <string>spu 0 0 0</string>
      <key>position</key>
      <string>wpu 0 0 0.2</string>
</dict>

station_roll

Determines the rotation speed of a station. Default value is determined by the systemwide station_roll in planetInfo.plist. If that is not defined, the default is 0.4. Negative values are also possible for a rotation in the other direction. (Key is added in Oolite 1.74.2)

Example:

<key>station_roll </key>
<string>-1.5</string>

subentities

An array of subentity definitions. A subentity is an object attached to your ship. There are several types of subentity:

• Static subentities, the default type, are simply extra models. They are defined as separate shipdata.plist entries, so technically they’re ships, but they don’t have a mind of their own. If the main ship is frangible, static subentities can take damage and blow up separately from the main ship. They can also be individually exploded or removed by scripts.
• Docks are recognized when setting up a station or carrier, and used to determine the station’s docking port parameters. After set-up, they work just like normal static subentities. The string "dock" in lowercase must be part of the old style name in order to get recognised as the dock subEntity.
• 'Ball turrets turn to track the ship’s current target, and shoot plasma balls if the target is within range (6000 metres). A ball turret’s field of fire is a 157 ° cone centred on its original facing. Currently, ball turrets make no effort not to shoot their own ship, so it is up to the designer to ensure this field of fire is clear. Like a static subentity, a ball turret is based on a shipdata.plist entry so its appearance can be customized. Oolite 1.72 or later provides a built-in shipdata entry for ball turrets called, imaginatively, ballturret.
• Flashers are blobs which glow with a pulsating light. From Oolite 1.74 onwards, constant light will also be an option. Note that while flashers appear luminous – they are unaffected by shadows – they do not cast light on other objects.

New-style subentity definition

Oolite 1.73 introduced a more flexible, dictionary-based way of specifying subentities. A new-style subentity is a dictionary using the following keys:

Subentity definition properties

Name	Type	Description
type	string	One of: “standard”, “ball_turret”, “flasher”. If not specified, “standard” is assumed.
subentity_key	string	The key of a shipdata.plist entry. Required for standard and ball_turret subentities, ignored for flashers.
position	vector	The position of the subentity relative to its parent. (This can be specified as a string with three numbers in it, or an array of three numbers, or a dictionary with x, y and z entries.) Default: (0, 0, 0).
orientation	quaternion	The orientation of the subentity. Ignored for flashers. (This can be specified as a string with four numbers in it, or an array of four numbers, or a dictionary with w, x, y and z entries.) Default: (1, 0, 0, 0), which corresponds to no rotation.
is_dock	boolean	True if the subentity is a dock; false by default. Only applies to standard subentities. Note: this is not implied by having “dock” in the subentity_key, as it is for old-style subentity definitions.
fire_rate	number	Interval between shots in seconds, for ball_turret subentities. Default: 0.5; minimum: 0.25.
color	colour specifier	Single colour for a flasher. Ignored for non-flashers. Default value: redColor.
colors	array	Array of colour specifiers for a flasher. Ignored for non-flashers. Before 1.74, only the first entry was used. If not present, see color. Note: like laser_color, flasher colours must be “reasonably bright”.
frequency	number	Pulse rate for flashers, in cycles per second. Ignored for non-flashers. If 0, the flasher will have full intensity all the time in Oolite 1.74 and later, but half intensity in earlier releases. Default: 2.
initially_on	boolean	Specifiers whether a flasher is turned on when created. Ignored for non-flashers. Default: yes.
phase	number	Pulse phase offset for flashers, in seconds. Ignored for non-flashers. (This value is simply added to the time to get the pulse parameter.) Default: 0.
size	positive number	Diameter of a flasher in metres. Ignored for non-flashers. Default: 8. (Why 8? I don’t remember.)

Old-style subentity definition

Prior to Oolite 1.73, this was the the only way to specify a subentity.

An old-style subentity definition is a string with eight items separated by spaces. In the description below, words in bold correspond to keys in new-style definitions. There are two variants:

Flashers

For a flasher, the entry takes the form:

*FLASHER* x y z hue frequency phase size

*FLASHER* must be precisely the string “*FLASHER*”, in capitals.

x, y and z form the position.

hue specifies the HSV hue component (in degrees) of color. Saturation and value are always 1.

frequency, phase and size are the same as in the new-style format.

initially_on is false.

Other subentities

For a non-flasher, the entry takes the form:

key x y z qw qx qy qz

key corresponds to subentity_key.

x, y and z form the position.

qw, qx, qy and qz form the orientation.

type is standard unless the command initialiseTurret is present in the setup_actions of the subentity, in which case it is ball_turret. Note that the initialiseTurret no longer does anything when executed in a script; its presence is only used as an indicator to set the is_turret property when old-style definitions are translated. If initialiseTurret is inside a condition, it will be ignored. The initialiseTurret command is not required or useful for turrets which are only referenced using new-style subentity definitions.

is_dock is implied by having the string “dock” (in lowercase) in the key.

track_contacts

Tracks the movement of the ship and sends a "CLOSE CONTACT" message to other ship AI's. It uses a time consuming tracking, so only set to true when actually used.

Example:

<key>track_contacts</key>
<true/>

throw_sparks

Each new ship should start in seemingly good operating condition, unless specifically told not to. (Added with oolite 1.73, false by default)

Example:

<key>throw_sparks</key>
<true/>

thrust

Gives the entity an 'inertia' value, telling how fast it can increase or reduce speed (in m/s^2). 0 for rocks and cargo, 50 for a very fast ship, 100 for a station. When used with turrets it defines the turn rate in revolutions per second (with 1 being an average value).

Example:

<key>thrust</key>
<real>25</real>

unpiloted

Used to designate items that will never have a pilot, thus never turn aggressive and never eject a pod. By chance factor, or true/false.
It will not add a pilot when set to false, but will remove any existing pilot when set to true. commsMessages can only be broadcasted by piloted ships. Ships are by default piloted. cargo , rocks, missiles etc. are not piloted by default.

Example:

<key>unpiloted</key>
<true/>

view_position_..

Sets the ship's 4 point-of-view positions in XYZ relative to the model.

Example:

<key>view_position_aft</key>
<string>0.0 5.0 -20.0</string>
<key>view_position_forward</key>
<string>0.0 1.9375 5.0</string>
<key>view_position_port</key>
<string>-11.85 2.825 -3.5</string>
<key>view_position_starboard</key>
<string>11.85 2.825 -3.5</string>

weapon_energy

This setting works differently depending on the type of entity it's used for:

Missiles. Changes the damage inflicted by the missile. Any value accepted.

Example:

<key>weapon_energy</key>
<real>180</real>

NPC ships. Changes the forward weapon damage to a value different to the default one. Values higher than 50 will be ignored.

Default values are: WEAPON_PLASMA_CANNON = 6.0; WEAPON_PULSE_LASER = 15.0; WEAPON_BEAM_LASER = 15.0; WEAPON_MINING_LASER = 50.0; WEAPON_THARGOID_LASER = 12.5; WEAPON_MILITARY_LASER = 23.0

Example:

<key>weapon_energy</key>
<real>17</real>

N.B. It does not have any effect on player ships.

weapon_offset

Removed after version 1.65 (it was used to change the offsetpoint of a plasma cannon.)

weapon_position_..

Plots the 'gunmouth' points of the model's 4 potential lasers.

Example:

<key>weapon_position_aft</key>
<string>0.0 -5.0 -20.0</string>
<key>weapon_position_forward</key>
<string>0.0 0.0417 16.6667</string>
<key>weapon_position_port</key>
<string>-13.75 -2.0625 -1.875</string>
<key>weapon_position_starboard</key>
<string>13.75 -2.0625 -1.875</string>

---