Difference between revisions of "Arma 3: Event Handlers/addMissionEventHandler"

From Bohemia Interactive Community
Jump to navigation Jump to search
(Sort alphabetically)
(First examples should not be notes and fixes, but a barebones example like the rest. Addendums should be last for consistency.)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
__NOEDITSECTION__
 
__NOEDITSECTION__
 
{{SideTOC}}
 
{{SideTOC}}
 +
 +
{{EffArg|com|eff|loc}}
  
 
== Description ==
 
== Description ==
  
 
Mission event handlers are specific EHs that are anchored to the running mission and automatically removed when mission is over.
 
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]].
 
For all other available EHs see the [[Arma_3:_Event_Handlers|Event Handlers main page]].
 +
  
 
== Related Commands ==
 
== Related Commands ==
Line 12: Line 16:
 
* [[removeMissionEventHandler]]
 
* [[removeMissionEventHandler]]
 
* [[removeAllMissionEventHandlers]]
 
* [[removeAllMissionEventHandlers]]
 +
  
 
== Events ==
 
== Events ==
 +
 
{{Cfg ref|start}}
 
{{Cfg ref|start}}
 
{{Cfg ref|abc}}
 
{{Cfg ref|abc}}
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.68}}</div>
+
{{ArgTitle|BuildingChanged|4|{{GVI|arma3|1.68}}}}
==== BuildingChanged ====
 
</div>
 
 
Fired each time a building model changes, for example due to stages of destruction.
 
Fired each time a building model changes, for example due to stages of destruction.
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
Line 31: Line 35:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|CommandModeChanged|4|{{GVI|arma3|1.57}}}}
==== CommandModeChanged ====
 
</div>
 
 
Executes assigned code when user switches to/from HC command mode (<tt>Left Shift + Space</tt>). Stackable version of [[onCommandModeChanged]].
 
Executes assigned code when user switches to/from HC command mode (<tt>Left Shift + Space</tt>). Stackable version of [[onCommandModeChanged]].
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
Line 42: Line 44:
  
 
* isHighCommand: [[Boolean]] - same as <tt>_isHighCommand</tt> param
 
* isHighCommand: [[Boolean]] - same as <tt>_isHighCommand</tt> param
* IsForced: [[Boolean]] - [[true]] if command mode was forced
+
* isForced: [[Boolean]] - [[true]] if command mode was forced
 +
 
 +
 
 +
{{ArgTitle|ControlsShifted|4|{{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 [[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.95.146023 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
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|0.50}}</div>
+
{{ArgTitle|Draw3D|4|{{GVI|arma3|0.50}}}}
==== Draw3D ====
 
</div>
 
 
Runs the EH code each frame in unscheduled environment. Client side EH only (presence of UI).
 
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]].
 
Will stop executing when UI loses focus (if user Alt+Tabs for example). Usually used with [[drawIcon3D]], [[drawLine3D]].
Line 57: Line 72:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|EachFrame|4|{{GVI|arma3|1.57}}}}
==== EachFrame ====
 
</div>
 
 
Executes assigned code each frame. Stackable version of [[onEachFrame]].
 
Executes assigned code each frame. Stackable version of [[onEachFrame]].
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
Line 68: Line 81:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|0.50}}</div>
+
{{ArgTitle|Ended|4|{{GVI|arma3|0.50}}}}
==== Ended ====
 
</div>
 
 
Triggered when mission ends, either using trigger of type "End", [[endMission]] command, [[BIS_fnc_endMission]] function or [[ArmA:_Cheats#ENDMISSION|ENDMISSION]] cheat.
 
Triggered when mission ends, either using trigger of type "End", [[endMission]] command, [[BIS_fnc_endMission]] function or [[ArmA:_Cheats#ENDMISSION|ENDMISSION]] cheat.
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
Line 80: Line 91:
 
* endType: [[String]] - mission end type. Used in [[Debriefing]] among other things.
 
* endType: [[String]] - mission end type. Used in [[Debriefing]] among other things.
  
 +
{{ArgTitle|MPEnded|4|{{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's 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>
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.55}}</div>
+
{{ArgTitle|EntityKilled|4|{{GVI|arma3|1.55}}}}
==== EntityKilled ====
+
Triggered when an entity is killed.  
</div>
 
Triggered when an entity is killed. Worth noting that ''instigator'' param is [[objNull]] during road kill. To work around this issue try:
 
<code>[[addMissionEventHandler]] ["EntityKilled",
 
{
 
[[params]] ["_killed", "_killer", "_instigator"];
 
[[if]] ([[isNull]] _instigator) [[then]] {_instigator = [[UAVControl]] [[vehicle]] _killer [[select]] 0}; {{codecomment|// UAV/UGV player operated road kill}}
 
[[if]] ([[isNull]] _instigator) [[then]] {_instigator = _killer}; {{codecomment|// player driven vehicle road kill}}
 
[[hint]] [[format]] ["Killed By %1", [[name]] _instigator];
 
}];</code>
 
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
 
addMissionEventHandler ["EntityKilled", {
 
addMissionEventHandler ["EntityKilled", {
Line 102: Line 111:
 
* {{GVI|arma3|1.65}} instigator: [[Object]] - person who pulled the trigger
 
* {{GVI|arma3|1.65}} instigator: [[Object]] - person who pulled the trigger
 
* {{GVI|arma3|1.67}} useEffects: [[Boolean]] - same as ''useEffects'' in [[setDamage]] alt syntax
 
* {{GVI|arma3|1.67}} 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}; {{codecomment|// UAV/UGV player operated road kill}}
 +
[[if]] ([[isNull]] _instigator) [[then]] {_instigator = _killer}; {{codecomment|// player driven vehicle road kill}}
 +
[[hint]] [[format]] ["Killed By %1", [[name]] _instigator];
 +
}];
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.55}}</div>
+
{{ArgTitle|EntityRespawned|4|{{GVI|arma3|1.55}}}}
==== EntityRespawned ====
 
</div>
 
 
Triggered when an entity is respawned.
 
Triggered when an entity is respawned.
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
Line 118: Line 134:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|ExtensionCallback|4|{{GVI|arma3|1.95}}}}
==== GroupIconClick ====
+
Triggered when an [[callExtension | extension]] calls provided function pointer with 3 params.
</div>
+
<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|GroupIconClick|4|{{GVI|arma3|1.57}}}}
 
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]].
 
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">
 
<syntaxhighlight lang="cpp">
Line 143: Line 170:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|GroupIconOverEnter|4|{{GVI|arma3|1.57}}}}
==== GroupIconOverEnter ====
 
</div>
 
 
'''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]].
 
'''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">
 
<syntaxhighlight lang="cpp">
Line 167: Line 192:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|GroupIconOverLeave|4|{{GVI|arma3|1.57}}}}
==== GroupIconOverLeave ====
 
</div>
 
 
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]].
 
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">
 
<syntaxhighlight lang="cpp">
Line 189: Line 212:
 
* ctrl: [[Boolean]] - [[true]] if <tt>Ctrl</tt> key was pressed
 
* ctrl: [[Boolean]] - [[true]] if <tt>Ctrl</tt> key was pressed
 
* alt: [[Boolean]] - [[true]] if <tt>Alt</tt> key was pressed
 
* alt: [[Boolean]] - [[true]] if <tt>Alt</tt> key was pressed
 +
  
 
{{ArgTitle|HandleAccTime|4|{{GVI|arma3|1.90}}}}
 
{{ArgTitle|HandleAccTime|4|{{GVI|arma3|1.90}}}}
Line 219: Line 243:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|HCGroupSelectionChanged|4|{{GVI|arma3|1.57}}}}
==== HCGroupSelectionChanged ====
 
</div>
 
 
Executes assigned code when user selects available HC group (<tt>F1, F2…</tt>). Stackable version of [[onHCGroupSelectionChanged]].
 
Executes assigned code when user selects available HC group (<tt>F1, F2…</tt>). Stackable version of [[onHCGroupSelectionChanged]].
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
Line 233: Line 255:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|0.50}}</div>
+
{{ArgTitle|Loaded|4|{{GVI|arma3|0.50}}}}
==== Loaded ====
 
</div>
 
 
Triggered when mission is loaded from save. <br>
 
Triggered when mission is loaded from save. <br>
'''NOTE''': "Loaded" event handler should be added <u>BEFORE</u> the mission is loaded from save. Placing it in a [[Functions_Library_(Arma_3)|function]] with preInit = 1; usually does the trick.
+
{{Warning | "Loaded" event handler should be added <u>BEFORE</u> the mission is loaded from save. Placing it in a [[Functions_Library_(Arma_3)|function]] with preInit {{=}} 1; usually does the trick.}}
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
 
addMissionEventHandler ["Loaded", {
 
addMissionEventHandler ["Loaded", {
Line 250: Line 270:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.62}}</div>
+
{{ArgTitle|Map|4|{{GVI|arma3|1.62}}}}
==== Map ====
 
</div>
 
 
Triggered when map is opened or closed either by user action or script command [[openMap]].
 
Triggered when map is opened or closed either by user action or script command [[openMap]].
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
Line 264: Line 282:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|MapSingleClick|4|{{GVI|arma3|1.57}}}}
==== MapSingleClick ====
 
</div>
 
 
Executes assigned code when user clicks anywhere on the main map. Stackable version of [[onMapSingleClick]] with some limitations:
 
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
 
* No arguments can be passed to the assigned code in comparison with the original EH
Line 282: Line 298:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}&nbsp;<div class="gvi">[[File:Exec_Server.gif]]</div></div>
+
{{ArgTitle|PlayerConnected|4|{{GVI|arma3|1.57}}&nbsp;<div class{{=}}"gvi">[[File:Exec_Server.gif]]</div>}}
==== PlayerConnected ====
 
</div>
 
 
Executes assigned code when client joins the mission in MP. Stackable version of [[onPlayerConnected]].
 
Executes assigned code when client joins the mission in MP. Stackable version of [[onPlayerConnected]].
 
+
<syntaxhighlight lang="cpp">
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.
+
addMissionEventHandler ["PlayerConnected",
In mission's initServer.sqf:
 
<code>handlercon = [[addMissionEventHandler]] ["PlayerConnected",
 
 
{
 
{
[[diag_log]] "Client connected";
+
params ["_id", "_uid", "_name", "_jip", "_owner", "_idstr"];
[[diag_log]] [[_this]];
 
}];</code>
 
In RPT:
 
<code>2016/12/16, 15:39:09 "Client connected"
 
2016/12/16, 15:39:09 [5.21041e+007,"7xxxxxxxxxxxxxxx1","longbow",false,4]
 
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]</code>
 
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)
 
<syntaxhighlight lang="cpp">
 
addMissionEventHandler ["PlayerConnected", {
 
params ["_id", "_uid", "_name", "_jip", "_owner"];
 
 
}];
 
}];
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 314: Line 312:
 
* jip: [[Boolean]] - [[didJIP]] of the joining client (same as <tt>_jip</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)
 
* 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]] [[_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)
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}&nbsp;<div class="gvi">[[File:Exec_Server.gif]]</div></div>
+
{{ArgTitle|PlayerDisconnected|4|{{GVI|arma3|1.57}}&nbsp;<div class{{=}}"gvi">[[File:Exec_Server.gif]]</div>}}
==== PlayerDisconnected ====
 
</div>
 
 
Executes assigned code when client leaves the mission in MP. Stackable version of [[onPlayerDisconnected]].
 
Executes assigned code when client leaves the mission in MP. Stackable version of [[onPlayerDisconnected]].
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
addMissionEventHandler ["PlayerDisconnected", {
+
addMissionEventHandler ["PlayerDisconnected",
params ["_id", "_uid", "_name", "_jip", "_owner"];
+
{
 +
params ["_id", "_uid", "_name", "_jip", "_owner", "_idstr"];
 
}];
 
}];
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 331: Line 347:
 
* jip: [[Boolean]] - [[didJIP]] of the leaving client (same as <tt>_jip</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)
 
* 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
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.66}}</div>
+
{{ArgTitle|PlayerViewChanged|4|{{GVI|arma3|1.66}}}}
==== PlayerViewChanged ====
 
</div>
 
 
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.
 
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">
 
<syntaxhighlight lang="cpp">
Line 354: Line 369:
  
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|PreloadStarted|4|{{GVI|arma3|1.57}}}}
==== PreloadStarted ====
 
</div>
 
 
Executes assigned code before the mission preload screen. Stackable version of [[onPreloadStarted]].<br>
 
Executes assigned code before the mission preload screen. Stackable version of [[onPreloadStarted]].<br>
 
{{Important | This event handler also fires on client after user closes the main map. }}
 
{{Important | This event handler also fires on client after user closes the main map. }}
Line 365: Line 378:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
 
==== PreloadFinished ====
+
{{ArgTitle|PreloadFinished|4|{{GVI|arma3|1.57}}}}
</div>
 
 
Executes assigned code after the mission preload screen. Stackable version of [[onPreloadFinished]].<br>
 
Executes assigned code after the mission preload screen. Stackable version of [[onPreloadFinished]].<br>
 
{{Important | This event handler also fires on client after user closes the main map. }}
 
{{Important | This event handler also fires on client after user closes the main map. }}
Line 375: Line 387:
 
}];
 
}];
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
  
 
==== SelectedActionPerformed ====
 
==== SelectedActionPerformed ====
Line 384: Line 397:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
{{Important|Limited or non-existent functionality}}  
+
{{Important|Limited or non-existent functionality}}
 +
 
  
 
==== SelectedActionChanged ====
 
==== SelectedActionChanged ====
Line 394: Line 408:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
{{Important|Limited or non-existent functionality}}  
+
{{Important|Limited or non-existent functionality}}
 +
 
  
 
==== SelectedRotorLibActionPerformed ====
 
==== SelectedRotorLibActionPerformed ====
Line 411: Line 426:
 
4: WheelsBrakeOn<br>
 
4: WheelsBrakeOn<br>
 
5: WheelsBrakeOff
 
5: WheelsBrakeOff
}}  
+
}}
 +
 
  
 
==== SelectedRotorLibActionChanged ====
 
==== SelectedRotorLibActionChanged ====
Line 421: Line 437:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
{{Important|Limited or non-existent functionality}}  
+
{{Important|Limited or non-existent functionality}}
 +
 
  
<div><div style="float: left; margin-right: 0.5em;">{{GVI|arma3|1.57}}</div>
+
{{ArgTitle|TeamSwitch|4|{{GVI|arma3|1.57}}}}
==== TeamSwitch ====
 
</div>
 
 
Executes assigned code when player teamswitches. Stackable version of [[onTeamSwitch]].
 
Executes assigned code when player teamswitches. Stackable version of [[onTeamSwitch]].
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
Line 433: Line 448:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
* from: [[Object]] - switching from unit (same as <tt>_from</tt> param)
+
* previousUnit: [[Object]] - switching from unit (same as <tt>_from</tt> param)
* to: [[Object]] - switching to unit (same as <tt>_to</tt> param)
+
* newUnit: [[Object]] - switching to unit (same as <tt>_to</tt> param)
  
 
{{Cfg ref|end}}
 
{{Cfg ref|end}}

Latest revision as of 02:09, 13 April 2020

Effects of this scripting command are not broadcasted over the network and remain local to the client the command is executed on

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.
For all other available EHs see the Event Handlers main page.


Related Commands


Events

Introduced with Arma 3 version 1.681.68

BuildingChanged

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

addMissionEventHandler ["BuildingChanged", {
	params ["_previousObject", "_newObject", "_isRuin"];
}];
  • from: Object - building it changes from
  • to: Object - building it changes to
  • isRuin: Boolean - true if changes to ruins


Introduced with Arma 3 version 1.571.57

CommandModeChanged

Executes assigned code when user switches to/from HC command mode (Left Shift + Space). Stackable version of onCommandModeChanged.

addMissionEventHandler ["CommandModeChanged", {
	params ["_isHighCommand", "_isForced"];
}];
  • isHighCommand: Boolean - same as _isHighCommand param
  • isForced: Boolean - true if command mode was forced


Introduced with Arma 3 version 1.001.00

ControlsShifted

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.95.146023 this EH is extended with additional params.

addMissionEventHandler ["ControlsShifted", {
	params ["_newController", "_oldController", "_vehicle", "_copilotEnabled", "_controlsUnlocked"];
}];
  • 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


Introduced with Arma 3 version 0.500.50

Draw3D

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.

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


Introduced with Arma 3 version 1.571.57

EachFrame

Executes assigned code each frame. Stackable version of onEachFrame.

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


Introduced with Arma 3 version 0.500.50

Ended

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

addMissionEventHandler ["Ended", {
	params ["_endType"];
}];
Introduced with Arma 3 version 1.601.60

MPEnded

Triggered when the server switches off from "playing" state (mission ends, server closes, etc.) It's only for MP games, it's 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.

addMissionEventHandler ["MPEnded", {
// code to execute
}];
Introduced with Arma 3 version 1.551.55

EntityKilled

Triggered when an entity is killed.

addMissionEventHandler ["EntityKilled", {
	params ["_unit", "_killer", "_instigator", "_useEffects"];
}];
  • killed: Object - entity that was killed
  • killer: Object - the killer (vehicle or person)
  • Introduced with Arma 3 version 1.651.65 instigator: Object - person who pulled the trigger
  • Introduced with Arma 3 version 1.671.67 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}; // UAV/UGV player operated road kill
	if (isNull _instigator) then {_instigator = _killer}; // player driven vehicle road kill
	hint format ["Killed By %1", name _instigator];
}];
Introduced with Arma 3 version 1.551.55

EntityRespawned

Triggered when an entity is respawned.

addMissionEventHandler ["EntityRespawned", {
	params ["_entity", "_corpse"];
}];
  • newEntity: Object - respawned entity
  • oldEntity: Object - corpse/wreck


Introduced with Arma 3 version 1.951.95

ExtensionCallback

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

addMissionEventHandler ["ExtensionCallback", {
	params ["_name", "_function", "_data"];
}];
  • name: String - user provided param
  • function: String - user provided param
  • data: String - user provided param


Introduced with Arma 3 version 1.571.57

GroupIconClick

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"
	];
}];
  • 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 Shift key was pressed
  • ctrl: Boolean - true if Ctrl key was pressed
  • alt: Boolean - true if Alt key was pressed


Introduced with Arma 3 version 1.571.57

GroupIconOverEnter

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"
	];
}];


Introduced with Arma 3 version 1.571.57

GroupIconOverLeave

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"
	];
}];
  • 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 Shift key was pressed
  • ctrl: Boolean - true if Ctrl key was pressed
  • alt: Boolean - true if Alt key was pressed


Introduced with Arma 3 version 1.901.90

HandleAccTime

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"];
}];
  • currentTimeAcc: Number - current value
  • prevTimeAcc: Number - previous value
  • messageSuppressed: Boolean - true if on-screen message was suppressed


Introduced with Arma 3 version 1.321.32 
Exec Server.gif

HandleDisconnect

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.

addMissionEventHandler ["HandleDisconnect", {
	params ["_unit", "_id", "_uid", "_name"];
	true;
}];

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 param disabledAI = 1;


Introduced with Arma 3 version 1.571.57

HCGroupSelectionChanged

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

addMissionEventHandler ["HCGroupSelectionChanged", {
	params ["_group", "_isSelected"];
}];
  • group: Group - group selected (same as _group param)
  • isSelected: Boolean - true if selected (same as _isSelected param)


Introduced with Arma 3 version 0.500.50

Loaded

Triggered when mission is loaded from save.

"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"];
}];
  • 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


Introduced with Arma 3 version 1.621.62

Map

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

addMissionEventHandler ["Map", {
	params ["_mapIsOpened", "_mapIsForced"];
}];


Introduced with Arma 3 version 1.571.57

MapSingleClick

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
addMissionEventHandler ["MapSingleClick", {
	params ["_units", "_pos", "_alt", "_shift"];
}];
  • units: Array - leader selected units, same as groupSelectedUnits (same as _units param)
  • pos: Array - world Position3D of the click in format [x,y,0] (same as _pos param)
  • alt: Boolean - true if Alt key was pressed (same as _alt param)
  • shift: Boolean - true if Shift key was pressed (same as _shift param)


Introduced with Arma 3 version 1.571.57 
Exec Server.gif

PlayerConnected

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

addMissionEventHandler ["PlayerConnected",
{
	params ["_id", "_uid", "_name", "_jip", "_owner", "_idstr"];
}];
  • id: Number - unique DirectPlay ID (very large number). It is also the same id used for user placed markers (same as _id param)
  • uid: String - getPlayerUID of the joining client. The same as Steam ID (same as _uid param)
  • name: String - profileName of the joining client (same as _name param)
  • jip: Boolean - didJIP of the joining client (same as _jip param)
  • owner: Number - owner id of the joining client (same as _owner param)
  • idstr: String - same as id but in string format, so could be exactly compared to 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 _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 JIPped.
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)


Introduced with Arma 3 version 1.571.57 
Exec Server.gif

PlayerDisconnected

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

addMissionEventHandler ["PlayerDisconnected",
{
	params ["_id", "_uid", "_name", "_jip", "_owner", "_idstr"];
}];
  • id: Number - unique DirectPlay ID (very large number). It is also the same id used for user placed markers (same as _id param)
  • uid: String - getPlayerUID of the leaving client. The same as Steam ID (same as _uid param)
  • name: String - profileName of the leaving client (same as _name param)
  • jip: Boolean - didJIP of the leaving client (same as _jip param)
  • owner: Number - owner id of the leaving client (same as _owner param)
  • idstr: String - same as id but in string format, so could be exactly compared to user marker ids


Introduced with Arma 3 version 1.661.66

PlayerViewChanged

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", "_vehicle",
		"_oldCamera", "_newCamera", "_uav"
	];
}];
  • 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)


Introduced with Arma 3 version 1.571.57

PreloadStarted

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

This event handler also fires on client after user closes the main map.
addMissionEventHandler ["PreloadStarted", {
	// no params
}];


Introduced with Arma 3 version 1.571.57

PreloadFinished

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

This event handler also fires on client after user closes the main map.
addMissionEventHandler ["PreloadFinished", {
	// no params
}];


SelectedActionPerformed

RTM helicopter user action event

addMissionEventHandler ["SelectedActionPerformed", {
	params ["_caller", "_target", "_enumNumber", "_actionId"];
}];
Limited or non-existent functionality


SelectedActionChanged

RTM helicopter user action event

addMissionEventHandler ["SelectedActionChanged", {
	params ["_caller", "_target", "_enumNumber", "_actionId"];
}];
Limited or non-existent functionality


SelectedRotorLibActionPerformed

RTM helicopter user action event

addMissionEventHandler ["SelectedRotorLibActionPerformed", {
	params ["_caller", "_target", "_enumNumber", "_actionId"];
}];
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"];
}];
Limited or non-existent functionality


Introduced with Arma 3 version 1.571.57

TeamSwitch

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

addMissionEventHandler ["TeamSwitch", {
	params ["_previousUnit", "_newUnit"];
}];
  • previousUnit: Object - switching from unit (same as _from param)
  • newUnit: Object - switching to unit (same as _to param)