Shiplibrary.plist

The shiplibrary.plist file places ship information on the Ship Library database when Oolite starts up, in version 1.79 or later. This is the same as the View Ship Specifications option on the docked F4 screen.

It is a list of dictionaries, with the following keys. Strictly, only the 'ship' key is required, but setting at least the 'class' and 'summary' keys is also recommended. All keys which display text to the end user will be expanded via descriptions.plist and the usual expansion rules.

In general, entries should only be included in this file if:

• no other near-identical variant is included (e.g. the core file includes the cobra3-trader but not the cobra3-pirate which is essentially the same ship with different equipment and maybe different paint; the description covers both subtypes - or the core file includes one asteroid entry to cover all asteroids, boulders, splinters and cinders)
• the entry is not a player ship (i.e. include cobra3-trader not cobra3-player)
• the ship is public knowledge (e.g. certain secret mission ships are not included in the core game's default library view) - though in 1.81 onwards you can use condition scripts to display secret ships the player has discovered.

This .plist belongs in the Config folder.

Keys

class

This can currently take one of five values: 'ship' (the default, including large ships with docks), 'station' (stationary dockable objects), 'weapon' (mines and missiles), 'thargoid', and 'misc' (asteroids, navigation buoys, cargo, etc.).
Other values are added in the descriptions.plist (eg. "Communist Craft" - see there for an example).

class = "station";

condition_script

(Oolite 1.81 and later)

If this is set, then:

• in game, the named condition script will be loaded and used to determine whether to include this entry in the library by calling the allowShowLibraryShip method.
• on the start screen, the ship will not be shown.

This is used in the core game to hide a mission-specific ship until that mission starts.

description

A short text description of the ship summarising its purpose, strengths, weaknesses and NPC preferred uses. Descriptions longer than 200-300 characters will probably start to look too long if ship_data is true.

description = "[myoxp-ship-description-myship]";

ship

The data key in shipdata.plist of this ship.

ship = "cobra3-trader";

See Problems with naming, below.

ship_data

Whether to display a mostly-automated 3 line data block assessing standard capabilities (speed, turn rate, energy, weapons, etc.) between the ship's name and its description text. This defaults to true if the class is 'ship', and false otherwise.

ship_data = true;

If it is set to or defaults to true, then additional keys listed in this section may also be specified to modify the display of each entry in the data block. Each modifier entry can be:

• unspecified - the data block entry will get a default value. In most cases this will be sufficient. The default values will be consistent in scale with the core ships, so only set a value if you have something different to say.
• a non-empty string - the data block entry will get this expandable string as a custom value
• an empty string - the data block entry will be completely absent, not even the title.

Rather than using an empty string, the descriptions.plist entries oolite-ship-library-classified and oolite-ship-library-unknown may sometimes be more appropriate.

cargo

The cargo capacity of the ship. Defaults to its real capacity in TC.

cargo = "20/35 TC"; // gives "Cargo: 20/35 TC"

generator

Defaults to an approximate string description of the energy recharge rate of the ship.

generator = "[oolite-ship-library-classified]"; // gives "Generator: Classified"

shields

Defaults to an approximate assessment of the ship's energy banks.

shields = "Impenetrable"; // gives "Shields: Impenetrable"

size

Defaults to a description of the size of the ship's bounding box (in x, y, z order), rounded to the nearest metre.

size = "Variable"; // gives "Size: Variable"

speed

Defaults to an approximate assessment of the maximum non-injector speed of the ship.

speed = "[oolite-ship-library-speed-stationary]"; // gives "Speed: Stationary"

turn_rate

Defaults to an approximate assessment of the ship's combined roll and pitch rates (yaw is not considered)

turn_rate = "Slow roll, fast pitch"; // gives "Turn Rate: Slow roll, fast pitch"

weapons

Defaults to a count of the ship's fixed laser mounts and pylons.

weapons = "6 plasma turrets"; // gives "Weapons: 6 plasma turrets"

witchspace

Defaults to 'yes' or 'no' depending on whether a ship has a witchdrive.

witchspace = "Mk 2 only"; // gives "Witchspace: Mk 2 only"

summary

A very short summary of the type of ship this is, e.g. "Heavy Fighter" or "Research Installation". Some common ship types are defined in descriptions.plist with keys beginning oolite-ship-library-summary- - if you wish to use one of these keys, then using the descriptions key will make it consistent with core entries if there is a translation OXP installed - e.g.

summary = "[oolite-ship-library-summary-HF]";

rather than

summary = "Heavy Fighter";

Ship summaries not used by any Oolite core ship can be requested for addition to the translatable list if they have general applicability.

Vanilla game code list (based on the ship roles):

 "oolite-ship-library-summary-CP"	= "Evacuation ship";		eg Escape Capsule
 "oolite-ship-library-summary-HF"	= "Heavy fighter";		eg Asp
 "oolite-ship-library-summary-HFr"	= "Heavy freighter";		eg Anaconda
 "oolite-ship-library-summary-HT"	= "Heavy transport";		
 "oolite-ship-library-summary-HM"	= "Heavy multi-role";		eg Cobra Mk3
 "oolite-ship-library-summary-LF"	= "Light fighter";		eg Krait, Mamba, Sidewinder - and Thargon
 "oolite-ship-library-summary-LFr"	= "Light freighter";		
 "oolite-ship-library-summary-LM"	= "Light multi-role";		eg Cobra Mk1, Moray
 "oolite-ship-library-summary-LT"	= "Light transport";		eg Adder, Orbital Shuttle, Worm
 "oolite-ship-library-summary-MF"	= "Medium fighter";		eg Gecko
 "oolite-ship-library-summary-MFr"	= "Medium freighter";		eg Boa, BCC, Python
 "oolite-ship-library-summary-MM"	= "Medium multi-role";		
 "oolite-ship-library-summary-MT"	= "Medium transport";		eg Transporter
 "oolite-ship-library-summary-PHF"	= "Police heavy fighter";	eg Viper Interceptor
 "oolite-ship-library-summary-PLF"	= "Police light fighter";	eg Viper
 "oolite-ship-library-summary-RW"	= "Recon warship";		eg Thargoid

Not ships:

 "oolite-ship-library-summary-CG"	= "Goods container";
 "oolite-ship-library-summary-NB"	= "Natural body";		eg Asteroid
 "oolite-ship-library-summary-SM"	= "Mining installation";	eg Rock Hermit
 "oolite-ship-library-summary-SA"	= "Navigation aid";		eg Buoy
 "oolite-ship-library-summary-SO"	= "Orbital station";
 "oolite-ship-library-summary-WMn"	= "Timed explosive";		eg Q-bomb
 "oolite-ship-library-summary-WMs"	= "Fire-and-forget missile";	eg Missile

The FdL has been left out as an example: it is officially listed as a Medium Transport which seems a tad incongruous for a luxury yacht with as many staff (12) as its cargo capacity!

Do not confuse these with the similarly named "roles" in Oolite Ship Roles!

Problems

• Finding the name: some oxp's contain more than one of a specific item - for example, the Behemoth.oxp contains lots of ships. These include both general Behemoths of types 1 - 4 and several dozen named Behemoths of each type. Identifying for a named Behemoth ("behemoth-argus") works. Identifying a generic type ("behemoth-type1") does not.

See also NiteOwl's comment here

• Changing the name: this can be done via the creation of a shipdata-overrides.plist if necessary.

Eg (for just one of the icesteroids in Staer9's .oxp):

{
// shipdata-overrides.plist
"staer9_asteroid_1" = 
    {
    name = "Asteroid (Ice)";
    };
}

Links

• Definitions: what is a medium freighter? See here (2020)
• Examples: See Missing Ship Specifications (2022).
• Overriding another Shiplibrary.plist (2022).