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.

Stations and the PlayerShip are types of ship. Note that these more specific types have additional properties and methods.

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.

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.

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

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

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

roles : 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 reccomended 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

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.

See also: thrust, velocity

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: deal damage 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 at idealRange, and then divide it by the square of the ratio of idealRange 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)², 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)², 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()

Launch the ship’s escorts, if any.

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.

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.