Shipdata.plist

The shipdata.plist would be more accurately called objectdata nowadays - a "ship" in Oolite might be a ship, a station, a rock, basically any solid object smaller than a planet (or moon)

(Cim)

Format

Shipdata.plist is in Property list format. The shipdata document is a dictionary of ships. Example:

   {
     "rsvh_adder" = {
       like_ship = "adder";
       is_external_dependency = yes;
       pilot = "oolite-hunter";
       roles = "rrs-vicious-hunter(1)";
       "missile_role" = "EQ_HARDENED_MISSILE";
   	"script_info" = {
   		"randomshipnames" = "hunter";
   		"skilled_npc_role" = "hunter";
   	};
     };
   
     "rsvh_asp" = {
       like_ship = "asp";
       is_external_dependency = yes;
       pilot = "oolite-hunter";
       roles = "rrs-vicious-hunter(1)";
       "aft_weapon_type" = "WEAPON_BEAM_LASER";
   	"script_info" = {
   		"randomshipnames" = "hunter";
   		"skilled_npc_role" = "hunter";
   	};
     };
   }

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

Example:

"accuracy" = 8.3;

See Cim's detailed explanation here (2012)

Compare with reaction_time

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.

auto_weapons

This property was added in Oolite test release 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.

Example:

"auto_weapons" = yes;

See here for more detail

beacon

A special feature for beacons and navigation aids. The string can be anything - the first letter was what was displayed in the advanced space compass before Oolite v.1.79. It is still the only display for the older HUD's.

Example:

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

Since v.1.79 the HUD also displays a longer label; before that several HUD OXPs were available to do something similar (see Advanced Space Compass).

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.

There are several devices which detect things from great distance: the Vanilla game's Advanced Space Compass, The Galactic Almanac OXZ, Telescope and the Long Range Scanner. The last is a cheat OXP useful for programmers. See the HIMSN thread for details of making things invisible to them.

beacon_label

This property was added in Oolite test release 1.79.

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.

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)

Note: A bug introduced in 1.82 means that only commodity keys from the Trade-goods.plist are recognised here. That is "gold" will be recognised, whereas "Gold" will not. This bug is fixed in the 1.83/1.84 release.

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 exemplified by the cloaking 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

This property was added in Oolite test release 1.75.

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)

Example:

"cloak_automatic" = no;

cloak_passive

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)

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

condition_script

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.

Example:

"condition_script" = "myoxp_conditions.js";

counts_as_kill

This property was added in Oolite test release 1.75.

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.

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

This property was added in Oolite test release 1.74.

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

Example:

"debris_role" = "my_boulder_foo";

See the discussion here: (RELEASE) Icesteroids V2 (2011-12) - about role circularity and about the vanilla game code creating alloys whenever anything big explodes!

density

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.

Example:

"density" = 1.5;

• See Eric Walch's comment on vanilla-game Coriolis stations here (2010)

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

See Energy rates and recharge for more detail (2012)

escape_pod_model

With this entry ships can have custom escape pods. Defaults to "escape-capsule".

Since v1.65: You have to specify the role of your custom escape pod (not its entry-name).

Since v1.77: Deprecated in favour of escape_pod_role.

Example:

"escape_pod_model" = "custom_pod_role";

Note: Each shipdata entry has an implicit unique role in the form of a shipdata key enclosed in square brackets - e.g. "[entry-name]". It might be useful if you want to use a specific escape pod that has no unique role.

escape_pod_role

With this entry ships can have custom escape pods. It's almost the same as escape_pod_model, but has a less ambiguous name. Added in v1.77.

The game first tries to spawn a pod using escape_pod_role, but if the property isn't set or a spawn fails, the game uses escape_pod_model. If the latter fails too, the game tries the "escape-capsule" role.

Example:

"escape_pod_model" = "custom_pod_role";

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_roles

This property was added in Oolite test release 1.79.

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.

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.

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

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

exhaust_emissive_color

This property was added in Oolite test release 1.79.

Determines the colour of the exhausts.

For the colour you can use either a colour specifier or a named colour.

Example:

"exhaust_emissive_color" = "redColor";

or

"exhaust_emissive_color" = "1 0 0";

explosion_type

This property was added in Oolite test release 1.81.

A list of explosions.plist entries describing how the ship explodes if destroyed.

Example:

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

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

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 (2.0 for ships equipped with EQ_HEAT_SHIELD). Values below 0.125 will be increased to that minimum. This parameter is only for NPC ships and stations. Player ships ignore this and always start with 1.0 heat insulation and can add an additional 1.0 (for a total of 2.0) with the ship equipment EQ_HEAT_SHIELD. Heat insulation for NPCs is only a factor when close to the sun. Energy damage does not cause overheating (because otherwise it would be too easy to overheat NPC ships with missiles or lasers), but it can raise ships' temperature to the maximum safe level. Overheating occurs when a ship's temperature exceeds the safe level, which is determined by the heat insulation level. External temperature is determined by distance from the sun. Larger suns are hotter. Suns that are going nova are, unsurprisingly, even warmer.

Example:

"heat_insulation" = "2.0";

NPC ships launched from stations are given the same heat insulation as the station if the station's is greater than the ship's. Courier ships generated by the core system populator are given a heat insulation level of 6.0. Escort ships (if any) receive at least the same heat insulation as the ship they are escorting. See BB Thread (2012)

Player ships use the same model as NPC ships for external temperature from the sun, but additionally simulate heat from air friction when inside planetary atmospheres, which is a factor that NPC ships ignore.

hud

Used for a playership, to assign another HUD than the default one. Note that small ships get the second default - the hud-small.plist

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

injector_burn_rate

This property was added in Oolite test release 1.81.

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;

injector_speed_factor

This property was added in Oolite test release 1.81.

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

"injector_speed_factor" = 7;

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

See Energy rates and recharge for more detail (2012). Divide by 64 to get the rough number of energy banks.

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

model_scale_factor

1.81 or later only.

If this is set, the model specified in the model property will be scaled by this factor (the default is 1.0, of course). Additionally, all subentities will have both their positions and sizes scaled (recursively if necessary), and the weapon positions will also be multiplied by the scale factor.

Player ships will also have their internal and external view positions multiplied by the scale factor.

model_scale_factors on subentities will be ignored - the value for the main entity will be used instead.

Example:

"model_scale_factor" = 2.0;

name

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

Example:

"name" = "ExampleShip Mark IX";

See also display name, ship_name & ship_class_name

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

This property was added in Oolite test release 1.77.

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

reaction_time

Sets the reaction time of the pilot of this ship. The default is 1.5 seconds.

Example:

"reaction_time" = 1.0; // this pilot is superhuman! or a cat

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

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.

• 1 1/2 pages of discussion of station population percentages (2010)

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

In practical terms, one can therefore use

"rotational_velocity"="3 0 0 1"

To alter the speed of rotation increase number 3, for slower rotations, decrease for higher speed. For opposite rotational direction, change 1 to -1.(ref: Arhuman BB 1/11-09)

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!

scan_description

This property was added in Oolite test release 1.81.

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

scanner_display_color1

Overrides the color that would normally be set by scanClass.

Example:

"scanner_display_color1" = "greenColor";

scanner_display_color2

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

Example:

"scanner_display_color2" = "redColor";

scanner_hostile_display_color1

This property was added in Oolite test release 1.81.

Overrides the color that would normally be set by scanClass when the ship is hostile and targeting the player.

If no hostile colours are set, but normal colours are set, then the normal colours, not the scan class colours, will be used for a hostile ship.

Example:

"scanner_hostile_display_color1" = "greenColor";

scanner_hostile_display_color2

This property was added in Oolite test release 1.81.

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

Example:

"scanner_hostile_display_color2" = "redColor";

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.

2008 note by Eric Walsh on what this does.

script

Specifies a Ship Script (through it's filename) to attach to the ship. Ship scripts written in JavaScript 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.

ship_name

This property was added in Oolite test release 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.

ship_class_name

This property was added in Oolite test release 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.

show_damage

This property was added in Oolite test release 1.81.

Whether to show sparks and other damage effects when this ship is hit.

Defaults to on if energy recharge rate is greater than zero, off otherwise, for compatibility with previous hard-coded behaviour.

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

This property was added in Oolite test release 1.77.

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.

For discussion on the effective range (before the reduction from the original 7500 to 7200) see here.

Note that the Vortex turrets can be switched off. This involved special scripting (basically removing and restoring the turrets by script). Needs a little fancy footwork when docked though or else if you dock with removed sub-entities (even deliberately removed ones) you'll get a maintenance overhaul offered which will put them back if purchased.

• 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.
• Random number of Subentities (eg Cargo pods): see Can the number of entities a ship be randomized? (2017)

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

See New range of turrets for more information on turret subentities (2012 discussion about modelling, quaternions, etc).

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:

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.

Links

• How are subentity scripts supposed to work ? (2017)
• Ball turrets (2012)
• Docking bay problems (2009) - covers a range of issues
• Some OXP's with subentities:

Thargoids: Stellar Serpents OXP (2010), Animated Ships/Butterflies (2011), Aquatics (2011: Hammerhead bulk carrier & the Aqualina stations), WildShips OXP (2012-14: moving elevators inside station struts)

Z GrOovy HPC pack (2014 - bought equipment is visible on ship!); Scrub (2022 - rotating rings)

sun_glare_filter

This property was added in Oolite test release 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;

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

This property was added in Oolite test release 1.73.

Each new ship should start in seemingly good operating condition, unless specifically told not to. (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

This property was added in Oolite test release 1.77.

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_mount_mode

This property was added in Oolite test release 1.83.

This controls how multiple weapon mount points work. It has three possible values:

• "single": this is the default, and replicates 1.82 and previous behaviour. In this mode, weapon_position_* properties are simple vector expressions, and there is exactly one mount per facing.
• "split": In this mode, weapon_position_* properties are an array of vector expressions. A weapon fitted to this facing has the same heat and energy cost as a single standard weapon, and the damage output is divided equally between all mount points. (in other words, the distinction is mainly cosmetic)
• "multiply": In this mode, weapon_position_* properties are an array of vector expressions. A weapon fitted to this facing has N times the heat and energy cost as a single standard weapon, and each mount point does normal damage. (in other words, the weapon is fitted N times at once)

For best results with AI and the "target reticle sensitive" feature, if there are several weapon positions in a (rough) line, the middle one should be listed first.

See this comment or Multiple Lasers for examples.

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.

In 1.82 and earlier, and in 1.83 and later in the "single" weapon_mount_mode, these are vector expressions.

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

In 1.83 and later, with "split" or "multiply" weapon_mount_mode, these values are specified as arrays of vector expressions. For example:

"weapon_position_forward" = ( "0.0 3.0 32.0" , "-15.0 0.0 32.0" , "15.0 0.0 32.0" )

Station keys

The following keys are only used by stations or carriers.

allegiance

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.

Example:

allegiance = "neutral";

allows_auto_docking

This property was added in Oolite test release 1.75.

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

Example:

allows_auto_docking = "no";

allows_fast_docking

This property was added in Oolite test release 1.75.

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

Example:

allows_fast_docking = "yes";

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

Example:

"has_npc_traffic" = yes;

has_patrol_ships

This property was added in Oolite test release 1.75.

Determines if a station launches periodic patrol ships. Default is "no". Main stations always have patrol ships.

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

This property was added in Oolite test release 1.75.

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

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

Example:

"market" = "none";

market_broadcast

This property was added in Oolite test release 1.81.

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;

market_capacity

This property was added in Oolite test release 1.81.

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;

market_definition

This property was added in Oolite test release 1.81.

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;
	}
);

Note: There is some discussion about this at Secondary Market Definitions Defined (2023)

market_monitored

This property was added in Oolite test release 1.81.

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;

market_script

This property was added in Oolite test release 1.81.

Allows a market script to be used to modify trade prices. This overrides market_definition, if it is present.

market_script = "myoxp_marketchanges.js";

Note: What's the difference between the market script specified in planetinfo.plist and the one called for by trade-goods.plist? (2015)

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

This property was added in Oolite test release 1.74.2.

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.

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

Example:

"station_roll" = "-1.5"

tunnel_corners

This property was added in Oolite test release 1.75.

Defines the number of corners in the docking tunnel. Ranges from 4 to 128. Default is "4".

Example:

"tunnel_corners" = 6;

tunnel_start_angle

This property was added in Oolite test release 1.75.

Defines the position of the first corner of the docking tunnel in degrees. 0 means the first corner is straight up. Default is "45".

Example:

"tunnel_start_angle" = 0;

tunnel_aspect_ratio

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

Example:

"tunnel_aspect_ratio" = 1;

---

Links

• understanding shipdata.plist (2009)
• Orientation Issues (Asteroid turns 180°, and want it to face planet, 2007)
• Empty System (Removing stations and rock hermits from a system, 2021)
• Changing compass values of ships (from white to red) (Hiding ships on the scanner, 2008)
• Problems with Explosions - metal plates birthing bigger plates when exploded (2016) -as here.