Difference between revisions of "Oolite JavaScript Reference: Player"

From Elite Wiki
m (→‎<code>setEquipmentStatus</code>)
(Updating Oolite scripting documentation for 1.73.)
Line 1: Line 1:
−
<small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code></small><br />
 +
<small>'''Prototype:''' <code>Object</code></small>
   
−
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.
 +
The '''<code>Player</code>''' class is represents the player. There is always exactly one <code>Player</code> object in existence, which can be accessed through the <code>player</code> global property.
   
 
== Properties ==
  
== Properties ==
Line 27: Line 27:
 
'''alertTemperature''' : Boolean (read-only)
  
'''alertTemperature''' : Boolean (read-only)
 
Whether the cabin temperature is dangerously high.
  
Whether the cabin temperature is dangerously high.
  +
  +
=== <code>bounty</code> ===
  +
'''bounty''' : Number (read/write integer)
  +
The bounty on the player, which determines legal status. It is halved at each witchspace jump.
  +
  +
'''See also''': <code>[[#legalStatus|legalStatus]]
  +
  +
=== <code>contractReputation</code> ===
  +
{{Oolite-prop-added|1.72}}
  +
'''contractReputation''' : Number (read-only integer)
  +
The player’s cargo contract reputation, ranging from -7 to +7.
  +
  +
'''See also:''' <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>
   
 
=== <code>credits</code> ===
  
=== <code>credits</code> ===
Line 32: Line 45:
 
The amount of money the player has.
  
The amount of money the player has.
   
−
=== <code>docked</code> ===
 +
=== <code>dockingClearanceStatus</code> ===
−
{{Oolite-prop-added|1.70}}
 +
{{Oolite-prop-added|1.72}}
−
'''docked''' : Boolean (read-only)
 +
'''dockingClearanceStatus''' : String (read-only)
−
True if the player is docked with a station or carrier.
 +
A string indicating whether the player has docking clearance. (''Clarify: for which station? -[[User:Ahruman|Ahruman]] 20:34, 3 November 2008 (UTC)'') Possible values are:
  +
* <code>"DOCKING_CLEARANCE_STATUS_NONE"</code>
  +
* <code>"DOCKING_CLEARANCE_STATUS_REQUESTED"</code>
  +
* <code>"DOCKING_CLEARANCE_STATUS_NOT_REQUIRED"</code>
  +
* <code>"DOCKING_CLEARANCE_STATUS_GRANTED"</code>
  +
* <code>"DOCKING_CLEARANCE_STATUS_TIMING_OUT"</code>
   
−
=== <code>dockedStation</code> ===
 +
=== <code>legalStatus</code> ===
−
{{Oolite-prop-added|1.70}}
 +
{{Oolite-prop-added|1.72}}
−
'''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
 +
'''legalStatus''' : String (read-only)
−
The station with which the player is currently docked.
 +
A string describing the player’s legal status for display purposes, based on <code>[[#bounty|bounty]]</code>. In English, this is one of <code>"Clean"</code> (bounty = 0), <code>"Offender"</code> (0 < bounty ≤ 50) or <code>"Fugitive"</code>, but note that it can be localized.
−  
−
=== <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> ===
  
=== <code>name</code> ===
 
'''name''' : String (read-only)
  
'''name''' : String (read-only)
 
The name of the player’s character (e.g., “Jameson”).
  
The name of the player’s character (e.g., “Jameson”).
  +
  +
=== <code>passengerReputation</code> ===
  +
{{Oolite-prop-added|1.72}}
  +
'''passengerReputation''' : Number (read-only integer)
  +
The player’s passenger contract reputation, ranging from -7 to +7.
  +
  +
'''See also:''' <code>[[#contractReputation|contractReputation()]]</code>, <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>
  +
  +
=== <code>rank</code> ===
  +
{{Oolite-prop-added|1.72}}
  +
'''rank''' : String (read-only)
  +
A string describing the player’s rank for display purposes, based on <code>[[#score|score]]</code>, such as <code>"Mostly Harmless"</code> or <code>"Dangerous"</code>. Note that it can be localized.
   
 
=== <code>score</code> ===
  
=== <code>score</code> ===
Line 50: Line 75:
 
The player’s score; nominally the number of kills the player has made, although some missions award additional points.
  
The player’s score; nominally the number of kills the player has made, although some missions award additional points.
   
−
=== <code>specialCargo</code> ===
 +
=== <code>trumbleCount</code> ===
−
{{Oolite-prop-future|1.72}}
 +
{{Oolite-prop-added|1.71}}
−
'''specialCargo''' : String (read-only)
 +
'''trumbleCount''' : Number (read-only nonnegative integer)
−
The special cargo the player is carrying, if any; otherwise <code>null</code>.
 +
The number of trumbles the player is currently blessed with.
−  
−
'''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code>
  
   
   
 
== Methods ==
  
== Methods ==
−
=== <code>awardCargo</code> ===
  
−
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.
  
−  
−
=== <code>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</code> ===
  
−
{{Oolite-method-future|1.72}}
  
−
function '''canAwardCargo'''(cargoName : String, amount : Number) : Boolean
  
−
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.
  
−  
−
'''See also:''' <code>[[#awardCargo|awardCargo]]()</code>
  
−  
 
=== <code>commsMessage</code> ===
  
=== <code>commsMessage</code> ===
 
function '''commsMessage'''(message : String [, duration: Number])
  
function '''commsMessage'''(message : String [, duration: Number])
Line 80: Line 90:
 
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.
  
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>hasEquipment</code> ===
 +
=== <code>decreaseContractReputation</code> ===
−
function '''hasEquipment'''(equipmentKey : String) : Boolean
 +
function '''decreaseContractReputation'''()
−
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>
 +
Give the player a negative reputation point for cargo contracts.
  +
  +
'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>
   
−
=== <code>launch</code> ===
 +
=== <code>decreasePassengerReputation</code> ===
−
function '''launch'''()
 +
function '''decreasePassengerReputation'''()
−
Launches the player’s ship if it is currently docked.
 +
Give the player a negative reputation point for passenger contracts.
   
−
=== <code>removeAllCargo</code> ===
  
  +
'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>
−
function '''removeAllCargo'''()
  
−
Removes all cargo from the ship’s cargo bay.
  
   
−
=== <code>removeEquipment</code> ===
 +
=== <code>increaseContractReputation</code> ===
−
function '''removeEquipment'''(equipmentKey : String)
 +
function '''increaseContractReputation'''()
−
Removes the given piece of equipment from the player’s ship. Example: <code>player.removeEquipment("EQ_TRUMBLE")</code>
 +
Give the player a positive reputation point for cargo contracts.
   
−
=== <code>setEquipmentStatus</code> ===
  
  +
'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#decreaseContractReputation|decreaseContractReputation()]]</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 '''EQUIPMENT_DAMAGED''' and '''EQUIPMENT_OK'''. (New in 1.71)
  
   
−
=== <code>useSpecialCargo</code> ===
 +
=== <code>increasePassengerReputation</code> ===
−
function '''useSpecialCargo'''(description : String)
 +
function '''increasePassengerReputation'''()
−
Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.
 +
Give the player a positive reputation point for passenger contracts.
   
−
'''See also''': <code>[[#specialCargo|specialCargo]]</code>
  
  +
'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>
   
 
[[Category:Oolite scripting]]
  
[[Category:Oolite scripting]]

Revision as of 21:34, 3 November 2008

Prototype: Object

The Player class is represents the player. 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.

bounty

bounty : Number (read/write integer)

The bounty on the player, which determines legal status. It is halved at each witchspace jump.

See also: legalStatus

contractReputation

This property was added in Oolite test release 1.72. 

contractReputation : Number (read-only integer)

The player’s cargo contract reputation, ranging from -7 to +7.

See also: decreaseContractReputation(), increaseContractReputation(), passengerReputation

credits

credits : Number (read/write, integer)

The amount of money the player has.

dockingClearanceStatus

This property was added in Oolite test release 1.72. 

dockingClearanceStatus : String (read-only)

A string indicating whether the player has docking clearance. (Clarify: for which station? -Ahruman 20:34, 3 November 2008 (UTC)) Possible values are:

  • "DOCKING_CLEARANCE_STATUS_NONE"
  • "DOCKING_CLEARANCE_STATUS_REQUESTED"
  • "DOCKING_CLEARANCE_STATUS_NOT_REQUIRED"
  • "DOCKING_CLEARANCE_STATUS_GRANTED"
  • "DOCKING_CLEARANCE_STATUS_TIMING_OUT"

legalStatus

This property was added in Oolite test release 1.72. 

legalStatus : String (read-only)

A string describing the player’s legal status for display purposes, based on bounty. In English, this is one of "Clean" (bounty = 0), "Offender" (0 < bounty ≤ 50) or "Fugitive", but note that it can be localized.

name

name : String (read-only)

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

passengerReputation

This property was added in Oolite test release 1.72. 

passengerReputation : Number (read-only integer)

The player’s passenger contract reputation, ranging from -7 to +7.

See also: contractReputation(), decreasePassengerReputation(), increasePassengerReputation()

rank

This property was added in Oolite test release 1.72. 

rank : String (read-only)

A string describing the player’s rank for display purposes, based on score, such as "Mostly Harmless" or "Dangerous". Note that it can be localized.

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.

trumbleCount

This property was added in Oolite test release 1.71. 

trumbleCount : Number (read-only nonnegative integer)

The number of trumbles the player is currently blessed with.


Methods

commsMessage

function 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

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

decreaseContractReputation

function decreaseContractReputation()

Give the player a negative reputation point for cargo contracts.

See also: contractReputation, increaseContractReputation()

decreasePassengerReputation

function decreasePassengerReputation()

Give the player a negative reputation point for passenger contracts.

See also: passengerReputation, increasePassengerReputation()

increaseContractReputation

function increaseContractReputation()

Give the player a positive reputation point for cargo contracts.

See also: contractReputation, decreaseContractReputation()

increasePassengerReputation

function increasePassengerReputation()

Give the player a positive reputation point for passenger contracts.

See also: passengerReputation, decreasePassengerReputation()

Retrieved from "http://backup.witchspacewiki.org/index.php?title=Oolite_JavaScript_Reference:_Player&oldid=11692"