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:
- 1 accuracy
- 2 aft_eject_position
- 3 aft_weapon_type
- 4 ai_type
- 5 auto_ai
- 6 beacon
- 7 bounty
- 8 cargo_carried
- 9 cargo_type
- 10 cloak_passive
- 11 conditions
- 12 custom_views
- 13 death_actions
- 14 debris_role
- 15 defense_ship
- 16 defense_ship_role
- 17 density
- 18 display_name
- 19 docking_pattern_model
- 20 energy_recharge_rate
- 21 escape_pod_model
- 22 escorts
- 23 escort-role
- 24 escort-ship
- 25 equipment_price_factor
- 26 equivalent_tech_level
- 27 exhaust
- 28 extra_cargo
- 29 forward_weapon_type
- 30 frangible
- 31 fragment_chance
- 32 fuel
- 33 has_cloaking_device
- 34 has_ecm
- 35 has_energy_bomb
- 36 has_escape_pod
- 37 has_fuel_injection
- 38 has_military_jammer
- 39 has_military_scanner_filter
- 40 has_npc_traffic
- 41 has_scoop
- 42 has_scoop_message
- 43 has_shield_booster
- 44 has_shield_enhancer
- 45 hasShipyard
- 46 heat_insulation
- 47 hud
- 48 hyperspace_motor_spin_time
- 49 isCarrier
- 50 is_submunition
- 51 is_template
- 52 laser_color
- 53 launch_actions
- 54 like_ship
- 55 likely_cargo
- 56 market
- 57 materials
- 58 max_cargo
- 59 max_defense_ships
- 60 max_energy
- 61 max_flight_pitch
- 62 max_flight_roll
- 63 max_flight_speed
- 64 max_flight_yaw
- 65 max_missiles
- 66 max_police
- 67 max_scavengers
- 68 missile_launch_position
- 69 missile_load_time
- 70 missiles
- 71 missile_role
- 72 model
- 73 name
- 74 no_boulders
- 75 pilot
- 76 port_dimensions
- 77 port_radius
- 78 requires_docking_clearance
- 79 roles
- 80 rotating
- 81 rotational_velocity
- 82 scanClass
- 83 scanner_range
- 84 scoop_position
- 85 script
- 86 script_info
- 87 script_actions
- 88 setup_actions
- 89 shaders
- 90 smooth
- 91 spawn
- 92 subentities
- 93 track_contacts
- 94 throw_sparks
- 95 thrust
- 96 unpiloted
- 97 view_position_..
- 98 weapon_energy
- 99 weapon_offset
- 100 weapon_position_..
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 assings to the missile the accuracy value of 0.0, which corresponds to the standard missile tracking behaviour.
Used with NPC ships it enlarges the chance of shooting at greater distances. Value with NPC ships is between -5 and 10.
Determines the XYZ point on the model from which cargo is ejected.
<key>aft_eject_position</key> <string>0.0 -4.5 -23.0</string>
Assigns the ship's laser. Any weapon type from the equipment.plist can be used (and WEAPON_NONE).
Assigns an AI to the entity. This may be a previously existing AI, or one custom made for the occasion.
Introduced in version 1.69 to autoswitch ai to the appropriate one if a ship was added by a script in one of its standard roles like trader or pirate. See also the comment inside the autoAIMap.plist inside Oolite 1.69 or newer. When not defined it will be true by default. Defining auto_ai is only necessary when using one of the standard roles mentioned in the autoAIMap.plist for your ship. Example:
Starting with Oolite 1.73 also the populator will look at the auto_ai during system setup. When auto_ai is false the ship will keep the ai_type defined for the ship and not give it the default ai for that role.
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.
The following characters are known to be used as identifiers for stations and other fixed objects (listed with their respective OXPs):
A = Astromine (Commies) B = Black Monk Monastery (Black Monks) A Seedy Space Bar (Random Hits) Nemeanian Military Base (Assassins) C = CoachWhip hOopy Casino (Hoopy Casino) Pi-42 Con Store (Your Ad Here) F = Collective Zero-G Factory (Commies) Collective SLAPU (Commies) Imperial AstroFactory (Dictators) G = Griff Research Ltd Orbital Base (Assassins) GRS Buoy Factory (GRS Buoy Repair) H = Hacker Outpost (Anarchies) Deep Space Hoopy Hotel : Hades Branch (Assassins) L = The Link Base (Ionics) Deep Space Hoopy Hotel : Lernean Branch (Assassins) N = Main Station Beacon P = Tianve Pulsar Monitoring Station (Tianve) R = Rock Hermit (Rock Hermit Locator) Augeaian Orbital Repair Facility (Assassins) Rebel Outpost (Assassins) Q = Hesperides Wiseguy Way-Station (Assassins) S = Navy SecCom Station (Galactic Navy) Special Branch Orbital Headquarters (Assassins) T = Taranis Corporation HQ (Taranis) W = Witchpoint Buoy Z = Free Trade Zone (Free Trade Zone)
The following characters are known to be used for non-station objects that may appear anywhere:
H = Homing Beacon (ett Homing Beacon)
The following characters should not be assigned easily to stations or ships that are supposed to appear anywhere, because they are likely to be used for ships in other OXPs:
M = Mark T = Target V = Victim X = general marker + = general marker
Starting with Oolite 1.73 we can also use custom icons with the compass. For that you must define a key in descriptions.plist with the same name as one of the roles of the ship with beacon. Than define the icon in the same way as missile icons. (An array of x/y-coordinates that will be connected by lines)
"fuelStation_location" = (1, 2, -3, 2, -3, -4, 3, -4, 3, 4, -3, 4, -3, 3, 2, 3, 2, -3, 1, -3 );
Sets a Cr. reward on the NPC's head, and is bound to give it trouble with the law .
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.
Since Oolite 1.74 it will also be possible to define a mix of random cargo for ships by using the string "SCARCE_GOODS" or "PLENTIFUL_GOODS", instead of a commodity name. The first selects random goods that are scarce at the main station, the second selects goods that are plentiful present at the main station. (Populator added traders heading toward the station always have scarce goods while traders heading from the main station always have plentiful goods on board. It would be wise to stick to this rule with custom ships.)
To make cargo_carried working for ships, the cargo_type must be "CARGO_NOT_CARGO" to define the ship not being cargo itself. (see below)
Determines if object is indeed cargo (CARGO_RANDOM, CARGO_SLAVES, CARGO_THARGOID, CARGO_ALLOY, CARGO_MINERALS, CARGO_CARRIED) or a ship, as below, which is not cargo. Works since Oolite 1.71 also for pods spawn by a script. CARGO_CARRIED needs in addition an second key cargo_carried that specifies the cargo. (see below)
In v1.63, more control of contents of barrels will be available through the CARGO_CARRIED string.
<key>cargo_type</key> <string>CARGO_CARRIED</string> <key>cargo_carried</key> <string>4 Gold</string>
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.
<key>cargo_type</key> <string>CARGO_NOT_CARGO</string> <key>cargo_carried</key> <string>Computers</string>
Another notable type of cargo is the scripted item CARGO_SCRIPTED_ITEM, as examplified by the cloacking device. When CARGO_SCRIPTED_ITEM is defined, the barrels will trigger scooping events for the ship-scripts. Other barrels don't trigger scooping events.
Until 1.74 such scripted barrels were removed from the system after scooping. Starting with 1.74 the barrels are stored in the ships hold like normal barrels when a cargo was defined for them with the JS method "setCargo". Scripted cargo works with any object that can be scooped. When you have scripted escape pods that must be preserved, fill it with one ton of Slaves.
When true, any firing of laser will deactivate the cloak. (Added in oolite 1.73. False by default)
Whit 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.
<key>conditions</key> <array> <string>systemGovernment_number equal 3</string> <string>systemEconomy_number lessthan 4</string> </array>
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.
<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>
Gives an opportunity to have a ship's death trigger one or a set of script_actions.
<key>death_actions</key> <array> <string>spawn: explosive_shrapnel 1</string> </array>
Specifies the kind of debris an asteroid or boulder generates. When not defined they default to generating 'ships' with role "boulder" or "splinter". (Key added with Oolite 1.74)
<key>debris_role</key> <string> <string>my_boulder_foo</string> </string>
Gives an oportunity to designate a particular ship by name that will defend a station/carrier. When launched from a carrier the scanclass becomes that of the carrier.
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 scanclass becomes that of the carrier.
This real value is used to calculate a ships total mass. Default is 1.0 (Introduced in version 1.69?)
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.
<key>display_name</key> <string>ExampleShip Mark IX</string>
The name of the .dat file that is used for displaying the docking pattern for this station only. Default is ring.dat. (Introduced in version 1.74)
The rate at which energy is replenished. Stations are at 100, Adders at 2.
With this entry ships can have custom escape pods. (starting from version 1.65) You have to specify the role of your custom escape pod (not its entry-name).
Determines how many escorts an NPC shall have. Maximum is 16. In save systems Oolite may randomly decide to subtract escorts from the defined value.
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.
Assigns the specific ship type to be the escort, by the ship's role. (Starting with Oolite 1.74 also the name "escort_role" is accepted.)
Warning: Only usable since Oolite 1.71. It will use the AI file defined in shipdata for this escort and will not use any default escortAI. So make sure the summoned escort has an AI defined in its entry that is capable of supporting escorting.
Assigns the specific ship type to be the escort, by the ship's name. (Starting with Oolite 1.74 also the name "escort_ship" is accepted.)
Equipment price mask for dockables.
Sets shipyard tech level for dockables, different to the local system techlevel.
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 wide a plume is on x axis. (x radius)
height in meters, how tall a plume is on y axis. (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)
<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>
New in version 1.62rc3 Cargobay extension size can now 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.
Assigns the ship's laser. Any weapon type from the equipment.plist can be used (and WEAPON_NONE).
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.
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)
Determines an NPC ship's fuel storage, which will affect how it uses its Fuel Injectors.
Determines if a ship has a cloacking device installed. By chance factor, or true/false.
Determines if a ship has the E.C.M system installed. By chance factor, or true/false.
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.
(Since Oolite 1.73 there is a check to only deploy the bomb when having also fuel-injectors and some fuel left to avoid getting killed by its own bomb)
Determines if a ship has an escape pod. Can be either a boolean value, or a number from 0 to 1 expressing the likelihood of the equipment being present. Starting with version 1.65 ships can have multiple escape pods. To specify more than one escape pod, has_escape_pod must be set to a numeric value corresponding to the escape pods present on board.
has_escape_pod = no; has_escape_pod = 0.75; has_escape_pod = 3;
Determines if a ship has the witchdrive fuel injector.
Determines if a ship has a military jammer. Ships equipped with this item become invisible on the radar. Example:
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:
Determines if a station has NPC traffic (carriers are treated as stations, too). Default is "YES", when set to NO the station will not launch random traders. Introduced in version 1.70
Determines if a ship has a fuel/cargo scoop.
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)
Determines if a ship has the shield booster. (enlarges max energy with 256)
Determines if a ship has the coveted shield enhancer. (enlarges max energy with 256 and raises energy recharge rate with 50%)
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. (Starting with Oolite 1.74 also the name "has_shipyard" is accepted.)
This real number gives the amount of heat insulation of a ship. Default is 1.0 Only for NPC ships. Playes ships can have the equipment EQ_HEAT_SHIELDING with gives the player than a heat_insulation of 2.0
Used for a playership, to assign another HUD than the default one.
Used for a playership to modify jump countdown time. Default = 15. (Added with Oolite 1.72)
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. (Starting with Oolite 1.74 also the name "is_carrier" is accepted.)
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. (Key added in Oolite 1.72)
Set this to yes/<true/> 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. (Key added in Oolite 1.72)
Determines a ship's laser colour.
In Oolite 1.69 and later, this is any colour specifier. In earlier versions, it must be a named colour. Also as of 1.69, the game requires laser colours to be reasonably bright; if the brightest colour component is less than 0.5, the colour will be brightened.
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" <key>launch_actions</key> <array> <string>setAITo: pirateAI.plist</string> </array>
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.
<key>like_ship</key> <string>adder</string> <key>max_flight_speed</key> <real>700</real> <key>name</key> <string>Freak Turbo Adder</string>
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.
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
See Materials in Oolite.
Sets the ship's cargo limit. On explosion of trader ships added by the System Populator, 10% of this value is used as likely cargo. When the result is lower than 16 it is the cargo, when higher than 15, it is changed in a random value between 0 and 15.
Designates how many ships a dockable entity (station, carrier) can launch in defense. See also Station Ships
Sets the ship's energy value.
Sets pitch factor. Will usually range from a sluggish 0.6 to a very sensitive 3.0
Sets roll factor. Will usually range from 0.8 to 4.6.
Sets the model's top speed. Interceptors fly at 520 (0.52 LM), Shuttles at 80.
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
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.
Designates how many police or patrol ships a dockable entity (station, carrier) can launch. See also Station Ships
<key>max_police </key> <integer>10</integer>
Designates how many scavengers or miners a dockable entity (station, carrier) can launch. See also Station Ships
Determines the XYZ point on the model from which a missile is launched.
<key>missile_launch_position</key> <string>0.0 -2.25 10.0</string>
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. Added with test release 1.74
Sets a ship's probable number of missiles.
Defines the entity that is launched as missile. Can specify a certain missile-type or any other ship-entity by role. Only applies to NPC's, player-ship dependacies must be defined in the shipyard.plist. If no missile_role is defined and a NPC ship launches a missile he most often chooses the default missile but sometimes chooses one at random from all ships with role missile inside one of the installed OXP's.
Assigns the entity's corresponding .dat file that will be found with the exact same name in the Models folder.
States the model's name as it will be known to the ID computer.
<key>name</key> <string>ExampleShip Mark IX</string>
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.
Gives the ship a predefined pilot, defined in characters.plist. Can eject in pod, if available, and be captured.
Defines the size of the docking port and takes 3 numbers. This key is generally of little use and can be skipped as it becomes overwritten by the size of the bounding box of the dock subentity.
<key>port_dimensions</key> <string>65 30 500</string>
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.
Sets the requirement for docking clearance. Default is false. See also DockingClearance
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.
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.
<key>roles</key> <string>hunter(0.25) trader(2.0) pirate</string>
or an exclusive role, simply:
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.
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.
Given to a station when rotation is desired.
<key>rotational_velocity</key> <string>0.707 0.0 0.0 0.707</string>
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.
(Starting with Oolite 1.74 also the name "scan_class" is accepted. Also starting with 1.74 is that scripts can define custom colours for ships on the IFF system so ships might have an other scan_class as is seams.)
Oolite uses scanClass 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!
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.
Determines the XYZ point on the model from which cargo is scooped. (default is 0,0,0)
<key>scoop_position</key> <string>0.0 -4.5 -23.0</string>
scriptInfo property of
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.
<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>
Arranges a process that may be necessary for some objects, like ball turrets.
<key>setup_actions</key> <array> <string>initialiseTurret</string> </array>
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.
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.
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.
<key>spawn</key> <dict> <key>facing_position</key> <string>spu 0 0 0</string> <key>position</key> <string>wpu 0 0 0.2</string> </dict>
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 1.72 or later provides a built-in shipdata entry for ball turrets called, imaginatively, ballturret.
- Flashers are blobs which glow with a pulsating light. From Oolite 1.74 onwards, constant light will also be an option. Note that while flashers appear luminous – they are unaffected by shadows – they do not cast light on other objects.
New-style subentity definition
Oolite 1.73 introduced a more flexible, dictionary-based way of specifying subentities. A new-style subentity is a dictionary using the following keys:
|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.|
|fire_rate||number||Interval between shots in seconds, for ball_turret subentities. Default: 0.5; minimum: 0.25.|
|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.)|
Old-style subentity definition
Prior to Oolite 1.73, this was the the only way to specify a subentity.
An old-style subentity definition is a string with eight items separated by spaces. In the description below, words in bold correspond to keys in new-style definitions. There are two variants:
For a flasher, the entry takes the form:
*FLASHER* x y z hue frequency phase size
*FLASHER* must be precisely the string “*FLASHER*”, in capitals.
x, y and z form the position.
hue specifies the HSV hue component (in degrees) of color. Saturation and value are always 1.
frequency, phase and size are the same as in the new-style format.
initially_on is false.
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.
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.
Each new ship should start in seemingly good operating condition, unless specifically told not to. (Added with oolite 1.73, false by default)
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).
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.
Sets the ship's 4 point-of-view positions in XYZ relative to the model.
<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>
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 ignored.
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
N.B. It does not have any effect on player ships.
Used to change the offsetpoint of a plasma cannon. Removed after version 1.65
Plots the 'gunmouth' points of the model's 4 potential lasers.
<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>