Oolite JavaScript Reference: Player (AI Readable Version) - Revision history

Wildeblood: Old c.i.w.a.s proverb: 'Whitespace is free.' ;-)

2025-07-27T17:15:36Z

Old c.i.w.a.s proverb: 'Whitespace is free.' ;-)

Wildeblood: Formatted with markdown, not wiki markup; please do not "fix". Do not add extraneous commentary. Do not add outward links.

2025-07-27T05:10:21Z

Formatted with markdown, not wiki markup; please do not "fix". Do not add extraneous commentary. Do not add outward links.

New page

<pre>

***

### `player` (Global Object)

* **Description:** Represents the player character. There is always exactly one `player` object in existence, accessible globally.

#### Properties

* `.alertAltitude` (Boolean, Read-only): `true` if the player is dangerously close to a planet's surface (less than 4000m).
* `.alertCondition` (Number, Read-only): The current alert condition.
* `0`: Docked
* `1`: Green
* `2`: Yellow
* `3`: Red
* `.alertEnergy` (Boolean, Read-only): `true` if the player’s energy is less than their ship's `maxEnergy`.
* `.alertHostiles` (Boolean, Read-only): `true` if there are hostile ships within scanner range.
* `.alertMassLocked` (Boolean, Read-only): `true` if the player is currently mass locked.
* `.alertTemperature` (Boolean, Read-only): `true` if the cabin temperature is dangerously high.
* `.bounty` (Number, Read/Write): The bounty on the player in whole numbers. This value determines `legalStatus` and is halved at each witchspace jump.
* `.contractReputation` (Number, Read-only): Integer part of the player’s cargo contract reputation, from -7 to +7.
* `.contractReputationPrecise` (Number, Read-only): Decimal version of the player’s cargo contract reputation.
* `.credits` (Number, Read/Write): The amount of money the player has, in Credits.
* `.dockingClearanceStatus` (String, Read-only): The player's current docking clearance status. 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` (Number, Read/Write): Seconds added to the clock upon escape pod rescue. A value of `0` uses the default calculation (up to 8 days).
* `.legalStatus` (String, Read-only): A display string for the player's legal status (e.g., "Clean", "Offender", "Fugitive"), based on `.bounty`. The text is localizable.
* `.name` (String, Read/Write): The player's character name (e.g., "Jameson").
* `.parcelReputation` (Number, Read-only): Integer part of the player’s parcel delivery reputation, from -7 to +7.
* `.parcelReputationPrecise` (Number, Read-only): Decimal version of the player’s parcel delivery reputation.
* `.passengerReputation` (Number, Read-only): Integer part of the player’s passenger transport reputation, from -7 to +7.
* `.passengerReputationPrecise` (Number, Read-only): Decimal version of the player’s passenger transport reputation.
* `.rank` (String, Read-only): A display string for the player’s rank (e.g., "Mostly Harmless"), based on `.score`. The text is localizable.
* `.roleWeights` (Array, Read-only): An array of the player's current roles as perceived by NPCs (e.g., 'player-unknown', 'trader').
* `.score` (Number, Read/Write): The player's score (kill count), which determines `.rank`.
* `.ship` (Ship): A reference to the player's current ship object.
* `.trumbleCount` (Number, Read-only): The number of trumbles currently on the player's ship.

#### Methods

* `addMessageToArrivalReport(message)`
* **Description:** Adds a string message to the arrival report screen shown after docking. Call during `shipWillDockWithStation` to place messages *above* Oolite's standard messages, or during `shipDockedWithStation` to place them *below*.
* **Signature:** `(message: String)`
* `commsMessage(message, duration)`
* **Description:** Displays a message in the comms log and on the player's HUD. The optional duration (1-10 seconds) controls how long it stays on the HUD. Defaults to 4.5 seconds.
* **Signature:** `(message: String, duration?: Number)`
* `consoleMessage(message, duration)`
* **Description:** Displays a message on the player's HUD. The optional duration (1-10 seconds) controls how long it stays on the HUD. Defaults to 3 seconds.
* **Signature:** `(message: String, duration?: Number)`
* `decreaseContractReputation()` / `increaseContractReputation()`
* **Description:** Adjusts the player's underlying cargo contract reputation by 1, clamped to the range [-7, 7].
* **Signature:** `()`
* `decreaseParcelReputation()` / `increaseParcelReputation()`
* **Description:** Adjusts the player's underlying parcel reputation by 1, clamped to the range [-7, 7].
* **Signature:** `()`
* `decreasePassengerReputation()` / `increasePassengerReputation()`
* **Description:** Adjusts the player's underlying passenger reputation by 1, clamped to the range [-7, 7].
* **Signature:** `()`
* `endScenario(key)`
* **Description:** Immediately ends the current game if it is a scenario game and the provided `key` matches the scenario's secret key. Returns `true` on success, `false` otherwise. There is no way to read the scenario key from a script.
* **Signature:** `(key: String): Boolean`
* `replaceShip(dataKey, personality)`
* **Description:** Replaces the player's current ship with a new one from `shipyard.plist`. This can only be called while docked. All cargo and non-portable equipment is lost. Fires the `playerReplacedShip` event.
* **Signature:** `(dataKey: String, personality?: Number)`
* `setEscapePodDestination(destination)`
* **Description:** Sets the player's destination after using an escape pod. Must be called from the `escapePodSequenceOver` event handler.
* **Signature:** `(destination: Station | String | null)` where String can be `"NEARBY_SYSTEM"`.
* `setPlayerRole(role, index)`
* **Description:** Sets one of the player's perceived roles. If `index` is omitted, a random role entry is changed.
* **Signature:** `(role: String, index?: Number)`

***

</pre>

@@ Line 1: / Line 1: @@
 <pre>
 ### `player` (Global Object)
@@ Line 42: / Line 41: @@
      * **Description:** Adds a string message to the arrival report screen shown after docking. Call during `shipWillDockWithStation` to place messages *above* Oolite's standard messages, or during `shipDockedWithStation` to place them *below*.
      * **Signature:** `(message: String)`
 * `commsMessage(message, duration)`
      * **Description:** Displays a message in the comms log and on the player's HUD. The optional duration (1-10 seconds) controls how long it stays on the HUD. Defaults to 4.5 seconds.
      * **Signature:** `(message: String, duration?: Number)`
 * `consoleMessage(message, duration)`
      * **Description:** Displays a message on the player's HUD. The optional duration (1-10 seconds) controls how long it stays on the HUD. Defaults to 3 seconds.
      * **Signature:** `(message: String, duration?: Number)`
 * `decreaseContractReputation()` / `increaseContractReputation()`
      * **Description:** Adjusts the player's underlying cargo contract reputation by 1, clamped to the range [-7, 7].
      * **Signature:** `()`
 * `decreaseParcelReputation()` / `increaseParcelReputation()`
      * **Description:** Adjusts the player's underlying parcel reputation by 1, clamped to the range [-7, 7].
      * **Signature:** `()`
 * `decreasePassengerReputation()` / `increasePassengerReputation()`
      * **Description:** Adjusts the player's underlying passenger reputation by 1, clamped to the range [-7, 7].
      * **Signature:** `()`
 * `endScenario(key)`
      * **Description:** Immediately ends the current game if it is a scenario game and the provided `key` matches the scenario's secret key. Returns `true` on success, `false` otherwise. There is no way to read the scenario key from a script.
      * **Signature:** `(key: String): Boolean`
 * `replaceShip(dataKey, personality)`
      * **Description:** Replaces the player's current ship with a new one from `shipyard.plist`. This can only be called while docked. All cargo and non-portable equipment is lost. Fires the `playerReplacedShip` event.
      * **Signature:** `(dataKey: String, personality?: Number)`
 * `setEscapePodDestination(destination)`
      * **Description:** Sets the player's destination after using an escape pod. Must be called from the `escapePodSequenceOver` event handler.
      * **Signature:** `(destination: Station | String | null)` where String can be `"NEARBY_SYSTEM"`.
 * `setPlayerRole(role, index)`
      * **Description:** Sets one of the player's perceived roles. If `index` is omitted, a random role entry is changed.
      * **Signature:** `(role: String, index?: Number)`
 </pre>