Difference between revisions of "Oolite JavaScript Reference: Ship"

Revision as of 08:45, 19 September 2023

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

`autoAI`

This property was added in Oolite test release 1.79.

autoAI : Boolean (read-only)

The value of the "auto_ai" shipdata key. If this is true, the ship's provider has given permission for scripts (such as the system populator) to alter the AI 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 AI of this ship but to use it as-is.

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

See here for more detail

`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 cannot 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, read-only for player)

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.

An item looks like this:

{
   unit: "t",
   displayName: "Liquor/Wines",
   commodity: "liquor_wines",
   quantity: 3
}

This property is for non-player ships. For the player ship, use manifest.list.

`cargoSpaceAvailable`

cargoSpaceAvailable : Number (read-only integer)

The ship’s available cargo space, in tons.

See also: cargoSpaceCapacity, cargoSpaceUsed, manifest (for the player ship), cargoList (for non-player ships), adjustCargo(), dumpCargo()

`cargoSpaceCapacity`

cargoSpaceCapacity : Number (read-only in 1.80, read/write in 1.81, integer)

The ship’s cargo capacity, in tons.

See also: cargoSpaceUsed, cargoSpaceAvailable, manifest (for the player ship), cargoList (for non-player ships), adjustCargo(), dumpCargo()

`cargoSpaceUsed`

cargoSpaceUsed : Number (read-only integer)

The ship’s current cargo, in tons.

See also: cargoSpaceCapacity, cargoSpaceAvailable, manifest (for the player ship), cargoList (for non-player ships), adjustCargo(), dumpCargo()

`collisionExceptions`

This property was added in Oolite test release 1.81.

collisionExceptions : Array (read-only)

A list of ships this ship is currently prevented from colliding with. See addCollisionException and removeCollisionException.

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

See also: awardContract(), removeContract(), contractReputation

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

`crew`

This property was added in Oolite test release 1.79.

crew : Array (read-only)

An array containing the ship's crew. Each crew member is represented as a dictionary:

 {
  "description":"a small yellow horned humanoid from Malama",
  "name":"Masten Onlo",
  "homeSystem":49,
  "insuranceCredits":500,
  "species":"small yellow horned humanoid",
  "legalStatus":0
 }

Note that in current Oolite versions ships only have a single crew member defined.

See also: setCrew()

`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 later, it is a combination of shipClassName and shipUniqueName.

`dockedStation`

dockedStation :  Station

The Station the ship is currently docked to.

`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
}

`energyRechargeRate`

This property was added in Oolite test release 1.79.

energyRechargeRate : Number (read-only, read/write from 1.81)

The rate at which energy is replenished in every second. The corresponding shipdata.plist key is energy_recharge_rate.

Note for the player ship that this includes the boost from an extra or naval energy unit, and NPC (but not player) ships with military shield boosters also have an increase to this in lieu of actual shields.

`entityPersonality`

entityPersonality : Number (read-only integer, read/write in 1.81 onwards)

A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the entityPersonalityInt uniform binding.

Altering this value is possible in 1.81 onwards, but requires a re-bind of the materials and shaders, and so is a relatively slow process.

`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 : Colour specifier (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.

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

Note that in 1.80 and earlier writes to this property had no effect on the player ship.

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

`hyperspaceSpinTime`

This property was added in Oolite test release 1.81.

hyperspaceSpinTime : Number (read/write)

The length of the ship's hyperspace countdown.

Setting this to a negative value disables the drive entirely.

Note that most NPC ship jumps use ship.exitSystem() to make the jump, which does not have a delay. Provided this value is zero or positive, the ship will jump instantly if ship.exitSystem() is called. The AI must use this property elsewhere if a delay before jumping is required.

`injectorBurnRate`

This property was added in Oolite test release 1.81.

injectorBurnRate : Number (read/write)

The rate at which the ship's injectors burn fuel in deci-LY per second. The default is 0.25.

`injectorSpeedFactor`

This property was added in Oolite test release 1.81.

injectorSpeedFactor : Number (read/write)

The multiplier to maximum speed granted to this ship when it is using injectors. The default is 7, and values must be between 1.0 and 32.0 (the torus drive's speed)

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

`isMinable`

This property was added in Oolite test release 1.79.

isMinable : Boolean (read-only)

true if the ship will break up usefully when hit by a mining laser, false otherwise. By default this is true for anything with "asteroid" or "boulder" in its role list - if you need to add anything which miners shouldn't be shooting at to those roles, give it "no_boulders" = yes; in its shipdata.plist.

`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- ships, stations and escape pods have pilots whereas cargo, rocks, missiles and buoys do not.

`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, read/write from 1.81)

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, read/write from 1.81)

The maximum roll rate of the ship, in radians per second.

See also: roll

`maxSpeed`

maxSpeed : Number (read-only, read/write from 1.81)

The ship’s maximum speed under normal power. Note that speed may exceed this when the Witch Fuel Injectors or Torus Drive are in use.

`maxThrust`

maxThrust : Number (read-only, read/write from 1.81)

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, read/write from 1.81)

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.

See also: addParcel(), removeParcel()

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

See also: addParcel(), removeParcel(), parcelReputation

`passengerCapacity`

passengerCapacity : Number (read-only integer)

The ship’s maximum passenger capacity.

See also: Passenger Berth, addPassenger(), removePassenger()

`passengerCount`

passengerCount : Number (read-only integer)

The ship’s current number of passengers.

See also: Passenger Berth, addPassenger(), removePassenger()

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

See also: Passenger Berth, addPassenger(), removePassenger(), passengerReputation

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

See also: maxPitch

`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 are ["escort", "pirate", "trader"] and its roleWeights are {"escort":1, "pirate":1, "trader":0.5}.

See also: roles, roleWeights

`reactionTime`

reactionTime : Number (read/write)

Gets or sets the reaction time of the pilot of the ship. The default value is 1.5 seconds.

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

See also: maxRoll, station.roll

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

`scanDescription`

This property was added in Oolite test release 1.81.

scanDescription : String (read/write)

The description of the ship in the "legal status" text shown by the Scanner Targeting Enhancement. If this is null then the default text for the ship's scan class and bounty level will be shown.

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

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

`scannerHostileDisplayColor1`

This property was added in Oolite test release 1.81.

scannerHostileDisplayColor1 : Colour specifier (read/write)

The first of two colours used by the ship’s scanner “lollipop” when the ship is specifically targeting the player with hostile intent. 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.

If hostile colours are set but normal colours aren't, then the normal colours will default to those for the ship's scan class. If normal colours are set but hostile colours aren't, the scanner blip will not change colour when the ship is hostile.

`scannerHostileDisplayColor2`

This property was added in Oolite test release 1.81.

scannerHostileDisplayColor2 : Colour specifier (read/write)

The second scanner colour when the ship is specifically targeting the player with hostile intent.. If both scannerHostileDisplayColor1 and scannerHostileDisplayColor2 are specified, the scanner lollipop will alternate between the two colours.

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

`subEntityRotation`

This property was added in Oolite test release 1.81.

subEntityRotation : Quaternion (read/write)

The subentity rotational velocity, expressed as a quaternion. This much rotation will be applied per second. Exact 180 degree rotations should not be specified, as it is not possible to determine what route to use to make that rotation. This property is ignored when set on non-subentities.

`sunGlareFilter`

This property was added in Oolite test release 1.79.

sunGlareFilter : Number (read/write)

The strength of the sun glare filter on this ship. It must be in the range 0 to 1 (0 is no filter).

`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 before 1.81)

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)

This property was added in Oolite test release 1.83.

weaponPositionAft : Array of Vectors (read-only)
weaponPositionForward : Array of Vectors (read-only)
weaponPositionPort : Array of Vectors (read-only)
weaponPositionStarboard : Array of Vectors (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.

In 1.83 this property changed syntax to become an array of vectors, as ships can now have multiple mounts per facing.

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

See also: maxYaw

Methods

`abandonShip`

function abandonShip() : Boolean

Returns true when the ship has an escape pod. It will launch all escape pods on board leaving the ship behind as a empty hulk (scanClass === "CLASS_CARGO"). This command does nothing when no escape pod is present.
Presence of an escape pod can be tested with: equipmentStatus("EQ_ESCAPE_POD") === "EQUIPMENT_OK"

`addCollisionException`

This method was added in Oolite test release 1.81.

function addCollisionException(exception : Ship)

Prevented this ship and the selected ship from colliding. See collisionExceptions and removeCollisionException.

Prevention from collision will specifically prevent the following:

the ships colliding with each other and suffering collision damage and/or momentum change
the ships receiving collision warning events if they come close to each other
if one of the ships is a station, the other ship will not be able to dock with it even if it enters a dock

This has no useful effect when applied to a subentity.

Adding a collision exception which already exists has no effect but will not cause an error.

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

`adjustCargo`

This method was added in Oolite test release 1.81.

function adjustCargo(commodity : String, amount : Number) : Boolean

Adjust the quantity of the specified commodity carried by the ship. Amount may be negative to remove cargo. The method will return false if the operation would fail due to insufficient free space or carried cargo and will not make a partial adjustment in this case.

This method is for non-player ships. For the player ship, use manifest.

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

See also: player.commsMessage()

`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 method 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, commodity: String]) : 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.

In 1.81 or later, a preferred commodity may be specified (if this is not present, a random item will be dumped as usual). This preference only applies to the first item dropped, not subsequent ones.

See also: ejectItem, 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 [, multiple : Boolean]) : String or Object

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

In 1.81 and later, if the optional multiple parameter is set to true, it will instead return an object in this format:

{
   "EQUIPMENT_OK": 3.
   "EQUIPMENT_DAMAGED": 2
}

to allow equipments which allow fitting multiple to be queried. If multiple equipments can be fitted, not setting the 'multiple' parameter will return the 'best' state of all items of that type.

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

`hasEquipmentProviding`

This method was added in Oolite test release 1.81.

function hasEquipmentProviding(key : String) : Boolean

This method returns true if the ship has any equipment providing the key equipment type, and false otherwise.

`hasRole`

function hasRole(role : String) : Boolean

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.

`notifyGroupOfWormhole`

This method was added in Oolite test release 1.79.

function notifyGroupOfWormhole()

Tells the ship's group about a wormhole (usually the one this ship has just entered). Causes a wormholeSuggested event to occur in the scripts of other group members.

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

`removeCollisionException`

This method was added in Oolite test release 1.81.

function removeCollisionException(exception : Ship)

Allow this ship and the selected ship to collide again. See collisionExceptions and addCollisionException.

Removing a collision exception which does not exist has no effect but will not cause an error.

`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 method 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 method 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 method 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 specified for a cargo barrel. This cannot be used to set cargo for ships. When more units are defined than 1 ton, the count is reduced to 1 ton. It returns false when the selected commodity is unknown. If count is not specified, 1 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 commodities of the specified type, discarding any cargo already present. This should generally only be used immediately after a ship is spawned. Valid commodity 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": similar to "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.

`setCrew`

This method was added in Oolite test release 1.79.

function setCrew(Object) : Boolean

Sets the ship's crew to one represented by the given object (or sets the ship to uncrewed if null is given as a parameter). Returns true if this succeeds, false otherwise (if the ship is always unpiloted). The object has the same keys as characters.plist, all of which are optional and will be replaced with default values if unset. They are applied in the following order:

origin system
random seed
role
the rest

You can therefore set a random seed or role to get particular behaviour, and use the other keys to override it.

At the moment this method only sets the first crew member (the pilot of the ship) in crew[0] .

`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(), EquipmentInfo.canBeDamagedfor equipment that cannot be damaged

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

Example:

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.

Example:

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

Example:

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.

Example:

var roles = Ship.roles();
for( var i = 0; i < roles.length; i++ ) {
 var roleKeys = Ship.keysForRole( roles[i] );
 log("roles", i + ". "+roles[i] + ": " + roleKeys );
}

`shipDataForKey`

This method was added in Oolite test release 1.79.

function shipDataForKey(datakey : String) : Object

Returns an object containing a representation of the raw shipdata.plist entry for a given data key, or null if the data key does not exist. Keys not defined in the shipdata.plist entry will not be defined in the object - they won't get their default values.

Using the ship object properties is generally a better way to get this information, but this is useful if you want to find out what a ship might be like if you did add it.

Example:

var shipdata = Ship.shipDataForKey("cobra3-trader");
log("test",shipdata["name"]); // "Cobra Mark III"
log("test",shipdata["ship_class_name"]); // undefined
log("test",shipdata["ship_unique_name"]); // undefined
log("test",shipdata["display_name"]); // undefined

`setShipDataForKey`

This method was added in Oolite test release 1.91.

function setShipDataForKey(datakey : String, newShipData : Object)

This method modifies or adds properties of a ship class specified by the datakey parameter. The newShipData parameter can be an existing property defined in shipdata.plist or a new one.

Example:

Ship.setShipDataForKey ("cobra3-trader", {name: "Cobra trader variant"})
var shipdata = Ship.shipDataForKey ("cobra3-trader")
log ("test", shipdata ["name"])

See also: bulletin board post by Tsoj

@@ Line 75: / Line 75: @@
 === <code>beaconCode</code> ===
-  '''beaconCode''' : String (read-only in 1.76, read-write from 1.77)
+  '''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 <code>null</code>. This cannot be changed by script for either the player's ship or the main station.

Difference between revisions of "Oolite JavaScript Reference: Ship"

Revision as of 08:45, 19 September 2023

Contents

Properties

accuracy

aftWeapon

AI

AIFoundTarget

AIPrimaryAggressor

AIScript

AIScriptWakeTime

AIState

alertCondition

autoAI

autoWeapons

beaconCode

beaconLabel

boundingBox

bounty

cargoList

cargoSpaceAvailable

cargoSpaceCapacity

cargoSpaceUsed

collisionExceptions

commodity

commodityAmount

contracts

cloakAutomatic

crew

cruiseSpeed

currentWeapon

dataKey

defenseTargets

desiredRange

desiredSpeed

destination

destinationSystem

displayName

dockedStation

dockingInstructions

energyRechargeRate

entityPersonality

equipment

escortGroup

escorts

exhaustEmissiveColor

exhausts

flashers

forwardWeapon

fuel

fuelChargeRate

group

hasHostileTarget

hasHyperspaceMotor

hasSuspendedAI

heatInsulation

homeSystem

hyperspaceSpinTime

injectorBurnRate

injectorSpeedFactor

isBeacon

isBoulder

isCargo

isCloaked

isDerelict

isFleeing

isFrangible

isJamming

isMinable

isMine

isMissile

isPiloted

isPirate

isPirateVictim

isPolice

isRock

isThargoid

isTrader

isTurret

isWeapon

`accuracy`

`aftWeapon`

`AI`

`AIFoundTarget`

`AIPrimaryAggressor`

`AIScript`

`AIScriptWakeTime`

`AIState`

`alertCondition`

`autoAI`

`autoWeapons`

`beaconCode`

`beaconLabel`

`boundingBox`

`bounty`

`cargoList`

`cargoSpaceAvailable`

`cargoSpaceCapacity`

`cargoSpaceUsed`

`collisionExceptions`

`commodity`

`commodityAmount`

`contracts`

`cloakAutomatic`

`crew`

`cruiseSpeed`

`currentWeapon`

`dataKey`

`defenseTargets`

`desiredRange`

`desiredSpeed`

`destination`

`destinationSystem`

`displayName`

`dockedStation`

`dockingInstructions`

`energyRechargeRate`

`entityPersonality`

`equipment`

`escortGroup`

`escorts`

`exhaustEmissiveColor`

`exhausts`

`flashers`

`forwardWeapon`

`fuel`

`fuelChargeRate`

`group`

`hasHostileTarget`

`hasHyperspaceMotor`

`hasSuspendedAI`

`heatInsulation`

`homeSystem`

`hyperspaceSpinTime`

`injectorBurnRate`

`injectorSpeedFactor`

`isBeacon`

`isBoulder`

`isCargo`

`isCloaked`

`isDerelict`

`isFleeing`

`isFrangible`

`isJamming`

`isMinable`

`isMine`

`isMissile`

`isPiloted`

`isPirate`

`isPirateVictim`

`isPolice`

`isRock`

`isThargoid`

`isTrader`

`isTurret`

`isWeapon`

`laserHeatLevel`*

`lightsActive`

`markedForFines`

`maxEscorts`