Oolite JavaScript Reference: PlayerShip

Prototype: Ship
Subtypes: none

The PlayerShip class is an Entity representing the player’s ship. The PlayerShip has all the properties and methods of a Ship, and several others. There is always exactly one PlayerShip object in existence, which can be accessed through player.ship.

Like any entity, the player ship can become invalid – specifically, when the player dies or ejects. Unlike other entities, the player ship can become valid again (after ejecting and being rescued). This is a technicality and it’s not guaranteed to work this way in future.

Properties

aftShield

aftShield : Number (read/write, nonnegative)

The current aft shield level, ranging from 0 to maxAftShield.

See also: aftShieldRechargeRate, forwardShield, maxAftShield

aftShieldRechargeRate

aftShieldRechargeRate : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)

The rate at which the aft shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as forwardShieldRechargeRate, but this is not the case from 1.81.

See also: aftShield, forwardShieldRechargeRate, maxAftShield

cargoSpaceAvailable

cargoSpaceAvailable : Number (read-only integer)

The ship’s available cargo space, in tons.

cargoSpaceUsed

cargoSpaceUsed : Number (read-only integer)

The ship’s current cargo, in tons.

compassMode

compassMode : String (read-only)

Returns the current compass mode, which can be any one of the following:

• COMPASS_MODE_BASIC
• COMPASS_MODE_PLANET
• COMPASS_MODE_STATION
• COMPASS_MODE_SUN
• COMPASS_MODE_TARGET
• COMPASS_MODE_BEACONS

compassTarget

compassTarget : Entity(read-only)

Points at the entity currently targeted by the compass.

crosshairs

This property was added in Oolite test release 1.77.

crosshairs : String (read/write)

The name of the crosshairs.plist defining the ship’s weapon crosshairs. HUDs can define crosshairs separately. This value will be null if the HUD built-in crosshairs are in use, and setting it to null will revert to the default HUD crosshairs.

If the HUD is changed, the old value of this property will be discarded, and the HUD's default crosshairs will be used.

currentWeapon

This property was added in Oolite test release 1.77.

currentWeapon : EquipmentInfo (read/write)

A shortcut property to whichever of aftWeapon, forwardWeapon, portWeapon or starboardWeapon is the currently active player weapon.

If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be null, and attempting to write to it will give an error.

cursorCoordinates

cursorCoordinates : Vector3D (read-only)

Discouraged in favour of cursorCoordinatesInLY.
The current x and y cursor coordinates on the long range screen in the internal coordinate system. The z coordinate is always 0.

cursorCoordinatesInLY

cursorCoordinatesInLY : Vector3D (read-only)

The current x and y cursor coordinates on the long range screen, in light years. The z coordinate is always 0.

docked

docked : Boolean (read-only)

True if the player is docked with a station or carrier.

dockedStation

dockedStation : Station (read-only)

The station with which the player is currently docked.

forwardShield

forwardShield : Number (read/write, nonnegative)

The current forward shield level, ranging from 0 to maxForwardShield.

See also: aftShield, forwardShieldRechargeRate, maxForwardShield

forwardShieldRechargeRate

forwardShieldRechargeRate : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)

The rate at which the forward shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as aftShieldRechargeRate, but this is no longer the case in 1.81

See also: aftShieldRechargeRate, forwardShield, maxForwardShield

fuelLeakRate

fuelLeakRate : Number (read/write)

The rate at which the player is losing fuel, in tenths of a LY per second. May not be negative. Reset to 0 when fuel is empty.

galacticHyperspaceBehaviour

galacticHyperspaceBehaviour : String (read/write)

A string indicating what the effect of a galactic hyperspace jump will be. The available options are:

• "BEHAVIOUR_STANDARD": the player arrives in the closest system to the starting point that is part of the main group of stars. Small groups (as seen in galaxy 6, among others) can’t be reached.
• "BEHAVIOUR_ALL_SYSTEMS_REACHABLE": The player arrives at the closest system to the starting point, even if it is in a small group. Important: this can leave the player stranded, unless there are missions providing the possibility of escape!
• "BEHAVIOUR_FIXED_COORDINATES": The player arrives at the system closest to galacticHyperspaceFixedCoordsInLY.

See also: galacticHyperspaceFixedCoordsInLY

galacticHyperspaceFixedCoords

galacticHyperspaceFixedCoords : Vector3D (read/write)

Discouraged in favour of galacticHyperspaceFixedCoordsInLY.
Like galacticHyperspaceFixedCoordsInLY, but in the internal coordinate system.

galacticHyperspaceFixedCoordsInLY

galacticHyperspaceFixedCoordsInLY : Vector3D (read/write)

The destination coordinates when galacticHyperspaceBehaviour mode is "GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES". The coordinate system corresponds to galaxyCoordinatesInLY. Currently, when assigning a value its x and y coordinates will be rounded to integer internal coordinates, and the z coordinate will be rejected.

See also: galacticHyperspaceBehaviour

galaxyCoordinates

galaxyCoordinates : Vector3D (read-only)

Discouraged in favour of galaxyCoordinatesInLY.
The player’s location in galactic space, in the internal coordinate system. The z coordinate is always 0.

galaxyCoordinatesInLY

galaxyCoordinatesInLY : Vector3D (read-only)

The player’s location in galactic space, in light years (measured from the top left of the map). The z coordinate is always 0.

hud

hud : String (read/write)

The name of the HUD plists defining the ship’s head up display.

hudAllowsBigGui

This property was added in Oolite test release 1.83.

hudAllowsBigGui : Boolean (read-only)

Whether the HUD allows a "big GUI" or not. Most useful for determining whether mission screens will have 21 or 27 lines.

If hudHidden is true this will also be true, even if the HUD which is hidden would not normally allow a big GUI.

hudHidden

hudHidden : Boolean (read/write)

Whether the HUD should be visible.

hyperspaceSpinTime

This property was added in Oolite test release 1.77.

hyperspaceSpinTime : Number (read-only, read/write in 1.81)

The length of the ship's hyperspace countdown.

Setting this to a negative value disables the drive entirely.

infoSystem

This property was added in Oolite test release 1.83.

infoSystem : Number (read/write)

The ID of the system shown in the system (F7) screen.

injectorsEngaged

This property was added in Oolite test release 1.81.

injectorsEngaged : Boolean(read-only)

Is the player ship currently using fuel injection.

manifest

manifest : Manifest (read/write)

The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class Manifest of its own.

maxAftShield

maxAftShield : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)

The highest possible value of aftShield. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as maxForwardShield, but this is not necessarily true from 1.81.

See also: aftShield, aftShieldRechargeRate, maxForwardShield

maxForwardShield

maxAftShield : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)

The highest possible value of forwardShield. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as maxAftShield, but this is not necessarily true from 1.81.

See also: forwardShield, forwardShieldRechargeRate, maxAftShield

missilesOnline

This property was added in Oolite test release 1.77.

missilesOnline : Boolean (read-only)

True if the ship's targeting system is currently in missile targeting mode, false if it is currently in identification mode.

multiFunctionDisplayList

This property was added in Oolite test release 1.81.

multiFunctionDisplayList : Array (read-only, strings)

The IDs of the currently active multi-function displays

e.g.

[null, "myoxp_mfd1"] // My OXP MFD1 in the second display, first display blank

multiFunctionDisplays

This property was added in Oolite test release 1.79.

multiFunctionDisplays : Number (read-only, integer)

The number of multi-function displays available on the current HUD.

price

This property was added in Oolite test release 1.77.

price : Number (read-only, positive integer in decicredits)

The value the player's ship would have, including equipment, if in a perfect servicing state. The ship can be exchanged at a shipyard for 75% of this value if it really is in perfect servicing state.

renovationCost

This property was added in Oolite test release 1.79.

renovationCost : Number (read-only, positive integer in decicredits)

The current price in decicredits to service the ship. Depending on the serviceLevel it may not be possible to actually purchase renovation at this time.

renovationMultiplier

This property was added in Oolite test release 1.79.

renovationMultiplier : Number (read-only, positive)

The multiplier applied to the base cost of renovation (renovationCost already includes this multiplier) to allow for some ships being more difficult to maintain than others. The default is 1.0 - other values are set in shipyard.plist

reticleTargetSensitive

reticleTargetSensitive : Boolean (read/write)

If true, and Scanner Targeting Enhancement is installed, the selected target reticle will light up in red when the target is in the player’s sights. This is equivalent to the reticle_target_sensitive key in HUD plists.

routeMode

This property was added in Oolite test release 1.81.

routeMode : String (read-only)

Gives the current mode of the Advanced Navigational Array. Three possible values

• "OPTIMIZED_BY_NONE": off, or not fitted
• "OPTIMIZED_BY_JUMPS": shortest route
• "OPTIMIZED_BY_TIME": quickest route

scannerNonLinear

scannerNonLinear : Boolean (read/write)

If true, the scanner is operating in non-linear mode. This property will be reset to the HUD default if the HUD is changed.

scannerUltraZoom

scannerUltraZoom : Boolean (read/write)

If true, the scanner has 1x, 2x, 4x, 8x and 16x zoom modes, rather than the conventional 1x, 2x, 3x, 4x and 5x. This property will be reset to the HUD default if the HUD is changed.

scoopOverride

scoopOverride : Boolean (read/write)

If true, and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.

serviceLevel

This property was added in Oolite test release 1.77.

serviceLevel : Number (read/write, positive integer in range 75-100)

The level of servicing the player's ship has. Renovation will be offered in shipyards at 85 or below, and malfunctions are more likely at lower values. This affects the sales price of the ship.

specialCargo

specialCargo : String (read-only)

The special cargo the player is carrying, if any; otherwise null.

See also: useSpecialCargo()

targetSystem

targetSystem : Integer (read-only, sometimes read/write in 1.77)

The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked.

torusEngaged

This property was added in Oolite test release 1.81.

torusEngaged : Boolean(read-only)

Is the player ship currently using torus drive

viewDirection

viewDirection : String (read-only)

Returns the view direction as string: "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD", "VIEW_CUSTOM" or "VIEW_GUI_DISPLAY".

viewPosition*

This property was added in Oolite test release 1.79.

viewPositionAft : Vector (read-only)
viewPositionForward : Vector (read-only)
viewPositionPort : Vector (read-only)
viewPositionStarboard : Vector (read-only)

The ship's 4 point-of-view positions in XYZ relative to the model. The corresponding shipdata.plist keys start with view_position_.

weaponsOnline

weaponsOnline : Boolean (read-only)

Returns the weapon safety status. Player can toggle the status with the underscore-key.

Methods

addParcel

This method was added in Oolite test release 1.77.

function addParcel(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean

Add a parcel contract to the ship. arrivalTime is the arrival time in seconds and must be greater than the current time. start and destination are the ID numbers of the start and end systems.

Returns false when there is already a parcel with that name or the arrival time is invalid.

The advance and risk parameters were added in Oolite 1.79. advance is purely advisory and describes any up-front payment given for the parcel. risk can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this parcel.

addPassenger

function addPassenger(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean

Add a passenger contract to the ship. arrivalTime is the arrival time in seconds and must be greater than the current time. start and destination are the ID numbers of the start and end systems.

Returns false when there is no room for the passenger, there is already a passenger with that name or the arrival time is invalid.

Example:

 player.ship.addPassenger("cmdr Jameson", 34, 67, clock.seconds+3*24*3600, 1500);

If successful - and in galaxy chart 1 - the player will have cmdr Jameson as a passenger, his documents will show that he boarded the ship at Inus, to go to Cemave, within exactly 3 days, and the player will be given 1500 credits if he gets there on time (early or late arrival will affect the amount paid).

N.B. Normally a passenger will pay the captain a small advance upon boarding. Using this method, no initial payment is made. In versions after 1.77, an optional parameter can be added to describe what the advance was, without actually making it.

The risk parameter was added in Oolite 1.79. risk can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this passenger.

awardContract

function awardContract(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, premium : Number]) : Boolean

Add a cargo contract to the ship. arrivalTime is the arrival time in seconds and must be greater than the current time. start and destination are the ID numbers of the start and end systems.

Returns false when there is no room for the cargo, the arrival time is invalid.

Example:

player.ship.awardContract(12, "Food", 34, 67, clock.seconds+7*24*3600, 5000)

If successful - and in galaxy chart 1 - the player will have 12 more food containers on board, the manifest will show that the cargo was picked up at Inus, to be delivered at Cemave, within exactly 7 days, and the player will be given 5000 credits if the cargo is delivered on time (early or late delivery will affect the amount paid).

N.B. Normally to get a contract, the player will have to pay a deposit similar in value to the cargo. Using this method, no deposit payment is made. In versions after 1.77, an optional parameter can be added to describe what the deposit payment was, without actually making it.

awardEquipmentToCurrentPylon

function awardEquipmentToCurrentPylon(item : equipmentInfoExpression) : Boolean

Replace the missile or mine currently being launched with the specified item (which must be an external store). This will only have an effect if called while a missile or mine is being launched. Effectively this means that this method must be used within the shipFiredMissile() handler or in the ENTER message of the GLOBAL state of an missileAI.plist.

Bug: In Oolite 1.74.0, if awardEquipmentToCurrentPylon() fails the script will be halted without any error message. In future versions, it will simply return false.

See also: Ship.awardEquipment()

beginHyperspaceCountdown

This method was added in Oolite test release 1.77.

function beginHyperspaceCountdown( [ length : Number ] ) : Boolean

This function begins the witchspace sequence for the player ship. It returns true if the sequence is started successfully, and false otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used.

See also: cancelHyperspaceCountdown

cancelHyperspaceCountdown

This method was added in Oolite test release 1.77.

function cancelHyperspaceCountdown() : Boolean

This function cancels the witchspace sequence for the player ship. It returns true if there was an ongoing sequence to cancel, and false otherwise.

See also: beginHyperspaceCountdown

disengageAutopilot

function disengageAutopilot()

Disenable autopilot.

See also: engageAutopilotToStation()

engageAutopilotToStation

function engageAutopilotToStation(station : Station) : Boolean

Engage autopilot, set to dock with the specified station.

See also: disengageAutopilot()

hideHUDSelector

This method was added in Oolite test release 1.79.

function hideHUDSelector(selector : String)

Hide all dials using the specified selector on the HUD display. For example

player.ship.hideHUDSelector("drawScanner:");

See also: showHUDSelector()

launch

function launch()

Launches the player’s ship if it is currently docked.

removeAllCargo

function removeAllCargo()

Removes all cargo from the ship’s cargo bay that are measured in tons. Does not affect Gold, Platinum or Gemstones. Can only be used while docked.

removeContract

function removeContract(commodity : String, destination : Number)

Remove the cargo contract matching that commodity and destination.

removeParcel

This method was added in Oolite test release 1.77.

function removeParcel(name : String)

Remove a named parcel.

removePassenger

function removePassenger(name : String)

Remove a named passenger.

resetCustomView

This method was added in Oolite test release 1.77.

function resetCustomView()

Resets the custom view back to the last-used setting defined in shipdata.plist

This function gives an error if used when the custom view camera is not selected.

resetScannerZoom

This method was added in Oolite test release 1.79.

function resetScannerZoom()

Resets the scanner zoom back to 1:1

setCustomView

This method was added in Oolite test release 1.77.

function setCustomView(Vector : position, Quaternion : orientation [,WeaponDirection weapon])

Set the position and orientation of the custom view camera to those specified. As with the custom views specified through shipdata.plist, these are relative to the player's ship's position, and the coordinate frame defined by the ship's forward, right and up Vectors.

The optional weapon parameter can be "FORWARD", "AFT", "PORT" or "STARBOARD" and sets the active weapon accordingly. If omitted, the active weapon for the previous custom view will be preserved.

This function gives an error if used when the custom view camera is not selected. Setting the custom view does not affect the custom views defined in shipdata.plist, which will be switched back to the next time 'v' is pressed, or when resetCustomView is called.

setCustomHUDDial

This method was added in Oolite test release 1.81.

function setCustomHUDDial(key : String, value : Value)

Sets the custom HUD dial data source 'key' to the specified value. Different types of custom HUD dial will expect different types of values; a value of an incorrect type will be converted if possible.

setMultiFunctionDisplay

This method was added in Oolite test release 1.79.

function setMultiFunctionDisplay(index : Number, key : String) : Boolean

Sets the multi-function display with the specified number to display the given multi-function display key set earlier with setMultiFunctionText(). Multi-function displays are numbered from 0 to multiFunctionDisplays-1. If the index given is outside this range, the first unused multi-function display will be used, or the function will return false if all are currently in use. Example:

// picks first unused one
player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd");

As the player can cycle the contents of their displays between the various active keys themselves using keyboard controls, it is advisable not to call this function to override a specific display except in emergencies, as this is likely to annoy the player.

setMultiFunctionText

This method was added in Oolite test release 1.79.

function setMultiFunctionText(key : String [, contents : String [, reflow : Boolean]])

Set the text for the multi-function display with the specified key to be contents. The limit on space for a multi-function display is ten lines of text, each 15 blocks wide.

If you specify the optional reflow parameter, then the text given will automatically be fitted into the available space, with any extra discarded. Otherwise, line-breaks will not be added automatically, so you must enter them into contents yourself. If any individual line is more than 15 blocks long, the text will be compressed to fit it into the available space. This looks bad and is best avoided.

showHUDSelector

This method was added in Oolite test release 1.79.

function showHUDSelector(selector : String)

Show all dials using the specified selector on the HUD display if they were previously hidden. For example

player.ship.showHUDSelector("drawScanner:");

See also: hideHUDSelector()

takeInternalDamage

This method was added in Oolite test release 1.77.

function takeInternalDamage()

Causes the player ship to potentially take "internal damage". Internal damage can also be caused by hits on the hull and some witchdrive malfunctions, and this function uses the same algorithm to determine the damage taken, which can be:

• damage to cargo
• damage to equipment (according to the damage_probability)
• reduction in service level
• no damage

The function will return 'false' if "no damage" was selected, and 'true' otherwise. The relative probabilities of the three options vary depending on the size of the player ship, its cargo capacity, cargo carried and installed equipment.

useSpecialCargo

function useSpecialCargo(description : String)

Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.

See also: specialCargo