Difference between revisions of "Oolite JavaScript Reference: World script event handlers"
Eric Walch (talk | contribs) (shipTargetLost: removed an old 1.71 remark) |
(→playerStartedJumpCountdown) |
||
Line 130: | Line 130: | ||
==== <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> ==== |
Revision as of 14:42, 15 November 2011
This page provides an exhaustive list of event handlers which can be implemented inside world scripts JavaScript scripts for Oolite.
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.
Contents
Game State
startUp
The startUp
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.startUp = function() { // Your code here }
reset (removed in 1.74)
The reset
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.reset = function() { // Your code here }
in 1.74 the startUp event is called in its place, eliminating the need for two separate events.
playerWillSaveGame
This property was added in Oolite test release 1.75.
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.
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.
this.shipLaunchedFromStation = function(station) { // 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.
this.playerStartedAutoPilot = function() { // Your code here }
playerCancelledAutoPilot
The playerCancelledAutoPilot
handler is called when the player cancels autopilot docking.
this.playerCancelledAutoPilot = 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".
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; currently, the possible values are “blocked”, “too far” and “insufficient fuel”. Other values may be added in future.
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.
this.shipWillEnterWitchspace = function(cause) { // 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 }
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 }
shipTargetDestroyed
The shipTargetDestroyed
handler is called when the target gets destroyed. 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
This property was added in Oolite test release 1.74.
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 }
Equipment
equipmentDestroyed
The equipmentDestroyed
handler is called when equipment gets destroyed completely beyond repair. (in strict mode) (world script only)
this.equipmentDestroyed = function(equipment) { // Your code here }
equipmentDamaged
The equipmentDamaged
handler is called when equipment get damaged. (world script only)
this.equipmentDamaged = function(equipment) { // Your code here }
playerBoughtEquipment
The playerBoughtEquipment
handler is called when equipment is bought at the outfit screen.
this.playerBoughtEquipment = function(equipment) { // Your code here }
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) { // Your code here }
Other
compassTargetChanged
This property was added in Oolite test release 1.74.
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 }
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 now instead of using the 'to' parameter. (world script only)
this.guiScreenChanged = function(to, from) { // Your code here }
guiScreenWillChange
This property was added in Oolite test release 1.74.
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 and GUI_SCREEN_SHIPYARD. On these screens a script could change the content of the page to be displayed. In Oolite 1.75 will 'GUI_SCREEN_SYSTEM_DATA' be added to this list. (world script only)
this.guiScreenWillChange = function(to, from) { // Your code here }
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
This property was added in Oolite test release 1.74.
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
This property was added in Oolite test release 1.73.
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 }
shipCollided
The shipCollided
handler is send after a collision with otherShip.
this.shipCollided = function(otherShip) { // Your code here }
shipScoopedOther
The shipScoopedOther
handler is called when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) Other cargo, even scooping escapepods, doesn't trigger a handler.
The scooped item is transferred as argument. The scooped cargo itselfs gets the handler: shipWasScooped
with the scooper as argument.
this.shipScoopedOther = function(whom) { // Your code here }
shipSpawned
The shipSpawned
handler is called after a 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 }
shipLaunchedEscapePod
The shipLaunchedEscapePod
handler is called when the player bails out. This will be followed by a shipWillDockWithStation()
/shipDockedWithStation()
pair after a few seconds.
this.shipLaunchedEscapePod = function(escapepod) { // Your code here }
tickle
The tickle
handler is called periodically-ish, whenever the old 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 status
parameter is a string containing the player’s current status - “STATUS_IN_FLIGHT” and “STATUS_DOCKED” being commonly-seen examples.
this.tickle = function(status) { // Your code here }
viewDirectionChanged
This property was added in Oolite test release 1.75.
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 } }
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