Arma 3: Event Handlers

An event handler (abbreviated to EH) allows you to automatically monitor and then execute custom code upon particular events being triggered.

See also Event Scripts for special event triggered scripts.

addEventHandler

Object event handler, always executed on the computer where it was added.

Commands:

• addEventHandler
• removeEventHandler
• removeAllEventHandlers

Example:

mySoldier addEventHandler ["Killed",{hint format ["%1 was killed by %2",name (_this select 0),name (_this select 1)];}]

Default

Class	Description	Arguments	MP-Effects	Since
AnimChanged	Triggered every time a new animation is started. It can be assigned to a remote unit but will only fire on the PC where the actual addEventHandler command was executed.	unit: Object - Object the event handler is assigned to anim: String - Name of the anim that is started
AnimDone	Triggered every time an animation is finished. It can be assigned to a remote unit but will only fire on the PC where the actual addEventHandler command was executed.	unit: Object - Object the event handler is assigned to anim: String - Name of the anim that has been finished
AnimStateChanged	Triggered every time an animation state changes. Unlike AnimChanged and AnimDone, it is triggered for all animation states in a sequence. It can be assigned to a remote unit but will only fire on the PC where the actual addEventHandler command was executed.	unit: Object - Object the event handler is assigned to anim: String - Name of the anim that has been started
ControlsShifted	Triggers when controls of vehicle are shifted (pilot->co-pilot, co-pilot->pilot). Works for both, "Take" and "Release" controls actions. Event only triggers on PC where vehicle is local and EH was added. Notes: If helicopter is local to the server and co-pilot takes controls, the helicopter changes locality to co-pilot PC. This means that if "ControlsShifted" EH was added on both server and client, "Take Controls" action will trigger EH on the server PC, but subsequent co-pilot "Release Controls" action will trigger it on co-pilot's PC.	vehicle: Object - Vehicle which controls were shifted. newController: Object - Unit who controls vehicle after this event. oldController: Object - Unit who controled vehicle before this event.
Dammaged	Triggered when the unit is damaged. In ArmA works with all vehicles not only men like in OFP. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed. Notes: If simultaneous damage occured (e.g. via grenade) EH might be triggered several times. The Dammaged EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased.	unit: Object - Object the event handler is assigned to selectionName: String - Name of the selection where the unit was damaged damage: Number - Resulting level of damage
Engine	Triggered when the engine of the unit is turned on/off.	vehicle: Object - Vehicle the event handler is assigned to engineState: Boolean - True when the engine is turned on, false when turned off
EpeContact	Triggered when object collision (PhysX) is in progress. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.	object1: Object - Object with attached handler. object2: Object - Object which is colliding with object1. select1: String - Selection of object1 which is colliding - not in use at this moment, empty string is always returned. select2: String - Selection of object2 which is colliding - not in use at this moment, empty string is always returned. force: Number - Force of collision.
EpeContactEnd	Triggered when object collision (PhysX) ends. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.	object1: Object - Object with attached handler. object2: Object - Object which is colliding with object1. select1: String - Selection of object1 which is colliding - not in use at this moment, empty string is always returned. select2: String - Selection of object2 which is colliding - not in use at this moment, empty string is always returned. force: Number - Force of collision.
EpeContactStart	Triggered when object collision (PhysX) starts. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.	object1: Object - Object with attached handler. object2: Object - Object which is colliding with object1. select1: String - Selection of object1 which is colliding - not in use at this moment, empty string is always returned. select2: String - Selection of object2 which is colliding - not in use at this moment, empty string is always returned. force: Number - Force of collision.
Explosion	Triggered when a vehicle or unit is damaged by a nearby explosion. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed.	vehicle: Object - Object the event handler is assigned to damage: Number - Damage inflicted to the object
Fired	Triggered when the unit fires a weapon. This EH will not trigger if a unit fires out of a vehicle. For those cases an EH has to be attached to that particular vehicle.	unit: Object - Object the event handler is assigned to weapon: String - Fired weapon muzzle: String - Muzzle that was used mode: String - Current mode of the fired weapon ammo: String - Ammo used magazine: String - magazine name which was used projectile: Object - Object of the projectile that was shot (Arma 2: OA and onwards)
FiredNear	Triggered when a weapon is fired somewhere near the unit or vehicle. It is also triggered if the unit itself is firing. (Exception(s): the Throw weapon wont broadcast the FiredNear event)	unit: Object - Object the event handler is assigned to firer: Object - Object which fires a weapon near the unit distance: Number - Distance in meters between the unit and firer (max. distance ~69m) weapon: String - Fired weapon muzzle: String - Muzzle that was used mode: String - Current mode of the fired weapon ammo: String - Ammo used
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).	vehicle: Object - Vehicle the event handler is assigned to fuelState: Boolean - 0 when no fuel, 1 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").	vehicle: Object - Vehicle the event handler is assigned to gearState: Boolean - True when the gear is lowered, false when retracted
GetIn	Triggers when a unit enters a vehicle. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed. This EH is neither triggered upon a change of positions within the same vehicle nor by the moveInXXXX commands. However it is triggered by a "GetInXXXX" action. In vehicles with multi-turret setup, entering any turret will show "gunner" for position.	vehicle: Object - Vehicle the event handler is assigned to position: String - Can be either "driver", "gunner", "commander" or "cargo" unit: Object - Unit that entered the vehicle
GetOut	Triggers when a unit gets out from a vehicle. It can be assigned to a remote vehicle but will only fire on the PC where the actual addEventHandler command was executed. This EH is triggered by both the moveOut command and by "GetOut" action.	vehicle: Object - Vehicle the event handler is assigned to position: String - Can be either "driver", "gunner", "commander" or "cargo" unit: Object - Unit that left the vehicle
HandleDamage	Triggers when the unit is damaged and fires for each damaged selection separately. Works with all vehicles. This EH can accept a remote unit as argument however it will only fire when the unit is local to the PC this event handler was added on. For example, you can add this event handler to one particular vehicle on every PC. When this vehicle gets hit, only EH on PC where the vehicle is currently local will fire. If code provided returns a numeric value, this value will overwrite the default damage of given selection after processing. Return value of 0 will make the unit invulnerable if damage is not scripted in other ways (i.e using setDamage and/or setHit for additional damage handling). If no value is returned, the default damage processing will be done. This allows for safe stacking of this event handler. Only the return value of the last added "HandleDamage" EH is considered. Notes: Multiple "HandleDamage" event handlers can be added to the same unit, however only the damage return value from the last added EH will be relayed to the game engine. You can save the last event as timestamp (diag_tickTime) onto the unit, as well as the current health of the unit/its selections, with setVariable and query it on each "HandleDamage" event with getVariable to define a system how to handle the "HandleDamage" event. "HandleDamage" will continue to trigger even if the unit is already dead. "HandleDamage" is persistent. If you add it to the player object, it will continue to exist after player respawned. "HandleDamage" can trigger "twice" per damage event. Once for direct damage, once for indirect damage (explosive damage). This can happen even in the same frame, but is unlikely. Additional Celery's explanation.	unit: Object - Object the event handler is assigned to. selectionName: String - Name of the selection where the unit was damaged. "" for over-all structural damage, "?" for unknown selections. damage: Number - Resulting level of damage for the selection. source: Object - The source unit that caused the damage. projectile: String - Classname of the projectile that caused inflicted the damage. ("" for unknown, such as falling damage.)
HandleHeal	Triggered when unit starts to heal (player using heal action or AI heals after being ordered). Triggers only on PC where EH is added and unit is local. If code returns false, engine side healing follows. Return true if you handle healing in script, use AISFinishHeal to tell engine that script side healing is done. See also lifeState and setUnconscious commands. NOTE: This Event Handler is broken but somewhat usable. When attached to a unit it will fire when medic action is started (not finished!) on the unit. _this select 0 will be the unit itself, _this select 1 will be the healer. The 3rd param will always be false and neither returning true nor using AISFinishHeal will have any effect on engine's default healing behaviour. If unit walks away from the healer during healing action, the heal will not finish but there is no way of detecting this within "handleheal" framework.	unit: Object healer: Object healercanheal: Boolean - true when healer is corpsman
Hit	Triggered when the unit is hit/damaged. Is not always triggered when unit is killed by a hit. Most of the time only the killed event handler is triggered when a unit dies from a hit. The hit EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased. Does not fire when a unit is set to allowDamage false.	unit: Object - Object the event handler is assigned to causedBy: Object - Object that caused the damage. Contains the unit itself in case of collisions. 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. While you can add "HitPart" handler to a remote unit, the respectful addEventHandler command must be executed on the shooter's PC and will only fire on shooter's PC as well. Additionally, if the unit gets damaged by any means other than shooter's shooting, "HitPart" will not fire. Because of this, this event handler is most suitable for when the shooter needs feedback on his shooting, such as target practicing or hitmarker creation.	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 (ASL). 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.
Init	Triggered on mission start or when a vehicle is created on the fly using createVehicle.	unit: Object - Object the event handler is assigned to
IncomingMissile	Triggered when a guided missile locked on the target or unguided missile or rocket aimed by AI at the target was fired.	unit: Object - Object the event handler is assigned to ammo: String - Ammo type that was fired on the unit whoFired: Object - Object that fired the weapon
InventoryOpened	Triggered when unit opens inventory.	unit: Object - Object the event handler is assigned to container: Object - connected container or weaponholder
Killed	Triggered when the unit is killed. Be careful when the killer has been a vehicle. For most cases the reference of the vehicle is the same as the effectiveCommander, but not always.	unit: Object - Object the event handler is assigned to killer: Object - Object that killed the unit Contains the unit itself in case of collisions.
LandedTouchDown	Triggered when a plane (AI or player) touches the ground.	plane: Object - Object the event handler is assigned to airportID: Number - ID of the airport (-1 for anything else)
LandedStopped	Triggered when an AI pilot would get out usually. Not executed for player.	plane: Object - Object the event handler is assigned to airportID: Number - ID of the airport (-1 for anything else)
Local	Triggered when locality of object in MP is changed.	localUnit: Object - Unit for who is object local. local: Boolean - If the object is local on given computer.
Respawn	Triggered when a unit respawns.	unit: Object - Object the event handler is assigned to corpse: Object - Object the event handler was assigned to, aka the corpse/unit player was previously controlling
Put	Triggers when a unit puts an item in a container.	unit: Object - Unit to which the event handler is assigned container: Object - The container into which the item was placed (vehicle, box, etc.) item: String - The class name of the moved item
Take	Triggers when a unit takes an item from a container.	unit: Object - Unit to which the event handler is assigned container: Object - The container from which the item was taken (vehicle, box, etc.) item: String - The class name of the taken item
SoundPlayed	Triggered when player is making noises when injured or fatigued.	unit: Object - Unit to which the event handler is assigned ?: Number - Unknown
WeaponAssembled	Triggers when weapon gets assembled.	unit: Object - Object the event handler is assigned to weapon: Object - Object of the assembled weapon
WeaponDisassembled	Triggers when weapon gets disassembled.	unit: Object - Object the event handler is assigned to primaryBag: Object - First backpack object which was weapon disassembled into secondarybag: Object - Second backpack object which was weapon disassembled into

Curator

Curator Event Handlers are also added with addEventHandler command and are supposed to be added to curator object (not player object) and where curator object is local and will be executed only where curator is local (i.e., on computer of player who's in control of it).

Class	Description	Arguments	MP-Effects	Since
CuratorFeedbackMessage	Triggered when curator attempts invalid action in curator interface. Each error has its own unique ID, recognized values are: 003 - when trying to teleport camera outside of curatorCameraArea 101 - trying to place an object when placing is disabled using setCuratorCoef "place" 102 - trying to place an object which is too expensive (cost set in curatorObjectRegistered multiplied by setCuratorCoef "place" is larger than curatorPoints) 103 - trying to place an object outside of curatorEditingArea 201 - trying to place a waypoint when waypoint placing is disabled 202 - trying to place a waypoint which is too expensive (cost set by setCuratorWaypointCost multiplied by setCuratorCoef "place" is larger than curatorPoints) 206 - trying to place a waypoint when no AI unit is selected 301 - trying to move or rotate an entity when editing is disabled using setCuratorCoef "edit" 302 - trying to move or rotate an entity when it's too expensive (entity cost multiplied by setCuratorCoef "edit" is larger than curatorPoints) 303 - trying to move an entity outside of curatorEditingArea 304 - trying to move or rotate an entity which is outside of curatorEditingArea 307 - trying to move or rotate a player (players cannot be manipulated with) 401 - trying to delete an entity when deleting is disabled using setCuratorCoef "delete" 402 - trying to delete an entity which is too expensive (cost multiplied by setCuratorCoef "delete" is larger than curatorPoints) 404 - trying to delete an entity which is outside of curatorEditingArea 405 - trying to delete an entity which has non-editable crew in it 407 - trying to delete a player (players cannot be manipulated with) 501 - trying to destroy an object when destroying is disabled using setCuratorCoef "destroy" 502 - trying to destroy an object which is too expensive (cost multiplied by setCuratorCoef "destroy" is larger than curatorPoints) 504 - trying to destroy an object which is outside of curatorEditingArea 505 - trying to destroy an object which has non-editable crew in it 506 - trying to destroy an object when no object is selected 507 - trying to destroy a player (players cannot be manipulated with) This handler is supposed to be added to curator module, not player.	curator: Object errorID: Number
CuratorGroupDoubleClicked	Triggered when a group is double-clicked on in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Group
CuratorGroupPlaced	Triggered when new group is placed in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Group
CuratorGroupSelectionChanged	Triggered when a group is selected in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Group
CuratorMarkerDeleted	Triggered when a marker is deleted in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: String
CuratorMarkerDoubleClicked	Triggered when a marker is double-clicked on in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: String
CuratorMarkerEdited	Triggered when a marker is moved in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: String
CuratorMarkerPlaced	Triggered when new marker is placed in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: String
CuratorMarkerSelectionChanged	Triggered when a marker is selected in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: String
CuratorObjectDeleted	Triggered when an object is deleted in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Object
CuratorObjectDoubleClicked	Triggered when an object is double-clicked on in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Object
CuratorObjectEdited	Triggered when an object is moved or rotated in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Object
CuratorObjectPlaced	Triggered when new object is placed in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Object
CuratorObjectRegistered	Triggered when player enters curator interface. Assign curator cost to every object in the game. This is the primary way how mission designer can limit what can curator placed. Full article - Curator This handler is supposed to be added to curator module, not player.	curator: Object input: Array of Strings - all CfgVehicles classes
CuratorObjectSelectionChanged	Triggered when an object is selected in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Object
CuratorPinged	Triggered when a player pings his curator(s) by pressing Zeus key. To add player to specific curator, use addCuratorEditableObjects command. This handler is supposed to be added to curator module, not player.	curator: Object player: Object
CuratorWaypointDeleted	Triggered when a waypoint is deleted in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Array
CuratorWaypointDoubleClicked	Triggered when a waypoint is double-clicked on in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Array
CuratorWaypointEdited	Triggered when a waypoint is moved in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Array
CuratorWaypointPlaced	Triggered when new waypoint is placed in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Array
CuratorWaypointSelectionChanged	Triggered when a waypoint is selected in curator interface. This handler is supposed to be added to curator module, not player.	curator: Object entity: Array

addMPEventHandler

Global object event handler, executed on every connected machine.

Commands:

• addMPEventHandler
• removeMPEventHandler
• removeAllMPEventHandlers

Example:

mySoldier addMPEventHandler ["MPKilled",{hint format ["%1 was killed by %2",name (_this select 0),name (_this select 1)];}]

Class	Description	Arguments	MP-Effects	Since
MPHit	Triggered when the unit is hit/damaged. EH can be added on any machine and EH code will trigger globally on every connected client and server. Add it only on server because if you have 10 machines on network and add this EH to every machine, when triggered the EH code will be executed 10 x 10 = 100 times. Is not always triggered when unit is killed by a hit. Most of the time only the Killed event handler is triggered when a unit dies from a hit. The hit EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased. Can also trigger several times for an explosion (direct and indirect damage). Does not fire when a unit is set to allowDamage false. However it will fire with "HandleDamage" EH added alongside stopping unit from taking damage addEventHandler ["HandleDamage",{0}]; Will not trigger when unit is dead. This EH must be used in conjunction with the addMPEventHandler command. Note: Call a function from the MPHit EH code space, rather to define the full code in there directly. The reason is the code space will be transferred over network on each event activation - so keep the data as small as possible!	unit: Object - Object the event handler is assigned to causedBy: Object - Object that caused the damage. Contains the unit itself in case of collisions. damage: Number - Level of damage caused by the hit
MPKilled	Triggered when the unit is killed. EH can be added on any machine and EH code will trigger globally on every connected client and server. Add it only on server because if you have 10 machines on network and add this EH to every machine, when triggered the EH code will be executed 10 x 10 = 100 times.	unit: Object - Object the event handler is assigned to killer: Object - Object that killed the unit Contains the unit itself in case of collisions
MPRespawn	Triggered when a unit respawns. Notes: This event never triggers on server: [1] As of OA 1.62, this command does not work as one would expect. It is only triggered on the machine where the unit it was assigned to is local. The only difference between Respawn and MPRespawn is that MPRespawn can be assigned from anywhere while Respawn requires the unit to be local. This command must be used in conjunction with the command addMPEventHandler rather than the old command used for non MP commands.	unit: Object - Object the event handler is assigned to corpse: Object - Object the event handler was assigned to, aka the corpse/unit player was previously controlling.

addMissionEventHandler

Mission event handler, always executed on the computer where it was added.

Commands:

• addMissionEventHandler
• removeMissionEventHandler
• removeAllMissionEventHandlers

Example:

addMissionEventHandler ["Loaded",{playMusic "EventTrack03_F_EPB";}]

Class	Description	Arguments	Since
Ended	Triggered when mission ends, either using trigger of type "End", endMission command, BIS_fnc_endMission function or ENDMISSION cheat.	endType: String - mission end type. Used in Debriefing among other things.
Loaded	Triggered when mission is loaded.	saveType: String - save type, can be have following values: "save" - custom save, achieved by pressing SAVE button in the pause menu "autosave" - automatic checkpoint, saved using saveGame command "continue" - saved when leaving a mission to the main menu

addMusicEventHandler

Music event handler, always executed on the computer where it was added.

Commands:

• setMusicEventHandler
• addMusicEventHandler
• removeMusicEventHandler
• removeAllMusicEventHandlers

Example:

addMusicEventHandler ["MusicStop",{playMusic (_this select 0);}]

Class	Description	Arguments	Since
MusicStart	Triggers when CfgMusic sound starts playing, after being executed with playMusic command. This event handler needs to be added with addMusicEventHandler command and removed with removeMusicEventHandler.	className: String - CfgMusic class name of currently playing sound. handlerID: Number - EH id returned by addMusicEventHandler.
MusicStop	Triggers when CfgMusic sound finished playing, after being executed with playMusic command. Note that EH will not be triggered if you force stop the music with playMusic "". This event handler needs to be added with addMusicEventHandler command and removed with removeMusicEventHandler.	className: String - CfgMusic class name of currently played sound. handlerID: Number - EH id returned by addMusicEventHandler.

ctrlAddEventHandler

Full article - User Interface Event Handlers

displayAddEventHandler

Full article - User Interface Event Handlers