Difference between revisions of "Oolite JavaScript Reference: Ship script event handlers"
Eric Walch (talk | contribs) (shipScoopedOther: 1.77 update) |
m (→Miscellaneous: shipBountyChanged handler) |
||
Line 303: | Line 303: | ||
==== <code>commsMessageReceived</code> ==== |
==== <code>commsMessageReceived</code> ==== |
||
− | The <code>commsMessageReceived</code> handler is |
+ | The <code>commsMessageReceived</code> handler is sent when receiving a message from other ships. Handler is added in Oolite 1.75 |
commsMessageReceived = function(message: string, sender: ship) |
commsMessageReceived = function(message: string, sender: ship) |
||
Line 312: | Line 312: | ||
==== <code>distressMessageReceived</code> ==== |
==== <code>distressMessageReceived</code> ==== |
||
− | The <code>distressMessageReceived</code> handler is |
+ | The <code>distressMessageReceived</code> handler is sent when receiving a distress message from other ships. Handler is added in Oolite 1.75 |
distressMessageReceived = function(aggressor: ship, sender: ship) |
distressMessageReceived = function(aggressor: ship, sender: ship) |
||
+ | { |
||
+ | // Your code here |
||
+ | } |
||
+ | |||
+ | ==== <code>shipBountyChanged</code> ==== |
||
+ | {{Oolite-method-added|1.77}} |
||
+ | |||
+ | The <code>shipBountyChanged</code> handler is sent when an event tries to change the bounty level of the ship. <code>delta</code> may be zero, positive or negative. <code>reason</code> is a string that may either contain a standard value or a custom value set by an OXP. The standard values are: |
||
+ | * '''setup actions''': Bounty level settings in the system populator or as a side effect of launching a ship from a station with a particular role. |
||
+ | * '''scripted''': OXP scripted changes to bounties, with no specified cause. |
||
+ | * '''attacked police''': The ship attacked a police ship |
||
+ | * '''attacked main station''': The ship attacked the main station |
||
+ | * '''attacked innocent''': The ship attacked a Clean ship and was seen doing so |
||
+ | * '''seen by police''': The ship was seen by police committing a crime |
||
+ | * '''distress call''': A police ship responded to a distress call from a ship that this ship is attacking |
||
+ | * '''illegal exports''': The ship launched from a main station while carrying illegal goods (player only) |
||
+ | * '''assisting offenders''': The bounty adjustment applied when a clean ship escorts an offender, or vice versa (NPC only) |
||
+ | * '''new galaxy''': The ship entered a new galaxy (player only) |
||
+ | * '''new system''': The ship entered a new system |
||
+ | * '''paid fine''': The ship was marked for fines by police, and then paid them on docking (player only) |
||
+ | * '''escape pod''': The ship is a replacement ship from escape pod insurance (player only) |
||
+ | * '''assisting police''': The ship helped out a police ship in combat |
||
+ | * '''unknown''': The bounty changed for an unknown reason. This should not occur. |
||
+ | |||
+ | this.shipBountyChanged = function(delta,reason) |
||
{ |
{ |
||
// Your code here |
// Your code here |
||
Line 321: | Line 346: | ||
==== <code>shipCollided</code> ==== |
==== <code>shipCollided</code> ==== |
||
− | The <code>shipCollided</code> handler is |
+ | The <code>shipCollided</code> handler is sent after a collision with otherShip. |
this.shipCollided = function(otherShip) |
this.shipCollided = function(otherShip) |
||
Line 330: | Line 355: | ||
==== <code>shipReachedEndPoint</code> ==== |
==== <code>shipReachedEndPoint</code> ==== |
||
− | The <code>shipReachedEndPoint</code> handler is |
+ | The <code>shipReachedEndPoint</code> handler is sent after reaching the last navigation point when in mode <code>performFlyRacepoints</code>. |
shipReachedEndPoint = function() |
shipReachedEndPoint = function() |
||
Line 339: | Line 364: | ||
==== <code>shipReachedNavPoint</code> ==== |
==== <code>shipReachedNavPoint</code> ==== |
||
− | The <code>shipReachedNavPoint</code> handler is |
+ | The <code>shipReachedNavPoint</code> handler is sent after reaching a navigation point when in mode <code>performFlyRacepoints</code>. |
this.shipReachedNavPoint = function() |
this.shipReachedNavPoint = function() |
Revision as of 10:22, 12 May 2012
This page provides a list of event handlers which can be implemented by JavaScript scripts for Oolite.
Ship scripts are linked to Oolite either using the appropriate shipdata.plist setting or via javascript using ship.setScript and are only active when the ship is present. More than one ship can be assigned the same ship script. Each ship will create its own separate copy of the script, each one independent from the others.
(this page has just recently been split from world script event handlers, bear with us while we tidy up the content)
Contents
- 1 Docking
- 2 Witchspace Jumps
- 3 Enter/Exit Aegis
- 4 Combat
- 4.1 escortAttack
- 4.2 shipAttackedOther
- 4.3 shipAttackedWithMissile
- 4.4 shipBeingAttacked
- 4.5 shipBeingAttackedByCloaked
- 4.6 shipCloakActivated
- 4.7 shipCloakDeactivated
- 4.8 shipTargetDestroyed
- 4.9 shipDied
- 4.10 shipEnergyBecameFull
- 4.11 shipEnergyIsLow
- 4.12 shipHitByECM
- 4.13 shipFiredMissile
- 4.14 shipKilledOther
- 4.15 shipTargetAcquired
- 4.16 shipTargetCloaked
- 4.17 shipTargetLost
- 4.18 shipTakingDamage
- 5 Miscellaneous
- 6 NPC only
- 7 Stations only
- 8 Missing Events
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 == nil", "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.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
This handler was added for npc ships with test release 1.75, before it was a worldScript only handler.
The shipWillLaunchFromStation
handler is called for ship scripts on ship creation, before the shipSpawned event.
this.shipWillLaunchFromStation = function(station) { // Your code here }
shipLaunchedFromStation
The shipLaunchedFromStation
handler is called at the end of the launch tract, when the ship has clearly left the station and AI updating begins.
this.shipLaunchedFromStation = function(station) { // Your code here }
Witchspace Jumps
playerWillEnterWitchspace
The playerWillEnterWitchspace
handler is called just before a witchspace jump starts and after the shipWillEnterWitchspace
handler fires. It is send to all ships in the system to signal that the player is about to leave the system. (By jump or by wormhole)
this.playerWillEnterWitchspace = function() { // Your code here }
shipExitedWormhole
The shipExitedWormhole
handler is called when a ship exits a wormhole.
this.shipExitedWormhole = function() { // Your code here }
shipWillEnterWormhole
The shipWillEnterWormhole
handler is called when a ship enters a wormhole. only)
this.shipWillEnterWormhole = function() { // 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
escortAttack
The escortAttack
handler is sent to all escorts of a mothership that are deployed. The mother first changes the escorts AI to interceptAI.plist and also sets the escort target to his own target before sending this handler to the escorts.
this.escortAttack = function(target) { // Your code here }
shipAttackedOther
The shipAttackedOther
handler is called when this ship hits another with a laser shot. other
is the identity of the ship being hit (added in test version 1.74.2).
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. There is no parameter provided to identify the cloaked ship.
this.shipBeingAttackedByCloaked = function() { // Your code here }
shipCloakActivated
The shipCloakActivated
handler is called whenever the script's target ship activates its cloaking device. No parameters are required for this handler (added in test version 1.74).
this.shipCloakActivated = function() { // Your code here }
shipCloakDeactivated
The shipCloakDeactivated
handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler (added in test version 1.74).
this.shipCloakDectivated = 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)
shipEnergyBecameFull
The shipEnergyBecameFull
handler is called when the energy level reaches it's maximum value again.
this.shipEnergyBecameFull = function() { // Your code here }
shipEnergyIsLow
The shipEnergyIsLow
handler is called every time when a ship gets energy damage while the energy level lies below 25% of it's maximum value.
this.shipEnergyIsLow = function() { // Your code here }
shipHitByECM
The shipHitByECM
handler is called when a ship receives a ECM pulse. pulsesRemaining
contains the number of pulses that still have to be send by the sending ship. When a ship activates his ecm, he will send 4 pulses with 0.5 seconds interval and increasing range.: 6400 --> 12800 --> 19200 --> 25600. (Handler added in test version 1.71)
this.shipHitByECM = function(pulsesRemaining) { // Your code here }
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. (Handler added in test version 1.74)
this.shipFiredMissile = function(missile, target) { // Your code here }
shipKilledOther
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. (Handler added in test version 1.75)
this.shipKilledOther = function(whom,damageType) { // Your code here }
shipTargetAcquired
The shipTargetAcquired
handler is called whenever a new target is selected. (Handler added in test version 1.74)
this.shipTargetAcquired = function(target) { // Your code here }
shipTargetCloaked
The shipTargetCloaked
handler is called when the target cloakes.
this.shipTargetCloaked = function() { // Your code here }
shipTargetLost
The shipLostTarget
handler is called when the target gets lost. target
contains the lost target entity.
(Handler introduced in 1.74 as replacement with consistent name for the old handler: 'shipLostTarget'.)
this.shipLostTarget = function(target) { // Your code here }
shipTakingDamage
The shipTakingDamage
handler is called when a ship sustains damage. (For player ships this only happens after the shields are down) Handler is added in Oolite 1.75
It transfers the amount
of damage, who
caused the damage and the type
of damage.
this.shipTakingDamage = function(amount, whom, type) { // Your code here }
Miscellaneous
commsMessageReceived
The commsMessageReceived
handler is sent when receiving a message from other ships. Handler is added in Oolite 1.75
commsMessageReceived = function(message: string, sender: ship) { // Your code here }
distressMessageReceived
The distressMessageReceived
handler is sent when receiving a distress message from other ships. Handler is added in Oolite 1.75
distressMessageReceived = function(aggressor: ship, sender: ship) { // Your code here }
shipBountyChanged
This method was added in Oolite test release 1.77.
The shipBountyChanged
handler is sent when an event tries to change the bounty level of the ship. delta
may be zero, positive or negative. reason
is a string that may either contain a standard value or a custom value set by an OXP. The standard values are:
- setup actions: Bounty level settings in the system populator or as a side effect of launching a ship from a station with a particular role.
- scripted: OXP scripted changes to bounties, with no specified cause.
- attacked police: The ship attacked a police ship
- attacked main station: The ship attacked the main station
- attacked innocent: The ship attacked a Clean ship and was seen doing so
- seen by police: The ship was seen by police committing a crime
- distress call: A police ship responded to a distress call from a ship that this ship is attacking
- illegal exports: The ship launched from a main station while carrying illegal goods (player only)
- assisting offenders: The bounty adjustment applied when a clean ship escorts an offender, or vice versa (NPC only)
- new galaxy: The ship entered a new galaxy (player only)
- new system: The ship entered a new system
- paid fine: The ship was marked for fines by police, and then paid them on docking (player only)
- escape pod: The ship is a replacement ship from escape pod insurance (player only)
- assisting police: The ship helped out a police ship in combat
- unknown: The bounty changed for an unknown reason. This should not occur.
this.shipBountyChanged = function(delta,reason) { // Your code here }
shipCollided
The shipCollided
handler is sent after a collision with otherShip.
this.shipCollided = function(otherShip) { // Your code here }
shipReachedEndPoint
The shipReachedEndPoint
handler is sent after reaching the last navigation point when in mode performFlyRacepoints
.
shipReachedEndPoint = function() { // Your code here }
The shipReachedNavPoint
handler is sent after reaching a navigation point when in mode performFlyRacepoints
.
this.shipReachedNavPoint = function() { // 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. Starting with Oolite 1.77 this handler will fire on every scooped object.
this.shipScoopedOther = function(whom) { // Your code here }
shipLaunchedEscapePod
The shipLaunchedEscapePod
handler is called when the pilot bails out. This will be followed by a shipWillDockWithStation()
/shipDockedWithStation()
pair after a few seconds when it is the player that is ejecting.
this.shipLaunchedEscapePod = function(escapepod, passengers) { // Your code here }
escapepod
contains the main pod with the pilot. passengers
will be added with Oolite 1.77 and is an array with passenger pods for those ships that have more than one escape-capsule defined.
NPC only
entityDestroyed
The entityDestroyed
handler fires immediately after the ship becomes invalid, regardless of the reason, except when the game restarts. This is the best place for all kind of 'clean-up' code, for example stopping Timers associated with the ship script. (Added with Oolite 1.75.1)
entityDestroyed = function() { // Your code here }
escortAccepted
The escortAccepted
handler is called for mother ships that have accepted an escort. The escort simultaneously gets a shipAcceptedEscort
event.
this.escortAccepted = function(escortship) { // Your code here }
escortDock
The escortDock
handler is called by a mother ships that uses the AI command: dockEscorts
. Escorts are instructed to change AI into dockingAI.plist and enter the ABORT state of this AI after a certain delay. Than this event is send to all his escorts, each with a different delay with 3 seconds spacing.
this.escortDock = function(delay) { // Your code here }
offenceCommittedNearby
The offenceCommittedNearby
handler is only send to police ships in scanner range of a hostile action. It transfers the attacker and the victim to the police vessel.
this.offenceCommittedNearby = function(attacker, victim) { // Your code here }
shipAcceptedEscort
The shipAcceptedEscort
handler is called for ships that are accepted as escort. The mother simultaneously gets a escortAccepted
event.
this.shipAcceptedEscort = function(mother) { // Your code here }
shipLandedOnPlanet
The shipLandedOnPlanet
handler is called for ships landing on a planet. It transfers the planet
parameter. (Will be added with Oolite 1.77)
shipLandedOnPlanet = function(planet) { // Your code here }
shipRemoved
The shipRemoved
handler is called for ships removed by script. It transfers the suppressDeathEvent
parameter so the script knows if there will also follow a shipDied() event.
shipRemoved = function(suppressDeathEvent) { // Your code here }
shipSpawned
The shipSpawned
handler is called for newly added ships. It does not trigger on adding but on the first update after adding. On a witchspace jump it means that first all ships are added to the system, then afterwards all the shipSpawned() events are triggered.
this.shipSpawned = function() { // Your code here }
spawnedAsEscort
The spawnedAsEscort
handler is called for newly added escort ships. It does trigger on adding the ship and before the shipSpawned() handlers is activated. It has the mothership as argument.
this.spawnedAsEscort = function(mother) { // Your code here }
shipWasScooped
The shipWasScooped
handler is send to the cargopod when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) The scooper is transferred as argument. The scooper itself gets a trigger on the handler shipScoopedOther
. (ship script only)
this.shipWasScooped = function(scooper) { // Your code here }
Stations only
alertConditionChanged
The alertConditionChanged
handler is called when a station's alert status (Station.alertCondition) changes. Only the player and stations have an alert condition. The equivalent player event is handled inside world scripts.
this.alertConditionChanged = function(newCondition, oldCondition) { // Your code here }
otherShipDocked
The otherShipDocked
handler is called with a station script only, when an ship docks. It has the docked ship as argument.
this.otherShipDocked = function(whom) { // Your code here }
stationLaunchedShip
The stationLaunchedShip
handler is called with a station script only, when a ship launches. It has the launched ship as argument.
this.stationLaunchedShip = function(whom) { // Your code here }
Missing Events
All initially planned events have a corresponding event handler in v1.74.
If there are other events you would like to be able to respond to, please write a request on the forum.
See also: world_script_event_handlers