From Elite Wiki
Revision as of 23:19, 15 December 2014 by Cim (talk | contribs) (1.81 extra properties for flexible equipment)

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


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 assigns to the missile the accuracy value of 0.0, which corresponds to the standard missile tracking behaviour.

In 1.76 or earlier, when used with NPC ships it slightly enlarges the chance of shooting at greater distances, and makes a small improvement to their aim. Value with NPC ships is between -5 and 10 though all values between -5 and +1 will be increased to +1. When not defined, NPCs will be assigned a random value in the range +1 to +10.

In 1.77 or later, when used with NPC ships it affects various aspects of the ship AI. Values can be assigned between -5 and +10. When not defined, a random value between -5 and +5 will be used. NPC accuracy significantly affects the quality of the AI in combat.


"accuracy" = 8.3;


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


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


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


"aft_weapon_type" = "WEAPON_BEAM_LASER";


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


"ai_type" = "pirateAI.plist";


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.


Added in 1.79

This parameter if true (the default is false) indicates to the Oolite system populator (and potentially to OXPs) that they may change the weapons, missile load, equipment and other such parameters of this ship to make it better fit its role. This allows you to specify a single hull for multiple roles, and have the ship re-equipped to suit those roles. Ships intended for general addition to the spacelanes in standard roles and not intended to be significantly different in difficulty to the core ships should probably turn this on.


"auto_weapons" = yes;


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.


"beacon" = "X";

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. Most letters have been used multiple times in various OXPs. In 1.79 the HUD will therefore display a longer label also; before that several HUD OXPs are available to do something similar.

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.


(1.79 or later)

A full label for the beacon. If this is not set, it will default to be the same as beacon, but it may be useful to have a beacon with a full label starting with a different letter than its code. The beacon label text will be expanded using the standard description rules

"beacon_label" = "%H Station"; // Lave Station, Diso Station, etc.


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.


"bounty" = 50;


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.


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


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


"cargo_type" = "CARGO_RANDOM";

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


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


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


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


"cloak_automatic" = no;


When true, any firing of laser will deactivate the cloak. (False by default in 1.76 or earlier, true by default in 1.77 or later)


"cloak_passive" = yes;


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.


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


Available from Oolite 1.77 onwards

This option specifies a Javascript file which controls the addition of this ship. The allowSpawnShip function in that condition script will then be tested before the ship is added. Several ships can share a condition script.


"condition_script" = "myoxp_conditions.js";


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


"counts_as_kill" = no;


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.


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


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.


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


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)


"debris_role" = "my_boulder_foo";


This real value is used to calculate a ships total mass. Default is 1.0. The mass of the ship is then 20 * density * volume.

Ship's mass does not affect its flight under the non-inertial engines - see thrust. It does affect:

  • changes in momentum, and damage done, in a collision
  • the minimum distance needed from this ship for another ship to open a witchspace wormhole (the blocking radius is the square root of a tenth of the mass)
  • the length of time a witchspace wormhole opened by this ship will remain open, and the radius of that wormhole.


"density" = 1.5;


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.


"display_name" = "ExampleShip Mark IX";


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


"energy_recharge_rate" = "3.5";


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


"escape_pod_model" = "custom_pod";


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


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


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


"escort_role" = "my_custom_escort_role";

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


Available from Oolite 1.79 onwards

This property overrules escorts, escort_role and escort_ship to allow more flexible specification of a ship's escorts. It takes the form of a list of dictionaries, each containing a "role", "min" and "max" key. The ship will then get between "min" and "max" of that role of escort ship (specific ships can be added using the "[dataKey]" style of role), with "max" more likely in Anarchy systems and "min" more likely in Corporate States.

  escort_roles = (
     { role = "escort"; min = -2; max = 2; },
     { role = "escort-medium"; min = 0; max = 4; },
     { role = "escort-heavy"; min = -4; max = 2; },
     { role = ""; min = 0; max = 2; } // spare slots for wandering escorts

A negative number can be used for "min" - this makes it more likely that none of this type of escort will be used in safer systems, and makes the maximum number less likely in the more dangerous systems. In the example above, the ship will mainly be escorted by "escort-medium" ships, with a couple of "escort" ships likely in unsafe systems, and a small chance of "escort-heavy" ships also appearing in more dangerous systems.

Leaving the role key blank allows the ship to have spare slots for escorts which are left unfilled when the ship is spawned. This can be used to simulate a willingness to hire additional escorts, or to indicate that the ship has already lost some of its escorts.

The maximum number of escorts remains 16, and the list will be processed from top to bottom. Once 16 escorts are added no further entries will be considered.


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


"escort_ship" = "cobramk1";

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

In Oolite 1.77 and later it is also possible to use "escort_role" = "[cobramk1]"


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)


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


In Oolite 1.81 or later, a list of explosions.plist entries describing how the ship explodes if destroyed.


"explosion_type" = ("oolite-default-asteroid-explosion");


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.


"extra_cargo" = 25;


Assigns the ship's forward laser. Any weapon type from the equipment.plist can be used.


"forward_weapon_type" = "WEAPON_BEAM_LASER";


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.


"frangible" = no;


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)


"fragment_chance" = no;


Determines an NPC ship's fuel storage, which will affect how it uses its Fuel Injectors and how far it can jump. If unspecified the default is zero (though ships added via the system populator will often be given some fuel anyway)


"fuel" = 70;


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


"has_cloaking_device" = 0.5;


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


"has_ecm" = 0.5;


"has_ecm" = no;


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.


"has_energy_bomb" = yes;


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.


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


Determines if a ship has the witchdrive fuel injector.


"has_fuel_injection" = 0.99;


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

"has_military_jammer" = 0.75;


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;


Determines if a ship has a fuel/cargo scoop.


"has_scoop" = no;


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)


"has_scoop_message" = no;


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


"has_shield_booster" = 0.80;


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


"has_shield_enhancer" = 0.45;


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


"heat_insulation" = "2.0";


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


"hud" = "specialhud.plist";


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)


"hyperspace_motor" = no;


Used to modify jump countdown time. Default = 15.


"hyperspace_motor_spin_time" = "15";


The default fuel burn rate of injectors on this ship, in deci-LY per second. The default is 0.25.

"injector_burn_rate" = 0.25;

Added in Oolite 1.81


The multiplier applied to the ship's maximum speed when it is using injectors. The default is 7.

"injector_speed_factor" = 7;

Added in Oolite 1.81


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.


"is_external_dependency" = yes;


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.


"is_submunition" = yes;


Set this to 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.


"is_template" = yes;


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.


"laser_color" = "cyanColor"


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

"role = trader";
"launch_actions" = (
  "setAITo: pirateAI.plist"


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.


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


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.


"likely_cargo" = "2";


See Materials in Oolite.


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.


"max_cargo" = "5";


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


"max_energy" = "300";


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


"max_flight_pitch" = "2.2";


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


"max_flight_roll" = "4.2";


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


"max_flight_speed" = "320";


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


"max_flight_yaw" = "2.2";


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.


"max_missiles" = "1";


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


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


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.


"missile_load_time" = "2.1";


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.


"missiles" = "0";


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.


"missile_role" = "EQ_THARGON";


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


"model" = "example_ship.dat";


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


"name" = "ExampleShip Mark IX";


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.


"no_boulders" = yes;


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.


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


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


"port_weapon_type" = "WEAPON_BEAM_LASER";


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. An explanation of the generic roles available in Oolite 1.79 or later is at Oolite_Ship_Roles.

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.


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


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


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.


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


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.


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


The description of the ship's legal status on the Scanner Targeting Enhancement. If this is absent, the default text for the scan class will be used.

"scan_description" = "Unclaimed rock";

Added in Oolite 1.81


Overrides the color that would normally be set by scanClass.


"scanner_display_color1" = "greenColor";


Overrides the color that would normally be set by scanClass. If this is set, the ship will flash between the two colours.


"scanner_display_color2" = "redColor";


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.


"scanner_range" = "25600";


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


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


Specifies a JavaScript script (through it's filename) to attach to the ship. Ship scripts are the preferred approach for scripting ships in current Oolite.


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.


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.


"script_actions" =
    "testForEquipment: EQ_CLOAKING_DEVICE",
          "foundEquipment_bool equal NO"
          "awardEquipment: EQ_CLOAKING_DEVICE"
          "awardCargo: 100 Gold"


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


"setup_actions" =


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.


Added in 1.79. The name of this individual ship (e.g. Pride of Lave), which is placed in ship.shipUniqueName. It rarely makes sense to set this property in shipdata.plist, except perhaps for a unique mission ship.


Added in 1.79. The name of this ship's class (e.g. Sidewinder), which is placed in ship.shipClassName. If this is not set, it will default to name, which is usually suitable.


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.


"smooth" = yes;


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.


      "facing_position" = "spu 0 0 0";
      "position" = "wpu 0 0 0.2";


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


"starboard_weapon_type" = "WEAPON_BEAM_LASER";


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. In Oolite 1.76 or earlier a station may only have at most one dock subentity.
Subentity definition properties for dock subentities (1.77 or later)
Name Type Description
allow_docking boolean In Oolite 1.77 or later, whether the dock allows docking. Defaults to true. (and always true in 1.76). Ignored for non-docks.
allow_launching boolean In Oolite 1.77 or later, whether the dock allows launching. Defaults to true. (and always true in 1.76). Ignored for non-docks.
disallowed_docking_collides boolean In Oolite 1.77 or later, if this is true, ships attempting to dock here will collide with the dock if allow_docking is false. If it is false, ships attempting to dock here will be docked with the station anyway. Defaults to false. (and always false in 1.76). Ignored for non-docks.
dock_label string In Oolite 1.77 or later, the name given to the dock by traffic control (overrides the display_name of the dock subentity). Defaults to "the docking bay", and ignored for non-docks. In Oolite 1.76 or earlier the concept of dock names is meaningless.

See Multiple Docks for more information on dock subentities and stations with more than one dock in Oolite 1.77 or later.

Subentity definition properties for ball turrets
Name Type Description
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.
Subentity definition properties for flashers
Name Type Description
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.)
bright_fraction number In Oolite 1.77 or later, a number between 0 and 1 defining the proportion of the flasher's cycle that the flasher is bright for. Ignored for non-flashers. The default (which mimics the behaviour of all flashers in 1.76 or earlier) is 0.5.

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:


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.


Added in Oolite 1.79, the default strength of the sun glare filter on this ship. A number between 0 and 1, with the default being 0 (no filter)

 "sun_glare_filter" = 0.3;


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.


"track_contacts" = yes;


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


"throw_sparks" = yes;


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


"thrust" = "25"


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.


"unpiloted" = yes;


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


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


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.



"weapon_energy" = "17";


(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

Fore and aft weapon mounts only.


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.


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


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


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


An advisory flag that informs AIs how they should expect to be treated near or when attempting to dock with this station. See station.allegiance for the allowable values. If this is not set, the game will guess based on other station properties.


allegiance = "neutral";


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)


allows_auto_docking = "no";


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)


allows_fast_docking = "yes";


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


defense_ship" = "my_defender";


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"


"defense_ship_role" = " carrier_defenders";


Equipment price mask for dockables.


"equipment_price_factor" = "4.5";


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


"equivalent_tech_level" = 1;


Determines if a station launches NPC traffic. Default is "yes" for stationary stations, and "no" for stations with a non-zero maximum speed. When set to "no" the station will not launch random ships as part of the main Oolite system repopulator (though OXP scripts may still launch ships from it).

The type of traffic launched depends on the allegiance property of the station (which also determines what, if any, ships may try to dock at it).


"has_npc_traffic" = yes;


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


"has_patrol_ships" = yes;


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


"has_shipyard" = "0.75";


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


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)


interstellar_undocking = "yes";


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


"is_carrier" = yes;


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 and no longer used in 1.81 or later, where it is replaced by the market_* properties below.


"market" = "none";


In 1.81 or later, if this is enabled the station's market will appear on the F8 screen if the player is in flight and has the station targeted. The default is enabled. This is ignored (and always true) if the station is the main station.

"market_broadcast" = no;


In 1.81 or later, the capacity in units per trade good of the station market. If omitted, the default market capacity of 127 units will be used. This is ignored if the station is the main station as it will use the system market, not its own.

"market_capacity" = 31;


In 1.81 or later, an array of secondary market rules which modify some or all of the price, quantity, capacity and legal status of a good relative to the primary system market. This is ignored if the station is the main station as it will use the system market, not its own.

"market_definition" = (
		// export cheap clothes
		"type" = "class";
		"name" = "oolite-wearable";
		"price_multiplier" = 0.8;
		"price_randomiser" = 0.1;
		"quantity_multiplier" = 3.5;
		"quantity_randomiser" = 3.0;
		// not really interested in other goods
		"type" = "default";
		"price_multiplier" = 0.55;
		"price_randomiser" = 0.25;
		"quantity_multiplier" = 0.0;
		"capacity" = 3;

If the capacity set by a rule is larger than the market_capacity of the station, the market_capacity of the station is used instead.

A blank array

"market_definition" = ();

will give a market identical to the primary system market.

If this key is omitted, the station will have no market. This is roughly equivalent to

"market_definition = (
		"type" = "default";
		"price_multiplier" = 0;
		"quantity_multiplier" = 0;
		"capacity" = 0;


In Oolite 1.81 and later, if this is true, the market is subject to Cooperative law for the import and export of trade goods, and the player will gain the usual bounties for smuggling contraband. The default value is no. This is ignored (and effectively always true) if the station is the main station.

market_monitored = yes;


In Oolite 1.81 and later, allows a market script to be used to modify trade prices. This overrides market_definition, if it is present.

market_script = "myoxp_marketchanges.js";


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


"max_defense_ships" = "10";


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


"max_police " = "10";


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


"max_scavengers" = "10";


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.


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


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.


"port_radius" = "500";


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


"requires_docking_clearance" = yes;


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


"rotating" = yes;


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)

Note: unlike the other turn rate properties, for historical reasons station_roll is measured in right-angles/second, not radians/second.


"station_roll" = "-1.5"


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


"tunnel_corners" = 6;


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)


"tunnel_start_angle" = 0;


Defines the proportion of the tunnel’s width to its height. Default is "2.67".


"tunnel_aspect_ratio" = 1;