Elite Wiki - User contributions [en]

Oolite JavaScript Reference: PlayerShip

2016-04-29T10:28:01Z

Kanthoney: /* hyperspaceSpinTime */ Add infoSystem property

'''Prototype:''' <code>[[Oolite JavaScript Reference: Ship|Ship]]</code> 
'''Subtypes:''' none

The '''<code>PlayerShip</code>''' class is an <code>[[Oolite JavaScript Reference: Entity|Entity]]</code> representing the player’s ship. The <code>PlayerShip</code> has all the properties and methods of a <code> [[Oolite JavaScript Reference: Ship|Ship]]</code>, and several others. There is always exactly one PlayerShip object in existence, which can be accessed through <code>[[Oolite JavaScript Reference: Global#player|player]].ship</code>.

Like any entity, the player ship can become [[Oolite JavaScript Reference: Entity#Stale References|invalid]] – specifically, when the player dies or ejects. Unlike other entities, the player ship can become valid again (after ejecting and being rescued). This is a technicality and it’s not guaranteed to work this way in future.

== Properties ==
=== <code>aftShield</code> ===
'''aftShield''' : Number (read/write, nonnegative)
The current aft shield level, ranging from 0 to <code>[[#maxAftShield|maxAftShield]]</code>.

'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>

=== <code>aftShieldRechargeRate</code> ===
'''aftShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
The rate at which the aft shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, but this is not the case from 1.81.

'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>

=== <code>cargoSpaceAvailable</code> ===
'''cargoSpaceAvailable''' : Number (read-only integer)
The ship’s available cargo space, in tons.

=== <code>cargoSpaceUsed</code> ===
'''cargoSpaceUsed''' : Number (read-only integer)
The ship’s current cargo, in tons.

=== <code>compassMode</code> ===
'''compassMode''' : String (read-only)
Returns the current compass mode, which can be any one of the following:
* COMPASS_MODE_BASIC
* COMPASS_MODE_PLANET
* COMPASS_MODE_STATION
* COMPASS_MODE_SUN
* COMPASS_MODE_TARGET
* COMPASS_MODE_BEACONS

=== <code>compassTarget</code> ===
'''compassTarget''' : Entity(read-only)
Points at the entity currently targeted by the compass.

=== <code>crosshairs</code> ===
{{oolite-prop-added|1.77}}
'''crosshairs''' : String (read/write)
The name of the [[Crosshairs.plist|crosshairs.plist]] defining the ship’s weapon crosshairs. HUDs can define crosshairs separately. This value will be <code>null</code> if the HUD built-in crosshairs are in use, and setting it to <code>null</code> will revert to the default HUD crosshairs.

If the HUD is changed, the old value of this property will be discarded, and the HUD's default crosshairs will be used.

=== <code>currentWeapon</code> ===
{{oolite-prop-added|1.77}}
'''currentWeapon''' : EquipmentInfo (read/write)
A shortcut property to whichever of [[Oolite_JavaScript_Reference:_Ship#aftWeapon|aftWeapon]], [[Oolite_JavaScript_Reference:_Ship#forwardWeapon|forwardWeapon]], [[Oolite_JavaScript_Reference:_Ship#portWeapon|portWeapon]] or [[Oolite_JavaScript_Reference:_Ship#starboardWeapon|starboardWeapon]] is the currently active player weapon.

If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be null, and attempting to write to it will give an error.

=== <code>cursorCoordinates</code> ===
'''cursorCoordinates''' : Vector3D (read-only)
'''Discouraged in favour of <code>[[#cursorCoordinatesInLY|cursorCoordinatesInLY]]</code>.''' 
The current x and y cursor coordinates on the long range screen in the internal coordinate system. The <code>z</code> coordinate is always 0.

=== <code>cursorCoordinatesInLY</code> ===
'''cursorCoordinatesInLY''' : Vector3D (read-only)
The current x and y cursor coordinates on the long range screen, in light years. The <code>z</code> coordinate is always 0.

=== <code>docked</code> ===
'''docked''' : Boolean (read-only)
True if the player is docked with a station or carrier.

=== <code>dockedStation</code> ===
'''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only)
The station with which the player is currently docked.

=== <code>forwardShield</code> ===
'''forwardShield''' : Number (read/write, nonnegative)
The current forward shield level, ranging from 0 to <code>[[#maxForwardShield|maxForwardShield]]</code>.

'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>

=== <code>forwardShieldRechargeRate</code> ===
'''forwardShieldRechargeRate''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
The rate at which the forward shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, but this is no longer the case in 1.81

'''See also''': <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#forwardShield|forwardShield]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>

=== <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>galacticHyperspaceBehaviour</code> ===
'''galacticHyperspaceBehaviour''' : String (read/write)
A string indicating what the effect of a galactic hyperspace jump will be. The available options are:
* <code>"BEHAVIOUR_STANDARD"</code>: the player arrives in the closest system to the starting point that is part of the main group of stars. Small groups (as seen in [[Oolite planet list/Galaxy 6|galaxy 6]], among others) can’t be reached.
* <code>"BEHAVIOUR_ALL_SYSTEMS_REACHABLE"</code>: The player arrives at the closest system to the starting point, even if it is in a small group. '''Important:''' this can leave the player stranded, unless there are missions providing the possibility of escape!
* <code>"BEHAVIOUR_FIXED_COORDINATES"</code>: The player arrives at the system closest to <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.

'''See also:''' <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>

=== <code>galacticHyperspaceFixedCoords</code> ===
'''galacticHyperspaceFixedCoords''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)
'''Discouraged in favour of <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>.''' 
Like <code>[[#galacticHyperspaceFixedCoordsInLY|galacticHyperspaceFixedCoordsInLY]]</code>, but in the internal coordinate system.

=== <code>galacticHyperspaceFixedCoordsInLY</code> ===
'''galacticHyperspaceFixedCoordsInLY''' : [[Oolite JavaScript Reference: Vector3D|Vector3D]] (read/write)
The destination coordinates when <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code> mode is <code>"GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"</code>. The coordinate system corresponds to <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>. Currently, when assigning a value its <code>x</code> and <code>y</code> coordinates will be rounded to integer internal coordinates, and the <code>z</code> coordinate will be rejected.

'''See also:''' <code>[[#galacticHyperspaceBehaviour|galacticHyperspaceBehaviour]]</code>

=== <code>galaxyCoordinates</code> ===
'''galaxyCoordinates''' : Vector3D (read-only)
'''Discouraged in favour of <code>[[#galaxyCoordinatesInLY|galaxyCoordinatesInLY]]</code>.''' 
The player’s location in galactic space, in the internal coordinate system. The <code>z</code> coordinate is always 0.

=== <code>galaxyCoordinatesInLY</code> ===
'''galaxyCoordinatesInLY''' : Vector3D (read-only)
The player’s location in galactic space, in light years (measured from the top left of the map). The <code>z</code> coordinate is always 0.

=== <code>hud</code> ===
'''hud''' : String (read/write)
The name of the [[hud.plist|HUD plists]] defining the ship’s head up display.

=== <code>hudAllowsBigGui</code> ===
{{oolite-prop-added|1.83}}

'''hudAllowsBigGui''' : Boolean (read-only)
Whether the HUD allows a "big GUI" or not. Most useful for determining whether mission screens will have 21 or 27 lines.

If <code>hudHidden</code> is true this will also be true, even if the HUD which is hidden would not normally allow a big GUI.

=== <code>hudHidden</code> ===
'''hudHidden''' : Boolean (read/write)
Whether the HUD should be visible.

=== <code>hyperspaceSpinTime</code> ===
{{oolite-prop-added|1.77}}
'''hyperspaceSpinTime''' : Number (read-only, read/write in 1.81)
The length of the ship's hyperspace countdown.

Setting this to a negative value disables the drive entirely.

=== <code>infoSystem</code> ===

{{oolite-prop-added|1.83}}
'''infoSystem''' : Number (read/write)
The ID of the system shown in the system (F7) screen.

=== <code>injectorsEngaged</code> ===
{{Oolite-prop-added|1.81}}
'''injectorsEngaged''' : Boolean(read-only)
Is the player ship currently using fuel injection.

=== <code>manifest</code> ===
'''manifest''' : [[Oolite JavaScript Reference: Manifest|Manifest]] (read/write)
The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class [[Oolite JavaScript Reference: Manifest|Manifest]] of its own.

=== <code>maxAftShield</code> ===
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
The highest possible value of <code>[[#aftShield|aftShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#maxForwardShield|maxForwardShield]]</code>, but this is not necessarily true from 1.81.

'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#aftShieldRechargeRate|aftShieldRechargeRate]]</code>, <code>[[#maxForwardShield|maxForwardShield]]</code>

=== <code>maxForwardShield</code> ===
'''maxAftShield''' : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
The highest possible value of <code>[[#forwardShield|forwardShield]]</code>. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as <code>[[#maxAftShield|maxAftShield]]</code>, but this is not necessarily true from 1.81.

'''See also''': <code>[[#forwardShield|forwardShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code>

=== <code>missilesOnline</code> ===
{{Oolite-prop-added|1.77}}
'''missilesOnline''' : Boolean (read-only)
True if the ship's targeting system is currently in missile targeting mode, false if it is currently in identification mode.

=== <code>multiFunctionDisplayList</code> ===
{{Oolite-prop-added|1.81}}
'''multiFunctionDisplayList''' : Array (read-only, strings)
The IDs of the currently active multi-function displays

e.g.
[null, "myoxp_mfd1"] // My OXP MFD1 in the second display, first display blank

=== <code>multiFunctionDisplays</code> ===
{{Oolite-prop-added|1.79}}
'''multiFunctionDisplays''' : Number (read-only, integer)
The number of multi-function displays available on the current HUD.

=== <code>price</code> ===
{{Oolite-prop-added|1.77}}
'''price''' : Number (read-only, positive integer in decicredits)
The value the player's ship would have, including equipment, if in a perfect servicing state. The ship can be exchanged at a shipyard for 75% of this value if it really is in perfect servicing state.

=== <code>renovationCost</code> ===
{{Oolite-prop-added|1.79}}
'''renovationCost''' : Number (read-only, positive integer in decicredits)
The current price in decicredits to service the ship. Depending on the [[#serviceLevel|serviceLevel]] it may not be possible to actually purchase renovation at this time.

=== <code>renovationMultiplier</code> ===
{{Oolite-prop-added|1.79}}
'''renovationMultiplier''' : Number (read-only, positive)
The multiplier applied to the base cost of renovation (<code>renovationCost</code> already includes this multiplier) to allow for some ships being more difficult to maintain than others. The default is 1.0 - other values are set in [[Shipyard.plist#renovation_multiplier|shipyard.plist]]

=== <code>reticleTargetSensitive</code> ===
'''reticleTargetSensitive''' : Boolean (read/write)
If true, and Scanner Targeting Enhancement is installed, the selected target reticle will light up in red when the target is in the player’s sights. This is equivalent to the <code>reticle_target_sensitive</code> key in [[hud.plist|HUD plists]].

=== <code>routeMode</code> ===
{{oolite-prop-added|1.81}}
'''routeMode''' : String (read-only)
Gives the current mode of the [[Advanced Navigational Array]]. Three possible values
* "OPTIMIZED_BY_NONE": off, or not fitted
* "OPTIMIZED_BY_JUMPS": shortest route
* "OPTIMIZED_BY_TIME": quickest route

=== <code>scannerNonLinear</code> ===
'''scannerNonLinear''' : Boolean (read/write)
If <code>true</code>, the scanner is operating in non-linear mode. This property will be reset to the HUD default if the HUD is changed.

=== <code>scannerUltraZoom</code> ===
'''scannerUltraZoom''' : Boolean (read/write)
If <code>true</code>, the scanner has 1x, 2x, 4x, 8x and 16x zoom modes, rather than the conventional 1x, 2x, 3x, 4x and 5x. This property will be reset to the HUD default if the HUD is changed.

=== <code>scoopOverride</code> ===
'''scoopOverride''' : Boolean (read/write)
If <code>true</code>, and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.

=== <code>serviceLevel</code> ===
{{Oolite-prop-added|1.77}}
'''serviceLevel''' : Number (read/write, positive integer in range 75-100)
The level of servicing the player's ship has. Renovation will be offered in shipyards at 85 or below, and malfunctions are more likely at lower values. This affects the sales price of the ship.

=== <code>specialCargo</code> ===
'''specialCargo''' : String (read-only)
The special cargo the player is carrying, if any; otherwise <code>null</code>.

'''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code>

=== <code>targetSystem</code> ===
'''targetSystem''' : Integer (read-only, sometimes read/write in 1.77)
The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked.

=== <code>torusEngaged</code> ===
{{Oolite-prop-added|1.81}}
'''torusEngaged''' : Boolean(read-only)
Is the player ship currently using torus drive

=== <code>viewDirection</code> ===
'''viewDirection''' : String (read-only)
Returns the view direction as string: <code>"VIEW_FORWARD"</code>, <code>"VIEW_AFT"</code>, <code>"VIEW_PORT"</code>, <code>"VIEW_STARBOARD"</code>, <code>"VIEW_CUSTOM"</code> or <code>"VIEW_GUI_DISPLAY"</code>.

=== <code>viewPosition*</code> ===
{{Oolite-prop-added|1.79}}
'''viewPositionAft''' : Vector (read-only)
'''viewPositionForward''' : Vector (read-only)
'''viewPositionPort''' : Vector (read-only)
'''viewPositionStarboard''' : Vector (read-only)
The ship's 4 point-of-view positions in XYZ relative to the model. The corresponding ''[[shipdata.plist]]'' keys start with <code>view_position_</code>.

=== <code>weaponsOnline</code> ===
'''weaponsOnline''' : Boolean (read-only)
Returns the weapon safety status. Player can toggle the status with the underscore-key.

== Methods ==
=== <code>addParcel</code> ===
{{oolite-method-added|1.77}}
function '''addParcel'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean
Add a parcel contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.

Returns <code>false</code> when there is already a parcel with that name or the arrival time is invalid.

The <code>advance</code> and <code>risk</code> parameters were added in Oolite 1.79. <code>advance</code> is purely advisory and describes any up-front payment given for the parcel. <code>risk</code> can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this parcel.

=== <code>addPassenger</code> ===
function '''addPassenger'''(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean
Add a passenger contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.

Returns <code>false</code> when there is no room for the passenger, there is already a passenger with that name or the arrival time is invalid.

'''Example:'''
player.ship.addPassenger("cmdr Jameson", 34, 67, clock.seconds+3*24*3600, 1500);

If successful - and in galaxy chart 1 - the player will have cmdr Jameson as a passenger, his documents will show that he boarded the ship at Inus, to go to Cemave, within exactly 3 days, and the player will be given 1500 credits if he gets there on time (early or late arrival will affect the amount paid).

'''N.B.''' Normally a passenger will pay the captain a small advance upon boarding. Using this method, no initial payment is made. In versions after 1.77, an optional parameter can be added to describe what the advance ''was'', without actually making it.

The risk parameter was added in Oolite 1.79. <code>risk</code> can be 0, 1 or 2 - the higher the number, the more likely that assassins are likely to try to kill the player while they carry this passenger.

=== <code>awardContract</code> ===
function '''awardContract'''(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, premium : Number]) : Boolean
Add a cargo contract to the ship. <code>arrivalTime</code> is the arrival time in seconds and must be greater than the current time. <code>start</code> and <code>destination</code> are the ID numbers of the start and end systems.

Returns <code>false</code> when there is no room for the cargo, the arrival time is invalid.

'''Example:'''
player.ship.awardContract(12, "Food", 34, 67, clock.seconds+7*24*3600, 5000)

If successful - and in galaxy chart 1 - the player will have 12 more food containers on board, the manifest will show that the cargo was picked up at Inus, to be delivered at Cemave, within exactly 7 days, and the player will be given 5000 credits if the cargo is delivered on time (early or late delivery will affect the amount paid).

'''N.B.''' Normally to get a contract, the player will have to pay a deposit similar in value to the cargo. Using this method, no deposit payment is made. In versions after 1.77, an optional parameter can be added to describe what the deposit payment ''was'', without actually making it.

=== <code>awardEquipmentToCurrentPylon</code> ===
function '''awardEquipmentToCurrentPylon'''(item : [[Oolite JavaScript Reference: EquipmentInfo#Equipment Expressions|equipmentInfoExpression]]) : Boolean
Replace the missile or mine currently being launched with the specified item (which must be an external store). This will only have an effect if called while a missile or mine is being launched. Effectively this means that this method must be used within the <code>shipFiredMissile()</code> handler or in the ENTER message of the GLOBAL state of an missileAI.plist.

'''Bug:''' In Oolite 1.74.0, if <code>awardEquipmentToCurrentPylon()</code> fails the script will be halted without any error message. In future versions, it will simply return <code>false</code>.

'''See also:''' <code>[[Oolite JavaScript Reference: Ship#awardEquipment|Ship.awardEquipment()]]</code>

=== <code>beginHyperspaceCountdown</code> ===
{{oolite-method-added|1.77}}
function beginHyperspaceCountdown( [ length : Number ] ) : Boolean
This function begins the witchspace sequence for the player ship. It returns true if the sequence is started successfully, and false otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used.

'''See also:''' <code>[[#cancelHyperspaceCountdown|cancelHyperspaceCountdown]]</code>

=== <code>cancelHyperspaceCountdown</code> ===
{{oolite-method-added|1.77}}
function cancelHyperspaceCountdown() : Boolean
This function cancels the witchspace sequence for the player ship. It returns true if there was an ongoing sequence to cancel, and false otherwise.

'''See also:''' <code>[[#beginHyperspaceCountdown|beginHyperspaceCountdown]]</code>

=== <code>disengageAutopilot</code> ===
function disengageAutopilot()
Disenable autopilot.

'''See also:''' <code>[[#engageAutopilotToStation|engageAutopilotToStation()]]</code>

=== <code>engageAutopilotToStation</code> ===
function engageAutopilotToStation(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean
Engage autopilot, set to dock with the specified station.

'''See also:''' <code>[[#disengageAutopilot|disengageAutopilot()]]</code>

=== <code>hideHUDSelector</code> ===
{{oolite-method-added|1.79}}
function hideHUDSelector(selector : String)
Hide all dials using the specified selector on the HUD display. For example

player.ship.hideHUDSelector("drawScanner:");

'''See also:''' <code>[[#showHUDSelector|showHUDSelector()]]</code>

=== <code>launch</code> ===
function '''launch'''()
Launches the player’s ship if it is currently docked.

=== <code>removeAllCargo</code> ===
function '''removeAllCargo'''()
Removes all cargo from the ship’s cargo bay that are measured in tons. Does not affect Gold, Platinum or Gemstones. Can only be used while docked.

=== <code>removeContract</code> ===
function '''removeContract'''(commodity : String, destination : Number)
Remove the cargo contract matching that commodity and destination.

=== <code>removeParcel</code> ===
{{oolite-method-added|1.77}}
function '''removeParcel'''(name : String)
Remove a named parcel.

=== <code>removePassenger</code> ===
function '''removePassenger'''(name : String)
Remove a named passenger.

=== <code>resetCustomView</code> ===
{{oolite-method-added|1.77}}
function '''resetCustomView'''()
Resets the custom view back to the last-used setting defined in [[shipdata.plist]]

This function gives an error if used when the custom view camera is not selected.

=== <code>resetScannerZoom</code> ===
{{oolite-method-added|1.79}}
function '''resetScannerZoom'''()
Resets the scanner zoom back to 1:1

=== <code>setCustomView</code> ===
{{oolite-method-added|1.77}}
function '''setCustomView'''(Vector : position, Quaternion : orientation [,WeaponDirection weapon])
Set the position and orientation of the custom view camera to those specified. As with the custom views specified through [[shipdata.plist]], these are relative to the player's ship's position, and the coordinate frame defined by the ship's forward, right and up Vectors.

The optional weapon parameter can be "FORWARD", "AFT", "PORT" or "STARBOARD" and sets the active weapon accordingly. If omitted, the active weapon for the previous custom view will be preserved.

This function gives an error if used when the custom view camera is not selected. Setting the custom view does not affect the custom views defined in [[shipdata.plist]], which will be switched back to the next time 'v' is pressed, or when [[#resetCustomView|resetCustomView]] is called.

=== <code>setCustomHUDDial</code> ===
{{oolite-method-added|1.81}}
function '''setCustomHUDDial'''(key : String, value : Value)
Sets the custom HUD dial [[hud.plist#data_source|data source]] 'key' to the specified value. Different types of custom HUD dial will expect different types of values; a value of an incorrect type will be converted if possible.

=== <code>setMultiFunctionDisplay</code> ===
{{oolite-method-added|1.79}}
function '''setMultiFunctionDisplay'''(index : Number, key : String) : Boolean
Sets the multi-function display with the specified number to display the given multi-function display <code>key</code> set earlier with [[#setMultiFunctionText|setMultiFunctionText()]]. Multi-function displays are numbered from 0 to [[#multiFunctionDisplays|multiFunctionDisplays]]-1. If the index given is outside this range, the first unused multi-function display will be used, or the function will return <code>false</code> if all are currently in use.
Example:
// picks first unused one
player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd");

As the player can cycle the contents of their displays between the various active keys themselves using keyboard controls, it is advisable not to call this function to override a specific display except in emergencies, as this is likely to annoy the player.

=== <code>setMultiFunctionText</code> ===
{{oolite-method-added|1.79}}
function '''setMultiFunctionText'''(key : String [, contents : String [, reflow : Boolean]])
Set the text for the multi-function display with the specified <code>key</code> to be <code>contents</code>. The limit on space for a multi-function display is ten lines of text, each 15 blocks wide.

If you specify the optional <code>reflow</code> parameter, then the text given will automatically be fitted into the available space, with any extra discarded. Otherwise, line-breaks will not be added automatically, so you must enter them into <code>contents</code> yourself. If any individual line is more than 15 blocks long, the text will be compressed to fit it into the available space. This looks bad and is best avoided.

=== <code>showHUDSelector</code> ===
{{oolite-method-added|1.79}}
function showHUDSelector(selector : String)
Show all dials using the specified selector on the HUD display if they were previously hidden. For example

player.ship.showHUDSelector("drawScanner:");

'''See also:''' <code>[[#hideHUDSelector|hideHUDSelector()]]</code>

=== <code>takeInternalDamage</code> ===
{{oolite-method-added|1.77}}
function '''takeInternalDamage'''()
Causes the player ship to potentially take "internal damage". Internal damage can also be caused by hits on the hull and some witchdrive malfunctions, and this function uses the same algorithm to determine the damage taken, which can be:
* damage to cargo
* damage to equipment (according to the damage_probability)
* reduction in [[#serviceLevel|service level]]
* no damage
The function will return 'false' if "no damage" was selected, and 'true' otherwise. The relative probabilities of the three options vary depending on the size of the player ship, its cargo capacity, cargo carried and installed equipment.

=== <code>useSpecialCargo</code> ===
function '''useSpecialCargo'''(description : String)
Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed.

'''See also''': <code>[[#specialCargo|specialCargo]]</code>

[[Category:Oolite JavaScript Reference]]

Oolite JavaScript Reference: World script event handlers

2016-04-29T10:23:06Z

Kanthoney: /* guiScreenWillChange */ Add infoSystemChanged handler

This page provides a list of event handlers which can be implemented inside world scripts [[Scripting Oolite with JavaScript|JavaScript scripts for Oolite]]. Additionally, ship script handlers called on the player's ship will cause an equivalent world script event.

Most event handlers can be used both in world scripts and in ship scripts. Generally speaking, handlers starting with "ship" can be used for both scripts and those starting with "player" are meant only for the player (= can only be used in a world script). Exceptions on this rule are mentioned with the individual handlers below.

World scripts can be either found inside Config\script.js, or be distinctly named .js files inside the Scripts directory - in the latter case, the worldScript.plist will list the active world scripts.

World scripts are always active.

The list of event handlers will change from version to version (usually additions of extra handlers). For this reason, any variables or functions you create as <code>this.variable</code> should have a name beginning with '_' or '$' - e.g. <code>this._variable</code> or <code>this.$variable</code> - to avoid potential conflicts with future event handlers (which will never start with '_' or '$').

=== Game State ===

==== <code>gamePaused</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is paused. This is mainly useful for pausing sound playback which should not continue while the game is paused.

this.gamePaused = function()
{
// Your code here
}

==== <code>gameResumed</code> ====
{{oolite-method-added|1.81}}

This event is called when the game is resumed from pause. This is mainly useful for resuming sound playback paused in a <code>gamePaused</code> handler.

this.gameResumed = function()
{
// Your code here
}

==== <code>playerWillSaveGame</code> ====

The <code>playerWillSaveGame</code> handler is called whenever the player saves a game. The transferred message is one of the following strings: 'standardSave', 'autoSave' or 'quickSave'

this.playerWillSaveGame = function(message : String)
{
// Your code here
}

Using this event is useful for storing temporary variables in missionVariables, just before the game gets saved. missionVariables are slow in use compared to normal JS variables, therefor their use should be minimised for efficient code. The main benefit of using missionVariables is that they are saved in a saved game.

==== <code>startUp</code> ====

The <code>startUp</code> handler is called after all OXPs have been loaded. This also means that it is called every time the player loads a game, begins a new game or presses space after dying. It can be used to do one-off initialisation such as copying mission variables into <code>this.*</code> properties for efficiency or setting up data arrays to be used by the script in other handlers. (world script only)

this.startUp = function()
{
// Your code here
}

Note that from Oolite 1.79 onwards the player will be in the main station while this function is run, but may be moved from there to another station soon after.

==== <code>startUpComplete</code> ====
{{oolite-method-added|1.79}}

The <code>startUpComplete</code> handler is run at game startup after the initial population of the system has been complete, and after the player has been moved to the station recorded in their save game. The order of world events at game start is therefore:
* <code>startUp</code>
* <code>systemWillPopulate</code> (or an alternative handler specified by the system info)
* <code>startUpComplete</code>

=== Docking ===

==== <code>shipWillDockWithStation</code> ====

The <code>shipWillDockWithStation</code> handler is called at the beginning of the docking tunnel effect.

this.shipWillDockWithStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == null", "ship.docked == true", "ship.status == STATUS_DOCKING"

==== <code>shipDockedWithStation</code> ====

The <code>shipDockedWithStation</code> handler is called at the end of the docking tunnel effect.

this.shipDockedWithStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == the station", "ship.docked == true", "ship.status == STATUS_DOCKED" and "gui_screen" is either GUI_SCREEN_STATUS or GUI_SCREEN_REPORT. However, any identical handler from an other oxp could have changed those values. Never count on it but double check when important.

==== <code>shipWillLaunchFromStation</code> ====

The <code>shipWillLaunchFromStation</code> handler is called at the beginning of the launch tunnel effect.

this.shipWillLaunchFromStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == the station", "ship.docked == false", "ship.status == STATUS_LAUNCHING".

==== <code>shipLaunchedFromStation</code> ====

The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect.

this.shipLaunchedFromStation = function(station)
{
// Your code here
}
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".

==== <code>playerStartedAutoPilot</code> ====

The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command.

this.playerStartedAutoPilot = function()
{
// Your code here
}

==== <code>playerCancelledAutoPilot</code> ====

The <code>playerCancelledAutoPilot</code> handler is called when the player cancels autopilot docking.

this.playerCancelledAutoPilot = function()
{
// Your code here
}

==== <code>playerDockingClearanceExpired</code> ====
{{oolite-method-added|1.83}}

The <code>playerDockingClearanceExpired</code> handler is called when the player exceeds the two minute window without requesting an extension

this.playerDockingClearanceExpired = function()
{
// Your code here
}

==== <code>playerDockingRefused</code> ====

The <code>playerDockingRefused</code> handler is called when a station refuses to provide autopilot docking instructions.

this.playerDockingRefused = function()
{
// Your code here
}

==== <code>playerRequestedDockingClearance</code> ====

The <code>playerRequestedDockingClearance</code> handler is called when a station answers on a docking request of the player by targeting the station and pressing L (shift-l).

this.playerRequestedDockingClearance = function(message)
{
// Your code here
}

Message is a string and can take the values: "DOCKING_CLEARANCE_GRANTED", "DOCKING_CLEARANCE_DENIED_TRAFFIC_OUTBOUND", "DOCKING_CLEARANCE_DENIED_TRAFFIC_INBOUND", "DOCKING_CLEARANCE_DENIED_SHIP_FUGITIVE", "DOCKING_CLEARANCE_NOT_REQUIRED", "DOCKING_CLEARANCE_EXTENDED" or "DOCKING_CLEARANCE_CANCELLED".

==== <code>playerRescuedEscapePod</code> ====
{{oolite-method-added|1.81}}

The <code>playerRescuedEscapePod</code> handler is called when the player rescues an escape pod which does not have scripted content (all consequences of scripted content escape pods are assumed to be dealt with by the specified script instead). It has three parameters:
# the rescue fee, in decicredits
# the fee reason, which can be "insurance", "bounty" or "slave" (in the latter case, the fee will always be zero)
# a dictionary like those in the <code>ship.crew</code> property describing the pod occupant

this.playerRescuedEscapePod = function(fee, reason, occupant)
{
// Your code here
}

This method is called after the escape pod has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerCompletedContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerCompletedContract</code> handler is called when a passenger, parcel or cargo contract ends, either successfully or by defaulting on it. It is not called when all contracts are cancelled on a galactic jump. It has four parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The result of the contract, which can be "success", "late", "failed", or for cargo contracts only "short"
# The fee paid for the contract in decicredits
# The contract information dictionary
Note that the fee actually paid for the contract will often ''not'' match the originally agreed fee in the contract information dictionary, as penalties for late delivery or bonuses for good service are included in the fee parameter.

this.playerCompletedContract = function(type, result, fee, contract)
{
// Your code here
}

This method is called after the contract has been processed, but slightly before the arrival report screen giving the results of the processing is displayed to the player.

==== <code>playerEnteredContract</code> ====
{{oolite-method-added|1.81}}

The <code>playerEnteredContract</code> handler is called when a passenger, parcel or cargo contract starts, just after the items have been transferred to the player ship. It has two parameters:
# The type of contract, which can be "cargo", "parcel" or "passenger"
# The contract information dictionary

this.playerEnteredContract = function(type, contract)
{
// Your code here
}

=== Witchspace Jumps ===

==== <code>playerStartedJumpCountdown</code> ====

The <code>playerStartedJumpCountdown</code> handler is called when the user starts a witchspace or galactic witchspace jump countdown. The <code>type</code> parameter is a string specifying which type of jump is occuring; currently, the possible values are “standard” and “galactic”. Other values may be added in future. The <code>seconds</code> parameter is a number specifying the number of seconds the countdown is running for.

this.playerStartedJumpCountdown = function(type, seconds)
{
// Your code here
}

==== <code>playerCancelledJumpCountdown</code> ====

The <code>playerCancelledJumpCountdown</code> handler is called when the user cancels a witchspace or galactic witchspace jump countdown.

this.playerCancelledJumpCountdown = function()
{
// Your code here
}

==== <code>playerJumpFailed</code> ====

The <code>playerJumpFailed</code> handler is called at the end of a witchspace or galactic witchspace countdown, if the jump is not possible. The <code>reason</code> parameter is a string specifying why the jump failed. The current values are:
* '''"insufficient fuel"''' - the ship no longer has enough fuel to make the jump (e.g. injector use or fuel leak).
* '''"blocked"''' - a heavy ship is near the player (specifically <code>object mass</code> / <code>object distance</code>2 >= 10.0, and <code>object distance</code> <= scanner range).
* '''"malfunction"''' - the jump malfunctioned in a way that leaves the player ship in the current system.
* '''"malfunction"''' - the Galactic Hyperdrive is damaged or removed during a galactic jump countdown.

Also theoretically possible but unlikely in current Oolite:
* '''"too far"''' - the jump destination is outside the 7LY range (but wasn't when the countdown started).
* '''"no target"''' - the jump destination is the current location (but wasn't when the countdown started).

this.playerJumpFailed = function(reason)
{
// Your code here
}

==== <code>shipWillEnterWitchspace</code> ====

The <code>shipWillEnterWitchspace</code> handler is called immediately before a witchspace jump, while the player is still in the starting system. The <code>cause</code> parameter is a string specifying what sort of jump is occuring; currently, the possible values are “standard jump”, “galactic jump” and “wormhole”. Other values may be added in future.

// 1.80 or earlier
this.shipWillEnterWitchspace = function(cause)
{
// Your code here
}

In 1.81 or later the handler gains a second parameter, describing the jump destination. For standard and wormhole jumps, this will be the system ID of the destination system. For galactic jumps, this will be the galaxy ID of the destination galaxy. (As [[Oolite JavaScript Reference: PlayerShip#galacticHyperspaceBehaviour|player.ship.galacticHyperspaceBehaviour]] may be changed during <code>shipWillEnterWitchspace</code>, it is not possible to predict in advance of a galactic jump being made what the resulting system ID in the destination galaxy will be)

// 1.81 or later
this.shipWillEnterWitchspace = function(cause, destination)
{
// Your code here
}

==== <code>shipWillExitWitchspace</code> ====

The <code>shipWillExitWitchspace</code> handler is called as a witchspace jump concludes. When it is called, the player is (from a program perspective) in the destination system, but the tunnel effect has not yet been shown. Use this event to set up elements which need to be present in-system after the player exits witchspace.

this.shipWillExitWitchspace = function()
{
// Your code here
}

==== <code>shipExitedWitchspace</code> ====

The <code>shipExitedWitchspace</code> handler is called after a witchspace jump has concluded and the tunnel effect has been shown.

this.shipExitedWitchspace = function()
{
// Your code here
}

==== <code>playerEnteredNewGalaxy</code> ====

The <code>playerEnteredNewGalaxy</code> handler is called just before shipWillExitWitchspace.

the sequence of events for a player jumping to a different galaxy is as follows:

shipWillEnterWitchspace (world event) 
playerWillEnterWitchspace (NPC ship event) 
playerEnteredNewGalaxy (world event) 
shipWillExitWitchspace (world event) 
shipExitedWitchspace (world event) 

this.playerEnteredNewGalaxy = function(galaxyNumber)
{
// Your code here
}

=== Enter/Exit Aegis ===

==== <code>shipEnteredStationAegis</code> ====

The <code>shipEnteredStationAegis</code> handler is called when the player enters the aegis of the main-station (2x scanner range from main-station). Other stations than the main-station don't give aegis messages.

this.shipEnteredStationAegis = function(station)
{
// Your code here
}

==== <code>shipExitedStationAegis</code> ====

The <code>shipExitedStationAegis</code> handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).

this.shipExitedStationAegis = function(station)
{
// Your code here
}

==== <code>shipEnteredPlanetaryVicinity</code> ====

The <code>shipEnteredPlanetaryVicinity</code> handler is called when the player enters the planet aegis (3x planet radius).

this.shipEnteredPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipExitedPlanetaryVicinity</code> ====

The <code>shipExitedPlanetaryVicinity</code> handler is called when the player leaves the planet aegis (3x planet radius).

this.shipExitedPlanetaryVicinity = function(planet)
{
// Your code here
}

==== <code>shipApproachingPlanetSurface</code> ====

The <code>shipApproachingPlanetSurface</code> handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).

this.shipApproachingPlanetSurface = function(planet)
{
// Your code here
}

==== <code>shipLeavingPlanetSurface</code> ====

The <code>shipLeavingPlanetSurface</code> handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).

this.shipLeavingPlanetSurface = function(planet)
{
// Your code here
}

=== Combat ===

==== <code>alertConditionChanged</code> ====

The <code>alertConditionChanged</code> handler is called when the player’s alert status (<code>[[Oolite JavaScript Reference: Player#alertCondition|player.alertCondition]]</code>) changes. Only the player and stations have an alert condition. (world script and station scripts)

this.alertConditionChanged = function(newCondition, oldCondition)
{
// Your code here
}

==== <code>playerTargetedMissile</code> ====

The <code>playerTargetedMissile</code> handler is called when the player targets the nearest missile by pressing T (shift-t) on the keybord.

this.playerTargetedMissile = function(missile)
{
// Your code here
}

==== <code>shipAttackedOther</code> ====

The <code>shipAttackedOther</code> handler is called when the player hits another with a laser shot. <code>other</code> is the identity of the ship being hit.

this.shipAttackedOther = function(other)
{
// Your code here
}

==== <code>shipAttackedWithMissile</code> ====

The <code>shipAttackedWithMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>whom</code> the identity of the ship that launched the missile.

this.shipAttackedWithMissile = function(missile, whom)
{
// Your code here
}

==== <code>shipBeingAttacked</code> ====

The <code>shipBeingAttacked</code> handler is called when a laser shot hits. <code>whom</code> the identity of the ship that attacked.

this.shipBeingAttacked = function(whom)
{
// Your code here
}

==== <code>shipBeingAttackedByCloaked</code> ====

The <code>shipBeingAttackedByCloaked</code> handler is called when a laser shot from a cloaked ship hits. Guess what, there is no parameter because he is cloaked!

this.shipBeingAttackedByCloaked = function()
{
// Your code here
}

==== <code>shipKilledOther</code> ====

The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage. (Handler added in test version 1.75)

this.shipKilledOther = function(whom,damageType)
{
// Your code here
}

==== <code>shipTargetDestroyed</code> ====

The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed by the player. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler.

this.shipTargetDestroyed = function(target)
{
// Your code here
}

==== <code>shipDied</code> ====

The <code>shipDied</code> handler is called when the ship or player dies. Expect a <code>reset()</code> shortly when it is the player ship.

this.shipDied = function(whom, why)
{
// Your code here
}
'''whom''' contains the entity that caused the kill. '''why''' is the cause written as string and is one of: "removed", "hit a planet", "energy damage", "scrape damage", "heat damage", "cascade weapon". 
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)

==== <code>shipFiredMissile</code> ====

The <code>shipFiredMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>target</code> the identity of the target. The handler is send to the ship that launched the missile.

this.shipFiredMissile = function(missile, target)
{
// Your code here
}

==== <code>shipTargetLost</code> ====

The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.

this.shipTargetLost = function(target)
{
// Your code here
}

==== <code>shipTargetCloaked</code> ====

The <code>shipTargetCloaked</code> handler is called when the target cloakes.

this.shipTargetCloaked = function()
{
// Your code here
}

=== Equipment and Cargo ===

==== <code>equipmentAdded</code> ====
{{Oolite-method-added|1.81}}
The <code>equipmentAdded</code> handler is called whenever the player ship gains an item of equipment. This includes "gaining" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is damaged. This event will fire regardless of the reason for the equipment being added to the ship.

this.equipmentAdded = function(equipmentKey)
{
// Your code here
}

This is often more convenient than monitoring both <code>equipmentRepaired</code> and <code>playerBoughtEquipment</code>, and will also detect equipment addition by script.

==== <code>equipmentDamaged</code> ====

The <code>equipmentDamaged</code> handler is called when equipment gets damaged. (world script only)

this.equipmentDamaged = function(equipment)
{
// Your code here
}

==== <code>equipmentRemoved</code> ====
{{Oolite-method-added|1.81}}
The <code>equipmentRemoved</code> handler is called whenever the player ship loses an item of equipment. This includes "losing" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is repaired. This event will fire regardless of the reason for the equipment being removed from the ship.

this.equipmentRemoved = function(equipmentKey)
{
// Your code here
}

==== <code>equipmentRepaired</code> ====
{{Oolite-method-added|1.77}}

The <code>equipmentRepaired</code> handler is called when equipment gets repaired. (world script only)

this.equipmentRepaired = function(equipment)
{
// Your code here
}

==== <code>playerBoughtCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerBoughtCargo</code> handler is called when cargo is bought at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerBoughtCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>playerBoughtEquipment</code> ====

The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen.

this.playerBoughtEquipment = function(equipment)
{
// Your code here
}

==== <code>playerBoughtNewShip</code> ====

The <code>playerBoughtNewShip</code> handler is called when a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

this.playerBoughtNewShip = function(ship, price)
{
// Your code here
}

The 'price' parameter is added from 1.81 onwards. It is the cost of the ship (not counting any trade-in value of the player's old ship) in credits, or zero for changes using [[Oolite JavaScript Reference: Player#replaceShip|player.replaceShip]]

==== <code>playerSoldCargo</code> ====
{{Oolite-method-added|1.77}}

The <code>playerSoldCargo</code> handler is called when cargo is sold at the market screen. <code>commodity</code> contains the non-localised name for the cargo. You can get the localised name using <code>expandDescription("[commodity-name "+commodity+"]");</code>. <code>price</code> is price per unit in tenths of a credit.

this.playerSoldCargo = function(commodity, units, price)
{
// Your code here
}

==== <code>shipScoopedFuel</code> ====
{{Oolite-method-added|1.77}}

The <code>shipScoopedFuel</code> handler is called whenever the player's ship transfers 0.1LY of fuel from the scoops to the tank.

this.shipScoopedFuel = function()
{
// Your code here
}

==== <code>shipScoopedOther</code> ====

The <code>shipScoopedOther</code> handler is called when a ship scoops cargo. The scooped item is transferred as argument. If the cargo is scripted cargo, but not otherwise, then the scooped cargo itself gets the handler <code>shipWasScooped</code> with the scooper as argument.

this.shipScoopedOther = function(whom)
{
// Your code here
}

=== Other ===

==== <code>compassTargetChanged</code> ====

The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following:

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

this.compassTargetChanged = function(whom, mode)
{
log(' Now targeting ' + whom);
// Your code here
}

==== <code>dayChanged</code> ====
{{oolite-method-added|1.77}}

The <code>dayChanged</code> handler is called each time a new day starts. At very low frame rates while the clock is updating, it is possible for this handler to be called twice in the same frame. Therefore, clock.days will not be correct for one of the calls. Use the day number passed to the function instead.

this.dayChanged = function(newday)
{
// Your code here
}

==== <code>guiScreenChanged</code> ====

The <code>guiScreenChanged</code> handler is called when the guiScreen changes. "from" is the screen it is changing from and "to" is the screen were it initially switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefor, it will generally better to test for the global <code>guiScreen</code> to see which page is really on display instead of using the "to" parameter. (world script only) 
This handler will not fire for every screen the player can switch to, but only when switching to any of the following screens:

1.76: <code>GUI_SCREEN_MAIN, GUI_SCREEN_STATUS, GUI_SCREEN_MANIFEST, GUI_SCREEN_SYSTEM_DATA, GUI_SCREEN_OPTIONS, GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_SHIPYARD, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_MARKET, GUI_SCREEN_CONTRACTS, GUI_SCREEN_REPORT</code>

1.77: adds <code>GUI_SCREEN_INTERFACES</code> and removes <code>GUI_SCREEN_CONTRACTS</code>

this.guiScreenChanged = function(to, from)
{
// Your code here
}

==== <code>guiScreenWillChange</code> ====

The <code>guiScreenWillChange</code> handler is called when the guiScreen is about to change. It only fires for the screens: <code>GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET, GUI_SCREEN_SHIPYARD</code> and <code>GUI_SCREEN_SYSTEM_DATA</code> (in 1.77, also <code>GUI_SCREEN_STATUS</code>). On these screens a script could change the content of the page to be displayed. (world script only)

this.guiScreenWillChange = function(to, from)
{
// Your code here
}

==== <code>infoSystemChanged</code> ====

The <code>infoSystemChanged</code> handler is called when the system displayed in F7 is changed, e.g. by moving the small blue cursor along the planned route in the chart. Available in 1.83.

this.infoSystemChanged = function(to, from)
{
// Your code here
}

==== <code>missionChoiceWasReset</code> ====

The <code>missionChoiceWasReset</code> handler is called when the mission choice is set to null via script (either using the legacy script method resetMissionChice, or using mission.choice = null; in javascript)

this.missionChoiceWasReset= function()
{
// Your code here
}

==== <code>missionScreenEnded</code> ====

The <code>missionScreenEnded</code> handler is called when the missionscreen ends. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.missionScreenEnded = function()
{
// Your code here
}

==== <code>missionScreenOpportunity</code> ====

The <code>missionScreenOpportunity</code> handler is called if there are no mission / report screens active, and the player is docked to a station. It gets fired at game startup, upon docking, and after a docking report or previous mission screen has ended. (world script only)

this.missionScreenOpportunity= function()
{
// Your code here
}

This handler works a bit different as other handlers. It fires for every installed oxp, until an oxp creates a mission screen during this handler. Than it stops. When the mission screen ends and there is no callback function that created a new mission screen, than the missionScreenOpportunity is send again to all installed oxps, starting with the oxp that used the mission screen as last one. All this means that when this handler fires, it is safe to show a mission screen and no further test are needed.

==== <code>reportScreenEnded</code> ====

The <code>reportScreenEnded</code> handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

this.reportScreenEnded = function()
{
// Your code here
}

==== <code>shipCollided</code> ====

The <code>shipCollided</code> handler is send after a collision with otherShip.

this.shipCollided = function(otherShip)
{
// Your code here
}

==== <code>shipSpawned</code> ====

The <code>shipSpawned</code> handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered. 
This handler for the woldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

this.shipSpawned = function(ship)
{
// Your code here
}

==== <code>shipLaunchedEscapePod</code> ====

The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds.

this.shipLaunchedEscapePod = function(escapepod)
{
// Your code here
}

==== <code>systemInformationChanged</code> ====
{{oolite-method-added|1.79}}

The <code>systemInformationChanged</code> handler is called when system information is modified. It is passed the galaxy and system ID which were changed, and the key and new value in the SystemInfo object.

To avoid problems with recursion, attempting to change the value of any system information property from within this function will fail and log an error. Also note that changes which take place while Oolite is not running (from OXP planetinfo.plist files) will not cause this handler to be called when the game is reloaded.

this.systemInformationChanged = function(galaxy,system,key,newValue)
{
// Your code here
}

==== <code>viewDirectionChanged</code> ====

The <code>viewDirectionChanged</code> handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD",
"VIEW_CUSTOM",
"VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
if (viewString == "VIEW_PORT")
{
// Your code here
}
}

=== System population ===

In Oolite 1.79 and later, functions are called to populate and repopulate the system. These functions do not have fixed names, as they depend on the system, but otherwise act like normal worldscript functions. [[Oolite System Populator|The populator page]] has more documentation on these functions.

=== Defunct ===

==== <code>equipmentDestroyed</code> ====
''Handler no longer exists in current stable version 1.80''

The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode, 1.77 or earlier only) (world script only)

this.equipmentDestroyed = function(equipment)
{
// Your code here
}

==== <code>tickle</code> (removed in 1.77) ====

The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. <code>tickle()</code> is deprecated. In new code, use appropriate event handlers or [[Oolite JavaScript Reference: Timer|timers]] instead.

=== Missing Events ===

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].

'''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]]

[[Category:Oolite JavaScript Reference]]

Shaders in Oolite: uniforms

2016-02-24T17:03:04Z

Kanthoney: /* Entity */ Add fogUniform

:The information presented on this page applies to Oolite test release 1.69 and later.

A '''uniform''' in a [[Shaders in Oolite|shader]] is a variable whose value is specified by the host application – in this case, [[Oolite]]. Oolite allows arbitrary uniforms to be specified for shaders applied to ships, and these may either take constant values specified in ''shipdata.plist'', or be “bound” to an attribute of the ship. This allows shader authors to access numerous properties of a game entity without having to ask for them and wait for an updated version of Oolite. ('''Note:''' in the case of subentities, bound properties are fetched from the parent ship.)

=== Basic syntax ===
Uniforms are specified in the ''materials'' or ''shaders'' dictionary of a ship’s ''shipdata.plist'' entry:
"ahruman_shady_cobra_example" =
{
 like_ship = "cobra3-player";
 shaders =
 {
 "cobra3_redux.png" =
 {
 textures = ( "cobra3_redux.png" );
 fragment_shader = "ahruman_shady_cobra_example.fragment";
uniforms =
{
shininess =
{
type = float;
value = 42.0;
};
withinAegis = "withinStationAegis";
compassMode = "compassMode";
}
 }
 }
}
This contrived example declares three uniforms, ''shininess'', ''withinAegis'' and ''compassMode''. ''shininess'' is a constant <code>float</code>; it is always 42. ''withinAegis'' is bound to the ship’s ''withinStationAegis'' property. (See below for information on available properties.) This is a boolean, that is, a number whose value is either 0 (meaning no) or 1 (meaning yes). ''compassMode'' is a binding to the ''compassMode'' property. To use the uniforms within a shader (either a vertex shader or a fragment shader), they are declared as follows:
uniform float shininess;
uniform int withinAegis;
uniform int compassMode;
...
void main(void)
{
if (withinAegis)
{
// Do aegis-specific effect here
}
...
}

=== Uniform property types ===
Every bindable property has a '''type'''. The simplest types, ''int'' and ''float'', correspond directly to the same types in GLSL. Both represent numbers, with the difference that a ''float'' can represent fractional values and very large values, but always has the same level of precision (about six digits), while ''int''s can represent any integer (non-fractional value) in a limited range. A ''bool'' is an integer whose value can be only 0 (meaning no or false) or 1 (meaning yes or true). ('''Note:''' the GLSL specification is deliberately vague on the ranges of the number types. It also points out that most hardware will actually use floating-point calculations for ''int'' variables, which implies that integer calculations will incur rounding overhead.)

The ''vector'' type is translated to a GLSL ''vec4'', whose ''x'', ''y'' and ''z'' components correspond to those of the Oolite vector, and whose ''w'' component is always 1.0.

The ''quaternion'' type can be translated to a ''mat4x4'' representing a rotation matrix, or to a ''vec4'' whose ''x'', ''y'', ''z'' and ''w'' components correspond to those of the Oolite quaternion.

The ''matrix'' type is translated into a GLSL ''mat4x4''.

The ''colour'' type is translated into a GLSL ''vec4'' type, whose ''r'', ''g'', ''b'' and ''a'' components correspond to those of the Oolite colour object.

==== Conversions ====
Several types of binding can be modified by conversion options, specified in the '''uniforms''' dictionary, for example:
haveFuel =
{
binding = "fuel";
clamped = true;
};
The '''clamped''' conversion option, when applied to a property of type ''float'', causes the value to be clamped to the range [0, 1]. When applied to an ''int'' property, any value other than 0 (including negative values) is converted to 1. The default value is ''false''.

The '''normalized''' option causes vector properties to be normalized, that is, scaled so they have the same direction but length 1. The default value is ''false''.

The '''asMatrix''' option causes quaternion properties to be converted to rotation matrix, rather than having their components packed into a ''vec4''. The default value is ''true''.

=== Bindable property reference ===
The following sections list entity properties which can be used in a uniform binding, regardless of apparent usefullness. Note, however, that '''some of these names may change before the next stable release'''.

==== Entity ====
The following properties are available for all entities:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable entity properties
! Name !! Type !! Description
|-
| ''position'' || vector || The location of the entity in system co-ordinates.
|-
| ''orientation'' || quaternion || The orientation of the entity.
|-
| ''relativePosition'' || vector || The location of the entity, relative to the player.
|-
| ''viewpointOffset'' || vector || The location of the current camera, in entity co-ordinates. Although this is defined for all entities, it is only meaningful for the player ship.
|-
| ''collisionRadius'' || float || Together with the ''position'', specifies a sphere completely containing the collidable volume of the entity.
|-
| ''mass'' || float || The mass of the entity.
|-
| ''energy'' || float || The current energy level of the entity.
|-
| ''maxEnergy'' || float || The current maximum energy level of the entity.
|-
| ''universalTime'' || float || The [[Time scales in Oolite#game real time|game real time]] clock. The value is the same for all entities and updates once per frame.
|-
| ''spawnTime'' || float || The [[Time scales in Oolite#game real time|game real time]] at which the entity came into existance.
|-
| ''timeElapsedSinceSpawn'' || float || The number of seconds (in the [[Time scales in Oolite#game real time|game real time]] scale) since the entity came into existance – the difference between ''universalTime'' and ''spawnTime''.
|-
| ''throwingSparks'' || bool || Whether the entity is generating sparks (for instance, a ship about to explode).
|-
| ''fogUniform'' (version 1.83) || vector || Atmosphere colour rgba for applying fog effect. Alpha channel is zero for no fogging to 1 for full fogging.
|-
|}

==== Ship ====
Ships (i.e., anything set up in ''shipdata.plist'', regardless of function) have all the properties of [[#Entity|entities]], and several others:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable ship properties
! Name !! Type !! Description
|-
| ''isBeacon'' || bool || True if the entity is a beacon.
|-
| ''isFrangible'' || bool || True if the entity is frangible, i.e. subentities can be shot off.
|-
| ''isCloaked'' || bool || True if the entity is cloaked. [b]Note:[/b] a cloaked ship will only be drawn approximately once per ten frames, regardless of shaders.
|-
| ''isJammingScanning'' || bool || True if the ship has an active military jammer.
|-
| ''hasMilitaryScannerFilter'' || bool || True if the ship has a military scanner filter.
|-
| ''messageTime'' || float || Time before a radio message may be sent, in seconds. (This is set to 6.0 seconds when an NPC ship sends a message, and decreases over time.)
|-
| ''groupID'' || int || Unique identifier for the escort group the ship belongs to.
|-
| ''escortCount'' || int || The number of active escorts the ship has.
|-
| ''hasHostileTarget'' || bool || True if the ship has a target and the ship’s current AI behaviour is one of hostile intent.
|-
| ''weaponRange'' || float || Maximum range (in metres) of the ship’s main weapon. [b]Note:[/b] since subentities’ shaders get the parent ship’s properties, this may not work as expected.
|-
| ''scannerRange'' || float || The distance (in metres) in which the ship will scan for enemies.
|-
| ''withinStationAegis'' || bool || True if the ship is within the aegis of the system’s main station.
|-
| ''fuel'' || int || Ship’s fuel level, in tenths of a light year.
|-
| ''flightPitch'' || float || Current pitch rate.
|-
| ''flightRoll'' || float || Current roll rate.
|-
| ''flightYaw'' || float || Current yaw rate. Currently always 0 for NPC ships.
|-
| ''flightSpeed'' || float || Ship’s current speed.
|-
| ''maxFlightSpeed'' || float || Ship’s speed at full throttle. Something of a misnomer – actual speed may be higher using afterburners or hyperspeed.
|-
| ''speedFactor'' || float || ''flightSpeed'' divided by ''maxFlightSpeed''. May be greater than 1.0 (unless [[#Conversions|clamped]] is used).
|-
| ''damage'' || int || ''energy'' expressed as a percentage of ''maxEnergy''.
|-
| ''laserHeatLevel'' || float || The temperature level of the current weapon.
|-
| ''hullHeatLevel'' || float || The temperature level of the hull, due to proximity to stars, atmospheric drag or combat hits. When it reaches 1.0, the ship starts taking damage rapidly.
|-
| ''entityPersonality'' || float || A randomly-generated value in the range 0.0 to 1.0 that stays with the entity for its lifetime. Useful for adding random variations.
|-
| ''entityPersonalityInt'' || float || Same as ''entity_personality'', scaled to the range 0 to 32767.
|-
| ''numberOfScannedShips'' || int || The number of ships within scanner range (but no more than 16).
|-
| ''destination'' || vector || The location, in system co-ordinates, that the AI is trying to fly to. This may not always be meaningful depending on AI state.
|-
| ''rangeToDestination'' || float || The distance in metres between ''position'' and ''destination''.
|-
| ''rangeToPrimaryTarget'' || float || The distance in metres to the AI’s target (i.e., the ship it is trying to shoot). 0 if no target.
|-
| ''laserColor'' || colour || The colour of the ship’s laser.
|-
| ''isHulk'' || bool || True if the ship has been abandoned.
|-
| ''lightsActive'' || bool || True if flashers are turned on, false otherwise.
|-
| ''alertCondition'' (1.77 or later) || int || Current alert condition – 0 for docked, 2 for yellow, 3 for red.
|-
|}

==== Player ship ====
The player ship has all the properties of [[#Entity|entities]] and [[#Ship|ships]], and several others:
{| class="wikitable" border="1" cellpadding="3" cellspacing="0"
|+ Bindable player ship properties
! Name !! Type !! Description
|-
| ''massLocked'' || bool || True if the ship is too close to a large object to be able to make a witchspace jump.
|-
| ''atHyperspeed'' || bool || True if the ship is at hyperspeed.
|-
| ''velocityVector'' || vector || The ship’s velocity.
|-
| ''dialForwardShield'' || float || The forward shield level, ranging from 0.0 to 1.0.
|-
| ''dialAftShield'' || float || The aft shield level, ranging from 0.0 to 1.0.
|-
| ''dialMissileStatus'' || int || State of selected missile – 0 for safe/no missile, 1 for active, 2 for locked.
|-
| ''dialFuelScoopStatus'' || int || State of cargo scoop – 0 for no scoop installed, 1 for full hold, 2 for idle with space in hold, 3 for actively scooping.
|-
| ''compassMode'' || int || State of advanced space compass – 0 for no advanced space compass installed, 1 for planet mode, 2 for station mode, 3 for sun mode, 4 for target mode, 5 for any beacon. More may be added in future.
|-
| ''activeMissile'' || int || Which missile slot is currently selected, from 0 to ''dialMaxMissiles'' - 1.
|-
| ''dialMaxMissiles'' || int || The number of missile slots on the ship.
|-
| ''dialIdentEngaged'' || bool || True if ident (targeting) mode is active.
|-
| ''alertCondition'' || int || Current alert condition – 0 for docked, 1 for green, 2 for yellow, 3 for red.
|-
| ''trumbleCount'' || int || Number of trumbles with which the player’s ship is infected.
|-
|}
Additionally, all [[Methods#Querying states|state query scripting methods]] ending with ''_number'' may be used for the player.

[[Category:Oolite]]
[[Category:Oolite scripting]]

Hidden Settings in Oolite

2015-05-12T20:49:26Z

Kanthoney: Document fix for git issue 136.

[[Oolite]] has a number of settings that are potentially interesting for advanced users – mostly those working on [[OXP]]s – or for those who are experiencing graphical problems. This article focuses on settings stored on disk; for other tools that can be used while the game is running, see [[Debugging Facilities in Oolite]]. All changes described below should be made when the game is not running.

All of these settings were introduced at some point after Oolite 1.65, and as such only apply to test releases at the moment.

== Startup Parameters ==
=== Windows ===

In Windows you can add a parameter to Oolite's shortcut (so that instead of pointing at C:\Oolite\oolite.app\oolite.exe it'll point at C:\Oolite\oolite.app\oolite.exe ''parameter''). [[:File:Oolite_Windows_Shortcut_Parameters.jpg|See here for an example.]]

=== Available parameters ===
The parameters are:

* -nosplash
This removes the splash screen that appears when loading, and is useful to fix some graphical issues with certain graphics cards.
* -splash
This forces Oolite to always display the splash screen. If you try to use both -splash and -nosplash, -nosplash "wins".
* -fullscreen
This forces Oolite to start in fullscreen mode, not windowed.
* -noshaders
This forces shaders to be disabled when loading. This may be useful on some older graphics cards (e.g. the Intel GMA series) which report shader support to Oolite but don't do it particularly well.
* -load path_to_savegame
This forces Oolite to load the specified saved game. Use the full path, eg: -load c:\oolite\oolite.app\oolite-saves\Jameson.oolite-save
* -verify-oxp path_to_oxp
Rather than starting Oolite, perform some basic syntax checks on the OXP at the specified path. This is only available in the OXP developer builds of Oolite.

== Changing settings ==
=== Mac OS X ===
For Oolite under Mac OS X, there are several ways to modify these settings.
* Most of them can be set with the [http://secrets.blacktree.com/ Secrets preference pane] for Mac OS X 10.5. (download the tool by selecting the "prefPane" option on the top right, click the downloaded prefPane to install it, choose Oolite in the list on the left)
* If you have Xcode tools installed, they can be edited with Property List Editor. The preferences file can be found at ~/Library/Preferences/org.aegidian.oolite.plist. (This is human-readable in Mac OS X 10.3.9 and earlier, but binary in 10.4 and later.)
* On all systems, the <code>defaults</code> command line tool can be used. To set a boolean value, use: <code>defaults write org.aegidian.oolite '''key''' -bool YES</code> (or <code>NO</code>). For numerical values, use <code>defaults write org.aegidian.oolite '''key''' 42</code>.

=== Windows, Linux and other platforms ===
For platforms other than Mac OS X, you must edit a text file called .GNUstepDefaults. This file is created when you change a preference in Oolite, then quit.

Under Windows, this file is found at <code><Oolite installation directory>\oolite.app\GNUstep\Defaults\.GNUstepDefaults</code>.

Under Linux and other platforms, the file is at <code>~/GNUstep/Defaults/.GNUstepDefaults</code>. Since its name starts with a full stop, it is hidden by default. If you’re using Gnome/Nautilus or KDE/Konqueror, you can show it by selecting Show Hidden Files from the View menu. In any event, it should be accessible from the command line.

The .GNUstepDefaults file is a kind of [[property list]], but uses a slightly different syntax than usual; you may see values like <code><*I300></code>. However, when you edit it by hand it’s safe to write numbers in plain form, and booleans are written as <code>YES</code> or <code>NO</code>. All Oolite settings are in the dictionary named “oolite”.

== Settings ==
=== Graphics ===
'''Key:''' max-texture-size 
'''Type:''' integer 
'''Default:''' Determined by graphics card and driver, typically 4096. 
'''Minimum:''' 64 
Limit the size (side length) of textures; textures larger than this size will be scaled down. The value should be a power of two; if it isn’t, it will be rounded '''up''' to the next power of two. '''Note:''' if reduced detail mode is enabled, textures with a side length larger than 512 pixels will be scaled down to half their size regardless of this setting. (This is done independently on each side; for instance, a 1024×2048 pixel texture will be scaled down to 512×1024 pixels, while a 512×1024 pixel texture will be scaled to 512×512 pixels.)

'''Key:''' polygon-sprite-dump-svg 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.74 
Test release 1.74 uses a more sophisticated mechanism for drawing missile and mine icons, which involves turning each one into two sets of triangles. This setting causes the generated triangle data to be written to SVG files in the logs folder.

'''Key:''' sky-render-inset-coords 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
If set to <code>YES</code>, the outermost edges of stars and nebula parts will be cut off. This is intended to help with a rendering problem where boxes are drawn around stars and nebula parts on certain systems with defective graphics drivers.

'''Key:''' splash-screen 
'''Type:''' boolean 
'''Default:''' <code>YES</code> 
'''Introduced:''' 1.73.4 
If set to <code>NO</code>, Oolite will not show the splash screen while loading. This works around a problem which causes some Windows systems with NVIDIA graphics accelerators to fall back to software rendering. No effect on Mac OS X.

'''Key:''' texture-anisotropy-scale 
'''Type:''' real 
'''Default:''' 0.5 
'''Range:''' 0–1 
'''Introduced:''' 1.73/1.72.3 (implementation was previously broken) 
Anisotropic filtering is a technique that improves the clarity of textures seen at a shallow angle, but has a significant performance cost. This setting changes the amount of anisotropic filtering applied, with 0 meaning none and 1 meaning as much as supported by your graphics hardware and drivers.

'''Key:''' use-texture-lod-bias 
'''Type:''' boolean 
'''Default:''' <code>YES</code> 
'''Introduced:''' 1.73 
Texture LOD bias is an extension used to control the tradeoff between blurriness and graphical artefacts in textures. On certain ATi hardware under Windows, the use of texture LOD bias causes graphical problems, notably untextured stars and nebulae.

'''Key:''' dump-synthesized-shaders 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.77 
Dumps the synthesized shaders that will be introduced in 1.77 in a folder beside the normal log.

=== Logging ===
'''Key:''' logging-echo-to-stderr 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
If set to <code>YES</code>, log messages are written to the standard error output as well as the log file.

'''Key:''' logging-show-function 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
If set to <code>YES</code>, log messages will be prefixed with the function or method in which they occurred. This is of limited use.

'''Key:''' logging-show-file-and-line 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
If set to <code>YES</code>, log messages will be prefixed with the source code location where they occurred. This is potentially convenient for developers.

'''Key:''' logging-show-time 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
If set to <code>YES</code>, log messages will be prefixed with the time on which they occurred. The time string is of the format hh:mm:ss.mil. This is potentially convenient for developers.

'''Key:''' logging-show-class 
'''Type:''' boolean 
'''Default:''' <code>YES</code> (but disabled when running the OXP verifier) 
If set to <code>YES</code>, log messages will be prefixed with their log message class, an identifier that can be used to enable or disable messages by editing ''[[logcontrol.plist]]''.

=== OXP verifier ===
All keys in this section are only relevant for the OXP Developer builds of Oolite.

'''Key:''' enforce-oxp-standards 
'''Type:''' integer 
'''Default:''' <code>1</code> 
'''Available:''' Oolite 1.81 onwards
This sets the level of run time checking of OXP standards.

* '''0''': Off (always the case in standard builds, regardless of this setting)
* '''1''': Warn (logs if deprecated or other common errors are found, default in OXP Developer builds)
* '''2''': Enforce (as 1, and it where possible will disable deprecated content)
* '''3''': Quit (as 1, and after reporting the error will immediately exit Oolite

Setting a higher level than the default may be useful for some styles of OXP development, though is unlikely to be suitable for playing the game.

'''Key:''' oxp-verifier-dump-debug-graphviz 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
If set to <code>YES</code>, a [http://www.graphviz.org/ Graphviz] dot file named ''OXPVerifierStageDependencies.dot'' will be generated (in the <code>../Oolite/Oolite.app/Logs/</code> folder) when the OXP verifier is run. This is used to analyze and debug the OXP verifier and is of little interest to end-users, unless they like technical-looking graphs. (If you do like technical-looking graphs, see '''[[#Miscellaneous|universe-dump-debug-graphviz]]''' below.)

'''Key:''' oxp-verifier-open-log 
'''Type:''' boolean 
'''Default:''' <code>YES</code> 
'''Platform:''' Mac OS X only. 
If set to <code>YES</code>, the log file will be opened after the OXP verifier is run.

'''Key:''' plist-schema-verifier-dump-structure 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
If set to <code>YES</code>, OXP verifier logs will be filled with meaningless gobbledegook. (The [[property list|plist]] schema verifier is a tool used to verify the structure of property lists, currently used only for ''[[shipdata.plist]]'' entries. This setting causes detailed information to be logged for every property list element inspected by the verifier. It is unlikely to be useful except for debugging the verifier.)

=== Miscellaneous ===
'''Key:''' always-flush-cache 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.73 
If set to <code>YES</code>, the data cache will be rebuilt each time Oolite runs. This is roughly equivalent to placing a brick on your shift key.

'''Key:''' debug-show-extra-menu-items 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
Mac-specific: if set to <code>YES</code>, a few extra menu items appear in the Debug menu when the [[Debug OXP]] is installed (specifically, ''Graphics Reset'', ''Clear Texture Cache'', ''Reset and Clear'' and ''Clear All Caches'').

'''Key:''' disable-operation-queue-work-manager 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.74 
Test release 1.74 introduces a new way of managing certain operations, primarily texture loading, under Mac OS X 10.5 and later, which should also automatically be used with GNUstep 0.20 and later. In the event that this causes problems, it can be disabled with this preference.

'''Key:''' dump-stack-for-errors 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.75 
(Test releases only) If this preference is set, additional debugging information is logged when a script encounters an error. If the [[Debug OXP]] is active, this is ignored in favour of the setting <code>debugConsole.dumpStackForErrors</code> (which defaults to <code>true</code>).

'''Key:''' dump-stack-for-warnings 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.75 
(Test releases only) If this preference is set, additional debugging information is logged when a script encounters an warning. If the [[Debug OXP]] is active, this is ignored in favour of the setting <code>debugConsole.dumpStackForWarnings</code> (which defaults to <code>true</code>).

'''Key:''' escape-pod-activation-immediate 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.75 
If true, the escape pod is activated by a single key press. If false, two key presses are needed (except in strict mode).

'''Key:''' generate-ai-graphviz 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.74 
When enabled, each time an AI is loaded (uncached), a [http://www.graphviz.org/ Graphviz] dot file is generated showing the AI’s states and the transitions between them. For an example, see [http://jens.ayton.se/oolite/ai-graphs/hardMissileAI.plist.pdf hardMissileAI.plist.pdf].

'''Key:''' groolite-disable 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.74 
Completely disables Growl integration (Mac OS X only).

'''Key:''' mouse-control-in-windowed-mode 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
'''Introduced:''' 1.74 
Enables the player to use mouse control in windowed Oolite.

'''Key:''' universe-dump-debug-graphviz 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
If set to <code>YES</code>, various [http://www.graphviz.org/ Graphviz] dot files will be generated (in the <code>../Oolite/Oolite.app/Logs/</code> folder) when Oolite starts. At the moment, this means ''SystemDescription.dot'', which is used to analyze the '''system_description''' table in ''[[descriptions.plist]]''. This is primarily useful to those writing localization OXPs.

'''Key:''' issue_136_fix 
'''Type:''' boolean 
'''Default:''' <code>NO</code> 
This is a workaround for a graphical glitch on Macs with a retina display which affects the short range chart - see the issue at [https://github.com/OoliteProject/oolite/issues/136 github]. Set to <code>YES</code> to enable.

[[Category:Oolite]]