Difference between revisions of "Shiplibrary.plist"
Cholmondely (talk | contribs) (→Problems: Added another) |
Cholmondely (talk | contribs) m (Minor tweak) |
||
(5 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | The <code>shiplibrary.plist</code> file places ship information on the | + | The <code>shiplibrary.plist</code> 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. | 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. | ||
Line 14: | Line 14: | ||
===class=== | ===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''.). <br> | 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''.). <br> | ||
− | Other values are added in the [[Misc plists|descriptions.plist]] (see there for an example). | + | Other values are added in the [[Misc plists|descriptions.plist]] (eg. "Communist Craft" - see there for an example). |
class = "station"; | class = "station"; | ||
Line 33: | Line 33: | ||
The data key in [[shipdata.plist]] of this ship. | The data key in [[shipdata.plist]] of this ship. | ||
ship = "cobra3-trader"; | ship = "cobra3-trader"; | ||
+ | |||
+ | See '''Problems''' with naming, below. | ||
===ship_data=== | ===ship_data=== | ||
Line 110: | Line 112: | ||
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! | 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 == | == 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. | *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 [ | + | :See also NiteOwl's comment [https://bb.oolite.space/viewtopic.php?p=288275#p288275 here] |
Line 127: | Line 131: | ||
== Links == | == Links == | ||
− | *See [ | + | *Definitions: what ''is'' a medium freighter? See [https://bb.oolite.space/viewtopic.php?f=6&t=20714&p=271187 here] (2020) |
− | *[ | + | *Examples: See [https://bb.oolite.space/viewtopic.php?p=285453#p285453 Missing Ship Specifications] (2022). |
+ | *[https://bb.oolite.space/viewtopic.php?p=287342#p287342 Overriding another Shiplibrary.plist] (2022). | ||
[[Category:Oolite]] | [[Category:Oolite]] | ||
[[Category:Oolite scripting]] | [[Category:Oolite scripting]] |
Latest revision as of 08:54, 9 July 2024
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.
Contents
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).