Oolite JavaScript Reference: Ship

Prototype: Entity
Subtypes: Station, PlayerShip

This class was added in Oolite test release 1.70.

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 Player are types of ship. Note that these more specific types have additional properties and methods.

Properties

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)

availableCargoSpace

This property was added in Oolite test release 1.72.

availableCargoSpace : Number (read-only integer)

The ship’s free cargo space.

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.

cargoCapacity

cargoCapacity : Number (read-only integer)

The ship’s cargo capacity. Name introduced with version 1.72. Old name was maxCargo.

cargoSpaceUsed

This property was added in Oolite test release 1.72.

cargoSpaceUsed : Number (read-only integer)

The ship’s current cargo weight.

desiredSpeed

This property was added in Oolite test release 1.72.

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.

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(name key in shipdata.plist). This property is changed from shipDisplayName in 1.72

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.

escorts

escorts : Array (read-only array of Entitys)

The ship’s deployed escorts.

escortGroup

This property was added in Oolite test release 1.73.

escortGroup : ShipGroup (Class added with Oolite 1.73)

The ship’s deployed escorts.

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: Player.fuelLeakRate)

group

This property was added in Oolite test release 1.73.

group : ShipGroup  (Class added with Oolite 1.73)

Contains ship’s belonging to each other. Added pirate groups are an example or a station with its launched defenders.

groupID This property is removed with Oolite 1.73 in favour of the new shipGroup

groupID : Number (read-only) 

The ID of the group to which this ship belongs. 0 for no group. An example of a group is a ship with escorts and the escorts.

hasHostileTarget

hasHostileTarget : Boolean (read-only)

true if the ship’s AI is trying to kill something, false otherwise. Always false for the player.

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)

isCloaked

isCloaked : Boolean (read-only)

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, you can activate it by setting isCloaked to true.

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.

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

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 missile or mine, false otherwise.

maxCargo

maxCargo : Number (read-only integer)

The ship’s cargo capacity. This property is renamed to cargoCapacity in 1.72.

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)

name

name : String (read/write, read-only for player)

The name of the ship type (name key in shipdata.plist). This property was changed from shipDescription in 1.72

passengerCapacity

This property was added in Oolite test release 1.72.

passengerCapacity : Number (read-only integer)

The ship’s maximum passenger capacity.

passengerCount

This property was added in Oolite test release 1.72.

passengerCount : Number (read-only integer)

The ship’s current number of passengers.

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 roleProbabilities is { "escort":1, "pirate":1, "trader":0.5}.

See also: roles, roleProbabilities.

reportAIMessages

reportAIMessages : Boolean (read/write)

Debugging facility: set to true to dump information about AI activity to the log.

roleProbabilities

roles : Object (read-only)

The probabilities for each role in roles. Example:

this.pirateProb = ship.roleProbabilities["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, roleProbabilities, hasRole().

scannerRange

scannerRange : Number (read-only)

The range of the ship’s scanner.

script

script : Script (read-only)

The ship’s script.

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.

shipDescription

shipDescription : String (read/write, read-only for player)

The name of the ship type (name key in shipdata.plist). This property is changed into name in 1.72

shipDisplayName

shipDisplayName : String (read/write, read-only for player)

The name of the ship as seen by the player. By default it is the same as shipDescription(name key in shipdata.plist). This property is changed into displayName in 1.72

speed

speed : Number (read-only)

The ship’s current speed. (See also: maxSpeed)

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)

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.

weaponRange

weaponRange : Number (read/write)

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.

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

commsMessage

This method was added in Oolite test release 1.72.

function commsMessage(message : String) : Ship

Make the ship type entity broadcast the specified message. Works on buoys and subentities as well as normal ships and stations.

deployEscorts

function deployEscorts()

Launch the ship’s escorts, if any.

dockEscorts

function dockEscorts()

Dock the ship’s deployed escorts, if any.

dumpCargo

This method was added in Oolite test release 1.71.

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

This method was added in Oolite test release 1.71.

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

This method was added in Oolite test release 1.71.

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

explode

function explode()

Like it says. Works on otherwise-indestructible main station, and everything else too.

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

hasEquipment

function hasEquipment(equipmentKey : String [, includeWeapons : Boolean]) : Boolean

Returns true if the given piece of equipment is present on/in the ship, false if it is not. If includeWeapons is false, primary weapons (lasers) and secondary weapons (missiles and mines) are excluded. If includeWeapons is not specified, true is assumed.

Prior to Oolite 1.73, hasEquipment() is only available for the player’s ship and includeWeapons is ignored (treated as always false).

Example: if (player.hasEquipment("EQ_TRUMBLE")) log("Oh noes, I has a trumble!")

hasRole

function hasRole(role : String)

Returns true if the ship has role among its roles, false otherwise.

See Also: roles

reactToAIMessage

function reactToAIMessage(AIState : String)

Immediately execute the ship’s AI in the specified state.

remove

This method was added in Oolite test release 1.72.

function remove()

Like it says. Works on otherwise-indestructible main station, and everything else too. Same as explode except for the explosion itself

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

setScript

This method was added in Oolite test release 1.71.

function setScript(scriptName : String)

Set, or completely replace, the javascript code associated to a ship entity.

spawn

This method was added in Oolite test release 1.71.

function spawn(role : String [, count : Number]) : Array

Attempts to create count 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.

spawnOne

This method was added in Oolite test release 1.71.

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