Shipdata.plist

2006-07-30T15:50:11Z

Randall: /* extra_cargo */

'''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 [[shipdata_structure|(extra)]]. The following (property) entries are, for order's sake, listed alphabetically:

==accuracy==
Added to an NPC mining ship to set the degree of efficiency.

Example:
<key>accuracy</key>
<integer>8</integer>

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

Example:
<key>aft_eject_position</key>
<string>0.0 -4.5 -23.0</string>

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

Example:
<key>ai_type</key>
<string>pirateAI.plist</string>

== beacon ==
A special feature for beacons and navigation aids.
The string can be anything - the first letter is what's displayed in the advanced space compass.

Example:
<key>beacon</key>
<string>X-code</string>

== bounty ==
Sets a Cr. reward on the NPC's head, and is bound to give it trouble with the law .

Example:
<key>bounty</key>
<integer>50</integer>

== cargo_carried ==
Determines the type of cargo carried as described in [[commodities]] and [[commodities.plist]]. Only one type can be specified.

Example:
<key>cargo_carried</key>
<string>Gold</string>

== cargo_type ==
Determines if object is indeed cargo (CARGO_RANDOM, CARGO_SLAVES, CARGO_THARGOID) or a ship, as below, which is not cargo. Another notable type of cargo is the scripted item (CARGO_SCRIPTED_ITEM), as examplified by the cloacking device. Only works for randomly generated cargopods.

Example:
<key>cargo_type</key>
<string>CARGO_NOT_CARGO</string>

In v1.63, more controll will be available through the CARGO_CARRIED string. (see also discussion)

Example:
<key>cargo_type</key>
<string>CARGO_CARRIED</string>
<key>cargo_carried</key>
<string>4 Gold</string>

== 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 [[Quaternions|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<br />
X = the sine of half the angle rotated about xyz, multiplied by x<br />
Y = the sine of half the angle rotated about xyz, multiplied by y <br />
Z = the sine of half the angle rotated about xyz, multiplied by z <br />

Four decimal places are probably enough accuracy for these values.

Example:
<key>custom_views</key>
<array>
<dict>
<key>view_description</key>
<string>External View - Aft</string>
<key>view_position</key>
<string>0.0 100.0 -173.21</string>
<key>view_orientation</key>
<string>0.966 -0.259 0.0 0.0</string>
<key>weapon_facing</key>
<string>FORWARD</string>
</dict>
<dict>
<key>view_description</key>
<string>Scoop camera</string>
<key>view_position</key>
<string>0.0 -38.3333 1.6666</string>
<key>view_orientation</key>
<string>1.0 0.0 0.0 0.0</string>
<key>weapon_facing</key>
<string>FORWARD</string>
</dict>
</array>

== death_actions ==
Gives an oportunity to have a ship's death trigger one or a set of [[Shipdata.plist#script_actions|script_actions]].

Example:
<key>death_actions</key>
<array>
<string>spawn: explosive_shrapnel 1</string>
</array>

== 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 [[Shipdata.plist#roles|roles]] of the ship(s) that are assigned to defend.

Example:
<key> defense_ship_role </key>
<string>carrier_defenders</string>

== energy_recharge_rate ==
The rate at which energy is replenished. Stations are at 100, Adders at 2..

Example:
<key>energy_recharge_rate</key>
<real>3.5</real>

== escorts ==
Determines how many escorts an NPC shall have.

Example:
<key>escorts</key>
<integer>4</integer>

== escort-role ==
Assigns the specific ship type to be the escort, by the ship's role

Example:
<key>escort-role</key>
<string>my_custom_escort_role</string>

== escort-ship ==
Assigns the specific ship type to be the escort, by the ship's name.

Example:
<key>escort-ship</key>
<string>cobramk1</string>

== 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 metres, how wide a plume is on x axis.

'''height''' in metres, how tall a plume is on y axis.

'''length''' in metres, how long a plume is on z axis.

Below are 2 assigned plumes at coords 5, 0, -25 and -5, 0, -25, and each plume is 6 m wide, 4 m tall and m 10 long

Example:
<key>exhaust</key>
<array>
<string>5 0.0 -25 6.0 4.0 10.0</string>
<string>-5 0.0 -25 6.0 4.0 10.0</string>
</array>

== extra_cargo ==
New in version 1.62rc3
Cargobay extension size can now be customised.

Example:
<key>extra_cargo</key>
<integer>value</integer>

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

Example:
<key>forward_weapon_type</key>
<string>WEAPON_BEAM_LASER</string>

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

Example:
<key>frangible</key>
<false/>

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

Example:
<key>fuel</key>
<integer>70</integer>

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

Example:
<key>has_ecm</key>
<real>0.5</real>
or
<key>has_ecm</key>
<false/>

== has_escape_pod ==
Determines if a ship has an escape pod.

Example:
<key>has_escape_pod</key>
<false/>

== has_fuel_injection ==
Determines if a ship has the witchdrive fuel injector.

Example:
<key>has_fuel_injection </key>
<real>0.99</real>

== has_scoop ==
Determines if a ship has a fuel/cargo scoop.

Example:
<key>has_scoop</key>
<false/>

== has_shield_enhancer ==
Determines if a ship has the coveted shield enhancer.

Example:
<key>has_shield_enhancer</key>
<real>0.45000000000000001</real>

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

Example:
<key>hud</key>
<string>specialhud.plist</string>

==isCarrier==
Added as a tag for making the model be considered a carrier. An alternative to including ''carrier'' among the [[Shipdata.plist#roles|roles]].

Example:
<key>isCarrier</key>
<true/>

== laser_color ==
Determines a ship's laser colour. NPCs that is, not the player's laser.

Example:
<key>laser_color</key>
<string>pinkColor</string>

== like_ship ==
Allows a shipdata entry (of a ship with many matching characteristics to another) to be short and sweet, adopting data of stated ship (name), and allowing for any differences between these ships that will be listed. (It is best not to refer to other references.)

Example:
<key>like_ship</key>
<string>adder</string>
<key>max_flight_speed</key>
<real>700</real>
<key>name</key>
<string>Freak Turbo Adder</string>

== likely_cargo ==
Sets a probable number of tons cargo carried by an NPC, as something else than the stated maximum cargo limit.

Example:
<key>likely_cargo</key>
<integer>2</integer>

== max_cargo ==
Sets the ship's cargo limit.

Example:
<key>max_cargo</key>
<integer>5</integer>

== max_defense_ships ==
Designates how many ships a dockable entity (station, carrier) can launch in defense.

Example:
<key>max_defense_ships </key>
<integer>10</integer>

== max_energy ==
Sets the ship's energy value.

Example:
<key>max_energy</key>
<real>300</real>

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

Example:
<key>max_flight_pitch</key>
<real>2.2</real>

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

Example:
<key>max_flight_roll</key>
<real>4.2000000000000002</real>

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

Example:
<key>max_flight_speed</key>
<real>320</real>

== max_missiles ==
Sets a ship's missile limit.

Example:
<key>max_missiles</key>
<integer>1</integer>

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

Example:
<key>missile_launch_position</key>
<string>0.0 -2.25 10.0</string>

== missiles ==
Sets a ship's probable number of missiles.

Example:
<key>missiles</key>
<integer>0</integer>

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

Example:
<key>model</key>
<string>example_ship.dat</string>

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

Example:
<key>name</key>
<string>ExampleShip Mark IX</string>

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

Example:
<key>roles</key>
<string>hunter(0.25) trader(2.0) pirate</string>

or an exclusive role, simply:

<key>roles</key>
<string>uniquely_named_role</string>

This has the benefit of being the only ship to be selected when a [[Script.plist|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:
<key>roles</key>
<string>Gold</string>

==rotating==
Given to a station when rotation is desired.

Example:
<key>rotating</key>
<true/>

== rotational_velocity ==
May be applied to a sub-entity, like the following entry to the [[Shipdata.plist#subentities|subentity]] spines of the [[Weeviloid Hunter]].
Takes the form of [[Quaternions|quaternions]]. The following example enables rotation around the Z-axis.

Example:
<key>rotational_velocity</key>
<string>0.707 0.0 0.0 0.707</string>

== scanClass ==
Will alter the model's appearance on the [[IFF system]]. If this line is omitted, it will become by default a standard ship entity, appearing as yellow flag on the radar. There are other options.
* CLASS_BUOY
* CLASS_CARGO
* CLASS_MILITARY
* CLASS_MISSILE
* CLASS_POLICE
* CLASS_ROCK
* CLASS_STATION
* CLASS_THARGOID

==== Developer Note ====
Oolite uses scanClass internally to determine the behaviour of some ships (particularly with regard to who may shoot whom without incurring legal penatlties). Bear this in mind and don't allocate CLASS_POLICE or CLASS_THARGOID to ships lightly!

Example:
<key>scanClass</key>
<string>CLASS_ROCK</string>

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

Example:
<key>script_actions</key>
<array>
<string>debugOn</string>
<string>testForEquipment: EQ_CLOAKING_DEVICE</string>
<dict>
<key>conditions</key>
<array>
<string>foundEquipment_bool equal NO</string>
</array>
<key>do</key>
<array>
<string>awardEquipment: EQ_CLOAKING_DEVICE</string>
</array>
<key>else</key>
<array>
<string>awardCargo: 100 Gold</string>
</array>
</dict>
<string>debugOff</string>
</array>

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

Example:
<key>setup_actions</key>
<array>
<string>initialiseTurret</string>
</array>

== 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:
<key>smooth</key>
<true/>

== subentities ==
Can assign other objects, lights and turrets, to be associated with the model, fixed to a relative position. The first three numbers are XYZ positions, however, controlling positioning of enslaved objects is done by means of [[Quaternions|quaternions]].

Lights follow their own recipe.
*FLASHER* x y z hue speed offset size

'''x y z''' is the position relative to the origin of the main model.

'''hue''' describes the colour of the light as a position on a color wheel.

'''speed''' describes how fast the light pulses (on a sine wave) in Hertz (at 0 the light is constantly lit)

'''offset''' is the offset to the sine wave (0..1) to time-shift each light

'''size''' is the size of the light's corona in metres

Example:
<key>subentities</key>
<array>
<string>mySubEntity 0 -5 10 1 0 0 0</string>
<string>*FLASHER* 0 5.5 10 30.0 1 0.0 12</string>
</array>

note: armed subentities always fire along their Z-axis. When rotating along the Z(t=0)-axis.

== thrust ==
Gives the entity an 'inertia' value, translating size and speed into a form of velocity. 0 for rocks and cargo, 50 for a very fast ship, 100 for a station..

Example:
<key>thrust</key>
<real>25</real>

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

Example:
<key>view_position_aft</key>
<string>0.0 5.0 -20.0</string>
<key>view_position_forward</key>
<string>0.0 1.9375 5.0</string>
<key>view_position_port</key>
<string>-11.85 2.825 -3.5</string>
<key>view_position_starboard</key>
<string>11.85 2.825 -3.5</string>

== weapon_energy ==
Gives a weapon energy value to the ship's laser that is different than the default.

Example:
<key>weapon_energy</key>
<real>15</real>

== weapon_offset ==
must ask Aegidian. does it make a poor shot?

Example:
<key>weapon_offset_x</key>
<real>10</real>

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

Example:
<key>weapon_position_aft</key>
<string>0.0 -5.0 -20.0</string>
<key>weapon_position_forward</key>
<string>0.0 0.0417 16.6667</string>
<key>weapon_position_port</key>
<string>-13.75 -2.0625 -1.875</string>
<key>weapon_position_starboard</key>
<string>13.75 -2.0625 -1.875</string>

--------------------------------------------------------------------------------
[[Category:Oolite]]

Elite Wiki - User contributions [en]

Shipdata.plist