Oolite JavaScript Reference: Ship
Prototype: Entity
Subtypes: Station
, PlayerShip
The Ship
class is an Entity
representing a ship, station, missile, cargo pod or other flying item – anything that can be specified in shipdata.plist. A Ship
has all the properties and methods of a Entity
, and several others.
Station
s and the PlayerShip
are types of ship. Note that these more specific types have additional properties and methods.
Contents
- 1 Properties
- 1.1 accuracy
- 1.2 aftWeapon
- 1.3 AI
- 1.4 AIFoundTarget
- 1.5 AIPrimaryAggressor
- 1.6 AIState
- 1.7 beaconCode
- 1.8 boundingBox
- 1.9 bounty
- 1.10 cargoSpaceCapacity
- 1.11 commodity
- 1.12 commodityAmount
- 1.13 contracts
- 1.14 cloakAutomatic
- 1.15 cruiseSpeed
- 1.16 currentWeapon
- 1.17 dataKey
- 1.18 defenseTargets
- 1.19 desiredRange
- 1.20 desiredSpeed
- 1.21 destination
- 1.22 displayName
- 1.23 energyRechargeRate
- 1.24 entityPersonality
- 1.25 equipment
- 1.26 escortGroup
- 1.27 escorts
- 1.28 extraCargo
- 1.29 forwardWeapon
- 1.30 fuel
- 1.31 group
- 1.32 hasHostileTarget
- 1.33 hasHyperspaceMotor
- 1.34 hasSuspendedAI
- 1.35 heatInsulation
- 1.36 isBeacon
- 1.37 isBoulder
- 1.38 isCargo
- 1.39 isCloaked
- 1.40 isDerelict
- 1.41 isFrangible
- 1.42 isJamming
- 1.43 isMine
- 1.44 isMissile
- 1.45 isPiloted
- 1.46 isPirate
- 1.47 isPirateVictim
- 1.48 isPolice
- 1.49 isRock
- 1.50 isThargoid
- 1.51 isTrader
- 1.52 isWeapon
- 1.53 laserHeatLevel*
- 1.54 lightsActive
- 1.55 maxEscorts
- 1.56 maxPitch
- 1.57 maxRoll
- 1.58 maxSpeed
- 1.59 maxThrust
- 1.60 maxYaw
- 1.61 missileCapacity
- 1.62 missileLoadTime
- 1.63 missiles
- 1.64 name
- 1.65 parcelCount
- 1.66 parcels
- 1.67 passengerCapacity
- 1.68 passengerCount
- 1.69 passengers
- 1.70 pitch
- 1.71 portWeapon
- 1.72 potentialCollider
- 1.73 primaryRole
- 1.74 reportAIMessages
- 1.75 roleWeights
- 1.76 roles
- 1.77 roll
- 1.78 savedCoordinates
- 1.79 scannerDisplayColor1
- 1.80 scannerDisplayColor2
- 1.81 scannerRange
- 1.82 script
- 1.83 scriptedMisjump
- 1.84 scriptedMisjumpRange
- 1.85 scriptInfo
- 1.86 speed
- 1.87 starboardWeapon
- 1.88 subEntities
- 1.89 subEntityCapacity
- 1.90 target
- 1.91 temperature
- 1.92 thrust
- 1.93 thrustVector
- 1.94 trackCloseContacts
- 1.95 vectorForward
- 1.96 vectorRight
- 1.97 vectorUp
- 1.98 velocity
- 1.99 weaponFacings
- 1.100 weaponPosition*
- 1.101 weaponRange
- 1.102 withinStationAegis
- 1.103 yaw
- 2 Methods
- 2.1 abandonShip
- 2.2 addDefenseTarget
- 2.3 awardEquipment
- 2.4 canAwardEquipment
- 2.5 clearDefenseTargets
- 2.6 commsMessage
- 2.7 dealEnergyDamage
- 2.8 deployEscorts
- 2.9 dockEscorts
- 2.10 dumpCargo
- 2.11 ejectItem
- 2.12 ejectSpecificItem
- 2.13 equipmentStatus
- 2.14 exitAI
- 2.15 exitSystem
- 2.16 explode
- 2.17 fireECM
- 2.18 fireMissile
- 2.19 getMaterials
- 2.20 getShaders
- 2.21 hasRole
- 2.22 reactToAIMessage
- 2.23 remove
- 2.24 removeEquipment
- 2.25 restoreSubEntities
- 2.26 selectNewMissile
- 2.27 sendAIMessage
- 2.28 setAI
- 2.29 setBounty
- 2.30 setCargo
- 2.31 setEquipmentStatus
- 2.32 setMaterials
- 2.33 setScript
- 2.34 setShaders
- 2.35 spawn
- 2.36 spawnOne
- 2.37 switchAI
- 2.38 updateEscortFormation
- 3 Static Methods
- 4 See also
Properties
accuracy
This property was added in Oolite test release 1.77.
accuracy : Number (read/write, read-only and irrelevant for player ship)
The accuracy of the ship's AI. Varies between -5 and +10 for ships, or 0 and +10 for missiles. Setting a value outside the allowed range will set the closest value within the allowed range.
For missiles, this affects the missile tracking, with 0 being the default value.
For NPC ships, this affects their combat AI in many ways. Values of +5 or higher enable various special combat AIs for a tough fight.
aftWeapon
aftWeapon : EquipmentType (read-only, read/write in 1.77)
The currently equipped aft weapon, or null
.
See also: forwardWeapon
, portWeapon
, starboardWeapon
AI
AI : String (read-only)
The name of the ship’s current AI.
See also: AIState
, setAI()
, switchAI()
, exitAI()
AIFoundTarget
This property was added in Oolite test release 1.77.
AIFoundTarget : Entity (read/write, read-only for player)
The "found target" of the ship's AI. This is set by various AI state commands, and is often copied to the primary target with the setTargetToFoundTarget
AI command.
AIPrimaryAggressor
This property was added in Oolite test release 1.77.
AIPrimaryAggressor : Entity (read/write, read-only for player)
The "primary aggressor" of the ship's AI. Often the last ship to attack this ship.
AIState
AIState : String (read/write, read-only for player)
The ship’s AI’s current state.
See also: AI
, reactToAIMessage()
, hasSuspendedAI
beaconCode
beaconCode : String (read-only in 1.76, read-write from 1.77)
If the ship is a beacon, an identifying string. The first character is used for identification on the Advanced Space Compass. For non-beacons, this property is null
. This can not be changed by script for either the player's ship or the main station.
See also: isBeacon
boundingBox
This property was added in Oolite test release 1.77.
boundingBox : Vector (read-only)
For ships, a vector describing the dimensions of the cuboid box containing the ship aligned to the ship axes, including all non-flasher sub-entities. For sub-entities, the dimensions of the box for the sub-entity alone.
Vector components match the standard model order - x
is width, y
is height, z
is length.
bounty
bounty : Number (read/write integer)
The bounty on the ship.
In 1.77, changes to the bounty are given a reason. If you change this directly, the reason sent to shipBountyChanged will be "scripted". To set a different reason, use setBounty instead.
cargoSpaceCapacity
cargoSpaceCapacity : Number (read-only integer)
The ship’s cargo capacity, in tons.
commodity
This property was added in Oolite test release 1.77.
commodity : String (read-only)
The commodity for cargo containers as a lowercase string. Returns null
for non-cargo ships. For scripted cargo that has no specific cargo defined, it returns the general description "goods".
commodityAmount
This property was added in Oolite test release 1.77.
commodityAmount : Number (read-only)
The amount of commodity in a cargo container. (not the number of containers in a ship)
contracts
contracts : Array (read-only NSDictionary)
The ship’s contracts. (For now only available for the player). Each contract contains the entries: commodity: string, quantity: integer, description: string, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer
For example, the information of the first contract can be obtained by:
player.ship.contracts[0].commodity player.ship.contracts[0].quantity player.ship.contracts[0].description player.ship.contracts[0].start player.ship.contracts[0].destination player.ship.contracts[0].startName player.ship.contracts[0].destinationName player.ship.contracts[0].eta // Estimated Time of Arrival. player.ship.contracts[0].etaDescription player.ship.contracts[0].fee // The profit of the contract, paid out on successful delivery. player.ship.contracts[0].premium // The sum paid to obtain the goods and paid back on successful delivery.
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this contract, and premium was the amount the player had to pay to secure this contract.
cloakAutomatic
cloakAutomatic : Boolean (read/write)
If true
(the default), the ship will automatically engage its cloak while attacking. Otherwise, it must be managed by a script. The corresponding shipdata.plist key is cloak_automatic
.
cruiseSpeed
cruiseSpeed : Number (read-only nonnegative)
The ship’s “normal” desiredSpeed
, used in normal flight. Normally this is 80 % of maxSpeed
, but it may be lowered when accepting a slow escort.
currentWeapon
This property was added in Oolite test release 1.77.
currentWeapon : EquipmentType (read/write)
A shortcut property to whichever of aftWeapon
, forwardWeapon
, portWeapon
or starboardWeapon
represents the ship's currently active laser mount.
dataKey
This property was added in Oolite test release 1.77.
dataKey : String (read-only)
The ship data key used to define this ship (e.g. adder-player
or coriolis-station
)
defenseTargets
This property was added in Oolite test release 1.77.
defenseTargets : Array (read-only)
The array of defense targets that the ship has. If the ship has point defense weapons (turrets, thargoid lasers) it may fire them at these targets if it cannot hit its primary target.
See also: addDefenseTarget
, clearDefenseTargets
desiredRange
This property was added in Oolite test release 1.77.
desiredRange : Number (read/write nonnegative, read-only for player)
The range the AI uses in various AI routines to set a distance between the ship and another object - for example, the radius of a sphere around a destination point, or the distance to flee from a hostile ship.
desiredSpeed
desiredSpeed : Number (read/write nonnegative, read-only for player)
The speed the AI will attempt to maintain. The AI core and AI script may change this from time to time. The corresponding AI method is setSpeedFactorTo:
; a speed factor of 1.0 corresponds to a desiredSpeed
equal to maxSpeed
.
See also: cruiseSpeed
destination
This property was added in Oolite test release 1.77.
destination : Vector (read/write, read-only for player)
The destination coordinates for the AI, used in behaviours such as performFlyToRangeFromDestination
.
displayName
displayName : String (read/write, read-only for player)
The name of the ship as seen by the player. By default it is the same as name
.
energyRechargeRate
This property was added in Oolite test release 1.79.
energyRechargeRate : Number (read-only)
The rate at which energy is replenished in every second. The corresponding shipdata.plist key is energy_recharge_rate
.
entityPersonality
entityPersonality : Number (read-only integer)
A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the entityPersonalityInt
uniform binding.
equipment
equipment : Array of EquipmentInfo (read-only)
The equipment a ship is carrying.
escortGroup
escortGroup : ShipGroup
The ship’s deployed escorts.
See also: maxEscorts
escorts
escorts : Array (read-only array of Entitys)
The ship’s deployed escorts.
extraCargo
This property was added in Oolite test release 1.79.
extraCargo : Number (read-only integer)
The amount the cargo capacity increases when an extra cargobay is installed. The corresponding shipdata.plist key is extra_cargo
.
forwardWeapon
forwardWeapon : EquipmentType (read-only, read/write in 1.77)
The currently equipped forward weapon, or null
.
See also: aftWeapon
, portWeapon
, starboardWeapon
fuel
fuel : Number (read/write)
The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth.
See also: PlayerShip.fuelLeakRate
group
group : ShipGroup
Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders.
A group is an individual object that can be linked to several ships belonging to the same group. When a ship dies and the group object has still owners, the group stays active as object. The group is only removed from memory after the last ship that had this group as property is removed.
Adding a group to a ship does not automatic puts that ship in the group. For that to happen you need also use the addShip() command.
e.g.
this.ship.group = new ShipGroup(); this.ship.group.addShip(this.ship);
hasHostileTarget
hasHostileTarget : Boolean (read-only)
true
if the ship’s AI is trying to kill something, false
otherwise. Always false
for the player.
hasHyperspaceMotor
hasHyperspaceMotor : Boolean (read-only)
True if the ship can make witchspace jumps. The corresponding shipdata.plist entry is hyperspace_motor
.
hasSuspendedAI
hasSuspendedAI : Boolean (read-only)
true
if the ship has suspended AIs, false
otherwise.
heatInsulation
heatInsulation : Number (read/write)
The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.
isBeacon
isBeacon : Boolean (read-only)
true
if the ship is a beacon (i.e., can show up on the Advanced Space Compass with a character indicating its identity), false
otherwise.
See also: beaconCode
isBoulder
isBoulder : Boolean (read/write)
true
if the ship is a boulder (i.e., has the role "boulder in its roleset)
isCargo
isCargo : Boolean (read-only)
true
if the ship is cargo (i.e., has scan_class CLASS_CARGO and contains at least one unit)
isCloaked
isCloaked : Boolean (read/write)
true
if the ship has a cloaking device which is currently active false
otherwise. If the ship has a cloaking device and sufficient energy to use it (energy > 0.75 * maxEnergy
), you can activate it by setting isCloaked
to true
.
isDerelict
isDerelict : Boolean (read-only)
true
if the ship is a derelict (i.e., the pilot has ejected from the ship, or the ship was created with the ship-key: "is_hulk")
isFrangible
isFrangible : Boolean (read-only)
true
if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), false
otherwise.
See also: subEntities
, restoreSubEntities()
isJamming
isJamming : Boolean (read-only)
true
if the ship has a military scanner jammer which is currently active false
otherwise.
isMine
isMine : Boolean (read-only)
true
if the ship is a mine, false
otherwise.
isMissile
isMissile : Boolean (read-only)
true
if the ship is a missile, false
otherwise.
isPiloted
isPiloted : Boolean (read-only)
true
if the ship has a pilot on board, false
otherwise. Generally have ships, station and escape pods pilots and have cargo, rocks, missiles or buoys no pilots.
isPirate
isPirate : Boolean (read-only)
true
if the ship is a pirate vessel, false
otherwise. Currently equivalent to primaryRole == "pirate"
.
isPirateVictim
isPirateVictim : Boolean (read-only)
true
if the ship’s primary role is listed in pirate-victim-roles.plist, false
otherwise. This is the same test used by the pirate AI to select victims.
isPolice
isPolice : Boolean (read-only)
true
if the ship is a police vessel, false
otherwise. Currently equivalent to scanClass == "CLASS_POLICE"
.
isRock
isRock : Boolean (read-only)
true
if the ship is a rock (i.e., has scan_class: CLASS_ROCK)
isThargoid
isThargoid : Boolean (read-only)
true
if the ship is a Thargoid vessel, false
otherwise. Currently equivalent to scanClass == "CLASS_THARGOID"
.
isTrader
isTrader : Boolean (read-only)
true
if the ship is a merchant vessel, false
otherwise. Currently equivalent to primaryRole == "trader" || isPlayer
. Note: isPirateVictim
may be a better choice in many cases.
isWeapon
isWeapon : Boolean (read-only)
true
if the ship is a weapon, false
otherwise. Currently equivalent to isMissile || isMine
, but new categories of weapon could be added in future.
laserHeatLevel
*
This property was added in Oolite test release 1.77.
laserHeatLevel : Number (read-only, 0 to 1)
The temperature of the ship's currently active weapon. Thermal cut-out is active above 0.85. For non-player ships, if their forward weapon is empty, then the temperature of the forward weapon may be the temperature of a subentity forward weapon.
laserHeatLevelAft : Number (read-only, 0 to 1) laserHeatLevelForward : Number (read-only, 0 to 1) laserHeatLevelPort : Number (read-only, 0 to 1) laserHeatLevelStarboard : Number (read-only, 0 to 1)
The temperature of specific laser mounts can also be queried.
lightsActive
lightsActive : Boolean (read-write)
Setting this property to true
turns on all the entity’s flashers, and setting it to false
turns them off. Setting it sets the lightsActive
property for all subentities, but subentities’ setting can also be manipulated separately. In addition to affecting flashers, the value can be used by shaders.
Note: lightsActive
is always true
when a ship is spawned, although individual flashers may be off because they have initially_on
set to false in their shipdata.plist declarations.
maxEscorts
This property was added in Oolite test release 1.77.
maxEscorts : Number (read/write)
The maximum number of escorts this ship can have. This cannot be set lower than the number of escorts it currently has, or higher than the value of the MAX_ESCORTS constant (currently 16). There may be other reasons why a ship can have fewer escorts than the value of maxEscorts
(for instance, ships which are escorts cannot have their own escorts)
See also: escortGroup
maxPitch
This property was added in Oolite test release 1.77.
maxPitch : Number (read-only)
The maximum pitch rate of the ship, in radians per second.
See also: pitch
maxRoll
This property was added in Oolite test release 1.77.
maxRoll : Number (read-only)
The maximum roll rate of the ship, in radians per second.
See also: roll
maxSpeed
maxSpeed : Number (read-only)
The ship’s maximum speed under normal power. Note that speed
may exceed this when witch fuel injectors or hyperspeed are in use.
See also: speed
maxThrust
maxThrust : Number (read-only)
The ship’s maximum thrust
. This value is the one defined as thrust
in shipdata.plist.
maxYaw
This property was added in Oolite test release 1.77.
maxYaw : Number (read-only)
The maximum yaw rate of the ship, in radians per second.
See also: yaw
missileCapacity
missileCapacity : Number (read-only integer)
The maximum number of missiles the ship can carry.
missileLoadTime
missileLoadTime : Number (read-write nonnegative)
The minimum amount of time between two missiles. The corresponding shipdata.plist key is missile_load_time
.
missiles
missiles : Array (read-only array of EquipmentInfo)
The ship’s loaded missiles.
name
name : String (read/write, read-only for player)
The name of the ship type (name
key in shipdata.plist).
Note: while name
can be changed, this is discouraged (and will probably not be supported in Oolite 2.0). Use displayName
instead.
parcelCount
This property was added in Oolite test release 1.77.
parcelCount : Number (read-only integer)
The ship’s current number of parcels.
parcels
This property was added in Oolite test release 1.77.
parcels : Array (read-only NSDictionary)
The ship’s parcels. (For now only available for the player). Each parcel list contains the entries: name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer
For example, the information of the first contract can be obtained by:
player.ship.parcels[0].name player.ship.parcels[0].start player.ship.parcels[0].destination player.ship.parcels[0].startName player.ship.parcels[0].destinationName player.ship.parcels[0].eta player.ship.parcels[0].etaDescription player.ship.parcels[0].fee // The final fee, paid out on successful delivery.
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this parcel.
passengerCapacity
passengerCapacity : Number (read-only integer)
The ship’s maximum passenger capacity.
passengerCount
passengerCount : Number (read-only integer)
The ship’s current number of passengers.
passengers
passengers : Array (read-only NSDictionary)
The ship’s passengers. (For now only available for the player). Each passengers list contains the entries: name: String, start: integer, destination: integer, startName: string, destinationName: string, eta: integer, etaDescription: string, fee: Integer, premium: Integer
For example, the information of the first contract can be obtained by:
player.ship.passengers[0].name player.ship.passengers[0].start player.ship.passengers[0].destination player.ship.passengers[0].startName player.ship.passengers[0].destinationName player.ship.passengers[0].eta player.ship.passengers[0].etaDescription player.ship.passengers[0].fee // The final fee, paid out on successful delivery. player.ship.passengers[0].premium // The advance fee, already paid on acceptance of the contract.
start and destination contain system ID numbers for planets in the current galaxy chart, eta is in clock seconds, fee is the amount that the player will receive when delivering this passenger, and premium shows the amount the player received when the passenger boarded the ship.
pitch
This property was added in Oolite test release 1.77.
pitch : Number (read-only)
The rate of pitch of the ship in radians/second (positive for dive, negative for climb)
portWeapon
portWeapon : EquipmentType (read-only, read/write in 1.77)
The currently equipped port weapon, or null
. This is always null
for non-player ships in 1.76.
See also: aftWeapon
, forwardWeapon
, starboardWeapon
potentialCollider
potentialCollider : Entity (read-only)
The entity the ship is currently trying not to crash into, if any.
primaryRole
primaryRole : String (read/write, read-only for player)
The main role of the ship; the role for which it was created. For instance, if a ship’s shipdata.plist entry specifies the roles “pirate trader(0.5) escort”, and a ship of that type is spawned to be a trader, its primaryRole
is "trader"
, its roles
is ["escort", "pirate", "trader"]
and its roleWeights
is { "escort":1, "pirate":1, "trader":0.5}
.
See also: roles
, roleWeights
reportAIMessages
reportAIMessages : Boolean (read/write)
Debugging facility: set to true
to dump information about AI activity to the log.
roleWeights
roleWeights : Object (read-only)
The probabilities for each role in roles
.
Example:
this.pirateProb = ship.roleWeights["pirate"]
See also: primaryRole
, roles
roles
roles : Array (read-only array of Strings)
The roles of the ship. This consists of the roles specified in the ship’s shipdata.plist entry, as well as the primaryRole
if it is not among those.
See also: primaryRole
, roleWeights
, hasRole()
roll
This property was added in Oolite test release 1.77.
roll : Number (read-only, read/write for stations)
The rate of roll of the ship in radians/second (positive for anti-clockwise, negative for clockwise)
For stations, this can be set to any value between -2 and +2 to adjust their roll rate. The default is 0.4, or the value specified by the station_roll
key in shipdata.plist.
savedCoordinates
savedCoordinates : Vector (read-write)
The savedCoordinates of the ship in system co-ordinates. The savedCoordinates vector is only used by AI scripting to store a coordinate that can be used by other AI commands like setDestinationFromCoordinates
. It are the same coordinates that are set by the AI command: "setCoordinates: X Y Z"
scannerDisplayColor1
scannerDisplayColor1 : Colour specifier (read/write)
The first of two colours used by the ship’s scanner “lollipop”. When read, this will always be an array of four numbers in the range 0..1 (representing red, green, blue and alpha components). Any colour specifier format may be assigned to it. Assigning null
will restore the value from shipdata.plist, or the default value for the ship’s scan class.
See also: scannerDisplayColor2
scannerDisplayColor2
scannerDisplayColor2 : Colour specifier (read/write)
The second scanner colour. If both scannerDisplayColor1
and scannerDisplayColor2
are specified, the scanner lollipop will alternate between the two colours.
See also: scannerDisplayColor1
scannerRange
scannerRange : Number (read-only)
The range of the ship’s scanner.
script
script : Script (read-only)
The ship’s script.
scriptedMisjump
scriptedMisjump : Boolean (read/write)
When true
, the next hyperspace jump will be a misjump. The scriptedMisjump
flag will remain true
during the shipWillExitWitchspace()
event handler, and will be set to false
after the shipExitedWitchspace()
event.
scriptedMisjumpRange
This property was added in Oolite test release 1.77.
scriptedMisjumpRange : Number (read/write)
If this ship misjumps, this number will be consulted to determine the length of the resulting misjump relative to the normal jump range. Setting this does not in itself force a misjump - this must occur through the usual mechanisms. Values must be greater than 0.0 and less than 1.0, and the default is 0.5 for a traditional half-way misjump. This will be reset to 0.5 at the same time as scriptedMisjump
is reset to false
.
scriptInfo
scriptInfo : Object (read-only)
The contents of the script_info
key in the ship’s shipdata.plist entry, if any. This may be any property list object, but the recommended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.
When using numeric values in the scriptInfo, the JS engine is not able to detect the type reliably on all systems, so you always must explicitly convert its content to a number by using parseInt(scriptInfo.myKey) or parseFloat(scriptInfo.myKey).
speed
speed : Number (read-only)
The ship’s current speed.
See also: maxSpeed
starboardWeapon
starboardWeapon : EquipmentType (read-only, read/write in 1.77)
The currently equipped forward weapon, or null
. This is always null
for non-player ships in 1.76.
See also: aftWeapon
, forwardWeapon
, portWeapon
subEntities
subEntities : Array (read-only array of Ships)
The ships subentities, or null
if it has none. Special subentities such as flashers and exhaust plumes are not included.
See also: isFrangible
, restoreSubEntities()
subEntityCapacity
subEntityCapacity : Number (read-only integer)
The original number of subentities on the ship.
See also: subEntities
, restoreSubEntities()
target
target : Ship (read-write)
The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.
temperature
temperature : Number (read/write)
The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.
thrust
thrust : Number (read/write for NPCs, read-only for player)
The ship’s thrust, ranging from 0 to maxThrust
. This value determines how fast the ship accelerates or decelerates, specified in m/s².
See also: thrustVector
thrustVector
thrustVector : Vector3D (read-only)
The inertialess velocity generated by the engines.
trackCloseContacts
trackCloseContacts : Boolean (read/write)
If true, AI events are generated for near collisions.
vectorForward
vectorForward : Vector3D (read-only)
The vector pointing forwards from the ship (in world space for ships, relative to the parent for subentities). Equivalent to ship.orientation.vectorForward
.
vectorRight
vectorRight : Vector3D (read-only)
The vector pointing right from the ship (in world space for ships, relative to the parent for subentities). Equivalent to ship.orientation.vectorRight
.
vectorUp
vectorUp : Vector3D (read-only)
The vector pointing up from the ship (in world space for ships, relative to the parent for subentities). Equivalent to ship.orientation.vectorUp
.
velocity
velocity : Vector3D (read/write)
The ship’s velocity.
Note: A ship’s velocity consists of two components, inertial velocity and inertialess thrust. Generally, inertial velocity is zero (so velocity
is equal to thrustVector
), but inertial impulses may be applied if a ship collides or is caught in an explosion. If inertial velocity is non-zero, the ship’s engines will work to counteract it. Changing the ship’s velocity will always apply inertial velocity, so for ships with non-zero maxThrust
the effect will be temporary.
See also: thrustVector
weaponFacings
This property was added in Oolite test release 1.77.
weaponFacings : Number (read-only, integer in range 0-15)
The weapon facings available for the ship. The format is the same as the equivalent property in shipyard.plist or shipdata.plist - a bitmask with the following bits:
1 - fore
2 - aft
4 - port
8 - starboard
weaponPosition*
This property was added in Oolite test release 1.77.
weaponPositionAft : Vector (read-only) weaponPositionForward : Vector (read-only) weaponPositionPort : Vector (read-only) weaponPositionStarboard : Vector (read-only)
The position relative to the ship at which the appropriate laser beam will start. These properties do not imply that the ship has or can have any such weapon.
weaponRange
weaponRange : Number (read-only)
The maximum range of the ship’s primary weapon. For the player it is the range of the weapon that fired as last, even when the view direction changed.
Range values are: WEAPON_PLASMA_CANNON: 5000, WEAPON_PULSE_LASER: 12500, WEAPON_BEAM_LASER: 15000, WEAPON_MINING_LASER: 12500, WEAPON_THARGOID_LASER: 17500, WEAPON_MILITARY_LASER: 30000, WEAPON_NONE: 32000.
(Turrets are secondary weapons with a maximum range of 6000)
withinStationAegis
withinStationAegis : Boolean (read-only)
true
if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).
yaw
This property was added in Oolite test release 1.77.
yaw : Number (read-only)
The rate of yaw of the ship in radians/second (positive for right, negative for left)
Methods
abandonShip
function abandonShip() : Boolean
Returns true
when the ship has an escapepod. It will launch all escapeposd on board leaving the ship behind as a empty hulk. (scanClass = CLASS_CARGO). This command does nothing when no escape-pod is present.
Pressence of an escapepod can be tested with: equipmentStatus("EQ_ESCAPE_POD") == "EQUIPMENT_OK"
addDefenseTarget
This method was added in Oolite test release 1.77.
function addDefenseTarget(target : Ship)
Adds the target ship to this ship's list of point defense targets, if it isn't already.
awardEquipment
function awardEquipment(equipmentType : equipmentInfoExpression) : Boolean
Adds the given piece of equipment to the ship, if possible, returning true
if successful and false
otherwise.
Example:
ship.awardEquipment("EQ_ECM");
See also: canAwardEquipment()
, removeEquipment()
canAwardEquipment
function canAwardEquipment(equipmentType : equipmentInfoExpression) : Boolean
Tests whether it is possible to add a given equipment type. This command takes the conditions for offering inside equipment.plist into account. Returns true
if awardEquipment()
is expected to succeed, false
otherwise.
See also: awardEquipment()
clearDefenseTargets
This method was added in Oolite test release 1.77.
function clearDefenseTargets()
Clears the ship's list of point defense targets.
commsMessage
function commsMessage(message : String [,target : Ship])
Make the ship broadcast the specified message. Works on buoys and subentities as well as normal ships and stations. Messages are send to a maximum of 16 ships in range and always to the player when in range. When the optional target is used, the message goes only to that ship.
dealEnergyDamage
This method was added in Oolite test release 1.77.
function dealEnergyDamage(damage : Number, idealRange : Number [, velocityBias : Number])
Deals damage to all ships within a sphere centred on this ship. If this ship has an owner (e.g. it is a missile or a subentity) the damage will be credited to its owner. Damage is dealt according to the following formula:
- Further away than MAX_SCANNER_RANGE (25.6km): deal no damage
- At or closer than
idealRange
: dealdamage
plus (or minus, for receding objects)velocityBias
damage for every 0.001LM of relative closing speed, up to a maximum of 1.0LM - Between
idealRange
and a derived maximum range: calculate the damage that would have been done atidealRange
, and then divide it by the square of the ratio ofidealRange
and the real range (i.e inverse-square). The derived maximum range is the distance where a target with no relative closing speed would take 1 point of damage.
As an example, the standard Oolite missile uses dealEnergyDamage(170, 32.5, 0.25)
, has a maximum speed of 0.75LM, and its AI tries to detonate it 25m from its target. Some worked examples (for comparision, one energy bank can absorb 64 points of damage, and a standard shield generator can absorb 128 points of damage):
- The missile is fired at a stationary asteroid. It detonates at 25m, within the ideal range, and the relative closing speed is 0.75LM. The asteroid takes 170 + (0.25 * 750) = 357.5 points of damage
- The missile is fired at a Cobra Mk III, which tries to flee from and evade the missile at its top speed of 0.35LM. The missile detonates at 25m, and the evasive manoeuvres mean that it is not heading directly at the Cobra when it detonates. The relative closing speed is 0.38LM. The Cobra takes 170 + (0.25 * 380) = 265 points of damage.
- An Anaconda freighter travelling at 0.2LM fires a missile at a distant Fer-de-lance. After the missile has travelled 150m away from the Anaconda, it is hit by an ECM pulse from the FDL, and detonates. The relative velocity is -0.55LM (the missile is travelling away from the Anaconda), so the damage at the ideal range would be 170 - (0.25 * 550) = 32.5. The damage is then divided by (150 / 32.5)2, so the Anaconda takes about 1.5 points of damage.
- A missile fired at something else detonates 500m away from a Sidewinder. The inverse-square rule divides the damage by (500 / 32.5)2, so the base damage at this range (ignoring velocityBias) is only 0.7. The Sidewinder is therefore safely outside the blast radius, and is not considered for damage.
deployEscorts
function deployEscorts()
Cause a random number (at least 1 if possible) of the ship's escorts which are not already attacking a target to attack this ship's primary target, unless this function has already been called for the current target without meanwhile being called for a different target.
dockEscorts
function dockEscorts()
Dock the ship’s deployed escorts, if any.
dumpCargo
function dumpCargo() : Ship
Ejects one item of cargo from the ship, and returns the cargo item. Returns null
if the ship has no cargo, anything has been ejected in the last 0.5 seconds, or if sent to the player while docked.
See also: dumpCargo
, ejectSpecificItem
ejectItem
function ejectItem(role : String) : Ship
Spawns a ship of role role
immediately behind the ship, with a slight backwards velocity. (Note: an equal and opposite reaction is applied to the parent ship, so doing this with large ships is rarely useful. player.ejectItem("station")
may seem funny, but don’t come running to me if you have someone’s eye out.) Returns the generated ship, or null
if no ship is generated. The scanClass of the ejected item will always be CLASS_CARGO.
See also: dumpCargo
, ejectSpecificItem
ejectSpecificItem
function ejectSpecificItem(itemKey : String) : Ship
Spawns a ship with the shipdata.plist key itemKey
immediately behind the ship, with a slight backwards velocity. The scanClass of the ejected item will always be CLASS_CARGO.
See also: dumpCargo
, ejectItem
equipmentStatus
function equipmentStatus(equipmentType : equipmentInfoExpression) : String
Tests whether the specified type of equipment is installed, and whether it is functioning. Returns one of the following strings: "EQUIPMENT_OK"
, "EQUIPMENT_DAMAGED"
, "EQUIPMENT_UNAVAILABLE"
or "EQUIPMENT_UNKNOWN"
.
See also: setEquipmentStatus()
exitAI
function exitAI()
Exit the current AI, restoring the previous one. Equivalent to the exitAI:
AI method. May not be used on player. Will generate a warning if there are no suspended AI states.
See also: AI
, setAI()
, hasSuspendedAI
exitSystem
function exitSystem([targetSystem : Number]) : Boolean
Cause the ship to jump out of the system, if possible. If targetSystem
is specified, it will attempt to jump to the specified system, otherwise a random system within range is chosen.
This method can fail for various reasons, in which case it returns false
. It always fails for the player ship.
explode
function explode()
Causes the ship to explode. Works on all ships, including the main station and the player except when docked.
See also: remove()
fireECM
function fireECM()
activates an ecm burst, identical as the AI command.
fireMissile
function fireMissile([missile]) : Ship
fireMissile() will try to fire the first available missile and will return the missile fired, or null
if no missiles can be fired at this time. It can take the optional missile identifier parameter, to allow for a specific missile to be fired. Missiles cannot be fired if the ship hasn’t got a valid target, or if the previous missile was launched less than missile_load_time
seconds before. If a missile type was specified, and not found on the ship, no missile will be fired.
getMaterials
This method was added in Oolite test release 1.77.
function getMaterials() : Object
getMaterials() returns the ship's current materials dictionary, or if none present an empty dictionary.
See also: setMaterials()
, getShaders()
getShaders
This method was added in Oolite test release 1.77.
function getShaders() : Object
getShaders() returns the ship's current shaders dictionary, or if none present an empty dictionary.
See also: setShaders()
, getMaterials()
hasRole
function hasRole(role : String)
Returns true
if the ship has role
among its roles, false
otherwise.
See also: roles
reactToAIMessage
function reactToAIMessage(message : String)
Immediately perform the specified handler in the ship’s current AI state.
See also: sendAIMessage()
remove
function remove([suppressDeathEvent : Boolean])
Immediately removes the ship from the universe. Works on all ships except the player, including the main station.
It generates a this.shipRemoved(suppressDeathEvent) event. By default it will also trigger a this.shipDied() event, unless suppressDeathEvent
is true.
See also: explode()
removeEquipment
function removeEquipment(equipmentType : equipmentInfoExpression)
Removes the given piece of equipment from the ship. This function can also be used to remove missiles (and mines). If more than one missile of the same type is found on board, only one of them will be removed.
Note that in Oolite prior to 1.76.1 there was a bug which could sometimes cause the game to crash if this function was used on pylon-mounted equipment. Therefore, if you do this in your OXP, you should set (at least) 1.76.1 as the version in requires.plist
Example:
ship.removeEquipment("EQ_ECM");
restoreSubEntities
function restoreSubEntities() : Boolean
Recreate all destroyed subentities of the ship. Returns true
if any subentities were added.
See also: subEntities
, isFrangible
selectNewMissile
function selectNewMissile() : equipmentKey
selectNewMissile() will automatically select a missile for a specific ship. It uses the missile_role shipdata.plist key to find out which missiles to select. As with the system populator, there's a small chance that missiles other than the missile_role specified in shipdata will be selected. e.g.
this.ship.awardEquipment(this.ship.selectNewMissile())
will automatically add the 'right type' of missile to a ship, i.e. one that its captain would normally choose.
sendAIMessage
function sendAIMessage(message : String)
Add a message to the ship’s AI deferred message queue. Messages in the queue are handled immediately after the next periodic UPDATE
message. Identical messages are coalesced.
See also: reactToAIMessage()
setAI
function setAI(AIName : String)
Set the current AI, leaving the old one suspended. Equivalent to the setAITo:
AI method. May not be used on player.
See also: AI
, switchAI()
, exitAI()
setBounty
This method was added in Oolite test release 1.77.
function setBounty(bounty : Number, reason : String)
Sets the ship's bounty to the new value. reason
will be sent to shipBountyChanged().
See also: bounty
setCargo
function setCargo(commodity : String [, count : Number]) : Boolean
Attempts to create count
weight units of the commodity commodity
for a cargo barrel. (Can not be used to set cargo for ships) When more units are defined than 1 ton, the count is reduced to one ton. It returns false when the selected commodity is unknown. If count
is not specified, one will be assumed.
setEquipmentStatus
function setEquipmentStatus(equipmentType : equipmentInfoExpression, statusKey : String)
Changes the status of the given piece of equipment from the ship. The two only valid status keys are "EQUIPMENT_OK"
, "EQUIPMENT_DAMAGED"
.
Note: by design, this method will throw an exception if called with an equipment type that does not exist. To test whether an equipment type exists, use EquipmentInfo.infoForKey()
, which will return null
for undefined equipment.
See also: equipmentStatus()
setMaterials
function setMaterials(materialDictionary : Object [, shaderDictionary : Object]) : Boolean
Set the materials of the ship’s model. This works exactly like the materials
dictionary in shipdata.plist. The optional shaderDictionary
argument overrides materialDictionary
if shaders are active.
Example:
this.ship.setMaterials({"my_ship_diffuse.png": { diffuse_map: "my_ship_damaged_diffuse.png" }});
See also: setShaders()
, getMaterials()
setScript
function setScript(scriptName : String)
Set, or completely replace, the javascript code associated to a ship entity.
setShaders
function setShaders(shaderDictionary : Object) : Boolean
Set the shader materials of the ship’s model. Equivalent to setMaterials()
with the materialDictionary
value set to the ship’s current material dictionary.
See also: setMaterials()
, getShaders()
spawn
function spawn(role : String [, count : Number]) : Array
Attempts to create count
(maximum: 64) ships of role role
close to the ship – specifically, inside the ship’s collision radius. (Since creating ships may fail, the number created may be less than count
). The created ships are returned in an array. If count
is not specified, one will be assumed.
spawn()
is intended for cases when a ship splits into multiple parts or drops parts. In particular, it has the following special behaviour:
- The spawned ships inherit most of the temperature of the parent.
- If the parent is a missile and a child has the
is_submunition
property, the child will be considered a missile, its target will be set to that of the parent and the child’s owner will be set to the parent. spawn()
does not set up escorts for the new ships, or generate witchspace effects, or do any special AI handling.
spawnOne
function spawnOne(role : String) : Ship
Convenience method which calls spawn(role)
and returns the first element of the resulting array, or null
if spawn()
fails.
switchAI
function switchAI(AIName : String)
Set the current AI, exiting the old one. Equivalent to the switchAITo:
AI method. May not be used on player.
See also: AI
, setAI()
, exitAI()
updateEscortFormation
function updateEscortFormation()
Request that the game updates the target positions for the ship’s escorts by calling the ship’s script’s coordinatesForEscortPosition()
method.
Static Methods
keys
This property was added in Oolite test release 1.79.
function keys() : Array
Returns all dataKeys of ships defined in all shipdata.plist including installed OXPs.
var dataKeysArray = Ship.keys();
keysForRole
This property was added in Oolite test release 1.79.
function keysForRole(role : String) : Array
Returns all dataKeys of ships defined in all shipdata.plist which contains the given role.
var role = "trader"; var roleKeys = Ship.keysForRole( role ); log("keysForRole", role + ": " + roleKeys );
roles
This property was added in Oolite test release 1.79.
function roles() : Array
Returns all roles of ships defined in all shipdata.plist including installed OXPs.
var roles = Ship.roles(); for( i = 0; i < roles.length; i++ ) { var roleKeys = Ship.keysForRole( roles[i] ); log("roles", i + ". "+roles[i] + ": " + roleKeys ); }