Difference between revisions of "Oolite JavaScript Reference: PlayerShip"

From Elite Wiki
m (viewDirection: removed 2 strings that are never visible for the script.)
(Update for 1.75.)
Line 2: Line 2:
 
<small>'''Subtypes:''' none</small>
 
<small>'''Subtypes:''' none</small>
  
−
The '''<code>PlayerShip</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing the player’s ship. The <code>PlayerShip</code> has all the properties and methods of a <code> [[Oolite JavaScript Reference: Ship|Ship]]</code>, and several others.
+
The '''<code>PlayerShip</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing the player’s ship. The <code>PlayerShip</code> has all the properties and methods of a <code> [[Oolite JavaScript Reference: Ship|Ship]]</code>, and several others. There is always exactly one Player object in existence, which can be accessed through <code>[[Oolite JavaScript Reference: Global#player|player]].ship</code>.
 +
 
 +
Like any entity, the player ship can become [[Oolite JavaScript Reference: Entity#Stale References|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 ==
 
== Properties ==
Line 18: Line 20:
  
 
=== <code>compassMode</code> ===
 
=== <code>compassMode</code> ===
−
{{Oolite-prop-added|1.74}}
 
 
  '''compassMode''' : String (read-only)
 
  '''compassMode''' : String (read-only)
 
Returns the current compass mode, which can be any one of the following:
 
Returns the current compass mode, which can be any one of the following:
−
 
+
* COMPASS_MODE_BASIC
−
COMPASS_MODE_BASIC
+
* COMPASS_MODE_PLANET
−
COMPASS_MODE_PLANET
+
* COMPASS_MODE_STATION
−
COMPASS_MODE_STATION
+
*COMPASS_MODE_SUN
−
COMPASS_MODE_SUN
+
* COMPASS_MODE_TARGET
−
COMPASS_MODE_TARGET
+
* COMPASS_MODE_BEACONS
−
COMPASS_MODE_BEACONS
 
  
 
=== <code>compassTarget</code> ===
 
=== <code>compassTarget</code> ===
−
{{Oolite-prop-added|1.74}}
 
 
  '''compassTarget''' : Entity(read-only)
 
  '''compassTarget''' : Entity(read-only)
 
Points at the entity currently targeted by the compass.
 
Points at the entity currently targeted by the compass.
Line 82: Line 81:
  
 
=== <code>hud</code> ===
 
=== <code>hud</code> ===
−
{{Oolite-prop-added|1.74}}
 
 
  '''hud''' : String (read/write)
 
  '''hud''' : String (read/write)
 
The name of the [[hud.plist|HUD plists]] defining the ship’s head up display.
 
The name of the [[hud.plist|HUD plists]] defining the ship’s head up display.
  
 
=== <code>hudHidden</code> ===
 
=== <code>hudHidden</code> ===
−
{{Oolite-prop-added|1.74}}
 
 
  '''hudHidden''' : Boolean (read/write)
 
  '''hudHidden''' : Boolean (read/write)
 
Whether the HUD should be visible.
 
Whether the HUD should be visible.
  
 
=== <code>manifest</code> ===
 
=== <code>manifest</code> ===
−
{{Oolite-prop-added|1.74}}
 
 
  '''manifest''' : [[Oolite JavaScript Reference: Manifest|Manifest]] (read/write)
 
  '''manifest''' : [[Oolite JavaScript Reference: 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 [[Oolite JavaScript Reference: Manifest|Manifest]] of its own.
 
The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class [[Oolite JavaScript Reference: Manifest|Manifest]] of its own.
Line 111: Line 107:
 
  '''reticleTargetSensitive''' : Boolean (read/write)
 
  '''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 <code>reticle_target_sensitive</code> key in [[hud.plist|HUD plists]].
 
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 <code>reticle_target_sensitive</code> key in [[hud.plist|HUD plists]].
−
 
−
=== <code>scriptedMisjump</code> ===
 
−
'''scriptedMisjump''' : Boolean (read/write)
 
−
When true, the next hyperspace jump will be a misjump. Scripted misjumps have a lifespan of one jump only, then they are autoreset. The scripted_misjump flag will remain set to true during the shipWillExitWitchspace handler, but will be back to false at the end of the shipExitedWitchspace handler
 
  
 
=== <code>scoopOverride</code> ===
 
=== <code>scoopOverride</code> ===
−
{{Oolite-prop-added|1.74}}
 
 
  '''scoopOverride''' : Boolean (read/write)
 
  '''scoopOverride''' : Boolean (read/write)
 
If <code>true</code>, and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.
 
If <code>true</code>, and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.
Line 132: Line 123:
  
 
=== <code>viewDirection</code> ===
 
=== <code>viewDirection</code> ===
−
{{Oolite-prop-future|1.75}}
+
{{Oolite-prop-added|1.75|beta}}
 
  '''viewDirection''' : String (read-only)
 
  '''viewDirection''' : String (read-only)
 
Returns the view direction as string: VIEW_FORWARD, VIEW_AFT, VIEW_PORT, VIEW_STARBOARD, VIEW_CUSTOM or VIEW_GUI_DISPLAY.
 
Returns the view direction as string: VIEW_FORWARD, VIEW_AFT, VIEW_PORT, VIEW_STARBOARD, VIEW_CUSTOM or VIEW_GUI_DISPLAY.
  
 
=== <code>weaponsOnline</code> ===
 
=== <code>weaponsOnline</code> ===
−
{{Oolite-prop-future|1.75}}
+
{{Oolite-prop-added|1.75|beta}}
 
  '''weaponsOnline''' : Boolean (read-only)
 
  '''weaponsOnline''' : Boolean (read-only)
 
Returns the weapon safety status. Player can toggle the status with the underscore-key.
 
Returns the weapon safety status. Player can toggle the status with the underscore-key.
Line 143: Line 134:
 
== Methods ==
 
== Methods ==
 
=== <code>addPassenger</code> ===
 
=== <code>addPassenger</code> ===
−
{{Oolite-method-added|1.74}}
 
 
  function '''addPassenger'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number) : Boolean
 
  function '''addPassenger'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number) : Boolean
 
Add a passenger contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.
 
Add a passenger contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.
Line 157: Line 147:
  
 
=== <code>awardContract</code> ===
 
=== <code>awardContract</code> ===
−
{{Oolite-method-added|1.74}}
 
 
  function '''awardContract'''(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number) : Boolean
 
  function '''awardContract'''(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number) : Boolean
 
Add a cargo contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.
 
Add a cargo contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.
Line 170: Line 159:
  
 
=== <code>awardEquipmentToCurrentPylon</code> ===
 
=== <code>awardEquipmentToCurrentPylon</code> ===
−
{{Oolite-method-added|1.74}}
 
 
  function '''awardEquipmentToCurrentPylon'''(item : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
 
  function '''awardEquipmentToCurrentPylon'''(item : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|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.
 
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.
Line 179: Line 167:
  
 
=== <code>disengageAutopilot</code> ===
 
=== <code>disengageAutopilot</code> ===
−
{{Oolite-method-added|1.74}}
 
 
  function disengageAutopilot()
 
  function disengageAutopilot()
 
Disenable autopilot.
 
Disenable autopilot.
Line 186: Line 173:
  
 
=== <code>engageAutopilotToStation</code> ===
 
=== <code>engageAutopilotToStation</code> ===
−
{{Oolite-method-added|1.74}}
 
 
  function engageAutopilotToStation(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean
 
  function engageAutopilotToStation(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean
 
Engage autopilot, set to dock with the specified station.
 
Engage autopilot, set to dock with the specified station.
−
 
−
'''Bug:''' In Oolite 1.74.0, if <code>engageAutopilotToStation()</code> fails in certain ways the script will be halted without any error message. In future versions, it will simply return <code>false</code>.
 
  
 
'''See also:''' <code>[[#disengageAutopilot|disengageAutopilot()]]</code>
 
'''See also:''' <code>[[#disengageAutopilot|disengageAutopilot()]]</code>
Line 201: Line 185:
 
  function '''removeAllCargo'''()
 
  function '''removeAllCargo'''()
 
Removes all cargo from the ship’s cargo bay.
 
Removes all cargo from the ship’s cargo bay.
 +
 +
=== <code>removePassenger</code> ===
 +
function '''removePassenger'''(name : String)
 +
Remove a named passenger.
  
 
=== <code>useSpecialCargo</code> ===
 
=== <code>useSpecialCargo</code> ===

Revision as of 12:06, 20 February 2011

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 Player 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, nonnegative)

The rate at which the aft shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. Currently always the same as forwardShieldRechargeRate, but this may change in future.

See also: aftShield, forwardShieldRechargeRate, maxAftShield

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.

cursorCoordinates

cursorCoordinates : Vector2D (read-only)

Gives the current x and y cursor Coordinates on the long range screen. 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, nonnegative)

The rate at which the forward shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. Currently always the same as aftShieldRechargeRate, but this may change in future.

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

See also: galacticHyperspaceFixedCoords,

galacticHyperspaceFixedCoords

galacticHyperspaceFixedCoords : Vector3D (read/write)

The destination coordinates when galacticHyperspaceBehaviour mode is "GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES". The z coordinate will always be 0, and x and y will always be integers ranging from 0 to 255.

See also: galacticHyperspaceBehaviour

galaxyCoordinates

galaxyCoordinates : Vector3D (read-only)

Gives the current x and y galactic coordinates. The z coordinate is always 0.

hud

hud : String (read/write)

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

hudHidden

hudHidden : Boolean (read/write)

Whether the HUD should be visible.

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, nonnegative)

The highest possible value of aftShield. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. Currently always the same as maxForwardShield, but this may change in future.

See also: aftShield, aftShieldRechargeRate, maxForwardShield

maxForwardShield

maxAftShield : Number (read-only, nonnegative)

The highest possible value of forwardShield. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. Currently always the same as maxAftShield, but this may change in future.

See also: forwardShield, forwardShieldRechargeRate, maxAftShield

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.

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.

specialCargo

specialCargo : String (read-only)

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

See also: useSpecialCargo()

targetSystem

targetSystem : Integer (read-only)

The ID of the selected hyperspace target system.

viewDirection

This property was added in Oolite beta release 1.75. 

viewDirection : String (read-only)

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

weaponsOnline

This property was added in Oolite beta release 1.75. 

weaponsOnline : Boolean (read-only)

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

Methods

addPassenger

function addPassenger(name : String, start : Number, destination : Number, arrivalTime : Number, fee : 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 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 inital payment is made.

awardContract

function awardContract(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : 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 buy the cargo at the local market price. Using this method, no inital payment is made.

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.

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

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

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.

removePassenger

function removePassenger(name : String)

Remove a named passenger.

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

Retrieved from "https://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_PlayerShip&oldid=27294"