Difference between revisions of "Oolite JavaScript Reference: PlayerShip"

From Elite Wiki
(→‎canAwardCargo (deprecated))
(Updated for 1.74.)
Line 1: Line 1:
 
<small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code></small><br />
  
<small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code></small><br />
−  
−
{{Oolite-class-added|1.72}}
  
   
 
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.
Line 17: Line 15:
   
 
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>
  
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>
−  
−
=== <code>aftWeapon</code> ===
  
−
{{Oolite-prop-added|1.74}}
  
−
'''aftWeapon''' : EquipmentType(read-only)
  
−
The currently equipped aft weapon, or null.<br>Example usage:
  
−
if (!player.ship.aftWeapon) consoleMessage('Time to buy an aft weapon, commander!');
  
−  
−
'''See also''': <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code><code>, [[#starboardWeapon|starboardWeapon]]</code>
 
   
 
=== <code>compassMode</code> ===
  
=== <code>compassMode</code> ===
Line 44: Line 34:
   
 
=== <code>cursorCoordinates</code> ===
  
=== <code>cursorCoordinates</code> ===
−
{{Oolite-prop-added|1.73}}
  
 
'''cursorCoordinates''' : Vector2D (read-only)
  
'''cursorCoordinates''' : Vector2D (read-only)
 
Gives the current x and y cursor Coordinates on the long range screen. The z coordinate is always 0.
  
Gives the current x and y cursor Coordinates on the long range screen. The z coordinate is always 0.
Line 67: Line 56:
   
 
'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>
  
'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>
−  
−
=== <code>forwardWeapon</code> ===
  
−
{{Oolite-prop-added|1.74}}
  
−
'''forwardWeapon''' : EquipmentType(read-only)
  
−
The currently equipped forward weapon, or null.<br>Example usage:
  
−
if (player.ship.forwardWeapon.equipmentKey == 'EQ_WEAPON_PULSE_LASER')
  
−
consoleMessage('Time to upgrade your pulse laser, commander!');
  
−  
−
'''See also''': <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code><code>, [[#starboardWeapon|starboardWeapon]]</code>
  
   
 
=== <code>fuelLeakRate</code> ===
  
=== <code>fuelLeakRate</code> ===
Line 99: Line 79:
   
 
=== <code>galaxyCoordinates</code> ===
  
=== <code>galaxyCoordinates</code> ===
−
{{Oolite-prop-added|1.73}}
  
 
'''galaxyCoordinates''' : Vector3D (read-only)
  
'''galaxyCoordinates''' : Vector3D (read-only)
 
Gives the current x and y galactic coordinates. The z coordinate is always 0.
  
Gives the current x and y galactic coordinates. The z coordinate is always 0.
  +
  +
=== <code>hud</code> ===
  +
{{Oolite-prop-added|1.74}}
  +
'''hud''' : String (read/write)
  +
The name of the [[hud.plist|HUD plists]] defining the ship’s head up display.
  +
  +
=== <code>hudHidden</code> ===
  +
{{Oolite-prop-added|1.74}}
  +
'''hudHidden''' : Boolean (read/write)
  +
Whether the HUD should be visible.
   
 
=== <code>manifest</code> ===
  
=== <code>manifest</code> ===
Line 119: Line 108:
   
 
'''See also''': <code>[[#forwardShield|forwardShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>
  
'''See also''': <code>[[#forwardShield|forwardShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>
−  
−
=== <code>portWeapon</code> ===
  
−
{{Oolite-prop-added|1.74}}
  
−
'''portWeapon''' : EquipmentType(read-only)
  
−
The currently equipped port weapon, or null.
  
−  
−
'''See also''': <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#starboardWeapon|starboardWeapon]]</code>
  
   
 
=== <code>reticleTargetSensitive</code> ===
  
=== <code>reticleTargetSensitive</code> ===
Line 132: Line 114:
   
 
=== <code>scriptedMisjump</code> ===
  
=== <code>scriptedMisjump</code> ===
−
{{Oolite-prop-added|1.73}}
  
 
'''scriptedMisjump''' : Boolean (read/write)
  
'''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
  
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> ===
  +
{{Oolite-prop-added|1.74}}
  +
'''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.
   
 
=== <code>specialCargo</code> ===
  
=== <code>specialCargo</code> ===
Line 142: Line 128:
 
'''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code>
  
'''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code>
   
−
=== <code>starboardWeapon</code> ===
 +
=== <code>targetSystem</code> ===
−
{{Oolite-prop-added|1.74}}
 +
'''targetSystem''' : Integer (read-only)
−
'''starboardWeapon''' : EquipmentType(read-only)
 +
The ID of the selected hyperspace target system.
−
The currently equipped starboard weapon, or null.
  
   
−
'''See also''': <code>[[#aftWeapon|aftWeapon]]</code>, <code>[[#forwardWeapon|forwardWeapon]]</code>, <code>[[#portWeapon|portWeapon]]</code>
  
  +
'''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code>
   
 
== Methods ==
  
== Methods ==
−
=== <code>awardCargo (deprecated)</code> ===
 +
=== <code>awardEquipmentToCurrentPylon</code> ===
−
function '''awardCargo'''(cargoname : String, amount : Number)
 +
{{Oolite-method-added|1.74}}
−
Awards the given amount of the specified type of cargo. The cargo name must match the name in ''commodities.plist'' exactly.
 +
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.
   
−
This function is deprecated in 1.74 - use specific [[Oolite JavaScript Reference: Manifest|Manifest]] properties instead.
  
  +
'''Bug:''' In Oolite 1.74.0, if <code>awardEquipmentToCurrentPylon()</code> fails the script will be halted without any error message. In future versions, it will simply return <code>false</code>.
   
−
=== <code>awardEquipment</code> ===
 +
'''See also:''' <code>[[Oolite JavaScript Reference: Ship#awardEquipment|Ship.awardEquipment()]]</code>
−
function '''awardEquipment'''(equipmentKey : String)
  
−
Adds the given piece of equipment to the player’s ship. Example: <code>player.awardEquipment("EQ_TRUMBLE")</code>
  
   
−
=== <code>canAwardCargo (deprecated)</code> ===
 +
=== <code>disengageAutopilot</code> ===
−
function '''canAwardCargo'''(cargoName : String, amount : Number) : Boolean
 +
{{Oolite-method-added|1.74}}
−
Returns <code>true</code> if it is possible to add the specified cargo to the ship, <code>false</code> otherwise. In particular, it will return <code>false</code> if there is not enough space, if the cargo type is unknown or if there is currently special cargo installed (and the cargo is of a type measured in tons). Attempting to award cargo under these conditions will raise an error, so using <code>canAwardCargo</code> is strongly recommended.
 +
function disengageAutopilot()
  +
Disenable autopilot.
   
−
Both awardCargo and this function are deprecated in 1.74, in favour of the more direct [[Oolite JavaScript Reference: Manifest|Manifest]] read/write properties.
  
  +
'''See also:''' <code>[[#engageAutopilotToStation|engageAutopilotToStation()]]</code>
   
−
'''See also:''' <code>[[#awardCargo|awardCargo]]()</code>
  
  +
=== <code>engageAutopilotToStation</code> ===
  +
{{Oolite-method-added|1.74}}
  +
function engageAutopilotToStation(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean
  +
Engage autopilot, set to dock with the specified station.
   
−
=== <code>equipmentStatus</code> ===
  
  +
'''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>.
−
function '''equipmentStatus'''(equipmentKey : String) : String
  
−
Tests whether the specified type of equipment is installed, and whether it is functioning. Returns one of the following strings: <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>, <code>"EQUIPMENT_UNAVAILABLE"</code>.
  
   
−
'''See also''': <code>[[#setEquipmentStatus|setEquipmentStatus()]]</code>
 +
'''See also:''' <code>[[#disengageAutopilot|disengageAutopilot()]]</code>
−  
−
=== <code>hasEquipment</code> ===
  
−
Moved to <code>[[Oolite JavaScript Reference: Ship#hasEquipment|Ship]]</code> in 1.73.
  
   
 
=== <code>launch</code> ===
  
=== <code>launch</code> ===
Line 178: Line 165:
 
function '''removeAllCargo'''()
  
function '''removeAllCargo'''()
 
Removes all cargo from the ship’s cargo bay.
  
Removes all cargo from the ship’s cargo bay.
−  
−
=== <code>removeEquipment</code> ===
  
−
function '''removeEquipment'''(equipmentKey : String)
  
−
Removes the given piece of equipment from the player’s ship. Example: <code>player.removeEquipment("EQ_TRUMBLE")</code>
  
−  
−
=== <code>setEquipmentStatus</code> ===
  
−
function '''setEquipmentStatus'''(equipmentKey : String, statusKey : String)
  
−
Changes the status of the given piece of equipment from the player’s ship. The two only valid status keys are <code>"EQUIPMENT_OK"</code>, <code>"EQUIPMENT_DAMAGED"</code>.
  
−  
−
'''See also''': <code>[[#equipmentStatus|equipmentStatus()]]</code>
  
   
 
=== <code>useSpecialCargo</code> ===
  
=== <code>useSpecialCargo</code> ===

Revision as of 13:12, 18 June 2010

Prototype: Ship

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.

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

This property was added in Oolite test release 1.74. 

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

This property was added in Oolite test release 1.74. 

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

This property was added in Oolite test release 1.72.1. 

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

This property was added in Oolite test release 1.72.1. 

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

This property was added in Oolite test release 1.74. 

hud : String (read/write)

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

hudHidden

This property was added in Oolite test release 1.74. 

hudHidden : Boolean (read/write)

Whether the HUD should be visible.

manifest

This property was added in Oolite test release 1.74. 

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.

scriptedMisjump

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

scoopOverride

This property was added in Oolite test release 1.74. 

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.

See also: useSpecialCargo()

Methods

awardEquipmentToCurrentPylon

This method was added in Oolite test release 1.74. 

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

This method was added in Oolite test release 1.74. 

function disengageAutopilot()

Disenable autopilot.

See also: engageAutopilotToStation()

engageAutopilotToStation

This method was added in Oolite test release 1.74. 

function engageAutopilotToStation(station : Station) : Boolean

Engage autopilot, set to dock with the specified station.

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

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.

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 "http://backup.witchspacewiki.org/index.php?title=Oolite_JavaScript_Reference:_PlayerShip&oldid=22506"