View source for Arma 3: Mission Event Handlers

__NOEDITSECTION__
{{TOC|side}}

{{Icon|localEffect|32}}

== Description ==

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.<br>
For all other available EHs see the [[Arma_3:_Event_Handlers|Event Handlers main page]].

{{Feature|Informative|'''OnUser...''' mission event handlers 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:
* [[Arma_3:_Mission_Event_Handlers#OnUserConnected | OnUserConnected]]
* [[Arma_3:_Mission_Event_Handlers#OnUserDisconnected | OnUserDisconnected]]
* [[Arma_3:_Mission_Event_Handlers#OnUserClientStateChanged | OnUserClientStateChanged]]
* [[Arma_3:_Mission_Event_Handlers#OnUserAdminStateChanged | OnUserAdminStateChanged]]
* [[Arma_3:_Mission_Event_Handlers#OnUserSelectedPlayer | OnUserSelectedPlayer]]
* [[Arma_3:_Mission_Event_Handlers#OnUserKicked | OnUserKicked]]
}}


== Related Commands ==

* [[addMissionEventHandler]]
* [[removeMissionEventHandler]]
* [[removeAllMissionEventHandlers]]


== Events ==

{{ConfigPage|start}}
{{ConfigPage|abc}}
{{ArgTitle|4|BuildingChanged|{{GVI|arma3|1.68}}}}
Fired each time a building model changes, for example due to stages of destruction.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["BuildingChanged", {
	params ["_previousObject", "_newObject", "_isRuin"];
}];
</syntaxhighlight>

* from: [[Object]] - building it changes from
* to: [[Object]] - building it changes to
* isRuin: [[Boolean]] - [[true]] if changes to ruins


{{ArgTitle|4|CommandModeChanged|{{GVI|arma3|1.58}}}}
Executes assigned code when user switches to/from HC command mode (<tt>Left Shift + Space</tt>). Stackable version of [[onCommandModeChanged]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["CommandModeChanged", {
	params ["_isHighCommand", "_isForced"];
}];
</syntaxhighlight>

* isHighCommand: [[Boolean]] - same as <tt>_isHighCommand</tt> param
* isForced: [[Boolean]] - [[true]] if command mode was forced


{{ArgTitle|4|ControlsShifted|{{GVI|arma3|1.00}}}}
Triggers when control of a vehicle is shifted (pilot->co-pilot, co-pilot->pilot), usually when user performs an [[action]] such as [[action/Arma_3_Actions_List#TakeVehicleControl | TakeVehicleControl]], [[action/Arma_3_Actions_List#SuspendVehicleControl | SuspendVehicleControl]], [[action/Arma_3_Actions_List#UnlockVehicleControl | UnlockVehicleControl]], [[action/Arma_3_Actions_List#LockVehicleControl | 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 [[Multiplayer Scripting#Locality|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.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["ControlsShifted", {
	params ["_newController", "_oldController", "_vehicle", "_copilotEnabled", "_controlsUnlocked"];
}];
</syntaxhighlight>

* newController: [[Object]] - unit currently controlling the vehicle
* oldController: [[Object]] - unit previously controlling the vehicle
* vehicle: [[Object]] - the vehicle for which controls shifted
* copilotEnabled: [[Boolean]] - [[true]] if copilot is enabled
* controlsUnlocked: [[Boolean]] - [[true]] if controls are unlocked


{{ArgTitle|4|Draw3D|{{GVI|arma3|0.50}}}}
Runs the EH code each frame in unscheduled environment. Client side EH only (presence of UI).
Will stop executing when UI loses focus (if user Alt+Tabs for example). Usually used with [[drawIcon3D]], [[drawLine3D]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["Draw3D", {
	// no params
}];
</syntaxhighlight>


{{ArgTitle|4|EachFrame|{{GVI|arma3|1.58}}}}
Executes assigned code each frame. Stackable version of [[onEachFrame]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["EachFrame", {
	// no params
}];
</syntaxhighlight>


{{ArgTitle|4|Ended|{{GVI|arma3|0.50}}}}
Triggered when mission ends, either using trigger of type "End", [[endMission]] command, [[BIS_fnc_endMission]] function or [[Arma 3: Cheats#ENDMISSION|ENDMISSION]] cheat.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["Ended", {
	params ["_endType"];
}];
</syntaxhighlight>

* endType: [[String]] - mission end type. Used in [[Debriefing]] among other things.

{{ArgTitle|4|MPEnded|{{GVI|arma3|1.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's not called on clients when client disconnects from server (and mission continues). This EH has no arguments passed to the code.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["MPEnded", {
// code to execute
}];
</syntaxhighlight>
If you need to execute client code on disconnect, you can use this 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
 	}];
 };

{{ArgTitle|4|EntityKilled|{{GVI|arma3|1.56}}}}
Triggered when an entity is killed. 
<syntaxhighlight lang="cpp">
addMissionEventHandler ["EntityKilled", {
	params ["_unit", "_killer", "_instigator", "_useEffects"];
}];
</syntaxhighlight>

* killed: [[Object]] - entity that was killed
* killer: [[Object]] - the killer (vehicle or person)
* {{GVI|arma3|1.66}} instigator: [[Object]] - person who pulled the trigger
* {{GVI|arma3|1.68}} useEffects: [[Boolean]] - same as ''useEffects'' in [[setDamage]] alt syntax
----

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}; {{cc|UAV/UGV player operated road kill}}
 	[[if]] ([[isNull]] _instigator) [[then]] {_instigator = _killer}; {{cc|player driven vehicle road kill}}
 	[[hint]] [[format]] ["Killed By %1", [[name]] _instigator];
 }];

{{ArgTitle|4|EntityRespawned|{{GVI|arma3|1.56}}}}
Triggered when an entity is respawned.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["EntityRespawned", {
	params ["_entity", "_corpse"];
}];
</syntaxhighlight>

* newEntity: [[Object]] - respawned entity
* oldEntity: [[Object]] - corpse/wreck


{{ArgTitle|4|ExtensionCallback|{{GVI|arma3|1.96}}}}
Triggered when an [[callExtension | extension]] calls provided function pointer with 3 params.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["ExtensionCallback", {
	params ["_name", "_function", "_data"];
}];
</syntaxhighlight>

* name: [[String]] - user provided param
* function: [[String]] - user provided param
* data: [[String]] - user provided param


{{ArgTitle|4|GroupCreated|{{GVI|arma3|2.04}}}}
Triggered when a [[Group]] is created. Note that the group contains '''no''' units at that point!
<syntaxhighlight lang="cpp">
addMissionEventHandler ["GroupCreated", {
	params ["_group"];
}];
</syntaxhighlight>

* group: [[Group]] - the created group


{{ArgTitle|4|GroupDeleted|{{GVI|arma3|2.04}}}}
Triggered when a [[Group]] is [[deleteGroup|manually]] or [[deleteGroupWhenEmpty|automatically]] deleted.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["GroupDeleted", {
	params ["_group"];
}];
</syntaxhighlight>

* group: [[Group]] - the deleted group


{{ArgTitle|4|GroupIconClick|{{GVI|arma3|1.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]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["GroupIconClick", {
	params [
		"_is3D", "_group", "_waypointId",
		"_mouseButton", "_posX", "_posY",
		"_shift", "_control", "_alt"
	];
}];
</syntaxhighlight>

* is3D: [[Boolean]] - [[true]] if HUD icon, [[false]] if main map icon
* group: [[Group]] - group the icon belonds to
* wpID: [[Number]] - waypoint ID
* mb: [[Number]] - mouse button: 0 - LMB, 1 - RMB (only applicable to IconClick)
* posX: [[Number]] - screen X of the mouse
* posY: [[Number]] - screen Y of the mouse
* shift: [[Boolean]] - [[true]] if <tt>Shift</tt> key was pressed
* ctrl: [[Boolean]] - [[true]] if <tt>Ctrl</tt> key was pressed
* alt: [[Boolean]] - [[true]] if <tt>Alt</tt> key was pressed


{{ArgTitle|4|GroupIconOverEnter|{{GVI|arma3|1.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]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["GroupIconOverEnter", {
	params [
		"_is3D", "_group", "_waypointId",
		"_posX", "_posY",
		"_shift", "_control", "_alt"
	];
}];
</syntaxhighlight>

* is3D: [[Boolean]] - [[true]] if HUD icon, [[false]] if main map icon
* group: [[Group]] - group the icon belonds to
* wpID: [[Number]] - waypoint ID
* posX: [[Number]] - screen X of the mouse
* posY: [[Number]] - screen Y of the mouse
* shift: [[Boolean]] - [[true]] if <tt>Shift</tt> key was pressed
* ctrl: [[Boolean]] - [[true]] if <tt>Ctrl</tt> key was pressed
* alt: [[Boolean]] - [[true]] if <tt>Alt</tt> key was pressed


{{ArgTitle|4|GroupIconOverLeave|{{GVI|arma3|1.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]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["GroupIconOverLeave", {
	params [
		"_is3D", "_group", "_waypointId",
		"_posX", "_posY",
		"_shift", "_control", "_alt"
	];
}];
</syntaxhighlight>

* is3D: [[Boolean]] - [[true]] if HUD icon, [[false]] if main map icon
* group: [[Group]] - group the icon belonds to
* wpID: [[Number]] - waypoint ID
* posX: [[Number]] - screen X of the mouse
* posY: [[Number]] - screen Y of the mouse (Y is always 0 when leaving HUD icon for some reason)
* shift: [[Boolean]] - [[true]] if <tt>Shift</tt> key was pressed
* ctrl: [[Boolean]] - [[true]] if <tt>Ctrl</tt> key was pressed
* alt: [[Boolean]] - [[true]] if <tt>Alt</tt> key was pressed


{{ArgTitle|4|HandleAccTime|{{GVI|arma3|1.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.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["HandleAccTime", {
	params ["_currentTimeAcc", "_prevTimeAcc", "_messageSuppressed"];
}];
</syntaxhighlight>

* currentTimeAcc: [[Number]] - current value
* prevTimeAcc: [[Number]] - previous value
* messageSuppressed: [[Boolean]] - [[true]] if on-screen message was suppressed


{{ArgTitle|4|HandleChatMessage|{{GVI|arma3|2.00}}}}
Fires when a message is received, before adding it to the chat feed. Fires clientside. The output message could be overridden:
* Return [[true]] to block incoming chat message from being added to the chat feed.
* Return [[String]] to replace the chat message content but not the sender name.
* Return [[Array]] [from, text] to replace both the chat message content and the the sender's name.
{{Feature | Informative | Only the last added EH with override will be used to override the message.}}
{{Feature | 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.}}
<syntaxhighlight lang="cpp">
addMissionEventHandler ["HandleChatMessage", {
	params ["_channel", "_owner", "_from", "_text", "_person", "_name", "_strID", "_forcedDisplay", "_isPlayerMessage", "_sentenceType", "_chatMessageType"];
}];
</syntaxhighlight>

* channel: [[Number]] - See [[Description.ext#disableChannels|radio channel indexes]] (16 for system chat message for example)
* owner: [[Number]] - [[owner]] id of the sender:
** In SP: 0
** In MP with no sender: [[clientOwner]]
** In MP with sender: sender's [[clientOwner]], or if AI - creator id part of [[netId]] of the AI
* from: [[String]] - sender's formatted name as appeared on the chat 
* text: [[String]] - the chat message
* person: [[Object]] - sender's object
* name: [[String]] - sender's [[name]], could be different from <tt>from</tt>
* strID: [[String]] - sender's network player ID (marker id):
** "-1": means not available
** "0": means [[player | isPlayer]] in SP
** "1": means AI in SP or MP
** >1: [[getPlayerID]] in MP
* forcedDisplay: [[Boolean]] - if the message should be displayed when the chat list is disabled (when [[enableRadio]] is set to [[false]] radio protocol messages won't display)
* isPlayerMessage: [[Boolean]] - if the message is addressed to [[player]]
* sentenceType: [[Number]] - 0: Normal type, 1: Protocol type 
* chatMessageType: [[Number]] - 0: Generic type, 1: SimpleMove type, 2: KillConfirmation type 


{{ArgTitle|4|HandleDisconnect|{{GVI|arma3|1.32}}&nbsp;{{Icon|serverExec|32}}}}
Triggered when player disconnects from the game. Similar to [[onPlayerDisconnected]] event but can be stacked and contains the unit occupied by player before disconnect. Must be added on the server and triggers only on the server.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["HandleDisconnect", {
	params ["_unit", "_id", "_uid", "_name"];
	true;
}];
</syntaxhighlight>

* unit: [[Object]] - unit formerly occupied by player
* id: [[Number]] - same as _id in [[onPlayerDisconnected]]
* uid: [[String]] - same as _uid in [[onPlayerDisconnected]]
* name: [[String]] - same as _name in [[onPlayerDisconnected]]
'''Override''': If this EH code returns [[true]], the unit, previously occupied by player, gets transferred to the server, becomes AI and continues to live, even with [[Description.ext|description.ext]] param ''disabledAI = 1;''


{{ArgTitle|4|HCGroupSelectionChanged|{{GVI|arma3|1.58}}}}
Executes assigned code when user selects available HC group (<tt>F1, F2…</tt>). Stackable version of [[onHCGroupSelectionChanged]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["HCGroupSelectionChanged", {
	params ["_group", "_isSelected"];
}];
</syntaxhighlight>

* group: [[Group]] - group selected (same as <tt>_group</tt> param)
* isSelected: [[Boolean]] - [[true]] if selected (same as <tt>_isSelected</tt> param)


{{ArgTitle|4|Loaded|{{GVI|arma3|0.50}}}}
Triggered when mission is loaded from save. <br>
{{Feature | Warning | "Loaded" event handler should be added <u>BEFORE</u> the mission is loaded from save. Placing it in a [[Arma 3: Functions Library|function]] with preInit {{=}} 1; usually does the trick.}}
<syntaxhighlight lang="cpp">
addMissionEventHandler ["Loaded", {
	params ["_saveType"];
}];
</syntaxhighlight>

* 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


{{ArgTitle|4|Map|{{GVI|arma3|1.62}}}}
Triggered when map is opened or closed either by user action or script command [[openMap]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["Map", {
	params ["_mapIsOpened", "_mapIsForced"];
}];
</syntaxhighlight>

* mapIsOpened: [[Boolean]] - [[true]] if map is opened
* mapIsForced: [[Boolean]] - [[true]] if map is forced


{{ArgTitle|4|MapSingleClick|{{GVI|arma3|1.58}}}}
Executes assigned code when user clicks anywhere on the main map. Stackable version of [[onMapSingleClick]] with some limitations:
* No arguments can be passed to the assigned code in comparison with the original EH
* Does not have engine default functionality override like the original EH
<syntaxhighlight lang="cpp">
addMissionEventHandler ["MapSingleClick", {
	params ["_units", "_pos", "_alt", "_shift"];
}];
</syntaxhighlight>

* units: [[Array]] - leader selected units, same as [[groupSelectedUnits]] (same as <tt>_units</tt> param)
* pos: [[Array]] - world [[Position3D]] of the click in format [x,y,0] (same as <tt>_pos</tt> param)
* alt: [[Boolean]] - [[true]] if <tt>Alt</tt> key was pressed (same as <tt>_alt</tt> param)
* shift: [[Boolean]] - [[true]] if <tt>Shift</tt> key was pressed (same as <tt>_shift</tt> param)

{{ArgTitle|4|MarkerCreated|{{GVI|arma3|2.02}}}}
Executes when a marker is created either by a user or via script command.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["MarkerCreated", {
	params ["_marker", "_channelNumber", "_owner", "_local"];
}];
</syntaxhighlight>
* marker: [[String]] - The name of the created marker, can be used with the [[:Category:Command_Group:_Markers|marker commands]]
* channelNumber: [[Number]] - [[Channel IDs|Channel]] in which the marker was created
* owner: [[Object]] - Player that created the marker or [[objNull]]
* {{GVI|arma3|2.04}} local: [[Boolean]] - [[true]] if the event originated locally, [[false]] if it came over the network

{{ArgTitle|4|MarkerDeleted|{{GVI|arma3|2.02}}}}
Executes when a marker is deleted either by a user or via script command.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["MarkerDeleted", {
	params ["_marker", "_local"];
}];
</syntaxhighlight>
* marker: [[String]] - The name of the deleted marker
* {{GVI|arma3|2.04}} local: [[Boolean]] - [[true]] if the event originated locally, [[false]] if it came over the network

{{ArgTitle|4|MarkerUpdated|{{GVI|arma3|2.02}}}}
Executes when a marker is changed.
{{Feature|Warning|Changing the marker in the EH code will lead to an infinite loop and the game will crash!}}
<syntaxhighlight lang="cpp">
addMissionEventHandler ["MarkerUpdated", {
	params ["_marker", "_local"];
}];
</syntaxhighlight>
* marker: [[String]] - The name of the marker
* {{GVI|arma3|2.04}} local: [[Boolean]] - [[true]] if the event originated locally, [[false]] if it came over the network


{{ArgTitle|4|OnUserConnected|{{GVI|arma3|2.06}}&nbsp;{{Icon|serverExec|32}}}}
Executes assigned code on user joining server.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["OnUserConnected", {
	params ["_networkId", "_clientStateNumber", "_clientState"];
}];
</syntaxhighlight>
* networkId: [[String]] - user network id (see [[getPlayerID]], [[allUsers]])
* clientStateNumber: [[Number]] - client state number (see [[getClientStateNumber]]) // always 1
* clientState: [[String]] - client state (see [[getClientState]]) // always "CREATED"


{{ArgTitle|4|OnUserDisconnected|{{GVI|arma3|2.06}}&nbsp;{{Icon|serverExec|32}}}}
Executes assigned code on user leaving server.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["OnUserDisconnected", {
		params ["_networkId", "_clientStateNumber", "_clientState"];
}];
</syntaxhighlight>
* networkId: [[String]] - user network id (see [[getPlayerID]], [[allUsers]])
* clientStateNumber: [[Number]] - client state number (see [[getClientStateNumber]]) // always 0
* clientState: [[String]] - client state (see [[getClientState]]) // always "NONE"


{{ArgTitle|4|OnUserClientStateChanged|{{GVI|arma3|2.06}}&nbsp;{{Icon|serverExec|32}}}}
Executes assigned code for every stage of user client state change. 
<syntaxhighlight lang="cpp">
addMissionEventHandler ["OnUserClientStateChanged", {
	params ["_networkId", "_clientStateNumber", "_clientState"];
}];
</syntaxhighlight>
* networkId: [[String]] - user network id (see [[getPlayerID]], [[allUsers]])
* clientStateNumber: [[Number]] - client state number (see [[getClientStateNumber]])
* clientState: [[String]] - client state (see [[getClientState]])


{{ArgTitle|4|OnUserAdminStateChanged|{{GVI|arma3|2.06}}&nbsp;{{Icon|serverExec|32}}}}
Executes assigned code after user logs in, gets voted in or logs out as admin.
<syntaxhighlight lang="cpp">
	params ["_networkId", "_loggedIn", "_votedIn"];
}];
</syntaxhighlight>
* networkId: [[String]] - user network id (see [[getPlayerID]], [[allUsers]])
* loggedIn: [[Boolean]] - [[true]] if user logged in or got voted in as admin, [[false]] if logged out (see [[admin]])
* votedIn: [[Boolean]] - [[true]] if user got voted in as admin, [[false]] otherwise (see [[admin]])


{{ArgTitle|4|OnUserSelectedPlayer|{{GVI|arma3|2.06}}&nbsp;{{Icon|serverExec|32}}}}
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. 
<syntaxhighlight lang="cpp">
addMissionEventHandler ["OnUserSelectedPlayer", {
		params ["_networkId", "_playerObject"];
}];
</syntaxhighlight>
* networkId: [[String]] - user network id (see [[getPlayerID]], [[allUsers]])
* playerObject: [[Object]] - player object to be controlled by the user (see [[player]], [[selectPlayer]])
{{Feature|Important|This is the earliest the player object is known, but it is not local to the user yet, so there is a wait time depending on network connection. The best approach to handle this matter and get notified about completion of the transfer of the ownership is to use [[Arma_3:_Event_Handlers#Local|"Local"]] entity event handler, like so:
<code>[[addMissionEventHandler]] ["OnUserSelectedPlayer", 
{
	[[params]] ["_networkId", "_playerObject"];
	_playerObject [[addEventHandler]] ["Local", 
	{
		[[removeEventHandler]] ["Local", _thisEventHandler];
		[[params]] ["_player"];
		// code to handle _player
	}];
}];</code>
Note that the player object would change locality again if the user goes to lobby.}}


{{ArgTitle|4|OnUserKicked|{{GVI|arma3|2.06}}&nbsp;{{Icon|serverExec|32}}}}
Executes assigned code after after a user has been kicked from the server providing kick reason. The possible values for 'kickTypeNumber' and 'kickType' are:<br>0 : <tt>"TIMEOUT"</tt>, 1 : <tt>"DISCONNECTED"</tt>, 2 : <tt>"KICKED"</tt>, 3 : <tt>"BANNED"</tt>, 4 : <tt>"MISSING ADDON"</tt>, 5 : <tt>"BAD CD KEY"</tt>, 6 : <tt>"CD KEY IN USE"</tt>, 7 : <tt>"SESSION LOCKED"</tt>, 8 : <tt>"BATTLEYE"</tt>, 9 : <tt>"STEAM CHECK"</tt>, 10 : <tt>"DLC CONTENT"</tt>, 11 : <tt>"GS TIMEOUT"</tt>, 12 : <tt>"SCRIPT"</tt>, 13 : <tt>"OTHER"</tt>
<syntaxhighlight lang="cpp">
	params ["_networkId", "_kickTypeNumber", "_kickType", "_kickReason", "_kickMessageIncReason"];
}];
</syntaxhighlight>
* networkId: [[String]] - user network id (see [[getPlayerID]], [[allUsers]])
* kickTypeNumber: [[Number]] - kick type number (see above)
* kickType: [[String]] - kick type (see above)
* kickReason: [[String]] - reason given for the kick by the admin or by other means
* kickMessageIncReason: [[String]] - formatted engine message including the given reason


{{ArgTitle|4|PlayerConnected|{{GVI|arma3|1.58}}&nbsp;{{Icon|serverExec|32}}}}
Executes assigned code when client joins the mission in MP. Stackable version of [[onPlayerConnected]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["PlayerConnected",
{
	params ["_id", "_uid", "_name", "_jip", "_owner", "_idstr"];
}];
</syntaxhighlight>

* id: [[Number]] - unique DirectPlay ID (very large number). It is also the same id used for user placed markers (same as <tt>_id</tt> param)
* uid: [[String]] - [[getPlayerUID]] of the joining client. The same as Steam ID (same as <tt>_uid</tt> param)
* name: [[String]] - [[profileName]] of the joining client (same as <tt>_name</tt> param)
* jip: [[Boolean]] - [[didJIP]] of the joining client (same as <tt>_jip</tt> param)
* owner: [[Number]] - [[owner]] id of the joining client (same as <tt>_owner</tt> param)
* idstr: [[String]] - same as id but in string format, so could be exactly compared to [[allMapMarkers | user marker]] ids
----

If 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:
 handlercon = [[addMissionEventHandler]] ["PlayerConnected",
 {
 	[[diag_log]] "Client connected";
 	[[diag_log]] [[Magic Variables#this|_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.<br>
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 JIPped.<br>
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)


{{ArgTitle|4|PlayerDisconnected|{{GVI|arma3|1.58}}&nbsp;{{Icon|serverExec|32}}}}
Executes assigned code when client leaves the mission in MP. Stackable version of [[onPlayerDisconnected]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["PlayerDisconnected",
{
	params ["_id", "_uid", "_name", "_jip", "_owner", "_idstr"];
}];
</syntaxhighlight>

* id: [[Number]] - unique DirectPlay ID (very large number). It is also the same id used for user placed markers (same as <tt>_id</tt> param)
* uid: [[String]] - [[getPlayerUID]] of the leaving client. The same as Steam ID (same as <tt>_uid</tt> param)
* name: [[String]] - [[profileName]] of the leaving client (same as <tt>_name</tt> param)
* jip: [[Boolean]] - [[didJIP]] of the leaving client (same as <tt>_jip</tt> param)
* owner: [[Number]] - [[owner]] id of the leaving client (same as <tt>_owner</tt> param)
* idstr: [[String]] - same as id but in string format, so could be exactly compared to [[allMapMarkers | user marker]] ids


{{ArgTitle|4|PlayerViewChanged|{{GVI|arma3|1.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.
<syntaxhighlight lang="cpp">
addMissionEventHandler ["PlayerViewChanged", {
	params [
		"_oldUnit", "_newUnit", "_vehicle",
		"_oldCamera", "_newCamera", "_uav"
	];
}];
</syntaxhighlight>

* oldBody: [[Object]] - player body before EH fired
* newBody: [[Object]] - player body after EH fired
* vehicleIn: [[Object]] - vehicle player is in ([[objNull]] if not in vehicle)
* oldCameraOn: [[Object]] - [[cameraOn]] before EH fired
* newCameraOn: [[Object]] - [[cameraOn]] after EH fired
* UAV: [[Object]] - UAV reference if player is operating one ([[objNull]] if not operating UAV)


{{ArgTitle|4|PreloadStarted|{{GVI|arma3|1.58}}}}
Executes assigned code before the mission preload screen. Stackable version of [[onPreloadStarted]].<br>
{{Feature | important | This event handler also fires on client after user closes the main map. }}
<syntaxhighlight lang="cpp">
addMissionEventHandler ["PreloadStarted", {
	// no params
}];
</syntaxhighlight>


{{ArgTitle|4|PreloadFinished|{{GVI|arma3|1.58}}}}
Executes assigned code after the mission preload screen. Stackable version of [[onPreloadFinished]].<br>
{{Feature | important | This event handler also fires on client after user closes the main map. }}
<syntaxhighlight lang="cpp">
addMissionEventHandler ["PreloadFinished", {
	// no params
}];
</syntaxhighlight>


==== SelectedActionPerformed ====
RTM helicopter user action event
<syntaxhighlight lang="cpp">
addMissionEventHandler ["SelectedActionPerformed", {
	params ["_caller", "_target", "_enumNumber", "_actionId"];
}];
</syntaxhighlight>

{{Feature|important|Limited or non-existent functionality}}


==== SelectedActionChanged ====
RTM helicopter user action event
<syntaxhighlight lang="cpp">
addMissionEventHandler ["SelectedActionChanged", {
	params ["_caller", "_target", "_enumNumber", "_actionId"];
}];
</syntaxhighlight>

{{Feature|important|Limited or non-existent functionality}}


==== SelectedRotorLibActionPerformed ====
RTM helicopter user action event
<syntaxhighlight lang="cpp">
addMissionEventHandler ["SelectedRotorLibActionPerformed", {
	params ["_caller", "_target", "_enumNumber", "_actionId"];
}];
</syntaxhighlight>

{{Feature|important|Works only for key press combination <tt>RightCtrl</tt> + <tt>W</tt>, 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:<br>
0: HelicopterAutoTrimOn<br>
1: HelicopterAutoTrimOff<br>
2: HelicopterTrimOn<br>
3: HelicopterTrimOff<br>
4: WheelsBrakeOn<br>
5: WheelsBrakeOff
}}


==== SelectedRotorLibActionChanged ====
RTM helicopter user action event
<syntaxhighlight lang="cpp">
addMissionEventHandler ["SelectedRotorLibActionChanged", {
	params ["_caller", "_target", "_enumNumber", "_actionId"];
}];
</syntaxhighlight>

{{Feature|important|Limited or non-existent functionality}}


{{ArgTitle|4|TeamSwitch|{{GVI|arma3|1.58}}}}
Executes assigned code when player teamswitches. Stackable version of [[onTeamSwitch]].
<syntaxhighlight lang="cpp">
addMissionEventHandler ["TeamSwitch", {
	params ["_previousUnit", "_newUnit"];
}];
</syntaxhighlight>

* previousUnit: [[Object]] - switching from unit (same as <tt>_from</tt> param)
* newUnit: [[Object]] - switching to unit (same as <tt>_to</tt> param)

{{ConfigPage|end}}


[[Category: Event Handlers]]