Arma 3 Scripting

Topic in Event Handlers

Arma 3: Mission Event Handlers

Also available as Markdown and JSON, or read the original wiki page.

Arma 3 v0.50 Local Effect

Mission event handlers are specific EHs that are anchored to the running mission and automatically removed when mission is over. These events fire only on the machine where they have been added.

For all other available EHs see the Event Handlers main page.

Note

OnUser... mission event handlers used in combination with getUserInfo provide a way to track server users from the very early stage of joining a server to the very last stage of leaving the server. All these event handlers are designed to be used server side and return unique user network id in String format as the first param. These ids could also be obtained via getPlayerID and allUsers script commands. There may be other params specific to each event. See:

Events

ActionTargetChanged (Arma 3 v2.22)

Executes when action target object changes under cursor. This event handler fires before user actions are processed and added to the player.

addMissionEventHandler ["ActionTargetChanged", {
    params ["_newActionTarget", "_oldActionTarget"];
}];
ArtilleryShellFired (Arma 3 v2.18)

Global Mission Event Handler. Executes each time a vehicle classified as artillery (has an artillery computer) fires a shell.

addMissionEventHandler ["ArtilleryShellFired", {
    params ["_vehicle", "_weapon", "_ammo", "_gunner", "_instigator", "_artilleryTarget", "_targetPosition", "_shell"];
}];
BuildingChanged (Arma 3 v1.68)

Fired each time a building model changes, for example due to stages of destruction.

addMissionEventHandler ["BuildingChanged", {
    params ["_from", "_to", "_isRuin"];
}];
CommandModeChanged (Arma 3 v1.58)

Executes assigned code when user switches to/from High Command mode (LShift+Space). Stackable version of onCommandModeChanged.

addMissionEventHandler ["CommandModeChanged", {
    params ["_isHighCommand", "_isForced"];
}];
ControlsShifted (Arma 3 v1.00)

Triggers when control of a vehicle is shifted (pilot->co-pilot, co-pilot->pilot), usually when user performs an action such as TakeVehicleControl, SuspendVehicleControl, UnlockVehicleControl, LockVehicleControl, or when enableCopilot command is used. This event handler will always fire on the PC where action is triggered as well as where the vehicle is local at the time. When control of the vehicle is shifted, the locality of the vehicle changes to the locality of the new controller. Since Arma 3 v1.96 this EH is extended with additional params.

addMissionEventHandler ["ControlsShifted", {
    params ["_newController", "_oldController", "_vehicle", "_copilotEnabled", "_controlsUnlocked"];
}];
DisplayOpened (Arma 3 v2.22)

Executes when any display is opened.

addMissionEventHandler ["DisplayOpened", {
    params ["_display", "_configClass"];
}];
Draw2D (Arma 3 v2.18)

Runs after all UI has been drawn. Runs the EH code each frame in unscheduled environment. Client side EH only (presence of UI). Will stop executing when UI loses focus (Alt+Tab for example). Usually used with drawIcon.

addMissionEventHandler ["Draw2D", {
    // no params
}];
Draw3D (Arma 3 v0.50)

Runs the EH code each frame in unscheduled environment. Client side EH only (presence of UI). Will stop executing when UI loses focus (Alt+Tab for example). Usually used with drawIcon3D, drawLine3D.

addMissionEventHandler ["Draw3D", {
    // no params
}];
Drowned (Arma 3 v2.14)

Runs when a vehicle gets drowned (the vehicle is submerged below 'maxFord' for longer than 'waterResistance'). This will cause engine damage and for some vehicles that will render engine unusable until the vehicle/engine is fully repared. Some vehicles can drown but would still be recoverable as they wouldn't be destroyed. The event handler will also fire when vehicle is removed from water, in which case 'drowned' param will change to false. To check if the engine was damaged by water use waterDamaged command.

addMissionEventHandler ["Drowned", {
    params ["_vehicle", "_drowned"];
}];
EachFrame (Arma 3 v1.58)

Executes assigned code each frame. Stackable version of onEachFrame.

addMissionEventHandler ["EachFrame", {
    // no params
}];
Ended (Arma 3 v0.50)

Triggered when mission ends, either using trigger of type "End", endMission command, BIS_fnc_endMission function or ENDMISSION cheat.

addMissionEventHandler ["Ended", {
    params ["_endType"];
}];
MPEnded (Arma 3 v1.60)

Triggered when the server switches off from "playing" state (mission ends, server closes, etc.) It's only for MP games, it is called on server and also on clients. It is not called on clients when client disconnects from server (and mission continues). This EH has no arguments passed to the code.

addMissionEventHandler ["MPEnded", {
    // no params
}];

If client code must be executed on disconnect, this code can be used instead:

0 spawn
{
    waitUntil { !isNull findDisplay 46 };
    findDisplay 46 displayAddEventHandler ["Unload",
    {
        // code here gets executed on the client at end of mission, whether due to player abort, loss of connection, or mission ended by server
        // might not work on headless clients
    }];
};
EntityCreated (Arma 3 v2.10)

Triggered when an entity is created.

Note

Unlike most event handlers, the argument is entity Object and not an array containing the entity. However, it is recommended to use params to make sure the code remains compatible in case the event arguments are expanded in the future.

Important

This event is called before variable namespace is copied to remote respawning entity, keep this in mind so your setVariables are not overwritten in the next frame. EntityRespawned always fires after variable namespace is copied to new entity regardless of locality.

addMissionEventHandler ["EntityCreated", {
    params ["_entity"];
}];
EntityDeleted (Arma 3 v2.18)

Triggered when an entity is deleted. It only triggers for objects that support the "Deleted" event handler, such as vehicles, soldiers, animals, and houses. Simple objects for example are not supported.

Note

Unlike most event handlers, the argument is entity Object and not an array containing the entity. However, it is recommended to use params to make sure the code remains compatible in case the event arguments are expanded in the future.

addMissionEventHandler ["EntityDeleted", {
    params ["_entity"];
}];
EntityKilled (Arma 3 v1.56)

Triggered when an entity is killed.

addMissionEventHandler ["EntityKilled", {
    params ["_unit", "_killer", "_instigator", "_useEffects"];
}];

It's worth noting that instigator param is objNull during road kill. To work around this issue try:

addMissionEventHandler ["EntityKilled", {
    params ["_killed", "_killer", "_instigator"];
    if (isNull _instigator) then { _instigator = UAVControl vehicle _killer select 0 }; // UAV/UGV player operated road kill
    if (isNull _instigator) then { _instigator = _killer }; // player driven vehicle road kill
    hint format ["Killed By %1", name _instigator];
}];
EntityRespawned (Arma 3 v1.56)

Triggered when an entity is respawned.

addMissionEventHandler ["EntityRespawned", {
    params ["_newEntity", "_oldEntity"];
}];
ExtensionCallback (Arma 3 v1.96)

Triggered when an extension calls provided function pointer with 3 params.

addMissionEventHandler ["ExtensionCallback", {
    params ["_name", "_function", "_data"];
}];
GroupCreated (Arma 3 v2.04)

Triggered when a Group is created. Note that the group contains no units at that point!

addMissionEventHandler ["GroupCreated", {
    params ["_group"];
}];
GroupDeleted (Arma 3 v2.04)

Triggered when a Group is manually or automatically deleted.

addMissionEventHandler ["GroupDeleted", {
    params ["_group"];
}];
GroupIconClick (Arma 3 v1.58)

Executes assigned code when user clicks on the HC group icon on the map. If groupIconSelectable is true, LMB clicking (firing) at the HC group icon on the HUD will also trigger the event. To set group icon selectable use setGroupIconsSelectable. Stackable version of onGroupIconClick.

addMissionEventHandler ["GroupIconClick", {
    params [
        "_is3D", "_group", "_waypointId",
        "_mouseButton", "_posX", "_posY",
        "_shift", "_control", "_alt"
    ];
}];
GroupIconOverEnter (Arma 3 v1.58)

Continuously executes assigned code when user hovers with pointer over the HC group icon, either on the HUD or the main map. groupIconSelectable must be set to true for this EH to work at all. To set group icon selectable use setGroupIconsSelectable. When EH fires over the HUD icon, X and Y coordinates will change depending on the position of the pointer in relation to the icon area. When over main map, the X and Y do not change and indicate icon center. Stackable version of onGroupIconOverEnter.

addMissionEventHandler ["GroupIconOverEnter", {
    params [
        "_is3D", "_group", "_waypointId",
        "_posX", "_posY",
        "_shift", "_control", "_alt"
    ];
}];
GroupIconOverLeave (Arma 3 v1.58)

Executes assigned code when user moves the pointer away from HC group icon it was over. Fires either for on the HUD icons or the main map HC icons. groupIconSelectable must be set to true for this EH to work at all. To set group icon selectable use setGroupIconsSelectable. Stackable version of onGroupIconOverLeave.

addMissionEventHandler ["GroupIconOverLeave", {
    params [
        "_is3D", "_group", "_waypointId",
        "_posX", "_posY",
        "_shift", "_control", "_alt"
    ];
}];
HandleAccTime (Arma 3 v1.90)

Fires when user changes time acceleration with +/- keys in SP or setAccTime command. If the code returns true the on-screen message confirming the change is not displayed. Doesn't fire if desired value is already set.

addMissionEventHandler ["HandleAccTime", {
    params ["_currentTimeAcc", "_prevTimeAcc", "_messageSuppressed"];
}];
HandleChatMessage (Arma 3 v2.00)

Fires when a message is received, before adding it to the chat feed. Fires clientside.

Note

  • On a dedicated server and headless client it fires only for global (channel 0) and system messages (channel 16).
  • The HandleChatMessage EH can be used to disable/modify system messages like "Player NAME connecting/is losing connection".

Important

Does not trigger for any of the chat related script command such as systemChat, sideChat, or other chat commands.

The output message could be overridden:

Important

Only the last added HandleChatMessage EH with override will be used to override the message.

Warning

Do not put any of the chat related script command such as systemChat, sideChat, etc in this EH code as it would naturally cause recursion and the game will freeze.

addMissionEventHandler ["HandleChatMessage", {
    params ["_channel", "_owner", "_from", "_text", "_person", "_name", "_strID", "_forcedDisplay", "_isPlayerMessage", "_sentenceType", "_chatMessageType", "_params"];
}];
HandleDisconnect (Arma 3 v1.32 Server Execution)

Triggered right after a player disconnects from the game, more accurately when a player-controlled unit changes ownership due to the owning player being disconnected (disconnected player information is no available through e.g getUserInfo anymore). Similar to the #PlayerDisconnected event but contains the unit occupied by the player before their disconnection. Must be added on the server and triggers only on the server.

Important

A player disconnecting while not controlling a unit (not spawned, deleted unit, etc) does not trigger this event.

addMissionEventHandler ["HandleDisconnect", {
    params ["_unit", "_id", "_uid", "_name"];
    true;
}];
HCGroupSelectionChanged (Arma 3 v1.58)

Executes assigned code when user selects available HC group (F1, F2…). Stackable version of onHCGroupSelectionChanged.

addMissionEventHandler ["HCGroupSelectionChanged", {
    params ["_group", "_isSelected"];
}];
Loaded (Arma 3 v0.50)

Triggered when mission is loaded from save.

Warning

"Loaded" event handler should be added BEFORE the mission is loaded from save. Placing it in a function with preInit = 1; usually does the trick.

addMissionEventHandler ["Loaded", {
    params ["_saveType"];
}];
Map (Arma 3 v1.62)

Triggered when map is opened or closed either by user action or script command openMap.

addMissionEventHandler ["Map", {
    params ["_mapIsOpened", "_mapIsForced"];
}];
MapSingleClick (Arma 3 v1.58)

Executes when the player clicks anywhere on the main map. Stackable version of onMapSingleClick with the limitation that it does not have the ability to override the click (e.g. to prevent the player from placing the custom waypoint with LShift+LMB). Since the introduction of _thisArgs for addMissionEventHandler in Arma 3 v2.04, this EH also supports custom arguments (just like onMapSingleClick).

addMissionEventHandler ["MapSingleClick", {
    params ["_units", "_pos", "_alt", "_shift"];
}];
MarkerCreated (Arma 3 v2.02)

Executes when a marker is created either by a user or via script command.

addMissionEventHandler ["MarkerCreated", {
    params ["_marker", "_channelNumber", "_owner", "_local"];
}];
MarkerDeleted (Arma 3 v2.02)

Executes immediately before a marker is deleted either by a user or via script command.

addMissionEventHandler ["MarkerDeleted", {
    params ["_marker", "_local", "_deleter"];
}];
MarkerUpdated (Arma 3 v2.02)

Executes when a marker is changed.

Warning

Changing the marker in the EH code will lead to an infinite loop and the game will crash!

addMissionEventHandler ["MarkerUpdated", {
    params ["_marker", "_local"];
}];
OnUserConnected (Arma 3 v2.06 Server Execution)

Executes assigned code on user joining server.

addMissionEventHandler ["OnUserConnected", {
    params ["_networkId", "_clientStateNumber", "_clientState"];
}];
OnUserDisconnected (Arma 3 v2.06 Server Execution)

Executes assigned code on user leaving server.

addMissionEventHandler ["OnUserDisconnected", {
        params ["_networkId", "_clientStateNumber", "_clientState"];
}];
OnUserClientStateChanged (Arma 3 v2.06 Server Execution)

Executes assigned code for every stage of user client state change.

addMissionEventHandler ["OnUserClientStateChanged", {
    params ["_networkId", "_clientStateNumber", "_clientState"];
}];
OnUserAdminStateChanged (Arma 3 v2.06 Server Execution)

Executes assigned code after user logs in, gets voted in or logs out as admin.

addMissionEventHandler ["OnUserAdminStateChanged", {
    params ["_networkId", "_loggedIn", "_votedIn"];
}];
OnUserSelectedPlayer (Arma 3 v2.06 Server Execution)

Executes assigned code after player object is selected for user to take over control, the ownership information is broadcast and request to sync is made but the object is still owned by previous owner for a short time.

addMissionEventHandler ["OnUserSelectedPlayer", {
        params ["_networkId", "_playerObject", "_attempts"];
}];

Important

This is the earliest the player object is known when player joins the server, but it is not local to the user yet, so there is a wait time depending on network connection. When player respawns, the unit created on the client and so it might take a while before server has valid player object. From Arma 3 v2.18 the server will pospone this event until the object is not null, or until it tried 50 times, whichever is earlier. The best approach to handle this matter and get notified about completion of the transfer of the ownership is to use "Local" entity event handler, like so:

addMissionEventHandler ["OnUserSelectedPlayer", {
    params ["_networkId", "_playerObject", "_attempts"];
    _playerObject addEventHandler ["Local",
    {
        params ["_player"];
        _player removeEventHandler ["Local", _thisEventHandler];
        // code to handle _player
    }];
}];

Note that the player object would change locality again if the user goes to lobby.

OnUserKicked (Arma 3 v2.06 Server Execution)

Executes assigned code after after a user has been kicked from the server providing kick reason. The possible values for 'kickTypeNumber' and 'kickType' are: 0 : "TIMEOUT", 1 : "DISCONNECTED", 2 : "KICKED", 3 : "BANNED", 4 : "MISSING ADDON", 5 : "BAD CD KEY", 6 : "CD KEY IN USE", 7 : "SESSION LOCKED", 8 : "BATTLEYE", 9 : "STEAM CHECK", 10 : "DLC CONTENT", 11 : "GS TIMEOUT", 12 : "SCRIPT", 13 : "OTHER"

addMissionEventHandler ["OnUserKicked", {
    params ["_networkId", "_kickTypeNumber", "_kickType", "_kickReason", "_kickMessageIncReason"];
}];
PlayerConnected (Arma 3 v1.58 Server Execution)

Executes assigned code when client joins the mission in MP. Stackable version of onPlayerConnected.

addMissionEventHandler ["PlayerConnected", {
    params ["_id", "_uid", "_name", "_jip", "_owner", "_idStr"];
}];

Note

0 and 1 are special values:

  • 0 means everyone (including the server)
  • 1 means current machine but is not implemented and should not be used.

If a dedicated server was started without '-autoInit' option and this EH was created on server, on first GUI client this EH also fires against server, but after first client. In mission's initServer.sqf:

addMissionEventHandler ["PlayerConnected", {
    diag_log "Client connected";
    diag_log _this;
}];

In RPT: 2016/12/16, 15:39:09 "Client connected" 2016/12/16, 15:39:09 [1.51343e+009,"7xxxxxxxxxxxxxxx1","longbow",false,3,"1513430065"] 2016/12/16, 15:39:34 Mission id: 5071d20b183e9580d0ee4f95f413ca18681d6165 2016/12/16, 15:39:34 "Client connected" 2016/12/16, 15:39:34 [2,"","SERVER",false,2,"2"]

That happens only for GUI clients, if HC client connects first, EH does not fire for server.

If dedicated server was started with -autoInit option, this EH does not fire against server, only for future clients, and all further clients appear to be JIP'ed.

Interesting moment for headless clients, for headless clients instead of getPlayerUID, handler gets string like "HC12160", where '12160' is headless client process ID (matches HC's PID observed in windows task manager)

PlayerDisconnected (Arma 3 v1.58 Server Execution)

Executes assigned code when client leaves the mission in MP. Stackable version of onPlayerDisconnected.

addMissionEventHandler ["PlayerDisconnected", {
    params ["_id", "_uid", "_name", "_jip", "_owner", "_idstr"];
}];
PlayerViewChanged (Arma 3 v1.66)

Fired on player view change. Player view changes when player is changing body due to teamSwitch, gets in out of a vehicle or operates UAV for example.

addMissionEventHandler ["PlayerViewChanged", {
    params [
        "_oldUnit", "_newUnit", "_vehicleIn",
        "_oldCameraOn", "_newCameraOn", "_uav"
    ];
}];
PreloadStarted (Arma 3 v1.58)

Executes assigned code before the mission preload screen. Stackable version of onPreloadStarted.

Important

This event handler also fires on client after user closes the main map.

addMissionEventHandler ["PreloadStarted", {
    // no params
}];
PreloadFinished (Arma 3 v1.58)

Executes assigned code after the mission preload screen. Stackable version of onPreloadFinished.

Important

This event handler also fires on client after user closes the main map.

addMissionEventHandler ["PreloadFinished", {
    // no params
}];
ProjectileCreated (Arma 3 v2.10)

Triggered when a projectile is created.

addMissionEventHandler ["ProjectileCreated", {
    params ["_projectile"];
}];
SaveGame (Arma 3 v2.18)

Triggered just BEFORE the game saving process started but isSaving is already set to true. To know when the saving is finished check when isSaving returns false.

addMissionEventHandler ["SaveGame", {
    params ["_saveType"];
}];
ScriptError (Arma 3 v2.14)

Triggered when a script error occurs. See also the -showScriptErrors startup parameter.

Note

Event Handlers have a recursion check. Most of them have a level limit set to 1; ScriptError has it set to 2 - meaning that an error occuring inside the Event Handler will trigger once more the EH, but no more than two times total.

addMissionEventHandler ["ScriptError", {
    params ["_errorText", "_sourceFile", "_lineNumber", "_errorPos", "_content", "_stackTraceOutput"];
}];
ScriptSpawned (Arma 3 v2.22)

Executes when any script is spawned.

addMissionEventHandler ["ScriptSpawned", {
    params ["_data"];
}];
SelectedActionPerformed

RTM helicopter user action event

addMissionEventHandler ["SelectedActionPerformed", {
    params ["_caller", "_target", "_enumNumber", "_actionId"];
}];

Important

Limited or non-existent functionality

SelectedActionChanged

RTM helicopter user action event

addMissionEventHandler ["SelectedActionChanged", {
    params ["_caller", "_target", "_enumNumber", "_actionId"];
}];

Important

Limited or non-existent functionality

SelectedRotorLibActionPerformed

RTM helicopter user action event

addMissionEventHandler ["SelectedRotorLibActionPerformed", {
    params ["_caller", "_target", "_enumNumber", "_actionId"];
}];

Important

Works only for key press combination RightCtrl + W, which is the binding for helicopter wheels brakes. It fires with or without Advanced Flight Model enabled. The enum number returned is 4 and 5, probably because the enum is structured like this:

0: HelicopterAutoTrimOn

1: HelicopterAutoTrimOff

2: HelicopterTrimOn

3: HelicopterTrimOff

4: WheelsBrakeOn

5: WheelsBrakeOff

SelectedRotorLibActionChanged

RTM helicopter user action event

addMissionEventHandler ["SelectedRotorLibActionChanged", {
    params ["_caller", "_target", "_enumNumber", "_actionId"];
}];

Important

Limited or non-existent functionality

Service (Arma 3 v2.12)

Executes assigned code when a serviced vehicle gets rearmed, repaired or refueled. The code executes with interval while the serviced vehicle receives service. If the code returns true the default on-screen service message is not shown.

addMissionEventHandler ["Service", {
    params ["_serviceVehicle", "_servicedVehicle", "_serviceType", "_needsService", "_autoSupply"];
}];
TeamSwitch (Arma 3 v1.58)

Executes assigned code when player teamswitches. Stackable version of onTeamSwitch.

addMissionEventHandler ["TeamSwitch", {
    params ["_previousUnit", "_newUnit"];
}];
UAVCrewCreated (Arma 3 v2.14)

Fires when UAV or UGV is assembled from Backpack after the AI crew is created

addMissionEventHandler ["UAVCrewCreated", {
    params ["_uav", "_driver", "_gunner"];
}];