Event Handlers – Arma 3
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:
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. This EH is only triggered for the 1st animation state 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. |
|||
AnimDone |
Triggered every time an animation is finished. 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. |
|||
AnimStateChanged |
Triggered every time an animation state changes. 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. |
| ||
ContainerClosed |
Triggers when player finished accessing cargo container. This event handler is similar to "InventoryClosed" EH, but needs to be assigned to the container rather than the player. Note: will trigger only for the unit opening container. |
| ||
ContainerOpened |
Triggers when cargo container is accessed by player. This event handler is similar to "InventoryOpened" EH, but needs to be assigned to the container rather than the player and cannot be overridden. Note: will trigger only for the unit opening container.. |
|||
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:
|
| ||
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:
|
(Since Arma 3 v 1.67) (Since Arma 3 v 1.69)
|
||
Deleted |
Triggered just before the assigned entity is deleted. |
|
||
Engine |
Triggered when the engine of the unit is turned on/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. |
|
||
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. |
|
||
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. |
|
||
Explosion |
Triggered when a vehicle or unit is damaged by a nearby explosion. It can be assigned to a remote unit or vehicle but will only fire on the PC where EH is added and explosion is local, i.e. it really needs to be added on every PC and JIP and will fire only where the explosion is originated. |
|||
Fired |
Triggered when the unit fires a weapon. |
(Since Arma 2 OA)
(Since Arma 3 v 1.65)
|
||
FiredMan |
Triggered when the unit fires a weapon. This EH must be attached to a soldier and unlike with "Fired" EH, it will fire regardless of whether the soldier is on foot or firing vehicle weapon. For remoteControled unit use "Fired" EH instead. |
|
||
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). When "Manual Fire" is used, the gunner is objNull if gunner is not present or the gunner is not the one who fires. To check if "Manual Fire" is on, use isManualFire. The actual shot instigator could be retrieved with getShotParents command. 1.30 Works with thrown weapons. |
(Since Arma 3 v 1.65)
|
||
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). |
|||
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"). Also triggered for helicopters in landing mode, regardless if they have or don't have retractable gear. |
|||
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 triggered by moveInXXXX commands and "GetInXXXX" actions, but not upon a seat change within the same vehicle. In vehicles with multi-turret setup, entering any turret will show "gunner" for position. |
(Since Arma 3 v1.36)
|
||
GetInMan |
Triggers when a unit enters a vehicle. Similar to "GetIn" but must be assigned to a unit and not vehicle. Persistent on respawn if assigned where unit was local. This EH is triggered by moveInXXXX commands and "GetInXXXX" actions. |
|||
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 moveOut, "GetOut" & "Eject" actions, if an alive crew member disconnects or is deleted, but not upon a seat change within the same vehicle. |
|||
GetOutMan |
Triggers when a unit exits a vehicle. Similar to "GetOut" but must be assigned to a unit and not vehicle. Persistent on respawn if assigned where unit was local. This EH is triggered by moveOut and "GetOut" & "Eject" actions. |
| ||
HandleDamage |
Triggers when the unit is damaged and fires for each damaged selection separately (Note: Currently, in Arma 3 v1.70 it triggers for every selection of a vehicle, no matter if the section was damaged or not). 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:
Additional Celery's explanation (Updated by ShadowRanger for Arma 3). |
(Since Arma 3 v1.49)
(Since Arma 3 v1.65)
(Since Arma 3 v 1.67)
|
| |
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. |
| ||
HandleRating |
Triggered when engine adds rating to overall rating of the unit, usually after a kill or a friendly kill. If EH code returns Number, this will override default engine behaviour and the resulting value added will be the one returned by EH code. |
| ||
HandleScore |
Triggered when engine adds score to overall score of the unit, usually after a kill. If the EH code returns true or Nothing, the default engine score is applied, if it returns false, the engine score doesn't get added. For remote units like players, the event does not persist after respawn, and must be re-added to the new unit. |
| ||
Hit |
Triggered when the unit is hit/damaged. Is not always triggered when unit is killed by a hit. |
(Since Arma 3 v1.65)
|
||
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 one selection name for the hit component (i.e. a single piece of geometry can be simultaneously part of multiple, overlapping named selections). 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. The event will not fire if the shooter is not local, even if the target itself is local. 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. Notes
|
|
||
Init |
Triggered whenever an entity is created. Cannot be used in scripts, only inside class Eventhandlers in config. |
|
||
HandleIdentity |
Triggered whenever an entity is created. Can be used in scripts if EH is added immediately after unit is created in unscheduled environment. If EH scope returns true, the default engine identity application is overridden. |
|
||
IncomingMissile |
Triggered when a guided missile locked on the target or unguided missile or rocket aimed by AI at the target was fired. |
(Since Arma 3 v1.42)
(Since Arma 3 v1.65)
|
||
InventoryClosed |
Triggered when unit closes inventory.
|
|||
InventoryOpened |
Triggered when unit opens inventory. End EH main scope with true to override the opening of the inventory in case you wish to handle it yourself:
|
(Since Arma 3 v1.65.139079) |
||
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. |
(Since Arma 3 v1.65)
(Since Arma 3 v1.67) |
||
LandedTouchDown |
Triggered when a plane (AI or player) touches the ground. |
|||
LandedStopped |
Triggered when an AI pilot would get out usually. Not executed for player. |
|||
Landing |
Triggered when an AI pilot (or auto-pilot) is preparing for landing. The exact moment of triggering coincides with lowering of the gear ("Gear" EH) |
|||
LandingCanceled |
Triggered when AI pilot landing is cancelled (for example new order received to land elsewhere). The exact moment of triggering coincides with retracting of the gear ("Gear" EH). Note: Doesn't trigger if player switches off auto-pilot. Canceled is spelled with one L |
|||
Local |
Triggers when locality of object in MP is changed. The event handler only triggers on the computers that are directly involved in change of locality. So if EH is added to every computer on network, it will only trigger on 2 computers, on the computer that receives ownership of the object (new owner), in which case _this select 1 will be true, and on the computer from which ownership is transferred (old owner), in which case _this select 1 will be false. |
|||
PostReset |
Triggers after PP effects have been reset by the engine |
| ||
Put |
Triggers when a unit puts an item in a container. |
|||
Reloaded |
Triggers when a weapon is reloaded with a new magazine. For more information see: Reloaded |
|||
Respawn |
Triggered when a unit respawns. |
|||
RopeAttach |
Triggered when a rope is attached to an object. |
|||
RopeBreak |
Triggered when a rope is detached from an object. |
|||
SeatSwitched |
Triggered when unit changes seat within vehicle. EH returns both units switching seats. If switching seats with an empty seat, one of the returned units will be objNull. The new position can be obtained with assignedVehicleRole <unit>. This EH must be assigned to a vehicle. |
|||
SeatSwitchedMan |
Triggered when unit changes seat within vehicle. EH returns both units switching seats. If switching seats with an empty seat, one of the returned units will be objNull. The new position can be obtained with assignedVehicleRole <unit>. This EH must be assigned to a unit and not a vehicle. This EH is persistent and will be transferred to the new unit after respawn, but only if it was assigned where unit was local. |
|||
SoundPlayed |
Triggered when player is making noises when injured or fatigued for example. The number param passed to the EH code, points to the sound origin:
|
|||
Take |
Triggers when a unit takes an item from a container. |
|||
TaskSetAsCurrent |
Triggers when player's current task changes |
|||
TurnIn |
Triggers when member of crew in a vehicle uses Turn In action |
| ||
TurnOut |
Triggers when member of crew in a vehicle uses Turn Out action |
| ||
WeaponAssembled |
Triggers when weapon gets assembled. EH should be attached to the unit and not the weapon. |
|||
WeaponDisassembled |
Triggers when weapon gets disassembled. EH should be attached to the unit and not the weapon. |
|||
WeaponDeployed |
Triggers when the deployed state of a weapon or bipod changes. Note: A weapon cannot be rested and deployed at the same time. |
| ||
WeaponRested |
Triggers when weapon rested state changes (weapon near a surface that can provide weapon support). Note: A weapon cannot be rested and deployed at the same time. |
Curator
Curator Event Handlers are also added with addEventHandler command and are supposed to be added to curator object (not player object) where curator object is local and will be executed only where curator is local (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:
|
|||
CuratorGroupDoubleClicked |
Triggered when a group is double-clicked on in curator interface.
|
|||
CuratorGroupPlaced |
Triggered when new group is placed in curator interface.
|
|||
CuratorGroupSelectionChanged |
Triggered when a group is selected in curator interface.
|
|||
CuratorMarkerDeleted |
Triggered when a marker is deleted in curator interface.
|
|||
CuratorMarkerDoubleClicked |
Triggered when a marker is double-clicked on in curator interface.
|
|||
CuratorMarkerEdited |
Triggered when a marker is moved in curator interface.
|
|||
CuratorMarkerPlaced |
Triggered when new marker is placed in curator interface.
|
|||
CuratorMarkerSelectionChanged |
Triggered when a marker is selected in curator interface.
|
|||
CuratorObjectDeleted |
Triggered when an object is deleted in curator interface.
|
|||
CuratorObjectDoubleClicked |
Triggered when an object is double-clicked on in curator interface.
|
|||
CuratorObjectEdited |
Triggered when an object is moved or rotated in curator interface.
|
|||
CuratorObjectPlaced |
Triggered when new object is placed in curator interface. This event handler will trigger individually for each unit in a placed group - excluding the crew in vehicles.
|
|||
CuratorObjectRegistered |
Triggered when player enters curator interface. Assign curator cost to every object in the game. This is the primary method that a mission designer can use to limit the objects a curator can place. Full article - Curator This handler is supposed to be added to curator module, not player. |
|||
CuratorObjectSelectionChanged |
Triggered when an object is selected in curator interface.
|
|||
CuratorPinged |
Triggered when a player pings his curator(s) by pressing Zeus key. To add player to specific curator, use addCuratorEditableObjects command.
|
|||
CuratorWaypointDeleted |
Triggered when a waypoint is deleted in curator interface.
|
|||
CuratorWaypointDoubleClicked |
Triggered when a waypoint is double-clicked on in curator interface.
|
|||
CuratorWaypointEdited |
Triggered when a waypoint is moved in curator interface.
|
|||
CuratorWaypointPlaced |
Triggered when new waypoint is placed in curator interface.
|
|||
CuratorWaypointSelectionChanged |
Triggered when a waypoint is selected in curator interface.
|
Eden Editor
Full article - Event Handlers: Eden Editor
addMPEventHandler
Global object event handler, executed on every connected machine.
Commands:
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. This EH is clever enough to be triggered globally only once even if added on all clients or a single client that is then disconnected, EH will still trigger globally only once. 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! |
(Since Arma 3 v1.65)
|
||
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. This EH is clever enough to be triggered globally only once even if added on all clients or a single client that is then disconnected, EH will still trigger globally only once. This EH must be used in conjunction with the addMPEventHandler command. |
(Since Arma 3 v1.65)
(Since Arma 3 v1.67) |
||
MPRespawn |
Triggered when a unit, it is assigned to, respawns. This EH does not work as one would expect MP EH should work like. It is only triggered on one 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 EH must be used in conjunction with the addMPEventHandler command.
|
Mission Event Handlers
Mission event handlers are specific EHs that are anchored to the running mission and automatically removed when mission is over. There are following mission EHs available in Arma 3:
- Draw3D - Drawing HUD event
- Ended - Mission end event
- Loaded - Game loading from save event
- Map - Map open/close event
- HandleDisconnect - Player disconnect in MP event
- EntityRespawned - Some entity respawn event
- EntityKilled - Some entity death event
- EachFrame - Per frame event
- MapSingleClick - Map click event
- HCGroupSelectionChanged - High Command group select event
- CommandModeChanged - High Command mode change event
- GroupIconClick - High Command icon click event
- GroupIconOverEnter - High Command icon enter event
- GroupIconOverLeave - High Command icon leave event
- PlayerConnected - Client joining MP mission event
- PlayerDisconnected - Client leaving MP mission event
- TeamSwitch - Player teamswitch event
- PreloadStarted - Mission preload start event
- PreloadFinished - Mission preload finish event
- PlayerViewChanged - Player view change event
- BuildingChanged - Building model change event
For detailed description see Mission Event Handlers page.
In Game UI Event Handlers
In Game UI Event Handlers trigger when user scrolls or activates in game action menu. There are following mission EHs available in Arma 3:
- PrevAction - Action menu scroll up event
- Action - Action menu action event
- NextAction - Action menu scroll down event
For detailed description see In Game UI Event Handlers page.
addMusicEventHandler
Music event handler, always executed on the computer where it was added.
Commands:
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. |
|
|
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. |
|
add3DENEventHandler
Full article - Arma 3: Event Handlers: Eden Editor
ctrlAddEventHandler
Full article - User Interface Event Handlers
displayAddEventHandler
Full article - User Interface Event Handlers