Difference between revisions of "Oolite JavaScript Reference: Player"

Revision as of 12:27, 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

`alertAltitude`

alertAltitude : Boolean (read-only)

Whether the player is dangerously close to a planet.

`alertCondition`

alertCondition : Number (read-only, integer)

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

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

`alertMassLocked`

alertMassLocked : Boolean (read-only)

Whether the player is mass locked.

`alertTemperature`

alertTemperature : Boolean (read-only)

Whether the cabin temperature is dangerously high.

`credits`

credits : Number (read/write, integer)

The amount of money the player has.

`docked`

This property was added in Oolite test release 1.70.

docked : Boolean (read-only)

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

`dockedStation`

This property was added in Oolite test release 1.70.

dockedStation : Station (read-only)

The station with which the player is currently docked.

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

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

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

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

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

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

`launch`

launch()

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

`removeAllCargo`

removeAllCargo()

Removes all cargo from the ship’s cargo bay.

`removeEquipment`

removeEquipment(equipmentKey : String)

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

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

@@ Line 4: / Line 4: @@
 == Properties ==
-=== <code>name</code> ===
+=== <code>alertAltitude</code> ===
-  '''name''' : String (read-only)
+  '''alertAltitude''' : Boolean (read-only)
-The name of the player’s character (e.g., “Jameson”).
+Whether the player is dangerously close to a planet.
-=== <code>score</code> ===
- '''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''' : Number (read/write, integer)
-The amount of money the player has.
-=== <code>fuelLeakRate</code> ===
- '''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> ===
@@ Line 24: / Line 12: @@
 Returns the current alert condition. 0 = Docked, 1 = Green, 2 = Yellow, 3 = Red.
-=== <code>docked</code> ===
+=== <code>alertEnergy</code> ===
-  '''docked''' : Boolean (read-only)
+  '''alertEnergy''' : Boolean (read-only)
-True if the player is docked with a station or carrier.
+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>alertTemperature</code> ===
+=== <code>alertHostiles</code> ===
-  '''alertTemperature''' : Boolean (read-only)
+  '''alertHostiles''' : Boolean (read-only)
-Whether the cabin temperature is dangerously high.
+Whether there are hostile ships within scanner range.
 === <code>alertMassLocked</code> ===
@@ Line 36: / Line 24: @@
 Whether the player is mass locked.
-=== <code>alertAltitude</code> ===
+=== <code>alertTemperature</code> ===
-  '''alertAltitude''' : Boolean (read-only)
+  '''alertTemperature''' : Boolean (read-only)
-Whether the player is dangerously close to a planet.
+Whether the cabin temperature is dangerously high.
-=== <code>alertEnergy</code> ===
+=== <code>credits</code> ===
-  '''alertEnergy''' : Boolean (read-only)
+  '''credits''' : Number (read/write, integer)
-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>).
+The amount of money the player has.
-=== <code>alertHostiles</code> ===
+=== <code>docked</code> ===
-  '''alertHostiles''' : Boolean (read-only)
+{{Oolite-prop-added|1.70}}
-Whether there are hostile ships within scanner range.
+  '''docked''' : Boolean (read-only)
+True if the player is docked with a station or carrier.
 === <code>dockedStation</code> ===
+{{Oolite-prop-added|1.70}}
   '''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
 The station with which the player is currently docked.
+=== <code>fuelLeakRate</code> ===
+ '''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>name</code> ===
+ '''name''' : String (read-only)
+The name of the player’s character (e.g., “Jameson”).
+=== <code>score</code> ===
+ '''score''' : Number (read/write, integer)
+The player’s score; nominally the number of kills the player has made, although some missions award additional points.
 == Deprecated properties ==
@@ Line 60: / Line 62: @@
 == Methods ==
+=== <code>awardCargo</code> ===
+ '''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.
 === <code>awardEquipment</code> ===
   '''awardEquipment'''(equipmentKey : String)
@@ Line 71: / Line 77: @@
   '''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.
-=== <code>removeEquipment</code> ===
- '''removeEquipment'''(equipmentKey : String)
-Removes the given piece of equipment from the player’s ship. Example: <code>player.removeEquipment("EQ_TRUMBLE")</code>
 === <code>hasEquipment</code> ===
@@ Line 80: / Line 82: @@
 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>
-=== <code>awardCargo</code> ===
+=== <code>launch</code> ===
-  '''awardCargo'''(cargoname : String, amount : Number)
+  '''launch'''()
-Awards the given amount of the specified type of cargo. The cargo name must match the name in ''commodities.plist'' exactly.
+Launches the player’s ship if it is currently docked.
 === <code>removeAllCargo</code> ===
   '''removeAllCargo'''()
 Removes all cargo from the ship’s cargo bay.
+=== <code>removeEquipment</code> ===
+ '''removeEquipment'''(equipmentKey : String)
+Removes the given piece of equipment from the player’s ship. Example: <code>player.removeEquipment("EQ_TRUMBLE")</code>
 === <code>useSpecialCargo</code> ===
   '''useSpecialCargo'''(description : String)
 Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.
-=== <code>launch</code> ===
- '''launch'''()
-Launches the player’s ship if it is currently docked.
 [[Category:Oolite scripting]]