Oolite JavaScript Reference: Player (AI Readable Version)

### `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)`