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:

Ship keys

The following keys are used by all ships

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 aft 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";

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

Characters that are known to be used as identifiers for stations and other fixed objects are found on the page for the Advanced_Space_Compass.

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

We can also use custom icons with the compass. For that you must define a key in descriptions.plist with the same name as the beacon definition. Than define the icon in the same way as missile icons. (An array of x/y-coordinates that will be connected by lines). You can find more info at the Oolite BB.
Example in shipdata:

"beacon" = "fuelStation_location";

Example in descriptions.plist

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

Before 1.75 the ships primary role was used for defining the icon name in descriptions.plist, but since 1.75 the beacon name itself is used.

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.
It is 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. (CARGO_RANDOM is not fully random but means that a container can hold any kind of commodity.)

Example:

"cargo_type" = "CARGO_RANDOM";

Will create random cargo, often based on availability in the system. When you want fixed cargo you can use:

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.
The cargo barrels are stored in the ships hold like normal barrels when a cargo was defined for them with the JS method "setCargo". Without defined content, scripted barrels are removed after scooping. Scripted cargo works with any object that can be scooped. When you have scripted escape pods that must be preserved after scooping, fill it with one ton of Slaves.

cloak_automatic

When false, the cloak of npc ships will never get activate automatic during combat, but is only activated by JS script commands. (True by default) Key added with Oolite 1.75

Example:

"cloak_automatic" = no;

cloak_passive

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

Example:

"cloak_passive" = yes;

conditions

With 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"
               );

counts_as_kill

Killing this ship will not count as a kill by the player when set to false. (Default is true). Using this key prevents awarding kills to all kind of cargo, debris etc. Key is added with Oolite 1.75

Example:

"counts_as_kill" = no;

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

density

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

Example:

"density" = 1.5;

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:

"display_name" = "ExampleShip Mark IX";

energy_recharge_rate

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

Example:

"energy_recharge_rate" = "3.5";

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:

"escape_pod_model" = "custom_pod";

escorts

Determines how many escorts an NPC shall have. Maximum is 16.

Example:

"escorts" = 4;

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.
For ships that are added in a trader role, the populator can decide to subtract escorts from the defined value when the system is estimated as safe.

escort_role

Assigns the specific ship type to be the escort, by the ship's role. (Before Oolite 1.74 only the name "escort-role" is accepted.)

Example:

"escort_role" = "my_custom_escort_role";

Escort ships will use the escortAI.plist unless "auto_ai" is set to false.

escort_ship

Assigns the specific ship type to be the escort, by the ship's name. (Before Oolite 1.74 only the name "escort-ship" is accepted.)

Example:

"escort_ship" = "cobramk1";

Escort ships will use the escortAI.plist unless "auto_ai" is set to false.

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 far a plume extends on x axis, on each side of plume position. (x radius)

height in meters, how far a plume extends on y axis, above and below of plume position. (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:

"exhaust" = (
    "5 0.0 -25 3.0 2.0 10.0",
    "-5 0.0 -25 3.0 2.0 10.0"
);

extra_cargo

Cargobay extension size can 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:

"extra_cargo" = 25;

forward_weapon_type

Assigns the ship's forward laser. Any weapon type from the equipment.plist can be used.
e.g.: WEAPON_PULSE_LASER, WEAPON_BEAM_LASER, WEAPON_MILITARY_LASER, WEAPON_MINING_LASER, WEAPON_PLASMA_CANNON, WEAPON_THARGOID_LASER and WEAPON_NONE.

Example:

"forward_weapon_type" = "WEAPON_BEAM_LASER";

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:

"frangible" = no;

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:

"fragment_chance" = no;

fuel

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

Example:

"fuel" = 70;

has_cloaking_device

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

Example:

"has_cloaking_device" = 0.5;

has_ecm

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

Example:

"has_ecm" = 0.5;

or

"has_ecm" = no;

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:

"has_energy_bomb" = yes;

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;

has_fuel_injection

Determines if a ship has the witchdrive fuel injector.

Example:

"has_fuel_injection" = 0.99;

has_military_jammer

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

"has_military_jammer" = 0.75;

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:

"has_military_scanner_filter" = 0.50;

has_scoop

Determines if a ship has a fuel/cargo scoop.

Example:

"has_scoop" = no;

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:

"has_scoop_message" = no;

has_shield_booster

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

Example:

"has_shield_booster" = 0.80;

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:

"has_shield_enhancer" = 0.45;

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:

"heat_insulation" = "2.0";

hud

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

Example:

"hud" = "specialhud.plist";

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:

"hyperspace_motor" = no;

hyperspace_motor=NO;

hyperspace_motor_spin_time

Used to modify jump countdown time. Default = 15.

Examples:

"hyperspace_motor_spin_time" = "15";

is_external_dependency

This key should be added to ships that use like_ship references to ships in other oxps but don't depend on them. Normally will Oolite write errors in the log when it can't resolve a like_ship reference. When this key is set to YES, it will suppress the error generation.
WARNING: only set this key to YES when the model won't get added to the system without the other oxp installed or you will miss a valuable warning.

Example:

"is_external_dependency" = yes;

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:

"is_submunition" = yes;

is_template

Set this to yes/yes; 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:

"is_template" = yes;

laser_color

Determines a ship's laser colour.

As colour you can use a colour specifier or a named colour. 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:

"laser_color" = "cyanColor"

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";
"launch_actions" = (
  "setAITo: pirateAI.plist"
 );

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:

"my_ship" = {
"like_ship" = "adder";
"max_flight_speed" = "700";
"name" = "Freak Turbo Adder";
},

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:

"likely_cargo" = "2";

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:

"max_cargo" = "5";

max_energy

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

Example:

"max_energy" = "300";

max_flight_pitch

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

Example:

"max_flight_pitch" = "2.2";

max_flight_roll

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

Example:

"max_flight_roll" = "4.2";

max_flight_speed

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

Example:

"max_flight_speed" = "320";

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:

"max_flight_yaw" = "2.2";

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:

"max_missiles" = "1";

missile_launch_position

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

Example:

"missile_launch_position" = "0.0 -2.25 10.0";

This position should lie outside the bounding box of the core entity and not just outside of the ships mesh. Default value: (0, -4, 1)
If the position does lie inside the bounding box, the launch position is shifted along its direction until the launched missile lies outside the bounding box of the central entity. (Bounding boxes of subentities are ignored) The collision radius of the launched missile is taken into account. The collision radius for a plain missile is 4.52 meter.

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.

Example:

"missile_load_time" = "2.1";

missiles

Sets the number of missiles the ship is equipped with on ship creation. e.g. you can set this at zero and than use a dedicated script to fill up the bay with specific missiles.

Example:

"missiles" = "0";

missile_role

Defines the type of missiles (or mines) an NPC ship is provided with. Default is "EQ_MISSILE". When missiles are loaded on ship creation, 90% will be of this type and 10% will be random, chosen from all possible NPC missiles and mines. Also affects the javascript selectNewMissile() command. The string defined inside missile_role needs both to be defined inside equipment.plist, and be inside the roles property of the missile/mine shipdata entry.

To assign a specific missile type to a newly bought player ship, its dependancies must be defined inside shipyard.plist.

Example:

"missile_role" = "EQ_THARGON";

model

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

Example:

"model" = "example_ship.dat";

name

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

Example:

"name" = "ExampleShip Mark IX";

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:

"no_boulders" = yes;

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:

"pilot" = "constrictor-mission-thief";

When no pilot is defined, Oolite will create a random pilot based on the ships role. For custom roles this means that Oolite has no clue and the pilot might have other bounties/insurances than desired. For this reason contains Oolite, starting with v 1.75, some predefined pilots: "oolite-trader", "oolite-pirate", "oolite-hunter", "oolite-police", "oolite-miner", "oolite-passenger" and "oolite-slave". When using one of these pilots, a random bounty/insurance will be set appropriate for this pilot role. Pilot bounty is different as ship bounty but on ejecting the pilot inherits the highest of both values. (actually a bitwise OR of both values)

port_weapon_type

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

While not essential, you should generally assign the same weapon to starboard_weapon_type.

Example:

"port_weapon_type" = "WEAPON_BEAM_LASER";

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. Multiple roles are space separated.

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:

"roles" = "hunter(0.25) trader(2.0) pirate";

or an exclusive role, simply:

"roles" = "uniquely_named_role";

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:

"roles" = "Gold";

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.

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:

"rotational_velocity" = "0.707 0.0 0.0 0.707";

An explaining example taken from the Oolite Bulletin board.

The rotational velocity key is rotation per second.

For instance, if you want to rotate once per 20 seconds around the Z axis:

a = 360 ° / 20 = 18 °

[x, y, z] = [0, 0, 1]

sin a ˜ 0.30902

cos a ˜ 0.95106

Q = (0.95106, 0, 0, 0.30902)

shipdata.plist entry:

"rotational_velocity"="0.95106 0.0 0.0 0.30902";

scan_class

Will alter the model's appearance on the IFF system. If this line is omitted, it will usually become by default a standard ship entity (CLASS_NEUTRAL), appearing as a yellow flag on the radar (red if hostile to the player), but may be given a different scan class if added with other roles. There are other options.

• CLASS_BUOY - green/yellow on scanner, will rotate in idle state, does not masslock
• CLASS_CARGO - white on scanner, can be scooped, does not masslock
• CLASS_MILITARY - purple on scanner, better pilots, will not attack other military ships, flashes purple/magenta if hostile to player
• CLASS_MISSILE - cyan on scanner, will not avoid collisions
• CLASS_POLICE - purple on scanner, will not attack other police ships, legal penalties for attacking, never has bounty, flashes purple/magenta if hostile to player
• CLASS_ROCK - white on scanner, launched defense ships do not inherit scan class, does not masslock
• CLASS_STATION - green on scanner, launched defense ships do not inherit scan class
• CLASS_THARGOID - green/red on scanner, considered hostile to any non-thargoid ship
• CLASS_NO_DRAW - invisible on scanner, cannot be targeted by missiles, does not masslock
• CLASS_MINE - red/yellow on scanner, automatically set on mines launched by player to override existing scan class, does not masslock

(This property was called "scanClass" before Oolite 1.74.) Scan classes marked as "does not masslock" will masslock the player anyway if they are hostile to the player (as condition will be Red)

Scripts can define custom colours for ships on the IFF system so ships may have a scanner appearance different to the default for their scan class.

Example:

"scan_class" = "CLASS_ROCK";

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!

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.

Example:

"scanner_range" = "25600";

scoop_position

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

Example:

"scoop_position" = "0.0 -4.5 -23.0"

Scooping for a player ship starts when the cargo collides with the front half of the bottom of the ship. Any other place of first contact leads to smashing the cargo in pieces. A good y-value for the position would therefor be half the size of the lowest body part of this area of the ship. For the z-value a point in the back side would be better.

script

Specifies a JavaScript script to attach to the ship. Ship scripts are the preferred approach for scripting ships in current 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.

A short overview about used script_info keys in OXPs.

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:

"script_actions" =
(
    "testForEquipment: EQ_CLOAKING_DEVICE",
    {
       "conditions"
       (
          "foundEquipment_bool equal NO"
       )
       "do"
       (
          "awardEquipment: EQ_CLOAKING_DEVICE"
       )
       "else"
       (
          "awardCargo: 100 Gold"
       )
    }
);

setup_actions

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

Example:

"setup_actions" =
(
   "initialiseTurret"
);

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:

"smooth" = yes;

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

"spawn"
{
      "facing_position" = "spu 0 0 0";
      "position" = "wpu 0 0 0.2";
}

starboard_weapon_type

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

While not essential, you should generally assign the same weapon to port_weapon_type.

Example:

"starboard_weapon_type" = "WEAPON_BEAM_LASER";

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 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.
weapon_range	number	Range for ball_turret subentities. Default: 6000; maximum 7500.
weapon_energy	number	Weapon energy for ball_turret subentities. Default: 25; maximum 100.
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:

"track_contacts" = yes;

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:

"throw_sparks" = yes;

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:

"thrust" = "25"

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:

"unpiloted" = yes;

view_position_..

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

Example:

"view_position_aft" = "0.0 5.0 -20.0";
"view_position_forward" = "0.0 1.9375 5.0";
"view_position_port" = "-11.85 2.825 -3.5";
"view_position_starboard" = "11.85 2.825 -3.5";

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.

NPC ships. Changes the forward weapon damage to a value different to the default one. Values higher than 50 will be clamped to 50. Does not change the value for aft weapons or subEntity weapons.
N.B. It does not have any effect on player ships.

turrets. Unused for turrets. Set the turret weapon_energy in its subEntity directory.

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:

"weapon_energy" = "17";

weapon_facings

(1.77 or later only) What weapon mounts are available on the ship. This is a bit-mask, so pick the mounts and add the numbers:

1 - Forward
2 - Aft
4 - Port
8 - Starboard

Example:
Fore and aft weapon mounts only.

 <key>weapon_facings</key>
 <integer>3</integer>

If omitted, defaults to 15 (all mounts). If a player ship has this specified, and the same property specified in shipyard.plist, the shipyard.plist property takes precedence.

Weapons assigned to a mount that the ship does not have will be ignored. Scripting cannot be used to add weapons to these mounts later, either.

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:

"weapon_position_aft" = "0.0 -5.0 -20.0";
"weapon_position_forward" = "0.0 0.0417 16.6667";
"weapon_position_port" = "-13.75 -2.0625 -1.875";
"weapon_position_starboard" = "13.75 -2.0625 -1.875";

Station keys

The following keys are only used by stations or carriers.

allows_auto_docking

When set false for a station, this station will not allow the use of a docking computer. Default value in "yes". (Planned for Oolite 1.75)

Example:

allows_auto_docking = "no";

allows_fast_docking

When set true for a station, this station will allow fast docking with the docking computer. Default value in "no". (Planned for Oolite 1.75)

Example:

allows_fast_docking = "yes";

defense_ship

Gives an oportunity to designate a particular ship by name that will defend a station/carrier. See also defense_ship_role

Example:

defense_ship" = "my_defender";

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 scan_class becomes that of the carrier. Default role is "police"/"interceptor" for normal stations and "hermit-ship" for stations of CLASS_ROCK. Defense ships with scanclass police or with a hermit-ship role launch with a policeInterceptAI.plist. All other ships use the ai_type as defined in shipdata.plist. After launch, all primary roles are changed into: "defense_ship"

Example:

"defense_ship_role" = " carrier_defenders";

equipment_price_factor

Equipment price mask for dockables.

Example:

"equipment_price_factor" = "4.5";

equivalent_tech_level

Sets shipyard tech level for dockables, different to the local system tech_level. Default value is the system tech_level.

Example:

"equivalent_tech_level" = 1;

has_npc_traffic

Determines if a station has NPC traffic. Default is "yes". When set to "no the station will not launch random traders. Only rotating stations will launch traders when this is set to true.

Example:

"has_npc_traffic" = yes;

has_patrol_ships

Determines if a station launches periodic patrol ships. Default is "no". Main stations always have patrol ships. (Planned for Oolite 1.75)

Example:

"has_patrol_ships" = yes;

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. Default is "no", but for main stations has_shipyard is always "yes". (Name is valid starting with Oolite 1.74. Before it was called "hasShipyard".)

Example:

"has_shipyard" = "0.75";

or

"has_shipyard" = (
                  systemGovernment_number morethan 3,
                  systemEconomy_number lessthan 4
                 )

interstellar_undocking

When set true for a station, this station will allow interstellar docking and undocking in interstellar space. When set to "no" the player docks in nearby normal space. Default value in "no". (Planned for Oolite 1.75)

Example:

interstellar_undocking = "yes";

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:

"is_carrier" = yes;

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:

"market" = "none";

max_defense_ships

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

Example:

"max_defense_ships" = "10";

max_police

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

Example:

"max_police " = "10";

max_scavengers

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

Example:

"max_scavengers" = "10";

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:

"port_dimensions" = "65x30x500";

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:

"port_radius" = "500";

requires_docking_clearance

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

Example:

"requires_docking_clearance" = yes;

rotating

Given to a station when rotation is desired. Default is "no".

Example:

"rotating" = yes;

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:

"station_roll" = "-1.5"

tunnel_corners

Defines the number of corners in the docking tunnel. Ranges from 4 to 128. Default is "4". (Key is added in Oolite 1.75)

Example:

"tunnel_corners" = 6;

tunnel_start_angle

Defines the position of the first corner of the docking tunnel in degrees. 0 means the first corner is straight up. Default is "45". (Key is added in Oolite 1.75)

Example:

"tunnel_start_angle" = 0;

tunnel_aspect_ratio

Defines the proportion of the tunnel’s width to its height. Default is "2.67". (Key is added in Oolite 1.75)

Example:

"tunnel_aspect_ratio" = 1;

---