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

aftWeapon

aftWeapon : EquipmentType (read-only)

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()

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)

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.

See also: isBeacon

bounty

bounty : Number (read/write integer)

The bounty on the ship. In the case of the player, it is halved at each witchspace jump.
It is actually the legal status of the ship that is shown here and not the bounty. For all ships both are the same but for anything with scan class Thargoid the legal status is only based on the ships mass and has no relation to its defined bounty.

cargoSpaceCapacity

cargoSpaceCapacity : Number (read-only integer)

The ship’s cargo capacity, in tons.

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.

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

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.

escorts

escorts : Array (read-only array of Entitys)

The ship’s deployed escorts.

forwardWeapon

forwardWeapon : EquipmentType (read-only)

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.

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.

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.

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.

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.

portWeapon

portWeapon : EquipmentType (read-only)

The currently equipped forward weapon, or null. Currently, this is always null for non-player ships.

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()

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.

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 expclicit 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)

The currently equipped forward weapon, or null. Currently, this is always null for non-player ships.

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

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

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"

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()

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.

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.

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.

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()

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()

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()

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.