Difference between revisions of "Oolite JavaScript Reference: World script event handlers"
Eric Walch (talk | contribs) (shipTargetLost: removed an old 1.71 remark) |
m (minor elaboration) |
||
(85 intermediate revisions by 13 users not shown) | |||
Line 1: | Line 1: | ||
− | This page provides |
+ | 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. |
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. |
||
Line 6: | Line 6: | ||
World scripts are always active. |
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 === |
=== Game State === |
||
− | ==== <code> |
+ | ==== <code>gamePaused</code> ==== |
+ | {{oolite-method-added|1.81}} |
||
− | The <code>startUp</code> handler is called after all OXPs have been loaded. It can be used to do one-off initialisation such as registering to listen for certain keystrokes etc. note that keystroke listening is not implemented. (world script only) |
||
+ | 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. |
+ | this.gamePaused = function() |
{ |
{ |
||
// Your code here |
// Your code here |
||
} |
} |
||
− | ==== <code> |
+ | ==== <code>gameResumed</code> ==== |
+ | {{oolite-method-added|1.81}} |
||
− | The <code>reset</code> handler is called whenever the player is respawned, such as after dying or when loading a saved game. It should be used to reset any local state in the script. (world script only) |
||
+ | 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. |
+ | this.gameResumed = function() |
{ |
{ |
||
// Your code here |
// Your code here |
||
} |
} |
||
− | in 1.74 the startUp event is called in its place, eliminating the need for two separate events. |
||
+ | ==== <code>playerWillSaveGame</code> ==== |
||
− | |||
− | ==== <code>playerWillSaveGame</code> ==== |
||
− | {{Oolite-prop-added|1.75}}<br> |
||
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' |
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' |
||
Line 40: | Line 39: | ||
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. |
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 === |
=== Docking === |
||
Line 63: | Line 81: | ||
} |
} |
||
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. |
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> ==== |
==== <code>shipWillLaunchFromStation</code> ==== |
||
Line 77: | Line 94: | ||
==== <code>shipLaunchedFromStation</code> ==== |
==== <code>shipLaunchedFromStation</code> ==== |
||
− | The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect. |
+ | The <code>shipLaunchedFromStation</code> handler is called at the end of the launch tunnel effect. The argument passed to the handler function is the station entity from which the ship was launched. |
− | this.shipLaunchedFromStation = function( |
+ | this.shipLaunchedFromStation = function(stationLaunchedFrom) |
{ |
{ |
||
// Your code here |
// Your code here |
||
} |
} |
||
+ | |||
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT". |
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT". |
||
==== <code>playerStartedAutoPilot</code> ==== |
==== <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. |
+ | The <code>playerStartedAutoPilot</code> handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command. The handler is called with an argument containing the station entity that is the docking target. |
− | this.playerStartedAutoPilot = function() |
+ | this.playerStartedAutoPilot = function(stationForDocking) |
{ |
{ |
||
// Your code here |
// Your code here |
||
} |
} |
||
− | |||
==== <code>playerCancelledAutoPilot</code> ==== |
==== <code>playerCancelledAutoPilot</code> ==== |
||
Line 104: | Line 121: | ||
} |
} |
||
+ | ==== <code>playerDockingClearanceCancelled</code> ==== |
||
+ | {{oolite-method-added|1.85}} |
||
+ | |||
+ | The <code>playerDockingClearanceCancelled</code> handler is called when the player withdraws their request to dock at a station. |
||
+ | |||
+ | this.playerDockingClearanceCancelled = 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>playerDockingClearanceGranted</code> ==== |
||
+ | {{oolite-method-added|1.85}} |
||
+ | |||
+ | The <code>playerDockingClearanceGranted</code> handler is called when the player is given permission to dock at a station. If the player is given immediate clearance to dock, this event will be called immediately after the <code>playerRequestedDockingClearance</code> event. If, however, the station is unable to give immediate clearance, then there will be some delay between the request to dock and permission being granted. This event will be called when the station actually gives docking clearance. |
||
+ | |||
+ | this.playerDockingClearanceGranted = function() |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
==== <code>playerDockingRefused</code> ==== |
==== <code>playerDockingRefused</code> ==== |
||
Line 113: | Line 159: | ||
// Your code here |
// Your code here |
||
} |
} |
||
− | |||
==== <code>playerRequestedDockingClearance</code> ==== |
==== <code>playerRequestedDockingClearance</code> ==== |
||
Line 125: | Line 170: | ||
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". |
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 === |
=== Witchspace Jumps === |
||
Line 130: | Line 219: | ||
==== <code>playerStartedJumpCountdown</code> ==== |
==== <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>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) |
+ | this.playerStartedJumpCountdown = function(type, seconds) |
{ |
{ |
||
// Your code here |
// Your code here |
||
} |
} |
||
− | |||
==== <code>playerCancelledJumpCountdown</code> ==== |
==== <code>playerCancelledJumpCountdown</code> ==== |
||
Line 150: | Line 238: | ||
==== <code>playerJumpFailed</code> ==== |
==== <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 <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><sup>2</sup> >= 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) |
this.playerJumpFailed = function(reason) |
||
Line 156: | Line 244: | ||
// Your code here |
// Your code here |
||
} |
} |
||
− | |||
==== <code>shipWillEnterWitchspace</code> ==== |
==== <code>shipWillEnterWitchspace</code> ==== |
||
Line 162: | Line 249: | ||
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. |
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) |
this.shipWillEnterWitchspace = function(cause) |
||
{ |
{ |
||
Line 167: | Line 255: | ||
} |
} |
||
+ | 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> ==== |
==== <code>shipWillExitWitchspace</code> ==== |
||
Line 263: | Line 358: | ||
==== <code>alertConditionChanged</code> ==== |
==== <code>alertConditionChanged</code> ==== |
||
− | The <code>alertConditionChanged</code> handler is called when the player’s alert status (<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) |
this.alertConditionChanged = function(newCondition, oldCondition) |
||
Line 275: | Line 370: | ||
this.playerTargetedMissile = function(missile) |
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 |
// Your code here |
||
Line 302: | Line 406: | ||
this.shipBeingAttackedByCloaked = function() |
this.shipBeingAttackedByCloaked = function() |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | ==== <code>shipKilledOther</code> ==== |
||
+ | {{oolite-method-added|1.75}} |
||
+ | |||
+ | 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. |
||
+ | |||
+ | this.shipKilledOther = function(whom : ship, damageType : string) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | ==== <code>shipReleasedEquipment</code> ==== |
||
+ | |||
+ | The <code>shipReleasedEquipment</code> handler is called when a ship launches a mine (a pylon-mounted equipment item whose key ends with "_MINE"). <code>mine</code> contains the launched mine entity. |
||
+ | |||
+ | this.shipReleasedEquipment = function(mine) |
||
{ |
{ |
||
// Your code here |
// Your code here |
||
Line 308: | Line 431: | ||
==== <code>shipTargetDestroyed</code> ==== |
==== <code>shipTargetDestroyed</code> ==== |
||
− | The <code>shipTargetDestroyed</code> handler is called when the target gets destroyed. <code>target</code> contains the destroyed target entity. This command is always preceded by the <code>shipTargetLost</code> handler. |
+ | 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) |
this.shipTargetDestroyed = function(target) |
||
Line 328: | Line 451: | ||
==== <code>shipFiredMissile</code> ==== |
==== <code>shipFiredMissile</code> ==== |
||
− | {{Oolite-prop-added|1.74}}<br> |
||
+ | |||
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. |
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. |
||
Line 354: | Line 477: | ||
} |
} |
||
− | === Equipment === |
||
+ | ==== <code>weaponsSystemsToggled</code> ==== |
||
+ | {{oolite-method-added|1.85}} |
||
− | ==== <code>equipmentDestroyed</code> ==== |
||
+ | The <code>weaponsSystemsToggled</code> handler is called whenever the player toggles their weapons systems on or off. The <code>state</code> parameter contains the new state of the weapons systems |
||
− | |||
− | The <code>equipmentDestroyed</code> handler is called when equipment gets destroyed completely beyond repair. (in strict mode) (world script only) |
||
− | this. |
+ | this.weaponsSystemsToggled = function(state : boolean) |
{ |
{ |
||
// Your code here |
// 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> ==== |
==== <code>equipmentDamaged</code> ==== |
||
− | The <code>equipmentDamaged</code> handler is called when equipment |
+ | The <code>equipmentDamaged</code> handler is called when equipment gets damaged. (world script only) |
this.equipmentDamaged = function(equipment) |
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 |
// Your code here |
||
Line 378: | Line 544: | ||
The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen. |
The <code>playerBoughtEquipment</code> handler is called when equipment is bought at the outfit screen. |
||
− | this.playerBoughtEquipment = function(equipment) |
+ | this.playerBoughtEquipment = function(equipment, paid) |
{ |
{ |
||
// Your code here |
// Your code here |
||
} |
} |
||
+ | |||
+ | The 'paid' parameter is added from 1.89 onwards. This is the amount of credits the player paid for the equipment, including any refunds that might have been applied during the purchase (eg when purchasing a laser and installing it in a position where a laser is already fitted, the cost of the current laser will be refunded to the player during the purchase). |
||
==== <code>playerBoughtNewShip</code> ==== |
==== <code>playerBoughtNewShip</code> ==== |
||
Line 387: | Line 555: | ||
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. |
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) |
+ | this.playerBoughtNewShip = function(ship, price) |
{ |
{ |
||
// Your code here |
// 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|<code>player.replaceShip</code>]] |
||
+ | |||
+ | '''Note:''' In a future release of Oolite, <code>playerBoughtNewShip</code> will no longer be fired when the ship is replaced using the [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]] function. Instead, the <code>[[#playerReplacedShip|playerReplacedShip]]</code> event should be used. At the moment, both events (<code>playerBoughtNewShip</code> and <code>playerReplacedShip</code>) will fire. |
||
+ | |||
+ | '''See also:''' <code>[[#playerWillBuyNewShip|playerWillBuyNewShip]]</code> |
||
+ | |||
+ | ==== <code>playerChangedPrimedEquipment</code> ==== |
||
+ | {{Oolite-method-added|1.85}} |
||
+ | |||
+ | The <code>playerChangedPrimedEquipment</code> handler is called whenever the player changes the currently primed equipment (either with shift-n or ctrl-shift-n). The equipment key of the newly primed equipment will be passed as an argument. |
||
+ | |||
+ | this.playerChangedPrimedEquipment = function(equipmentKey) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | ==== <code>playerReplacedShip</code> ==== |
||
+ | {{Oolite-method-added|1.89}} |
||
+ | |||
+ | The <code>playerReplacedShip</code> handler is called when the player ship is replaced via the JS method [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]]. May be needed to re-evaluate the old equipment as replacing a ship does not trigger equipment removal. |
||
+ | |||
+ | this.playerReplacedShip = function(ship) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | '''See also:''' <code>[[#playerWillReplaceShip|playerWillReplaceShip]]</code> |
||
+ | |||
+ | ==== <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.<br>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 |
||
+ | } |
||
+ | |||
+ | ==== <code>playerWillBuyNewShip</code> ==== |
||
+ | {{Oolite-method-added|1.89}} |
||
+ | |||
+ | The <code>playerWillBuyNewShip</code> handler is called just before 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.playerWillBuyNewShip = function(dataKey, shipyard, price, tradeIn) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | <code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased. |
||
+ | |||
+ | <code>shipyard</code> is a dictionary object containing details about the ship being purchased, with information similar to the following: |
||
+ | { |
||
+ | short_description: "Python: Plus Galactic Hyperdrive. Extra Energy Unit. Docking Computers. E.C.M. System. Forward weapon upgraded to military laser. Price 215 000 ₢.", |
||
+ | shipdata_key: "python-player", |
||
+ | id: "675b6b-c60a74", |
||
+ | price: 215000, |
||
+ | ship: { |
||
+ | ...''[[shipdata.plist]]'' details of ship... |
||
+ | }, |
||
+ | personality: 9807, |
||
+ | extras: ["EQ_GAL_DRIVE", "EQ_FUEL_SCOOPS", "EQ_ENERGY_UNIT", "EQ_FUEL_INJECTION", "EQ_DOCK_COMP", "EQ_ECM"] |
||
+ | } |
||
+ | |||
+ | <code>price</code> is the amount being paid the for ship. |
||
+ | |||
+ | <code>tradeIn</code> is the trade in value of the current ship. |
||
+ | |||
+ | '''See also:''' <code>[[#playerBoughtNewShip|playerBoughtNewShip]]</code> |
||
+ | |||
+ | ==== <code>playerWillReplaceShip</code> ==== |
||
+ | {{Oolite-method-added|1.89}} |
||
+ | |||
+ | The <code>playerWillReplaceShip</code> handler is called just before a ship is replaced using the [[Oolite JavaScript Reference: Player#replaceShip|<code>player.replaceShip</code>]] function. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal. |
||
+ | |||
+ | this.playerWillReplaceShip = function(dataKey) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | <code>dataKey</code> is the shipdata.plist <code>dataKey</code> for the ship being purchased. |
||
+ | |||
+ | '''See also:''' <code>[[#playerReplacedShip|playerReplacedShip]]</code> |
||
=== Other === |
=== Other === |
||
+ | |||
+ | ==== <code>chartHightlightModeChanged</code> ==== |
||
+ | {{oolite-method-added|1.87}} |
||
+ | |||
+ | The <code>chartHighlightModeChanged</code> handler is called whenever the highlight mode of the galactic chart is changed, either manually (from player input), or programmatically (by code setting the mode with <code>player.ship.chartHightlightMode</code>. "newMode" is the new mode of the chart highlight, and will be one of the following: |
||
+ | |||
+ | OOLRC_MODE_SUNCOLOR |
||
+ | OOLRC_MODE_ECONOMY |
||
+ | OOLRC_MODE_GOVERNMENT |
||
+ | OOLRC_MODE_TECHLEVEL |
||
+ | |||
+ | this.chartHightlightModeChanged = function(newMode) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
==== <code>compassTargetChanged</code> ==== |
==== <code>compassTargetChanged</code> ==== |
||
− | {{Oolite-prop-added|1.74}}<br> |
||
+ | |||
The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following: |
The <code>compassTargetChanged</code> handler is called when a new target is selected. Mode can be any of the following: |
||
Line 411: | Line 695: | ||
{ |
{ |
||
log(' Now targeting ' + whom); |
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>escapePodSequenceOver</code> ==== |
||
+ | |||
+ | The <code>escapePodSequenceOver</code> handler is called at the end of the escape pod sequence, after the <code>shipLaunchedEscapePod</code> event and just prior to the <code>shipWillDockWithStation</code> and <code>shipDockedWithStation</code> events. |
||
+ | |||
+ | Use this function if you need to override the destination for the escape pod with the player method [[Oolite_JavaScript_Reference:_Player#setEscapePodDestination|<code>player.setEscapePodDestination()</code>]]. |
||
+ | |||
+ | this.escapePodSequenceOver = function() |
||
+ | { |
||
// Your code here |
// Your code here |
||
} |
} |
||
Line 416: | Line 721: | ||
==== <code>guiScreenChanged</code> ==== |
==== <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 |
+ | 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)<br> |
+ | 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) |
this.guiScreenChanged = function(to, from) |
||
Line 424: | Line 729: | ||
==== <code>guiScreenWillChange</code> ==== |
==== <code>guiScreenWillChange</code> ==== |
||
− | {{Oolite-prop-added|1.74}}<br> |
||
+ | |||
− | The <code>guiScreenWillChange</code> handler is called when the guiScreen is about to change. It only fires for the screens: GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET and |
+ | 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) |
this.guiScreenWillChange = function(to, from) |
||
Line 431: | Line 736: | ||
// Your code here |
// Your code here |
||
} |
} |
||
+ | |||
+ | ==== <code>infoSystemChanged</code> ==== |
||
+ | {{oolite-method-added|1.83}} |
||
+ | |||
+ | 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. |
||
+ | |||
+ | this.infoSystemChanged = function(to, from) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | ==== <code>infoSystemWillChange</code> ==== |
||
+ | {{oolite-method-added|1.85}} |
||
+ | |||
+ | The <code>infoSystemWChange</code> handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart. |
||
+ | |||
+ | this.infoSystemWillChange = function(to, from) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | ==== <code>mfdKeyChanged</code> ==== |
||
+ | {{oolite-method-added|1.85}} |
||
+ | |||
+ | The <code>mfdKeyChanged</code> handler is called whenever the player changes the content of an MFD slot. The <code>activeMFD</code> parameter identifies which MFD slot is being changed, and the <code>mfdKey</code> specifies the key code now in use in this slot. |
||
+ | |||
+ | this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | '''See also:''' <code>[[Oolite JavaScript Reference: PlayerShip#setMultiFunctionDisplay|PlayerShip.setMultiFunctionDisplay()]]</code> |
||
==== <code>missionChoiceWasReset</code> ==== |
==== <code>missionChoiceWasReset</code> ==== |
||
Line 451: | Line 788: | ||
==== <code>missionScreenOpportunity</code> ==== |
==== <code>missionScreenOpportunity</code> ==== |
||
− | {{Oolite-prop-added|1.74}}<br> |
||
+ | |||
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) |
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) |
||
Line 462: | Line 799: | ||
==== <code>reportScreenEnded</code> ==== |
==== <code>reportScreenEnded</code> ==== |
||
− | {{Oolite-prop-added|1.73}} |
||
+ | |||
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) |
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) |
||
Line 470: | Line 807: | ||
} |
} |
||
− | ==== <code> |
+ | ==== <code>selectedMFDChanged</code> ==== |
+ | {{oolite-method-added|1.85}} |
||
− | The <code>shipCollided</code> handler is send after a collision with otherShip. |
||
+ | The <code>selectedMFDChanged</code> handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The <code>activeMFD</code> paramater is the index of the MFD which is now active. |
||
− | this. |
+ | this.selectedMFDChanged = function(activeMFD : integer) |
{ |
{ |
||
// Your code here |
// Your code here |
||
} |
} |
||
− | ==== <code> |
+ | ==== <code>shipCollided</code> ==== |
− | The <code>shipScoopedOther</code> handler is called when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) Other cargo, even scooping escapepods, doesn't trigger a handler.<br>The scooped item is transferred as argument. The scooped cargo itselfs gets the handler: <code>shipWasScooped</code> with the scooper as argument. |
||
+ | The <code>shipCollided</code> handler is send after a collision with otherShip. |
||
− | this. |
+ | this.shipCollided = function(otherShip) |
{ |
{ |
||
// Your code here |
// Your code here |
||
Line 490: | Line 827: | ||
==== <code>shipSpawned</code> ==== |
==== <code>shipSpawned</code> ==== |
||
− | The <code>shipSpawned</code> handler is called after |
+ | 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.<br> |
− | This handler for the |
+ | This handler for the worldScript 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) |
this.shipSpawned = function(ship) |
||
Line 500: | Line 837: | ||
==== <code>shipLaunchedEscapePod</code> ==== |
==== <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. |
+ | The <code>shipLaunchedEscapePod</code> handler is called when the player bails out. This will be followed by the <code>escapePodSequenceOver</code> event, and then a <code>shipWillDockWithStation()</code>/<code>shipDockedWithStation()</code> pair after a few seconds. |
this.shipLaunchedEscapePod = function(escapepod) |
this.shipLaunchedEscapePod = function(escapepod) |
||
Line 507: | Line 844: | ||
} |
} |
||
− | ==== <code> |
+ | ==== <code>systemInformationChanged</code> ==== |
+ | {{oolite-method-added|1.79}} |
||
− | The <code>tickle</code> handler is called periodically-ish, whenever the old [[property list|plist]] scripts are updated. For performance reasons, it is reccomended that you avoid using this if possible, but it may be needed until the planned timer mechanism is implemented. (world script and ship scripts) |
||
+ | 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. |
||
− | The <code>status</code> parameter is a string containing the player’s current status - “STATUS_IN_FLIGHT” and “STATUS_DOCKED” being commonly-seen examples. |
||
+ | 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. |
+ | this.systemInformationChanged = function(galaxy,system,key,newValue) |
{ |
{ |
||
// Your code here |
// Your code here |
||
Line 519: | Line 856: | ||
==== <code>viewDirectionChanged</code> ==== |
==== <code>viewDirectionChanged</code> ==== |
||
− | {{Oolite-prop-added|1.75}}<br> |
||
+ | |||
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", |
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_CUSTOM", |
||
Line 531: | Line 868: | ||
} |
} |
||
} |
} |
||
+ | |||
+ | === 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 === |
=== Missing Events === |
||
Line 538: | Line 895: | ||
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]. |
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: |
+ | '''See also:''' [[Oolite JavaScript Reference: Ship script event handlers|ship script event handlers]] |
Latest revision as of 13:50, 24 June 2020
This page provides a list of event handlers which can be implemented inside world scripts 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 this.variable
should have a name beginning with '_' or '$' - e.g. this._variable
or this.$variable
- to avoid potential conflicts with future event handlers (which will never start with '_' or '$').
Contents
- 1 Game State
- 2 Docking
- 2.1 shipWillDockWithStation
- 2.2 shipDockedWithStation
- 2.3 shipWillLaunchFromStation
- 2.4 shipLaunchedFromStation
- 2.5 playerStartedAutoPilot
- 2.6 playerCancelledAutoPilot
- 2.7 playerDockingClearanceCancelled
- 2.8 playerDockingClearanceExpired
- 2.9 playerDockingClearanceGranted
- 2.10 playerDockingRefused
- 2.11 playerRequestedDockingClearance
- 2.12 playerRescuedEscapePod
- 2.13 playerCompletedContract
- 2.14 playerEnteredContract
- 3 Witchspace Jumps
- 4 Enter/Exit Aegis
- 5 Combat
- 5.1 alertConditionChanged
- 5.2 playerTargetedMissile
- 5.3 shipAttackedOther
- 5.4 shipAttackedWithMissile
- 5.5 shipBeingAttacked
- 5.6 shipBeingAttackedByCloaked
- 5.7 shipKilledOther
- 5.8 shipReleasedEquipment
- 5.9 shipTargetDestroyed
- 5.10 shipDied
- 5.11 shipFiredMissile
- 5.12 shipTargetLost
- 5.13 shipTargetCloaked
- 5.14 weaponsSystemsToggled
- 6 Equipment and Cargo
- 6.1 equipmentAdded
- 6.2 equipmentDamaged
- 6.3 equipmentRemoved
- 6.4 equipmentRepaired
- 6.5 playerBoughtCargo
- 6.6 playerBoughtEquipment
- 6.7 playerBoughtNewShip
- 6.8 playerChangedPrimedEquipment
- 6.9 playerReplacedShip
- 6.10 playerSoldCargo
- 6.11 shipScoopedFuel
- 6.12 shipScoopedOther
- 6.13 playerWillBuyNewShip
- 6.14 playerWillReplaceShip
- 7 Other
- 7.1 chartHightlightModeChanged
- 7.2 compassTargetChanged
- 7.3 dayChanged
- 7.4 escapePodSequenceOver
- 7.5 guiScreenChanged
- 7.6 guiScreenWillChange
- 7.7 infoSystemChanged
- 7.8 infoSystemWillChange
- 7.9 mfdKeyChanged
- 7.10 missionChoiceWasReset
- 7.11 missionScreenEnded
- 7.12 missionScreenOpportunity
- 7.13 reportScreenEnded
- 7.14 selectedMFDChanged
- 7.15 shipCollided
- 7.16 shipSpawned
- 7.17 shipLaunchedEscapePod
- 7.18 systemInformationChanged
- 7.19 viewDirectionChanged
- 8 System population
- 9 Defunct
- 10 Missing Events
Game State
gamePaused
This method was added in Oolite test release 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 }
gameResumed
This method was added in Oolite test release 1.81.
This event is called when the game is resumed from pause. This is mainly useful for resuming sound playback paused in a gamePaused
handler.
this.gameResumed = function() { // Your code here }
playerWillSaveGame
The playerWillSaveGame
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.
startUp
The startUp
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 this.*
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.
startUpComplete
This method was added in Oolite test release 1.79.
The startUpComplete
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:
startUp
systemWillPopulate
(or an alternative handler specified by the system info)startUpComplete
Docking
shipWillDockWithStation
The shipWillDockWithStation
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"
shipDockedWithStation
The shipDockedWithStation
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.
shipWillLaunchFromStation
The shipWillLaunchFromStation
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".
shipLaunchedFromStation
The shipLaunchedFromStation
handler is called at the end of the launch tunnel effect. The argument passed to the handler function is the station entity from which the ship was launched.
this.shipLaunchedFromStation = function(stationLaunchedFrom) { // Your code here }
At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".
playerStartedAutoPilot
The playerStartedAutoPilot
handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command. The handler is called with an argument containing the station entity that is the docking target.
this.playerStartedAutoPilot = function(stationForDocking) { // Your code here }
playerCancelledAutoPilot
The playerCancelledAutoPilot
handler is called when the player cancels autopilot docking.
this.playerCancelledAutoPilot = function() { // Your code here }
playerDockingClearanceCancelled
This method was added in Oolite test release 1.85.
The playerDockingClearanceCancelled
handler is called when the player withdraws their request to dock at a station.
this.playerDockingClearanceCancelled = function() { // Your code here }
playerDockingClearanceExpired
This method was added in Oolite test release 1.83.
The playerDockingClearanceExpired
handler is called when the player exceeds the two minute window without requesting an extension
this.playerDockingClearanceExpired = function() { // Your code here }
playerDockingClearanceGranted
This method was added in Oolite test release 1.85.
The playerDockingClearanceGranted
handler is called when the player is given permission to dock at a station. If the player is given immediate clearance to dock, this event will be called immediately after the playerRequestedDockingClearance
event. If, however, the station is unable to give immediate clearance, then there will be some delay between the request to dock and permission being granted. This event will be called when the station actually gives docking clearance.
this.playerDockingClearanceGranted = function() { // Your code here }
playerDockingRefused
The playerDockingRefused
handler is called when a station refuses to provide autopilot docking instructions.
this.playerDockingRefused = function() { // Your code here }
playerRequestedDockingClearance
The playerRequestedDockingClearance
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".
playerRescuedEscapePod
This method was added in Oolite test release 1.81.
The playerRescuedEscapePod
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
ship.crew
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.
playerCompletedContract
This method was added in Oolite test release 1.81.
The playerCompletedContract
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.
playerEnteredContract
This method was added in Oolite test release 1.81.
The playerEnteredContract
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
playerStartedJumpCountdown
The playerStartedJumpCountdown
handler is called when the user starts a witchspace or galactic witchspace jump countdown. The type
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 seconds
parameter is a number specifying the number of seconds the countdown is running for.
this.playerStartedJumpCountdown = function(type, seconds) { // Your code here }
playerCancelledJumpCountdown
The playerCancelledJumpCountdown
handler is called when the user cancels a witchspace or galactic witchspace jump countdown.
this.playerCancelledJumpCountdown = function() { // Your code here }
playerJumpFailed
The playerJumpFailed
handler is called at the end of a witchspace or galactic witchspace countdown, if the jump is not possible. The reason
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
object mass
/object distance
2 >= 10.0, andobject distance
<= 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 }
shipWillEnterWitchspace
The shipWillEnterWitchspace
handler is called immediately before a witchspace jump, while the player is still in the starting system. The cause
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 player.ship.galacticHyperspaceBehaviour may be changed during shipWillEnterWitchspace
, 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 }
shipWillExitWitchspace
The shipWillExitWitchspace
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 }
shipExitedWitchspace
The shipExitedWitchspace
handler is called after a witchspace jump has concluded and the tunnel effect has been shown.
this.shipExitedWitchspace = function() { // Your code here }
playerEnteredNewGalaxy
The playerEnteredNewGalaxy
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
shipEnteredStationAegis
The shipEnteredStationAegis
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 }
shipExitedStationAegis
The shipExitedStationAegis
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 }
shipEnteredPlanetaryVicinity
The shipEnteredPlanetaryVicinity
handler is called when the player enters the planet aegis (3x planet radius).
this.shipEnteredPlanetaryVicinity = function(planet) { // Your code here }
shipExitedPlanetaryVicinity
The shipExitedPlanetaryVicinity
handler is called when the player leaves the planet aegis (3x planet radius).
this.shipExitedPlanetaryVicinity = function(planet) { // Your code here }
shipApproachingPlanetSurface
The shipApproachingPlanetSurface
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 }
shipLeavingPlanetSurface
The shipLeavingPlanetSurface
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
alertConditionChanged
The alertConditionChanged
handler is called when the player’s alert status (player.alertCondition
) changes. Only the player and stations have an alert condition. (world script and station scripts)
this.alertConditionChanged = function(newCondition, oldCondition) { // Your code here }
playerTargetedMissile
The playerTargetedMissile
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 }
shipAttackedOther
The shipAttackedOther
handler is called when the player hits another with a laser shot. other
is the identity of the ship being hit.
this.shipAttackedOther = function(other) { // Your code here }
shipAttackedWithMissile
The shipAttackedWithMissile
handler is called when a missile is fired. missile
contains the missile entity and whom
the identity of the ship that launched the missile.
this.shipAttackedWithMissile = function(missile, whom) { // Your code here }
shipBeingAttacked
The shipBeingAttacked
handler is called when a laser shot hits. whom
the identity of the ship that attacked.
this.shipBeingAttacked = function(whom) { // Your code here }
shipBeingAttackedByCloaked
The shipBeingAttackedByCloaked
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 }
shipKilledOther
This method was added in Oolite test release 1.75.
The shipKilledOther
handler is called when a ship kills an other ship. whom
the identity of the ship that was killed. damageType
is the type of damage.
this.shipKilledOther = function(whom : ship, damageType : string) { // Your code here }
shipReleasedEquipment
The shipReleasedEquipment
handler is called when a ship launches a mine (a pylon-mounted equipment item whose key ends with "_MINE"). mine
contains the launched mine entity.
this.shipReleasedEquipment = function(mine) { // Your code here }
shipTargetDestroyed
The shipTargetDestroyed
handler is called when the target gets destroyed by the player. target
contains the destroyed target entity. This command is always preceded by the shipTargetLost
handler.
this.shipTargetDestroyed = function(target) { // Your code here }
shipDied
The shipDied
handler is called when the ship or player dies. Expect a reset()
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)
shipFiredMissile
The shipFiredMissile
handler is called when a missile is fired. missile
contains the missile entity and target
the identity of the target. The handler is send to the ship that launched the missile.
this.shipFiredMissile = function(missile, target) { // Your code here }
shipTargetLost
The shipTargetLost
handler is called when the target gets lost. target
contains the lost target entity.
this.shipTargetLost = function(target) { // Your code here }
shipTargetCloaked
The shipTargetCloaked
handler is called when the target cloakes.
this.shipTargetCloaked = function() { // Your code here }
weaponsSystemsToggled
This method was added in Oolite test release 1.85.
The weaponsSystemsToggled
handler is called whenever the player toggles their weapons systems on or off. The state
parameter contains the new state of the weapons systems
this.weaponsSystemsToggled = function(state : boolean) { // Your code here }
Equipment and Cargo
equipmentAdded
This method was added in Oolite test release 1.81.
The equipmentAdded
handler is called whenever the player ship gains an item of equipment. This includes "gaining" of EQ_SOMETHING_DAMAGED
when an EQ_SOMETHING
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 equipmentRepaired
and playerBoughtEquipment
, and will also detect equipment addition by script.
equipmentDamaged
The equipmentDamaged
handler is called when equipment gets damaged. (world script only)
this.equipmentDamaged = function(equipment) { // Your code here }
equipmentRemoved
This method was added in Oolite test release 1.81.
The equipmentRemoved
handler is called whenever the player ship loses an item of equipment. This includes "losing" of EQ_SOMETHING_DAMAGED
when an EQ_SOMETHING
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 }
equipmentRepaired
This method was added in Oolite test release 1.77.
The equipmentRepaired
handler is called when equipment gets repaired. (world script only)
this.equipmentRepaired = function(equipment) { // Your code here }
playerBoughtCargo
This method was added in Oolite test release 1.77.
The playerBoughtCargo
handler is called when cargo is bought at the market screen. commodity
contains the non-localised name for the cargo. You can get the localised name using expandDescription("[commodity-name "+commodity+"]");
. price
is price per unit in tenths of a credit.
this.playerBoughtCargo = function(commodity, units, price) { // Your code here }
playerBoughtEquipment
The playerBoughtEquipment
handler is called when equipment is bought at the outfit screen.
this.playerBoughtEquipment = function(equipment, paid) { // Your code here }
The 'paid' parameter is added from 1.89 onwards. This is the amount of credits the player paid for the equipment, including any refunds that might have been applied during the purchase (eg when purchasing a laser and installing it in a position where a laser is already fitted, the cost of the current laser will be refunded to the player during the purchase).
playerBoughtNewShip
The playerBoughtNewShip
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 player.replaceShip
Note: In a future release of Oolite, playerBoughtNewShip
will no longer be fired when the ship is replaced using the player.replaceShip
function. Instead, the playerReplacedShip
event should be used. At the moment, both events (playerBoughtNewShip
and playerReplacedShip
) will fire.
See also: playerWillBuyNewShip
playerChangedPrimedEquipment
This method was added in Oolite test release 1.85.
The playerChangedPrimedEquipment
handler is called whenever the player changes the currently primed equipment (either with shift-n or ctrl-shift-n). The equipment key of the newly primed equipment will be passed as an argument.
this.playerChangedPrimedEquipment = function(equipmentKey) { // Your code here }
playerReplacedShip
This method was added in Oolite test release 1.89.
The playerReplacedShip
handler is called when the player ship is replaced via the JS method player.replaceShip
. May be needed to re-evaluate the old equipment as replacing a ship does not trigger equipment removal.
this.playerReplacedShip = function(ship) { // Your code here }
See also: playerWillReplaceShip
playerSoldCargo
This method was added in Oolite test release 1.77.
The playerSoldCargo
handler is called when cargo is sold at the market screen. commodity
contains the non-localised name for the cargo. You can get the localised name using expandDescription("[commodity-name "+commodity+"]");
. price
is price per unit in tenths of a credit.
this.playerSoldCargo = function(commodity, units, price) { // Your code here }
shipScoopedFuel
This method was added in Oolite test release 1.77.
The shipScoopedFuel
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 }
shipScoopedOther
The shipScoopedOther
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 shipWasScooped
with the scooper as argument.
this.shipScoopedOther = function(whom) { // Your code here }
playerWillBuyNewShip
This method was added in Oolite test release 1.89.
The playerWillBuyNewShip
handler is called just before 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.playerWillBuyNewShip = function(dataKey, shipyard, price, tradeIn) { // Your code here }
dataKey
is the shipdata.plist dataKey
for the ship being purchased.
shipyard
is a dictionary object containing details about the ship being purchased, with information similar to the following:
{ short_description: "Python: Plus Galactic Hyperdrive. Extra Energy Unit. Docking Computers. E.C.M. System. Forward weapon upgraded to military laser. Price 215 000 ₢.", shipdata_key: "python-player", id: "675b6b-c60a74", price: 215000, ship: { ...shipdata.plist details of ship... }, personality: 9807, extras: ["EQ_GAL_DRIVE", "EQ_FUEL_SCOOPS", "EQ_ENERGY_UNIT", "EQ_FUEL_INJECTION", "EQ_DOCK_COMP", "EQ_ECM"] }
price
is the amount being paid the for ship.
tradeIn
is the trade in value of the current ship.
See also: playerBoughtNewShip
playerWillReplaceShip
This method was added in Oolite test release 1.89.
The playerWillReplaceShip
handler is called just before a ship is replaced using the player.replaceShip
function. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.
this.playerWillReplaceShip = function(dataKey) { // Your code here }
dataKey
is the shipdata.plist dataKey
for the ship being purchased.
See also: playerReplacedShip
Other
chartHightlightModeChanged
This method was added in Oolite test release 1.87.
The chartHighlightModeChanged
handler is called whenever the highlight mode of the galactic chart is changed, either manually (from player input), or programmatically (by code setting the mode with player.ship.chartHightlightMode
. "newMode" is the new mode of the chart highlight, and will be one of the following:
OOLRC_MODE_SUNCOLOR OOLRC_MODE_ECONOMY OOLRC_MODE_GOVERNMENT OOLRC_MODE_TECHLEVEL
this.chartHightlightModeChanged = function(newMode) { // Your code here }
compassTargetChanged
The compassTargetChanged
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 }
dayChanged
This method was added in Oolite test release 1.77.
The dayChanged
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 }
escapePodSequenceOver
The escapePodSequenceOver
handler is called at the end of the escape pod sequence, after the shipLaunchedEscapePod
event and just prior to the shipWillDockWithStation
and shipDockedWithStation
events.
Use this function if you need to override the destination for the escape pod with the player method player.setEscapePodDestination()
.
this.escapePodSequenceOver = function() { // Your code here }
guiScreenChanged
The guiScreenChanged
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 guiScreen
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: 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
1.77: adds GUI_SCREEN_INTERFACES
and removes GUI_SCREEN_CONTRACTS
this.guiScreenChanged = function(to, from) { // Your code here }
guiScreenWillChange
The guiScreenWillChange
handler is called when the guiScreen is about to change. It only fires for the screens: GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET, GUI_SCREEN_SHIPYARD
and GUI_SCREEN_SYSTEM_DATA
(in 1.77, also GUI_SCREEN_STATUS
). 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 }
infoSystemChanged
This method was added in Oolite test release 1.83.
The infoSystemChanged
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.
this.infoSystemChanged = function(to, from) { // Your code here }
infoSystemWillChange
This method was added in Oolite test release 1.85.
The infoSystemWChange
handler is called just before the system displayed in F7 is updated, e.g. by moving the small blue cursor along the planned route in the chart.
this.infoSystemWillChange = function(to, from) { // Your code here }
mfdKeyChanged
This method was added in Oolite test release 1.85.
The mfdKeyChanged
handler is called whenever the player changes the content of an MFD slot. The activeMFD
parameter identifies which MFD slot is being changed, and the mfdKey
specifies the key code now in use in this slot.
this.mfdKeyChanged = function(activeMFD : integer, mfdKey : string) { // Your code here }
See also: PlayerShip.setMultiFunctionDisplay()
missionChoiceWasReset
The missionChoiceWasReset
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 }
missionScreenEnded
The missionScreenEnded
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 }
missionScreenOpportunity
The missionScreenOpportunity
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.
reportScreenEnded
The reportScreenEnded
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 }
selectedMFDChanged
This method was added in Oolite test release 1.85.
The selectedMFDChanged
handler is send whenever the player selects a new MFD slot (normally using the default keypress ";"). The activeMFD
paramater is the index of the MFD which is now active.
this.selectedMFDChanged = function(activeMFD : integer) { // Your code here }
shipCollided
The shipCollided
handler is send after a collision with otherShip.
this.shipCollided = function(otherShip) { // Your code here }
shipSpawned
The shipSpawned
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 worldScript 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 }
shipLaunchedEscapePod
The shipLaunchedEscapePod
handler is called when the player bails out. This will be followed by the escapePodSequenceOver
event, and then a shipWillDockWithStation()
/shipDockedWithStation()
pair after a few seconds.
this.shipLaunchedEscapePod = function(escapepod) { // Your code here }
systemInformationChanged
This method was added in Oolite test release 1.79.
The systemInformationChanged
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 }
viewDirectionChanged
The viewDirectionChanged
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. The populator page has more documentation on these functions.
Defunct
equipmentDestroyed
Handler no longer exists in current stable version 1.80
The equipmentDestroyed
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 }
tickle
(removed in 1.77)
The tickle
handler is called periodically-ish, whenever the old plist scripts are updated. tickle()
is deprecated. In new code, use appropriate event handlers or 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 on the forum.
See also: ship script event handlers
- Updated JavaScript features in Oolite 1.81
- Updated JavaScript features in Oolite 1.79
- Updated JavaScript features in Oolite 1.85
- Updated JavaScript features in Oolite 1.83
- Updated JavaScript features in Oolite 1.75
- Updated JavaScript features in Oolite 1.77
- Updated JavaScript features in Oolite 1.89
- Updated JavaScript features in Oolite 1.87
- Oolite JavaScript Reference