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 plist-based state machine AI. If the ship is using Javascript-based AI, this will always be "nullAI.plist"

See also: AIState, setAI(), switchAI(), exitAI(), AIScript

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.

AIScript

This property was added in Oolite test release 1.79.

AIScript : String (read-only)

The name of the ship’s current Javascript-based AI. If the ship is using plist-based AI, this will always be "oolite-nullAI.js"

See also: AIScriptWakeTime, setAI(), switchAI(), exitAI(), AI

AIScriptWakeTime

This property was added in Oolite test release 1.79.

AIScriptWaketime : Number (read-write)

The next game time at which the ship's Javascript-based AI script will receive an aiAwoken event.

AIState

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

The ship’s plist AI’s current state.

See also: AI, reactToAIMessage(), hasSuspendedAI

alertCondition

alertCondition : Number (read-only integer)

The ship's current alert condition (Docked = 0, Green = 1, Yellow = 2, Red = 3). Non-Station non-Player ships are generally only found at condition Yellow or Red.

See also: station.alertCondition

autoWeapons

This property was added in Oolite test release 1.79.

autoWeapons : Boolean (read-only)

The value of the "auto_weapons" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the properties of this ship to better fit into scenarios or roles. If this is false, the ship's provider would prefer you not to alter the properties of this ship but to use it as-is.

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

beaconLabel

This property was added in Oolite test release 1.79.

beaconLabel : String (read/write)

A full label for the beacon. This is useful where the beacon code and the full beacon label do not begin with the same letter.

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.

cargoList

This property was added in Oolite test release 1.79.

cargoList : Array (read-only)

A list of the ship's current cargo, grouped by cargo type. For the player ship, this is equivalent to player.ship.manifest.list

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.

destinationSystem

This property was added in Oolite test release 1.79.

destinationSystem : Number (read/write)

The destination system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.

displayName

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

The name of the ship as seen by the player. By default in 1.78 or earlier it is the same as name. In 1.79 or earlier it is a combination of shipClassName and shipUniqueName

dockingInstructions

This property was added in Oolite test release 1.79.

dockingInstructions : Object (read-only)

If the ship is currently attempting to dock with a station, this describes the next step on its docking procedure

{
   station: [Station "Coriolis Station" "Coriolis Station" position: (-31043.6, -94232.3, 619036) scanClass: CLASS_STATION status: STATUS_ACTIVE],
   match_rotation: 0,
   ai_message: "APPROACH_COORDINATES",
   speed: 512,
   destination: {
       x: -28033.37401563089,
       y: -92813.76688970842,
       z: 622226.0625336492
   },
   range: 96
}

See also: requestDockingInstructions, recallDockingInstructions

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.

exhaustEmissiveColor

This property was added in Oolite test release 1.79.

exhaustEmissiveColor : Color (read/write)

The baseline colour of the ship's exhaust. Damage to the ship, and use of injectors and torus drive, apply a fixed transformation to this colour, so not all colours are effective as exhaust colours.

exhausts

This property was added in Oolite test release 1.79.

exhausts : Array (read-only)

An array of the ship's ExhaustPlume subentities.

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.

flashers

This property was added in Oolite test release 1.79.

flashers : Array (read-only)

An array of the ship's Flasher subentities.

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

fuelChargeRate

fuelChargeRate : Number (read-only)

The cost, relative to the cost for a new Cobra III, of a unit of fuel. When buying fuel for a ship, the price in equipment.plist will be multiplied by this number.

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.

homeSystem

This property was added in Oolite test release 1.79.

homeSystem : Number (read/write)

The home system ID of the ship, used by the AI for certain decisions. This defaults to the current system when a ship is spawned.

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

isFleeing

This property was added in Oolite test release 1.79.

isFleeing : Boolean (read-only)

true if the ship is currently fleeing combat. This may be queried for the player ship too, though the value is somewhat of a guess in that case as it's impossible to say for certain what the player is intending by their actions.

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.

isTurret

This property was added in Oolite test release 1.79.

isTurret : Boolean (read-only)

true if the ship is a plasma turret sub-entity, false otherwise.

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.

markedForFines

This property was added in Oolite test release 1.79.

markedForFines : Boolean (read-only)

True if the ship has been marked for fines the next time it docks at this system's main station.

See also : markTargetForFines()

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

shipClassName

This property was added in Oolite test release 1.79.

shipClassName : String (read/write)

The name of the ship class (e.g. "Python")

shipUniqueName

This property was added in Oolite test release 1.79.

shipUniqueName : String (read/write)

The name of this specific ship (e.g. "Sunrise of Lave")

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.

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

becomeCascadeExplosion

This method was added in Oolite test release 1.79.

function becomeCascadeExplosion()

This method causes the ship to explode as if it were hit by a quirium cascade.

broadcastCascadeImminent

This method was added in Oolite test release 1.79.

function broadcastCascadeImminent()

This method causes the ship to broadcast a message to the AIs of all nearby ships warning them of an imminent cascade explosion. It is polite to call this a few seconds before calling becomeCascadeExplosion

broadcastDistressMessage

This method was added in Oolite test release 1.79.

function broadcastDistressMessage()

This method causes the ship to broadcast a distress message to the AIs of all nearby ships (received also by the player as a comms message). Ships receiving a distress message will often intervene in the fight, depending on their own AI and the roles of the ships already involved.

checkCourseToDestination

This method was added in Oolite test release 1.79.

function checkCourseToDestination()

Checks the line between the ship's current position and its destination, and returns either null or an Entity (usually a planet, sun or other ship) that this ship would risk collision with if it travelled along that course.

See also: getSafeCourseToDestination()

checkScanner

This method was added in Oolite test release 1.79.

function checkScanner([poweredOnly : Boolean]) : Array

Runs a fast scanner check and returns the results. At most 32 objects within scanner range will be returned. If the poweredOnly parameter is present and set to true, then only powered objects will be returned (i.e. ships with a scan class other than CLASS_CARGO or CLASS_ROCK).

This method is usually considerably quicker than system.filteredEntities() and similar methods, with little loss of accuracy, though it is still advisable to cache the result for a while before re-scanning.

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.

damageAssessment

This method was added in Oolite test release 1.79.

function damageAssessment() : Number

Returns a number indicating the amount of damage or supply usage by this ship. Zero means that the ship is in excellent fighting condition, while higher numbers indicate increasing amounts of damage or supply shortages.

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

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([amount : Number]) : 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.

In 1.79 or later, multiple items may be scheduled for dumping by passing the number as a parameter.

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

enterWormhole

This method was added in Oolite test release 1.79.

function enterWormhole([wormhole : Wormhole])

If the player has entered witchspace, but before the old system is removed from memory, this method may be used to add this ship to the contents of the specified outbound wormhole. If no parameter is given, add them to the player's wormhole.

If the player is not entering witchspace, this method does nothing: the ship must fly to the wormhole in the normal way to enter it.

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.

findNearestStation

function findNearestStation()

Returns the nearest Station entity to this ship. This is quicker than manually searching system.stations and much quicker than using system.filteredEntities().

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.

getSafeCourseToDestination

This method was added in Oolite test release 1.79.

function getSafeCourseToDestination()

Returns some coordinates which can be flown to as an intermediate destination to allow travel between the ship's current position and its destination without colliding with any objects on the way. Use this if checkCourseToDestination returns an object you are unable or unwilling to destroy to calculate a new route.

See also: checkCourseToDestination()

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

markTargetForFines

This method was added in Oolite test release 1.79.

function markTargetForFines()

If this ship is eligible to give out fines and the primary target has a bounty, mark the current primary target for fines, which will need to be paid when the ship docks. If used on a ship other than the player, of course, the fines are not particularly meaningful.

offerToEscort

This method was added in Oolite test release 1.79.

function offerToEscort(mother : Ship)

Offer to escort the specified ship. The ship making the offer must have the same scan class as the mothership and must have one of the designated escort roles. After the mothership has made a decision this ship will receive either an escortAccepted or escortRejected ship script event.

perform*

Each of these functions switches the frame-by-frame behaviour of the ship to a different mode. It may not necessarily remain in that mode, however - for example, those modes which require a target will usually fall back to idle mode if the target is lost.

performAttack

This method was added in Oolite test release 1.79.

function performAttack()

Attack the current target with available weapons.

performCollect

This method was added in Oolite test release 1.79.

function performCollect()

Attempt to scoop up the current target. If the current target is not scoopable, it will be lost.

performEscort

This method was added in Oolite test release 1.79.

function performEscort()

Escort the group leader. If this ship is not an escort of the group leader, it will not receive escort position updates from that ship.

performFaceDestination

This method was added in Oolite test release 1.79.

function performFaceDestination()

Come to a stop, and turn to face the current destination coordinates.

performFlee

This method was added in Oolite test release 1.79.

function performFlee()

Flee from the current target, using injectors if possible, until it is out of scanner range.

performFlyToRangeFromDestination

This method was added in Oolite test release 1.79.

function performFlyToRangeFromDestination()

Fly to the current destination coordinates, stopping when the distance between the ship and those coordinates is the desiredRange. If the ship is already closer to the destination coordinates than the desired range, it will move away from the coordinates.

performHold

This method was added in Oolite test release 1.79.

function performHold()

Come to a stop, and continually turn to face the current target

performIdle

This method was added in Oolite test release 1.79.

function performIdle()

Cancel any current turns to return to level flight, then move forward at current speed.

performIntercept

This method was added in Oolite test release 1.79.

function performIntercept()

Fly to intercept (i.e. ram) the current target.

performLandOnPlanet

This method was added in Oolite test release 1.79.

function performLandOnPlanet()

Land on rather than crash into the planet. This is a slow flight, so it is recommended to get close to the planet surface before activating this behaviour.

performMining

This method was added in Oolite test release 1.79.

function performMining()

Attack the current target with a mining laser. This does not count as hostile behaviour, so cannot be used except on rocks.

performScriptedAI

This method was added in Oolite test release 1.79.

function performScriptedAI()

Request flight instructions from a scripted AI callback each frame.

performScriptedAttackAI

This method was added in Oolite test release 1.79.

function performScriptedAttackAI()

Request flight instructions, including weapons fire, from a scripted AI callback each frame.

performStop

This method was added in Oolite test release 1.79.

function performStop()

Come to a complete halt

performTumble

This method was added in Oolite test release 1.79.

function performTumble()

Come to a complete halt and rotate randomly.

reactToAIMessage

function reactToAIMessage(message : String)

Immediately perform the specified handler in the ship’s current AI state.

See also: sendAIMessage()

recallDockingInstructions

This method was added in Oolite test release 1.79.

function recallDockingInstructions() : Object

Returns the current docking instructions as an object, and sets the destination, desired range and desired speed to match the instructions. Use this if the ship may have been interrupted while docking to ensure its flight parameters are set correctly.

See also: dockingInstructions, requestDockingInstructions

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

removeDefenseTarget

This method was added in Oolite test release 1.79.

function removeDefenseTarget(target : Ship)

Ensures that the target ship is not on this ship's list of point defense targets.

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");

requestDockingInstructions

This method was added in Oolite test release 1.79.

function requestDockingInstructions() : Object

Requests the next docking instructions from the station, and returns them as an object, setting the destination, desired range and desired speed to match the instructions. Use this to get the next step in the docking sequence after completing the previous one.

See also: dockingInstructions, recallDockingInstructions

requestHelpFromGroup

This method was added in Oolite test release 1.79.

function requestHelpFromGroup()

This function sends the helpRequestReceived event to the other ships in this ship's group and escort group, sending the name of this ship's current target as the aggressor.

restoreSubEntities

function restoreSubEntities() : Boolean

Recreate all destroyed or removed subentities of the ship. Returns true if any subentities were added. Whether or not any subentities were added, this will also reset all subentities to their original configuration of position, orientation and other properties.

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. From 1.79 onwards AI files may either be plist-based (with a .plist extension) or Javascript-based (with a .js extension).

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.

setCargoType

This method was added in Oolite test release 1.79.

function setCargoType(commodityType : String) : Boolean

Attempts to set the ship's cargo hold to contain cargo of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid cargo types are:

• SCARCE_GOODS: goods which are likely to be rare in the current system, usually legal.
• PLENTIFUL_GOODS: goods which are likely to be plentiful in the current system, usually legal.
• MEDICAL_GOODS: narcotics (used for the Moray Medical Boat)
• ILLEGAL_GOODS: various goods likely to be rare in the current system, with a strong bias towards contraband
• PIRATE_GOODS: as ILLEGAL_GOODS, but the total amount carried will be lower

This will return false if an unrecognised commodity type is used, and will throw an exception if used on a cargo pod rather than a cargo carrier. Using it on a ship like an Asp without a cargo hold is valid but pointless.

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

threatAssessment

This method was added in Oolite test release 1.79.

function threatAssessment(full : Boolean) : Number

Returns a number indicating the relative strength of the ship. If the 'full' parameter is true, additional information will be considered as part of the assessment which would generally only be known by ships which know this ship or have seen it in combat. Otherwise, only data which could reasonably be expected to be common knowledge based on the class of the ship will be included.

For example, which weapon facings are available is part of the basic assessment, but what forward laser the ship has is part of the full assessment.

throwSpark

This method was added in Oolite test release 1.79.

function throwSpark()

Sets the ship to throw a spark as if it was seriously damaged. If this ship is already scheduled to throw a spark, this does nothing.

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 method 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 method 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 );

roleIsInCategory

This method was added in Oolite test release 1.79.

function roles(role : String, category : String) : Boolean

Returns whether the role given is in a particular category as defined in role-categories.plist

Ship.roleIsInCategory("trader","oolite-pirate-victims"); // true

roles

This method 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( var i = 0; i < roles.length; i++ ) {
 var roleKeys = Ship.keysForRole( roles[i] );
 log("roles", i + ". "+roles[i] + ": " + roleKeys );
}

See also

• Shipdata.plist