Difference between revisions of "Oolite JavaScript Reference: Player"

Revision as of 12:22, 6 December 2007

Prototype: Ship

The Player class is an Entity representing the player, and the player’s ship – the two are inseperable. The Player 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 the player global property.

Properties

`name`

name : String (read-only)

The name of the player’s character (e.g., “Jameson”).

`score`

score : Number (read/write, integer)

The player’s score; nominally the number of kills the player has made, although some missions award additional points.

`credits`

credits : Number (read/write, integer)

The amount of money the player has.

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

`alertCondition`

alertCondition : Number (read-only, integer)

Returns the current alert condition. 0 = Docked, 1 = Green, 2 = Yellow, 3 = Red.

`docked`

docked : Boolean (read-only)

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

`alertTemperature`

alertTemperature : Boolean (read-only)

Whether the cabin temperature is dangerously high.

`alertMassLocked`

alertMassLocked : Boolean (read-only)

Whether the player is mass locked.

`alertAltitude`

alertAltitude : Boolean (read-only)

Whether the player is dangerously close to a planet.

`alertEnergy`

alertEnergy : Boolean (read-only)

Whether the player’s energy level is depleted (i.e., energy is less than maxEnergy).

`alertHostiles`

alertHostiles : Boolean (read-only)

Whether there are hostile ships within scanner range.

`dockedStation`

dockedStation : Station (read-only)

The station with which the player is currently docked.

Deprecated properties

The following properties are deprecated as of Oolite 1.70, and will be removed before the next stable release:

legalStatus: use bounty instead.
dockedStationName: use dockedStation.shipDescription instead.
dockedAtMainStation: use dockedStation.isMainStation instead.

Methods

`awardEquipment`

awardEquipment(equipmentKey : String)

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

`commsMessage`

commsMessage(message : String [, duration: Number])

Writes the specified message in the player’s communications log, as well as displaying it as a console message. The optional duration parameter determines how long the message should be displayed on the console before fading out. It is clamped to the range [1, 10]. If no duration is specified, 4.5 seconds will be used. Example: player.commsMessage("Hello, cruel universe.", 6)

`consoleMessage`

consoleMessage(message : String [, duration: Number])

Displays the specified message as a console message, that is, as a message on the HUD. The optional duration parameter determines how long the message should be displayed before fading out. It is clamped to the range [1, 10]. If no duration is specified, 3 seconds will be used.

`removeEquipment`

removeEquipment(equipmentKey : String)

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

`hasEquipment`

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!")

`awardCargo`

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.

`removeAllCargo`

removeAllCargo()

Removes all cargo from the ship’s cargo bay.

`useSpecialCargo`

useSpecialCargo(description : String)

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

`launch`

launch()

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

@@ Line 1: / Line 1: @@
 <small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code></small><br />
-{{Oolite-class-added|1.70}}
 The '''<code>Player</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing the player, and the player’s ship – the two are inseperable. The <code>Player</code> has all the properties and methods of a <code> [[Oolite JavaScript Reference: Ship|Ship]]</code>, and several others. There is always exactly one <code>Player</code> object in existence, which can be accessed through the <code>player</code> global property.
 == Properties ==
-=== <code> name </code> ===
+=== <code>name</code> ===
- name [read-only string]
+ '''name''' : String (read-only)
 The name of the player’s character (e.g., “Jameson”).
 === <code>score</code> ===
- score [read-write integer]
+ '''score''' : Number (read/write, integer)
 The player’s score; nominally the number of kills the player has made, although some missions award additional points.
 === <code>credits</code> ===
- credits [read-write integer]
+ '''credits''' : Number (read/write, integer)
 The amount of money the player has.
 === <code>fuelLeakRate</code> ===
- fuelLeakRate [read-write double]
+ '''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.
 === <code>alertCondition</code> ===
- alertCondition [read-only integer]
+ '''alertCondition''' : Number (read-only, integer)
 Returns the current alert condition. 0 = Docked, 1 = Green, 2 = Yellow, 3 = Red.
 === <code>docked</code> ===
- docked [read-only boolean]
+ '''docked''' : Boolean (read-only)
 True if the player is docked with a station or carrier.
 === <code>alertTemperature</code> ===
- alertTemperature [read-only boolean]
+ '''alertTemperature''' : Boolean (read-only)
 Whether the cabin temperature is dangerously high.
 === <code>alertMassLocked</code> ===
- alertMassLocked [read-only boolean]
+ '''alertMassLocked''' : Boolean (read-only)
 Whether the player is mass locked.
 === <code>alertAltitude</code> ===
- alertAltitude [read-only boolean]
+ '''alertAltitude''' : Boolean (read-only)
 Whether the player is dangerously close to a planet.
 === <code>alertEnergy</code> ===
- alertEnergy [read-only boolean]
+ '''alertEnergy''' : Boolean (read-only)
 Whether the player’s energy level is depleted (i.e., <code>[[Oolite JavaScript Reference: Entity#energy|energy]]</code> is less than <code>[[Oolite JavaScript Reference: Entity#maxEnergy|maxEnergy]]</code>).
 === <code>alertHostiles</code> ===
- alertHostiles [read-only boolean]
+ '''alertHostiles''' : Boolean (read-only)
 Whether there are hostile ships within scanner range.
 === <code>dockedStation</code> ===
- dockedStation [read-only [[Oolite JavaScript Reference: Station|Station]]]
+ '''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
 The station with which the player is currently docked.
@@ Line 62: / Line 60: @@
 == Methods ==
-===awardEquipment===
+=== <code>awardEquipment</code> ===
- void awardEquipment(equipmentKey)
+ '''awardEquipment'''(equipmentKey : String)
 Adds the given piece of equipment to the player’s ship. Example: <code>player.awardEquipment("EQ_TRUMBLE")</code>
-=== commsMessage ===
+=== <code>commsMessage</code> ===
  '''commsMessage'''(message : String [, duration: Number])
-Writes the specified message in the player’s communications log, as well as displaying it as a console message. The optional <code>duration</code> parameter determines how long the message should be displayed on the console before fading out. It is clamped to the range [1, 10]. If no duration is specified, 4.5 seconds will be used. Example:
+Writes the specified message in the player’s communications log, as well as displaying it as a console message. The optional <code>duration</code> parameter determines how long the message should be displayed on the console before fading out. It is clamped to the range [1, 10]. If no duration is specified, 4.5 seconds will be used. Example: <code>player.commsMessage("Hello, cruel universe.", 6)</code>
- player.commsMessage("Hello, cruel universe.", 6)
-=== consoleMessage ===
+=== <code>consoleMessage</code> ===
  '''consoleMessage'''(message : String [, duration: Number])
 Displays the specified message as a console message, that is, as a message on the HUD. The optional <code>duration</code> parameter determines how long the message should be displayed before fading out. It is clamped to the range [1, 10]. If no duration is specified, 3 seconds will be used.
-===removeEquipment===
+=== <code>removeEquipment</code> ===
- void removeEquipment(equipmentKey)
+ '''removeEquipment'''(equipmentKey : String)
 Removes the given piece of equipment from the player’s ship. Example: <code>player.removeEquipment("EQ_TRUMBLE")</code>
-===hasEquipment===
+=== <code>hasEquipment</code> ===
- boolean hasEquipment(equipmentKey)
+ '''hasEquipment'''(equipmentKey : String) : Boolean
 Returns <code>true</code> if the given piece of equipment is present on/in the player’s ship, <code>false</code> if it is not. Example: <code>if (player.hasEquipment("EQ_TRUMBLE")) Log("Oh noes, I has a trumble!")</code>
-===awardCargo===
+=== <code>awardCargo</code> ===
- void awardCargo(cargoname, amount)
+ '''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.
-===removeAllCargo===
+=== <code>removeAllCargo</code> ===
- void removeAllCargo()
+ '''removeAllCargo'''()
 Removes all cargo from the ship’s cargo bay.
-===useSpecialCargo===
+=== <code>useSpecialCargo</code> ===
- void useSpecialCargo(description)
+ '''useSpecialCargo'''(description : String)
 Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.
-===launch===
+=== <code>launch</code> ===
- void launch()
+ '''launch'''()
 Launches the player’s ship if it is currently docked.