Difference between revisions of "Oolite JavaScript Reference: Player"

From Elite Wiki
m (Added Oolite scripting category.)
(Updating BB links)
 
(60 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
<small>'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code></small><br />
+
<small>'''Prototype:''' <code>Object</code></small><br />
 +
<small>'''Subtypes:''' none</small>
  
−
{{Oolite-class-added|1.70}}
+
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.
  
−
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>alertAltitude</code> ===
 +
'''alertAltitude''' : Boolean (read-only)
 +
Whether the player is dangerously close to a planet. (closer than 4000 meter to the surface)
 +
 
 +
=== <code>alertCondition</code> ===
 +
'''alertCondition''' : Number (read-only, integer)
 +
Returns the current alert condition. 0 = Docked, 1 = Green, 2 = Yellow, 3 = Red.
 +
 
 +
=== <code>alertEnergy</code> ===
 +
'''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''' : Boolean (read-only)
 +
Whether there are hostile ships within scanner range.
 +
 
 +
=== <code>alertMassLocked</code> ===
 +
'''alertMassLocked''' : Boolean (read-only)
 +
Whether the player is mass locked.
 +
 
 +
=== <code>alertTemperature</code> ===
 +
'''alertTemperature''' : Boolean (read-only)
 +
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>
  
−
== Properties ==
+
=== <code>contractReputation</code> ===
−
=== <code> name </code> ===
+
  '''contractReputation''' : Number (read-only integer)
−
  name [read-only string]
+
{{oolite-prop-added|1.79}}
−
The name of the player’s character (e.g., “Jameson”).
+
'''contractReputationPrecise''' : Number (read-only decimal)
 +
The player’s cargo contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards..
  
−
=== <code>score</code> ===
+
'''See also:''' <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#contracts|contracts]]</code>, <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>
−
score [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> ===
 
=== <code>credits</code> ===
−
  credits [read-write integer]
+
  '''credits''' : Number (read/write, float)
−
The amount of money the player has.
+
The amount of money the player has, in credits.
 +
 
 +
=== <code>dockingClearanceStatus</code> ===
 +
'''dockingClearanceStatus''' : String (read-only)
 +
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>escapePodRescueTime</code> ===
 +
{{oolite-prop-added|1.89}}
 +
'''escapePodRescueTime''' : Number (read/write decimal)
 +
Number of seconds that will be added to the clock when the player uses an escape pod and is rescued. Default value is 0 (zero), which will utilise the default time calculation that can add up to eight days to the clock.
 +
Negative numbers will be ignored (and default calculation will apply).
 +
 
 +
=== <code>legalStatus</code> ===
 +
'''legalStatus''' : String (read-only)
 +
A string mainly for display purposes describing the player’s legal status 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.<br>
 +
See [https://bb.oolite.space/viewtopic.php?p=30692#p30692 this] - and several later posts - for more detail. '''setLegalStatus: <number>''' works in legacy script - it might also work in Javascript! <br>
 +
See [[Bounty]] for a (partial?) list of OXPs affecting this.
  
−
=== <code>fuelLeakRate</code> ===
+
=== <code>name</code> ===
−
  fuelLeakRate [read-write double]
+
  '''name''' : String (read-only, read/write from 1.79)
−
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.
+
The name of the player’s character (e.g., <code>"Jameson"</code>). Prior to 1.79, this was also used as the filename for the savegame and so was not writable.
  
−
=== <code>alertCondition</code> ===
+
=== <code>parcelReputation</code> ===
−
  alertCondition [read-only integer]
+
{{oolite-prop-added|1.77}}
−
Returns the current alert condition. 0 = Docked, 1 = Green, 2 = Yellow, 3 = Red.
+
  '''parcelReputation''' : Number (read-only integer)
 +
{{oolite-prop-added|1.79}}
 +
'''parcelReputationPrecise''' : Number (read-only decimal)
 +
The player’s parcel contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.
  
−
=== <code>docked</code> ===
+
'''See also:''' <code>[[#decreaseParcelReputation|decreaseParcelReputation()]]</code>, <code>[[#increaseParcelReputation|increaseParcelReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#parcels|parcels]]</code>, <code>[[#contractReputation|contractReputation]]</code>, <code>[[#passengerReputation|passengerReputation]]</code>
−
docked [read-only boolean]
 
−
True if the player is docked with a station or carrier.
 
  
−
=== <code>alertTemperature</code> ===
+
=== <code>passengerReputation</code> ===
−
  alertTemperature [read-only boolean]
+
  '''passengerReputation''' : Number (read-only integer)
−
Whether the cabin temperature is dangerously high.
+
{{oolite-prop-added|1.79}}
 +
'''passengerReputationPrecise''' : Number (read-only decimal)
 +
The player’s passenger contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.
  
−
=== <code>alertMassLocked</code> ===
+
'''See also:''' <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengers|passengers]]</code>, <code>[[#contractReputation|contractReputation]]</code>, <code>[[#parcelReputation|parcelReputation]]</code>
−
alertMassLocked [read-only boolean]
 
−
Whether the player is mass locked.
 
  
−
=== <code>alertAltitude</code> ===
+
=== <code>rank</code> ===
−
  alertAltitude [read-only boolean]
+
  '''rank''' : String (read-only)
−
Whether the player is dangerously close to a planet.
+
A string mainly for display purposes describing the player’s rank (such as <code>"Mostly Harmless"</code> or <code>"Dangerous"</code>) based on <code>[[#score|score]]</code>. Note that it can be localized.
  
−
=== <code>alertEnergy</code> ===
+
=== <code>roleWeights</code> ===
−
  alertEnergy [read-only boolean]
+
{{oolite-prop-added|1.79}}
−
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>).
+
  '''roleWeights''' : Array (read-only)
 +
An array of the player's current role as perceived by the game. Generally NPCs will pick a random entry from this list and treat the player as if they were an NPC of that role. The '<code>player-unknown</code>' role is the default role. The size of the list depends on the player's current Elite ranking.
  
−
=== <code>alertHostiles</code> ===
+
'''See also:''' <code>[[#setPlayerRole|setPlayerRole()]]</code>
−
alertHostiles [read-only boolean]
 
−
Whether there are hostile ships within scanner range.
 
  
−
=== <code>dockedStation</code> ===
+
=== <code>score</code> ===
−
  dockedStation [read-only [[Oolite JavaScript Reference: Station|Station]]]
+
  '''score''' : Number (read/write, integer)
−
The station with which the player is currently docked.
+
The player’s score; nominally the number of kills the player has made, although some missions award additional points.
  
−
== Deprecated properties ==
+
=== <code>ship</code> ===
−
The following properties are deprecated as of Oolite 1.70, and will be removed before the next stable release:
+
'''ship''' : [[Oolite_JavaScript_Reference:_Ship | Ship]]
−
* '''<code>legalStatus</code>''': use <code>[[Oolite JavaScript Reference: Ship#bounty|bounty]]</code> instead.
+
The player’s ship
−
* '''<code>dockedStationName</code>''': use <code>[[#dockedStation|dockedStation]].[[Oolite JavaScript Reference: Ship#shipDescription|shipDescription]]</code> instead.
 
−
* '''<code>dockedAtMainStation</code>''': use <code>[[#dockedStation|dockedStation]].[[Oolite JavaScript Reference: Ship#isMainStation|isMainStation]]</code> instead.
 
  
 +
=== <code>trumbleCount</code> ===
 +
'''trumbleCount''' : Number (read-only nonnegative integer)
 +
The number of trumbles the player is currently blessed with.
  
 
== Methods ==
 
== Methods ==
−
===awardEquipment===
+
=== <code>addMessageToArrivalReport</code> ===
−
  void awardEquipment(equipmentKey)
+
  function '''addMessageToArrivalReport'''(message : String)
−
Adds the given piece of equipment to the player’s ship. Example: <code>player.awardEquipment("EQ_TRUMBLE")</code>
+
Adds a message to the arrival report shown immediately after docking. Oolite puts its own stuff on the list immediately after [[Oolite JavaScript Reference: World script event handlers#shipWillDockWithStation|shipWillDockWithStation]] so this is a good moment to add the messages when you know what station will be docked.  [[Oolite JavaScript Reference: World script event handlers#shipDockedWithStation|shipDockedWithStation]] may also be used.  Messages added while in flight or during shipWillDockWithStation will be above Oolite's own arrival messages.  Those added during shipDockedWithStation will be below Oolite's own arrival messages.
 +
 
 +
'''See also''': <code>[[Oolite JavaScript Reference: Station#suppressArrivalReports|station.suppressArrivalReports]]</code>, [https://bb.oolite.space/viewtopic.php?f=4&t=12519 Arrival Reports] (2012)
 +
 
 +
=== <code>commsMessage</code> ===
 +
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 <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.
  
−
=== commsMessage ===
+
'''Example:'''
−
'''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:
 
 
  player.commsMessage("Hello, cruel universe.", 6)
 
  player.commsMessage("Hello, cruel universe.", 6)
 +
NB, this <code>commsMessage()</code> is a method of the <code>player</code> object.  <code>player.ship</code> can also have a <code>[[Oolite_JavaScript_Reference:_Ship#commsMessage|commsMessage()]]</code> method, but that belongs to the ship and has a different second parameter.
 +
*[https://bb.oolite.space/viewtopic.php?f=4&t=10880 Formatting text msgs on a HUD] (2011)
  
−
=== consoleMessage ===
+
=== <code>consoleMessage</code> ===
−
  '''consoleMessage'''(message : String [, duration: Number])
+
  function '''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.
 
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===
+
'''See also''': [https://bb.oolite.space/viewtopic.php?f=4&t=10880 Formatting text msgs on a HUD] (2011)
−
  void removeEquipment(equipmentKey)
+
 
−
Removes the given piece of equipment from the player’s ship. Example: <code>player.removeEquipment("EQ_TRUMBLE")</code>
+
=== <code>decreaseContractReputation</code> ===
 +
function '''decreaseContractReputation'''()
 +
Give the player a negative reputation point for cargo contracts. Decreases the underlying value for contractReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.
 +
 
 +
'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#increaseContractReputation|increaseContractReputation()]]</code>
 +
 
 +
=== <code>decreaseParcelReputation</code> ===
 +
{{oolite-method-added|1.77}}
 +
function '''decreaseParcelReputation'''()
 +
Give the player a negative reputation point for parcel contracts. Decreases the underlying value for parcelReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.
 +
 
 +
'''See also:''' <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#increaseParcelReputation|increaseParcelReputation()]]</code>
 +
 
 +
=== <code>decreasePassengerReputation</code> ===
 +
function '''decreasePassengerReputation'''()
 +
Give the player a negative reputation point for passenger contracts. Decreases the underlying value for passengerReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.
 +
 
 +
'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#increasePassengerReputation|increasePassengerReputation()]]</code>
 +
 
 +
=== <code>endScenario</code> ===
 +
{{oolite-method-added|1.79}}
 +
function '''endScenario'''(key : String) : Boolean
 +
End the current game immediately and return to the start game screen. Returns <code>true</code> if it succeeds (though this will shortly be irrelevant) or <code>false</code> if it fails, which it will do if the key passed in is not the same as the [[scenarios.plist#scenario|scenario key]] in the current game scenario. If the current game scenario has no scenario key, this method will always fail.
 +
 
 +
There is no way to find out what, if any, the current scenario key is. If you are calling this method, you should be doing so in a context where you already know what it is.
 +
 
 +
=== <code>increaseContractReputation</code> ===
 +
function '''increaseContractReputation'''()
 +
Give the player a positive reputation point for cargo contracts. Increases the underlying value for contractReputation by 1 until a maximum of 7
 +
 
 +
'''See also:''' <code>[[#contractReputation|contractReputation]]</code>, <code>[[#decreaseContractReputation|decreaseContractReputation()]]</code>
 +
 
 +
=== <code>increaseParcelReputation</code> ===
 +
{{oolite-method-added|1.77}}
 +
function '''increaseParcelReputation'''()
 +
Give the player a positive reputation point for parcel contracts. Increases the underlying value for parcelReputation by 1 until a maximum of 7
 +
 
 +
'''See also:''' <code>[[#parcelReputation|parcelReputation]]</code>, <code>[[#decreaseParcelReputation|decreaseParcelReputation()]]</code>
 +
 
 +
=== <code>increasePassengerReputation</code> ===
 +
function '''increasePassengerReputation'''()
 +
Give the player a positive reputation point for passenger contracts. Increases the underlying value for passengerReputation by 1 until a maximum of 7
 +
 
 +
'''See also:''' <code>[[#passengerReputation|passengerReputation]]</code>, <code>[[#decreasePassengerReputation|decreasePassengerReputation()]]</code>
 +
 
 +
=== <code>setEscapePodDestination</code> ===
 +
  function '''setEscapePodDestination'''(destination)
 +
This method can only be called after the player has launched an escape pod – mainly from the [[Oolite_JavaScript_Reference:_World_script_event_handlers#escapePodSequenceOver|<code>escapePodSequenceOver</code>]] event handler. It determines where the player will end up. The <code>destination</code> parameter may be any station/carrier, the string <code>"NEARBY_SYSTEM"</code> or <code>null</code>. If it is <code>"NEARBY_SYSTEM"</code>, the player will end up at the main station in a random nearby system. If it is <code>null</code> (which is the default in interstellar space), the player will die of life support failure.
 +
 
 +
=== <code>setPlayerRole</code> ===
 +
{{oolite-method-added|1.79}}
 +
function '''setPlayerRole'''(role [,index])
 +
Sets one of the player's perceived role entries to the specified role. If index is not specified, a random entry will be chosen.
 +
 
 +
'''See also:''' <code>[[#roleWeights|roleWeights]]</code>
 +
 
 +
=== <code>replaceShip</code> ===
 +
{{Oolite-method-added|1.77}}
 +
function '''replaceShip'''(dataKey [, personality])
 +
This method can only be called while the player is docked at a station. It discards the player's current ship (including all cargo, passenger contracts, and equipment), and replaces it with the ship defined by the shipyard.plist entry <code>dataKey</code> (obviously the key must also be defined in shipyard.plist as a valid player ship). The new ship will have all standard equipment for a ship of that type, and any equipment from the previous ship which was [[Oolite JavaScript Reference: EquipmentInfo#isPortableBetweenShips|isPortableBetweenShips]]. While this may not necessarily be a ship purchase, the [[Oolite JavaScript Reference: World script event handlers#playerBoughtNewShip|playerBoughtNewShip]] will fire to notify other scripts of the change, although this event is being deprecated in favour of [[Oolite JavaScript Reference: World script event handlers#playerReplacedShip|playerReplacedShip]], which was added in Oolite Test Release 1.89.
 +
 
 +
If the dataKey was not defined in both shipdata.plist and shipyard.plist, or the player is in flight, this method does nothing.
 +
 
 +
<code>personality</code> is optional, and can be between 0 and 32767. The new ship is given that specific [[Oolite_JavaScript_Reference:_Ship#entityPersonality|entityPersonality]], which for some ships may affect its appearance with shaders.
 +
 
 +
== Some OXP items ==
 +
=== <code>missionVariables.random_hits_criminal_hate_score</code> ===
 +
Added by [[Random Hits OXP]] - seems to be (to this dumb pilot) a measure of the extent to which criminals wish to attack the player
 +
:if (hate < 5) rank = "an innocent fighter"
 +
:else if (hate < 25) rank = "an annoyance"
 +
:else if (hate < 50) rank = "a "+expandDescription("[random_hits_notwelcome_para3e]")+" pilot"
 +
:else if (hate < 70) rank = "a target that must be "+expandDescription("[random_hits_complete2]")
 +
:else if (hate < 90) rank = "on their top ten hit list of "+expandDescription("[random_hits_notwelcome_para3e]")+" pilots"
 +
 
 +
=== <code>_litf.LITF_cmdStats.health</code> ===
 +
Added by [[Life in the Frontier]] - a health rating (wounds, bruises ''etc''.)
 +
 
 +
=== <code>_litf.LITF_cmdStats.sickness</code> ===
 +
Added by [[Life in the Frontier]] - a sickness rating
 +
 
 +
=== <code>_litf.LITF_cmdStats.strength</code> ===
 +
Added by [[Life in the Frontier]] - a strength rating (physical shape, fitness)
  
−
===hasEquipment===
+
=== <code>_litf.LITF_cmdStats.reputation</code> ===
−
boolean hasEquipment(equipmentKey)
+
Added by [[Life in the Frontier]] - a reputation rating (from unknown to legendary)
−
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>_litf.LITF_cmdStats.stance</code> ===
−
void awardCargo(cargoname, amount)
+
Added by [[Life in the Frontier]] - a political rating
−
Awards the given amount of the specified type of cargo. The cargo name must match the name in ''commodities.plist'' exactly.
 
  
−
===removeAllCargo===
+
:if (sta == 0) { desc = "absolutely neutral"; }
−
void removeAllCargo()
+
:if (sta < 5 && sta > -5) { desc = "generally neutral"; }
−
Removes all cargo from the ship’s cargo bay.
 
  
−
===useSpecialCargo===
+
:if (sta >= 5) { desc = "sympathetic with GalCop"; }
−
void useSpecialCargo(description)
+
:if (sta >= 25) { desc = "friendly with GalCop"; }
−
Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.
+
:if (sta >= 75) { desc = "loyal with GalCop"; }
 +
:if (sta >= 200) { desc = "sworn to act along the rules of GalCop"; }
  
−
===launch===
+
:if (sta <= -5) { desc = "sympathetic with criminals"; }
−
void launch()
+
:if (sta <= -25) { desc = "friendly with criminals"; }
−
Launches the player’s ship if it is currently docked.
+
:if (sta <= -75) { desc = "loyal with criminals"; }
 +
:if (sta <= -200) { desc = "respectful of the laws of the criminal underworld";
  
−
[[Category:Oolite scripting]]
+
[[Category:Oolite JavaScript Reference]]

Latest revision as of 02:19, 29 February 2024

Prototype: Object
Subtypes: none

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. (closer than 4000 meter to the surface)

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

contractReputation : Number (read-only integer)

This property was added in Oolite test release 1.79. 

contractReputationPrecise : Number (read-only decimal)

The player’s cargo contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards..

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

credits

credits : Number (read/write, float)

The amount of money the player has, in credits.

dockingClearanceStatus

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"

escapePodRescueTime

This property was added in Oolite test release 1.89. 

escapePodRescueTime : Number (read/write decimal)

Number of seconds that will be added to the clock when the player uses an escape pod and is rescued. Default value is 0 (zero), which will utilise the default time calculation that can add up to eight days to the clock. Negative numbers will be ignored (and default calculation will apply).

legalStatus

legalStatus : String (read-only)

A string mainly for display purposes describing the player’s legal status 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.
See this - and several later posts - for more detail. setLegalStatus: <number> works in legacy script - it might also work in Javascript!
See Bounty for a (partial?) list of OXPs affecting this.

name

name : String (read-only, read/write from 1.79)

The name of the player’s character (e.g., "Jameson"). Prior to 1.79, this was also used as the filename for the savegame and so was not writable.

parcelReputation

This property was added in Oolite test release 1.77. 

parcelReputation : Number (read-only integer)

This property was added in Oolite test release 1.79. 

parcelReputationPrecise : Number (read-only decimal)

The player’s parcel contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.

See also: decreaseParcelReputation(), increaseParcelReputation(), parcels, contractReputation, passengerReputation

passengerReputation

passengerReputation : Number (read-only integer)

This property was added in Oolite test release 1.79. 

passengerReputationPrecise : Number (read-only decimal)

The player’s passenger contract reputation, ranging from -7 to +7. Reputation is made up internally of three components - "good", "bad", and "unknown". "good" and "bad" will decay back to "unknown" slowly over time, while "unknown" may in some systems (randomised on entry) be partially treated as "good", to represent imperfect knowledge of the player's reputation. The value reported by these properties is the final value after this randomisation is applied. The "Precise" version includes fractional reputation, used in Oolite 1.79 onwards.

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

rank

rank : String (read-only)

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

roleWeights

This property was added in Oolite test release 1.79. 

roleWeights : Array (read-only)

An array of the player's current role as perceived by the game. Generally NPCs will pick a random entry from this list and treat the player as if they were an NPC of that role. The 'player-unknown' role is the default role. The size of the list depends on the player's current Elite ranking.

See also: setPlayerRole()

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.

ship

ship :  Ship

The player’s ship

trumbleCount

trumbleCount : Number (read-only nonnegative integer)

The number of trumbles the player is currently blessed with.

Methods

addMessageToArrivalReport

function addMessageToArrivalReport(message : String)

Adds a message to the arrival report shown immediately after docking. Oolite puts its own stuff on the list immediately after shipWillDockWithStation so this is a good moment to add the messages when you know what station will be docked. shipDockedWithStation may also be used. Messages added while in flight or during shipWillDockWithStation will be above Oolite's own arrival messages. Those added during shipDockedWithStation will be below Oolite's own arrival messages.

See also: station.suppressArrivalReports, Arrival Reports (2012)

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)

NB, this commsMessage() is a method of the player object. player.ship can also have a commsMessage() method, but that belongs to the ship and has a different second parameter.

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.

See also: Formatting text msgs on a HUD (2011)

decreaseContractReputation

function decreaseContractReputation()

Give the player a negative reputation point for cargo contracts. Decreases the underlying value for contractReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

See also: contractReputation, increaseContractReputation()

decreaseParcelReputation

This method was added in Oolite test release 1.77. 

function decreaseParcelReputation()

Give the player a negative reputation point for parcel contracts. Decreases the underlying value for parcelReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

See also: parcelReputation, increaseParcelReputation()

decreasePassengerReputation

function decreasePassengerReputation()

Give the player a negative reputation point for passenger contracts. Decreases the underlying value for passengerReputation by 1 until a minimum of -7. Depending on the randomised part of the value can the visible value stay the same in one system.

See also: passengerReputation, increasePassengerReputation()

endScenario

This method was added in Oolite test release 1.79. 

function endScenario(key : String) : Boolean

End the current game immediately and return to the start game screen. Returns true if it succeeds (though this will shortly be irrelevant) or false if it fails, which it will do if the key passed in is not the same as the scenario key in the current game scenario. If the current game scenario has no scenario key, this method will always fail.

There is no way to find out what, if any, the current scenario key is. If you are calling this method, you should be doing so in a context where you already know what it is.

increaseContractReputation

function increaseContractReputation()

Give the player a positive reputation point for cargo contracts. Increases the underlying value for contractReputation by 1 until a maximum of 7

See also: contractReputation, decreaseContractReputation()

increaseParcelReputation

This method was added in Oolite test release 1.77. 

function increaseParcelReputation()

Give the player a positive reputation point for parcel contracts. Increases the underlying value for parcelReputation by 1 until a maximum of 7

See also: parcelReputation, decreaseParcelReputation()

increasePassengerReputation

function increasePassengerReputation()

Give the player a positive reputation point for passenger contracts. Increases the underlying value for passengerReputation by 1 until a maximum of 7

See also: passengerReputation, decreasePassengerReputation()

setEscapePodDestination

function setEscapePodDestination(destination)

This method can only be called after the player has launched an escape pod – mainly from the escapePodSequenceOver event handler. It determines where the player will end up. The destination parameter may be any station/carrier, the string "NEARBY_SYSTEM" or null. If it is "NEARBY_SYSTEM", the player will end up at the main station in a random nearby system. If it is null (which is the default in interstellar space), the player will die of life support failure.

setPlayerRole

This method was added in Oolite test release 1.79. 

function setPlayerRole(role [,index])

Sets one of the player's perceived role entries to the specified role. If index is not specified, a random entry will be chosen.

See also: roleWeights

replaceShip

This method was added in Oolite test release 1.77. 

function replaceShip(dataKey [, personality])

This method can only be called while the player is docked at a station. It discards the player's current ship (including all cargo, passenger contracts, and equipment), and replaces it with the ship defined by the shipyard.plist entry dataKey (obviously the key must also be defined in shipyard.plist as a valid player ship). The new ship will have all standard equipment for a ship of that type, and any equipment from the previous ship which was isPortableBetweenShips. While this may not necessarily be a ship purchase, the playerBoughtNewShip will fire to notify other scripts of the change, although this event is being deprecated in favour of playerReplacedShip, which was added in Oolite Test Release 1.89.

If the dataKey was not defined in both shipdata.plist and shipyard.plist, or the player is in flight, this method does nothing.

personality is optional, and can be between 0 and 32767. The new ship is given that specific entityPersonality, which for some ships may affect its appearance with shaders.

Some OXP items

missionVariables.random_hits_criminal_hate_score

Added by Random Hits OXP - seems to be (to this dumb pilot) a measure of the extent to which criminals wish to attack the player

if (hate < 5) rank = "an innocent fighter"
else if (hate < 25) rank = "an annoyance"
else if (hate < 50) rank = "a "+expandDescription("[random_hits_notwelcome_para3e]")+" pilot"
else if (hate < 70) rank = "a target that must be "+expandDescription("[random_hits_complete2]")
else if (hate < 90) rank = "on their top ten hit list of "+expandDescription("[random_hits_notwelcome_para3e]")+" pilots"

_litf.LITF_cmdStats.health

Added by Life in the Frontier - a health rating (wounds, bruises etc.)

_litf.LITF_cmdStats.sickness

Added by Life in the Frontier - a sickness rating

_litf.LITF_cmdStats.strength

Added by Life in the Frontier - a strength rating (physical shape, fitness)

_litf.LITF_cmdStats.reputation

Added by Life in the Frontier - a reputation rating (from unknown to legendary)

_litf.LITF_cmdStats.stance

Added by Life in the Frontier - a political rating

if (sta == 0) { desc = "absolutely neutral"; }
if (sta < 5 && sta > -5) { desc = "generally neutral"; }
if (sta >= 5) { desc = "sympathetic with GalCop"; }
if (sta >= 25) { desc = "friendly with GalCop"; }
if (sta >= 75) { desc = "loyal with GalCop"; }
if (sta >= 200) { desc = "sworn to act along the rules of GalCop"; }
if (sta <= -5) { desc = "sympathetic with criminals"; }
if (sta <= -25) { desc = "friendly with criminals"; }
if (sta <= -75) { desc = "loyal with criminals"; }
if (sta <= -200) { desc = "respectful of the laws of the criminal underworld";
Retrieved from "https://wiki.alioth.net/index.php?title=Oolite_JavaScript_Reference:_Player&oldid=82082"