Contents 1 Introduction 2 General MP Note 3 Other Types of Event 4 Event Handler List 4.1 Collisions/Damages 4.1.1 BeforeKilled 4.1.2 Dammaged 4.1.3 DamagedHitPart 4.1.4 EpeContact 4.1.5 EpeContactStart/EpeContactEnd 4.1.6 FreeFall 4.1.7 HandleDamage 4.1.8 HandleHeal 4.1.9 Hit 4.1.10 HitPart 4.1.11 Killed 4.2 Editor 4.2.1 Delete 4.2.2 Deleted 4.2.3 GroupChangedRTE 4.2.4 Paste 4.3 Units 4.3.1 AnimChanged 4.3.2 AnimDone 4.3.3 AnimStateChanged 4.3.4 GroupChanged 4.3.5 LoadOutChanged (Unit) 4.3.6 PathPlanFailed (Unit) 4.3.7 Respawn 4.3.8 Suppressed 4.3.9 WaypointComplete 4.4 Vehicles 4.4.1 AfterGetIn/AfterGetOut 4.4.2 BeforeGetIn/BeforeGetOut 4.4.3 CargoChanged 4.4.4 Engine 4.4.5 Fuel 4.4.6 Gear 4.4.7 GetIn/GetOut 4.4.8 GetInMan/GetOutMan 4.4.9 LandedStopped 4.4.10 LandedTouchDown 4.4.11 LoadOutChanged (Vehicle) 4.4.12 PathPlanFailed (Vehicle) 4.4.13 PositionChanged 4.4.14 TurnIn/TurnOut 4.5 Weapons/Shots 4.5.1 AmmoExplode/AmmoHit 4.5.2 ChangedWeapon 4.5.3 Explosions 4.5.4 Fired 4.5.5 FiredNear 4.5.6 IncomingFire 4.5.7 IncomingMissile 4.5.8 LaserFired 4.6 Other 4.6.1 AttachTo 4.6.2 Init

Introduction

Event Handlers (EHs) are attached to objects, and allow you to automatically execute custom code upon particular events being triggered by that object.

These event handlers are added to objects using the addEventHandler command, or in the object's configuration file (see below).

Multiple event handlers of the same type can be attached to an object (and are identified by the index returned by addEventHandler), and will fire in the order they were created.

General MP Note

A respawned unit still has the EHs it had before, so it is not neccessary to re-add EHs after respawning.

Other Types of Event

• Configs: See Config Event Handlers on how to add EHs to object's config files.
• Global Events (not tied to a specific object, but responding to global, or system, events)
  • Global Event Handlers
  • Custom Event Handlers
  • System Event Handlers
• User Interface: See User Interface Event Handlers for event handlers used in displays/dialogs.
• Mission Events: See Mission Event Scripts for special scripts that are triggered under certain mission events.

Event Handler List

Collisions/Damages

BeforeKilled

Fires just before a unit is killed.
Does not work with objects, and only fires after destruction, if used with vehicles.

Passed array: [object]

• object: Object - Unit that is about to die.

Dammaged

Triggered when the object is damaged.
Only fires if the damage to the hit selection is greater than 0.5.
Does not fire if damage is set via setDammage.
If simultaneous damage occurred (e.g. via grenade) EH will be triggered several times.

Passed array: [unit, selectionName, damage]

• unit: Object - Object the event handler is assigned to.
  
• selectionName: String - Name of the selection that was damaged.
  
• damage: Number - Resulting total damage to the hit selection.

DamagedHitPart

Triggered when the object is damaged.
Does not fire if damage is set via setDammage.
If simultaneous damage occurred (e.g. via grenade) EH will be triggered several times.

Passed array: [target, shooter, hitzone,totaldamage,hitdamage,structdamage,hitzonecenter,hitzoneradius,selections,surfaces]

• target: Object - Object that got damaged.
• shooter: Object - Unit that inflicted the damage. If injured by a vehicle impact or a fall the target itself is returned. In case of IEDs or artillery either the target itself is returned, or the null object, if further away from the explosion. In case of explosives that were planted by someone (e.g. satchel charges), either that unit is returned, or the target unit itself, if further away.
• hitzone: String - HitZone that was damaged.
• totaldamage: Number - Accumulated damage to hitzone.
• hitdamage: Number - Amount of damage hitzone received with this hit
• structdamage: Number - Damage increase to object itself, received by this hit.
• hitzonecenter: Position3D - Position of hitzone center in model space.
• hitzoneradius: Number - Radius of the hitzone.
• selections: Array of Strings - Names of selections the hitzone belongs to.
• surfaces: Array of Strings - Surface types of hitzone.

EpeContact

Fires (every frame) while a physX object is in contact with another physX object.
If used with a moving object (e.g. a car) be aware that it will constantly trigger this event while moving (due to the ground contact).

Passed array: [owner, object, ownsel, objsel, force]

• owner: Object - Object EH is attached to
• object: Object - Object that is colliding with owner object (may be objNull is a moving object is touching the ground)
• ownsel: String - Selection name of owner object that is being touched (empty if no selections defined)
• objsel: String - Selection name of colliding object that is being touched (empty if no selections defined)
• force: Number - Amount of force (in N) of collision. Can be 0 during the contact release.

EpeContactStart/EpeContactEnd

Fires when a contact between two physX objects is initiated (or ended).
If used with a moving object (e.g. a car) be aware that it will constantly trigger this event while moving (due to the ground contact).

Passed array: [owner, object, ownsel, objsel, force]

• owner: Object - Object EH is attached to
• object: Object - Object that is colliding with owner object (may be objNull is a moving object is touching the ground)
• ownsel: String - Selection name of owner object that is being touched (empty if no selections defined)
• objsel: String - Selection name of colliding object that is being touched (empty if no selections defined)
• force: Number - Amount of force (in N) of collision.

FreeFall

Fires when a unit drops from a height (e.g. falling off a building, or after being thrown into the air by an explosion). Will not fire on parachute ejections.

Passed array: [owner]

• owner: Object - Object EH is attached to

HandleDamage

Fires when the damage value for an object changes, and allows the adjustment of the damage value inside the EH's code section.
May fire multiple times, if multiple sections are affected, or if damage is caused by a direct, as well as indirect, hit (e.g. via grenades).
The code section of this EH can contain a return value which specifies the damage that should be applied to the target. If no return value is given, then no damage is applied (same effect as passing a 0). To use the original damage that would've been caused by the hit, _this select 2 should be returned, e.g. unit1 addEventHandler ["HandleDamage","hint 'ouch'; _this select 2"]. A return value of 1 will destroy the attached object (the example below will do this whenever the vehicle's engine is hit, any other hit will not cause any damage): car1 addEventHandler ["HandleDamage","if ('engine' in _this) then {1} else {0}"] The command setDamage should not be used in the code section of this EH, as it might lead to a dead loop (with the engine endlessly resetting and reacting to the changes of damages).
Due to the fact that this EH may fire multiple times, damage values set by one event may be overwritten by a later one, if these happen within the same frame. While full damage (as in the example above) cannot be reversed, if only partial damage is applied, then it could be overwritten by a later event (e.g. if the car example applied a damage of only 0.9, then a damage event to the "hull" could negate the originally applied damage).

Passed array: [target, selection, damage, shooter, bullet]

• target: Object - Object EH is attached to (can be unit, vehicle or object)
• selection: String - Name of selection that received damage. Empty string ("") for overall damage. "?" for unknown/unnamed section.
• damage: Number - Damage value inflicted by this hit
• shooter: Object - Source of damage. If injured by a vehicle impact or a fall the target itself is returned, or, in case of explosions, or for vehicles hitting obstacles, the null object.
• bullet: String - Class name of projectile that caused damage. Empty string ("") if damage was caused by different means (e.g. a fall or impact).

HandleHeal

Fires when a unit is healed by another one.
Does not fire when healing at an ambulance vehicle or tent.
If the EH code returns nothing (or false), then the normal healing process is activated. If it returns true, then this EH will continue to fire until either the target's health is set to full (via setDamage), or the AISFinishHeal command is executed. player addEventHandler["HandleHeal","if (okToHeal) then {false} else {AISFinishHeal [_this select 0,_this select 1,false]}"] Passed array: [target, healer, isMedic]

• target: Unit - Unit EH is attached to
• healer: String - Unit that is healing the target.
• isMedic: Boolean - Is true if healer is a medic

Hit

Triggered when the unit is hit/damaged.

Will only fire if a minimum threshold of damage has been reached (about .06). Otherwise, even if the object damage did increase, this EH will not be triggered.
In addition, if an object is killed/destroyed right away with the first hit, this EH may not trigger either; only the killed EH will fire in that case.

Passed array: [target, shooter, damage]

• target: Object - Object that got injured/damaged.
• shooter: Object - Unit that inflicted the damage. If injured by a vehicle impact or a fall the target itself is returned, or, in case of IEDs or artillery, the null object. In case of explosives that were planted by someone (e.g. satchel charges), that unit is returned.
• damage: Number - Level of damage caused by the hit.

HitPart

Runs when the object it was added to gets injured/damaged. It returns the position and component that was hit on the object within a nested array, this is because the model may have more than selection name for the hit component.

Passed array: [[target, shooter, bullet, position, velocity, selection, ammo, direction, radius, surface, direct]]

• target: Object - Object that got injured/damaged.
• shooter: Object - Unit that inflicted the damage. If injured by a vehicle impact or a fall the target itself is returned, or, in case of explosions, the null object. In case of explosives that were planted by someone (e.g. satchel charges), that unit is returned.
• bullet: Object - Object that was fired.
• position: Position3D - Position the bullet impacted.
• velocity: Vector3D - 3D speed at which bullet impacted.
• selection: Array - Array of Strings with named selection of the object that were hit.
• ammo: Array - Ammo info: [hit value, indirect hit value, indirect hit range, explosive damage, ammo class name] OR, if there is no shot object: [impulse value on object collided with,0,0,0]
• direction: Vector3D - vector that is orthogonal (perpendicular) to the surface struck. For example, if a wall was hit, vector would be pointing out of the wall at a 90 degree angle.
• radius: Number - Radius (size) of component hit.
• surface: String - Surface type struck.
• direct: Boolean - true if object was directly hit, false if it was hit by indirect/splash damage.

Killed

Triggered when the unit is killed.

Passed array: [unit, killer]

• target: Object - Object that got killed.
• shooter: Object - Unit that caused the death. If injured by a vehicle impact or a fall the target itself is returned. In case of IEDs or artillery either the target itself is returned, or the null object, if further away from the explosion. In case of explosives that were planted by someone (e.g. satchel charges), that unit is returned.

Editor

Delete

Runs just before an object is deleted. Object can be deleted in several ways, few of which are: the deleteVehicle command, the RTE, or LVC Game.

Passed array: [object]

• object: Object - Object that was deleted

Note: Delete EH can only be added within scrips using addEventHandler scripting command. If used in a config, an error will occur during packing of content.

Deleted

Identical to the Delete EH, except this EH can be added in config.

Passed array: [object]

• object: Object - Object that was deleted

GroupChangedRTE

Added to a Side, not an object. Triggered only if RTE is open, when a change occurs to a specific group's or subgroup status. Also triggered on creation of new group, or deletion of an existing group.

Passed array: [group]

• group: Group - Group for which the change occurred.

Paste

Triggered when an object has been copied and pasted in the editor.
If a vehicle is copied, the EH will fire once for the vehicle, and once for every crew member.

Passed array: [original, copy]

• original: Object - Object that was copied
  
• copy: Object - Object that was created.
  

Units

AnimChanged

Trigerred every time a new animation is started.

Passed array: [unit, anim, currentPhase, targetPhase]

• unit: Object - Object the event handler is assigned to.
• anim: String - Name of the animation that started.
• currentPhase: Number - Current animation phase.
• targetPhase: Number - Desired animation phase.

AnimDone

Trigerred everytime an animation is finished.

Passed array: [unit, anim]

• unit: Object - Object the event handler is assigned to.
• anim: String - Name of the animation that has been finished.

AnimStateChanged

Trigerred everytime an animation state changes.
Unlike AnimChanged and AnimDone, it is triggered for all animation states in a sequence.

Passed array: [unit, anim]

• unit: Object - Object the event handler is assigned to.
• anim: String - Name of the animation that has been started.

GroupChanged

Added to a Side, not an object. Triggered when a change occurs to a specific group's or subgroup status. Also triggered on creation of new group, or deletion of an existing group.
See also #GroupChangedRTE.

Passed array: [group]

• group: Group - Group for which the change occurred.

LoadOutChanged (Unit)

Runs whenever a weapon or magazine is added/removed from a unit or vehicle. This could occur as a result of scripting commands (such as addWeapon or removeMagazine), or it could happen as a result of in-game actions such as reloading magazines, dropping weapons, etc.

Passed array: [object]

• object: Object - Object that had its equipment changed

Note: In versions below 1.30, these event handlers will be removed from nearby objects when a player uses the inventory (and thus can not be considered 100% reliable). This does not happen in v1.30+ (and thus can be considered 100% reliable).

PathPlanFailed (Unit)

Unit/vehicle was not able to reach a assigned destination (assignment can be via waypoint, move commands, or group order).

Passed array: [unit, destination, retry]

• unit: Object - Unit/vehicle the event handler is assigned to
  
• destination: Position3D - Position that cannot be reached.
  
• retry: Boolean - If true then unit will retry reaching the destination (normally it retries twice before giving up, at which point false is returned).
  

Respawn

Runs when the object respawns. This EH is only fired where the respawned unit is local, if its not known where the unit is local (or will be local when it is respawned), you have to add it on all machines.

Passed array: [new unit, old unit]

• new unit: Object - The player's new unit, after respawning
• old unit: Object - The player's old unit, before respawning

Note: This EH is persistent, thus unit once respawned will have it again.

Suppressed

Runs each time a unit is suppressed (by incoming rounds).

Passed array: [unit, who fired, type, distance, position]

• unit: Object - The unit that was suppressed
• who fired: Object - Object that fired the suppressing round
• type: String - Classname of the round that caused suppression
• distance: Number - Nearest distance that round came to suppressed unit
• position: Position3D - AGL position where round was closest to suppressed unit

Note: "Suppression of user" must be enabled in difficulty settings for this event to trigger. This event will trigger for both AI as well as player units.

WaypointComplete

This event must be added to a Group, not an individual unit or vehicle. It is triggered when that group completes a waypoint.

Passed array: [group, index]

• group: Group - Group that triggered event was added to
• index: Number - Index of waypoint that was completed

Vehicles

AfterGetIn/AfterGetOut

Triggered after a unit gets in or out of a vehicle.

Passed array: [vehicle, position, unit]

• vehicle: Object - Vehicle the event handler is assigned to
• position: String - Can be either "driver", "gunner" or "cargo"
• unit: Object - Unit that has left or entered the vehicle

BeforeGetIn/BeforeGetOut

Triggered just before a unit gets in or out of a vehicle.

Passed array: [vehicle, position, unit]

• vehicle: Object - Vehicle the event handler is assigned to
• position: String - Can be either "driver", "gunner" or "cargo"
• unit: Object - Unit that will be leaving or entering the vehicle

CargoChanged

Runs whenever a weapon or magazine is added/removed from a vehicle's cargo space. This could occur as a result of scripting commands (such as addWeaponCargo or clearMagazineCargo), or it could happen as a result of in-game actions such as AI taking gear from the vehicle.

Passed array: [object]

• object: Object - Object that had its cargo changed

Note: before v1.30, these eventhandlers are removed from nearby objects when a player uses the inventory; therefore these events can not be considered 100% reliable in versions before 1.30.

Engine

Triggered when the engine of the unit is turned on/off.

Passed array: [vehicle, engineState]

• vehicle: Object - Vehicle the event handler is assigned to
  
• engineState: Boolean - True when the engine is turned on, false when turned off

Fuel

Triggered when the unit's fuel status changes between completely empty / not empty (only useful if the event handler is assigned to a vehicle).

Global.

Passed array: [vehicle, fuelState]

• vehicle: Object - Vehicle the event handler is assigned to
  
• fuelState: Boolean - false when no fuel, true when the fuel tank is full

Gear

Triggered when the unit lowers/retracts the landing gear (only useful if the event handler is assigned to is a member of the class "Plane").

Passed array: [vehicle, gearState]

• vehicle: Object - Vehicle the event handler is assigned to
  
• gearState: Boolean - True when the gear is lowered, false when retracted

GetIn/GetOut

Triggered when a unit enters or leaves the object (only useful when the event handler is assigned to a vehicle). It does not trigger upon a change of positions within the same vehicle. It also is not triggered by the moveInX commands.

Passed array: [vehicle, position, unit]

• vehicle: Object - Vehicle the event handler is assigned to
• position: String - Can be either "driver", "gunner", "commander" or "cargo"
• unit: Object - Unit that entered or left the vehicle

GetInMan/GetOutMan

Triggered when a unit enters or leaves a vehicle. It does not trigger upon a change of positions within the same vehicle. This event is attached to a person, not a vehicle like the GetIn event.

Passed array: [unit, position, vehicle]

• unit: Object - Unit that entered or left the vehicle
• position: String - Can be either "driver", "gunner", "commander" or "cargo"
• vehicle: Object - Vehicle the event handler is assigned to

LandedStopped

Triggered when an AI pilot would get out usually. Not executed for player.

Passed array: [plane, airportID]

• plane: Object - Object the event handler is assigned to
  
• airportID: Number - ID of the airport (-1 for anything else).
  

LandedTouchDown

Triggered when a plane (AI or player) touches the ground.

Passed array: [plane, airportID]

• plane: Object - Object the event handler is assigned to
  
• airportID: Number - ID of the airport (-1 for anything else).
  

LoadOutChanged (Vehicle)

See #LoadOutChanged (Unit)

PathPlanFailed (Vehicle)

See [#PathPlanFailed (Unit)]]

PositionChanged

Added to a vehicle. Runs when a person either enters, exits, or moves position inside the vehicle.

Passed array: [vehicle, person, positionFromArray, positionToArray]

• vehicle: Object - Vehicle that event handler was attached to
• person: Object - Unit that entered/exited/moved in the vehicle
• positionFromArray/positionToArray: Array - Array indicating what position the person was in, and what position they moved into. Format of both arrays is: [type, turretPath or cargoIndex]
  If vehicle is entered as the driver, then the from/to arrays are reversed, i.e. it will return [1,0],[0,0], instead of [0,0],[1,0]
  • type: Number - 0 = not in vehicle; 1 = driver; 2 = cargo position, 3 = turret
  • turretPath: Array - Path to turret
  • cargoIndex: Number - Index indicating which cargo slot

TurnIn/TurnOut

Triggered when a unit turns in (or out of) a vehicle's turret position.

Passed array: [vehicle, unit, turretpath]

• vehicle: Object - Vehicle the unit is in
• unit: Object - Unit that is turning in or out
• turretpath: Array - [] for driver

Weapons/Shots

AmmoExplode/AmmoHit

AmmoHit runs when the ammunition hits something (even if it ricochets), while AmmoExplode only runs when the ammo explodes or terminally impacts something.
Scripted "AmmoHit" events will only fire if the bullet has already traveled for a certain distance (about 40m or 0.03 seconds).

Passed array: [bullet, shooter, target, position, velocity, selection, ammo, direction, exploded]

• bullet: Object - Object that was fired
• shooter: Object - Unit that fired shot
• target: Object - Object that was hit, or objnull if the ground was hit
• position: Position3D - Position the bullet impacted in PositionASL coordinates
• velocity: Vector3D - 3D speed at which bullet impacted
• selection: Array - Array of Strings with named selection of the object that were hit.
• ammo: Array - Ammo info: [hit value, indirect hit value, indirect hit range, explosive damage, ammo class name]
• direction: Vector3D - vector that is orthogonal (perpendicular) to the surface struck. For example, if a wall was hit, vector would be pointing out of the wall at a 90 degree angle
• exploded: Boolean - true if the ammo exploded / was destroyed, false if it ricocheted

Note: In versions below 1.3, these EHs only works from CfgAmmo (you cannot add it with addEventHandler). However, in v1.3 and above the "AmmoHit" EH can be added via the script command.

ChangedWeapon

Added to the config of a weapon (not added via the addEventHandler scripting command)! Runs whenever this weapon is added or removed from a unit.

Passed array: [owner, weapon, added?]

• owner: Object - Object that had the weapon added or removed
• weapon: String - Classname of weapon that was added or removed
• added?: Boolean - True if weapon was added to owner, false if it was removed

Explosions

Fires when an explosion happens in the mission (only works with player units).

Passed array: [positionX, positionY, positionZ, indirectHit, indirectHitRange, energyFactor]

• positionX/Y/Z: Number - impact coordinates (above sea level)
• indirectHit: String - ammo configuration value
• indirectHitRange: String - ammo configuration value
• energyFactor: String - unknown

Fired

Executes when a weapon is fired.
For addons, this Event Handler can be configured to run from either CfgWeapons or CfgVehicles.

Passed array: [unit, weapon, muzzle, mode, ammo, magazine, projectile]

• unit: Object - Object the event handler is assigned to
  
• weapon: String - Fired weapon
  
• muzzle: String - Muzzle which was used
  
• mode: String - Current mode of the fired weapon
  
• ammo: String - Ammo used
  
• magazine: String - Magazine which was used
  
• projectile: Object - Object of the projectile that was shot

FiredNear

Executes when a weapon is fired nearby.
Does not respond to explosions (e.g. IEDs or artillery) or thrown projectiles.
The effective range depends on the environment. In an open area this EH may fire up to a distance of up 80m, whereas in an urban area it may be less than 40m.
The caliber and ammo type do not affect the trigger range (i.e. a silenced 9mm pistol may have the same range as a 50cal machine gun).
This handler will continue to fire, even after the unit it's attached to is dead.
For addons, this Event Handler can be configured to run from either CfgWeapons or CfgVehicles.

Passed array: [unit, shooter, distance, weapon, muzzle, mode, ammo]

• unit: Object - Object the event handler is assigned to
  
• shooter: Object - Unit/vehicle that fired the weapon
  
• distance: Number - Distance to shooter
  
• weapon: String - Fired weapon
  
• muzzle: String - Muzzle which was used
  
• mode: String - Current mode of the fired weapon
  
• ammo: String - Ammo used

IncomingFire

Triggered when a bullet was fired at the associated object.

Passed array: [unit, shooter, ammo, distance, position]

• unit: Object - Object the event handler is assigned to.
• shooter: Object - Object that fired the weapon.
• ammo: String - Ammo type that was fired on the unit.
• distance: Number - Nearest distance the bullet came to the unit
  
• position: Number - Nearest position the bullet came to the unit
  

IncomingMissile

Triggered when a guided missile locked on the target or unguided missile or rocket aimed by AI at the target was fired.

Passed array: [unit, ammo, shooter]

• unit: Object - Object the event handler is assigned to.
• ammo: String - Ammo type that was fired on the unit.
• shooter: Object - Object that fired the weapon.

LaserFired

Executes when a vehicle's laser range finder is invoked.
Returned values are relative to the vehicle.
If the EH command returns true (e.g. tank addEventHandler["LaserFired","hint 'fired'; true"]), lasing will be interrupted (and the distance displayed will show up red).
If a range finder is returning an illegal range (too far or too close, as indicated by an "ERR" message), this EH will return the last lased distance, in addition to the new directions.

Passed array: [distance, elevation, turn]

• distance: Number - Current distance (or previous one, in case of error)
  
• elevation: Number - Required weapon elevation (in degrees) to hit the specified location
  
• turn: Number - Required weapon turning angle (in degrees) to hit the specified location
  

Other

AttachTo

Runs whenever an object is attached to another using the attachTo scripting command. Also runs when an object is detached from another object.

Passed array: [child, parent, position]

• child: Object - Object that was attached to another; or objNull if an object was detached
• parent: Object - Object that had an object attached to it
• position: Position3D - Position where object was attached to, in model coordinates

Init

Triggered on mission start or when a vehicle is created on the fly using createVehicle.

Passed array: [unit]

• unit: Object - Object the event handler is assigned to.