Difference between revisions of "Oolite JavaScript Reference: PlayerShip"

From Elite Wiki
m (→‎<code>galacticHyperspaceBehaviour</code>)
(Updated for 1.72.1 galactic hyperspace semantics.)
Line 41: Line 41:
   
 
=== <code>galacticHyperspaceBehaviour</code> ===
  
=== <code>galacticHyperspaceBehaviour</code> ===
−
'''galacticHyperspaceBehaviour''' : Number (read-only)
  
  +
{{Oolite-prop-future|1.72.1}}
−
A number indicating what the effect of a galactic hyperspace jump will be: 0 for <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_STANDARD"</code>, 1 for <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_ALL_SYSTEMS_REACHABLE"</code>, 2 for <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>. (See <code>[[#setGalacticHyperspaceBehaviour|setGalacticHyperspaceBehaviour()]]</code> for definitions.)
  
  +
'''galacticHyperspaceBehaviour''' : String (read/write)
  +
A string indicating what the effect of a galactic hyperspace jump will be. The available options are:
  +
* <code>"BEHAVIOUR_STANDARD"</code>: 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 [[Oolite planet list/Galaxy 6|galaxy 6]], among others) can’t be reached.
  +
* <code>"BEHAVIOUR_ALL_SYSTEMS_REACHABLE"</code>: 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!
  +
* <code>"BEHAVIOUR_FIXED_COORDINATES"</code>: The player arrives at the system closest to <code>[[#galacticHyperspaceFixedCoords|galacticHyperspaceFixedCoords]]</code>.
   
−
'''Note''': the semantics of this property are expected to change in version 1.72.1.
  
  +
'''See also:''' <code>[[#galacticHyperspaceFixedCoords|galacticHyperspaceFixedCoords]]</code>,
−  
−
'''See also:''' <code>[[#galacticHyperspaceFixedCoords|galacticHyperspaceFixedCoords]]</code>, <code>[[#setGalacticHyperspaceBehaviour|setGalacticHyperspaceBehaviour()]]</code>
  
   
 
=== <code>galacticHyperspaceFixedCoords</code> ===
  
=== <code>galacticHyperspaceFixedCoords</code> ===
−
'''galacticHyperspaceFixedCoords''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read-only)
  
  +
{{Oolite-prop-future|1.72.1}}
−
The destination coordinates when the galactic hyperspace behaviour mode is <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>. The <code>z</code> coordinate will always be 0.
  
  +
'''galacticHyperspaceFixedCoords''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)
  +
The destination coordinates when <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code> mode is <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>. The <code>z</code> coordinate will always be 0, and <code>x</code> and <code>y</code> will always be integers ranging from 0 to 255.
   
−
'''See also:''' <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code>, <code>[[#setGalacticHyperspaceFixedCoords|setGalacticHyperspaceFixedCoords()]]</code>
 +
'''See also:''' <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code>
   
 
=== <code>maxAftShield</code> ===
  
=== <code>maxAftShield</code> ===
Line 120: Line 123:
   
 
'''See also''': <code>[[#equipmentStatus|equipmentStatus()]]</code>
  
'''See also''': <code>[[#equipmentStatus|equipmentStatus()]]</code>
−  
−
=== <code>setGalacticHyperspaceBehaviour</code> ===
  
−
function '''setGalacticHyperspaceBehaviour'''(behaviour : String)
  
−
Specifies what should happen when the player performs a galactic hyperspace jump. The available options are:
  
−
* <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_STANDARD"</code>: 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 [[Oolite planet list/Galaxy 6|galaxy 6]], among others) can’t be reached.
  
−
* <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_ALL_SYSTEMS_REACHABLE"</code>: 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!
  
−
* <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>: The player arrives at the system closest to the coordinates specified via <code>[[#setGalacticHyperspaceFixedCoords|setGalacticHyperspaceFixedCoords()]]</code>.
  
−  
−
'''See also:''' <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code>, <code>[[#setGalacticHyperspaceFixedCoords|setGalacticHyperspaceFixedCoords()]]</code>
  
−  
−
=== <code>setGalacticHyperspaceFixedCoords</code> ===
  
−
function '''setGalacticHyperspaceFixedCoords'''(x : Number, y : Number)
  
−
''or''
  
−
function '''setGalacticHyperspaceFixedCoords'''(v : [[Oolite JavaScript Reference: Vector3D#Vector Expressions|vectorExpression]])
  
−
Specify the location on the galactic map where the player should appear after the next galactic hyperspace jump, assuming the current galactic hyperspace behaviour is <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>.
  
−  
−
'''See also:''' <code>[[#galacticHyperspaceFixedCoords|galacticHyperspaceFixedCoords]]</code>, <code>[[#setGalacticHyperspaceBehaviour|setGalacticHyperspaceBehaviour()]]</code>
  
   
 
=== <code>useSpecialCargo</code> ===
  
=== <code>useSpecialCargo</code> ===

Revision as of 23:53, 5 November 2008

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

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 is planned for Oolite beta release 1.72.1. The design and functionality presented is not final.
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 is planned for Oolite beta release 1.72.1. The design and functionality presented is not final.
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

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.

specialCargo

specialCargo : String (read-only)

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

See also: useSpecialCargo()


Methods

awardCargo

function awardCargo(cargoname : String, amount : Number)

Awards the given amount of the specified type of cargo. The cargo name must match the name in commodities.plist exactly.

awardEquipment

function awardEquipment(equipmentKey : String)

Adds the given piece of equipment to the player’s ship. Example: player.awardEquipment("EQ_TRUMBLE")

canAwardCargo

function canAwardCargo(cargoName : String, amount : Number) : Boolean

Returns true if it is possible to add the specified cargo to the ship, false otherwise. In particular, it will return false 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 canAwardCargo is strongly recommended.

See also: awardCargo()

equipmentStatus

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: "EQUIPMENT_OK", "EQUIPMENT_DAMAGED", "EQUIPMENT_UNAVAILABLE".

See also: setEquipmentStatus()

hasEquipment

function hasEquipment(equipmentKey : String) : Boolean

Returns true if the given piece of equipment is present on/in the player’s ship, false if it is not. Example: if (player.hasEquipment("EQ_TRUMBLE")) Log("Oh noes, I has a trumble!")

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.

removeEquipment

function removeEquipment(equipmentKey : String)

Removes the given piece of equipment from the player’s ship. Example: player.removeEquipment("EQ_TRUMBLE")

setEquipmentStatus

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 "EQUIPMENT_OK", "EQUIPMENT_DAMAGED".

See also: equipmentStatus()

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=11720"