Mission Event Handlers – Arma 3
Description
Mission event handlers are specific EHs that are anchored to the running mission and automatically removed when mission is over. For all other available EHs see the Event Handlers main page.
Related Commands
Events
Template:Cfg ref Template:Cfg ref
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
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
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
}];
EachFrame
Executes assigned code each frame. Stackable version of onEachFrame.
addMissionEventHandler ["EachFrame", {
// no params
}];
Ended
Triggered when mission ends, either using trigger of type "End", endMission command, BIS_fnc_endMission function or ENDMISSION cheat.
addMissionEventHandler ["Ended", {
params ["_endType"];
}];
- endType: String - mission end type. Used in Debriefing among other things.
EntityKilled
Triggered when an entity is killed. 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];
}];
addMissionEventHandler ["EntityKilled", {
params ["_unit", "_killer", "_instigator", "_useEffects"];
}];
- killed: Object - entity that was killed
- killer: Object - the killer (vehicle or person)
1.65 instigator: Object - person who pulled the trigger- 1.67 useEffects: Boolean - same as useEffects in setDamage alt syntax
EntityRespawned
Triggered when an entity is respawned.
addMissionEventHandler ["EntityRespawned", {
params ["_entity", "_corpse"];
}];
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
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"
];
}];
- 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 Shift key was pressed
- ctrl: Boolean - true if Ctrl key was pressed
- alt: Boolean - true if Alt key was pressed
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
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;
}];
- 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 param disabledAI = 1;
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)
Loaded
Triggered when mission is loaded from save.
NOTE: "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
Map
Triggered when map is opened or closed either by user action or script command openMap.
addMissionEventHandler ["Map", {
params ["_mapIsOpened", "_mapIsForced"];
}];
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)
PlayerConnected
Executes assigned code when client joins the mission in MP. Stackable version of onPlayerConnected.
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 [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]
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)
addMissionEventHandler ["PlayerConnected", {
params ["_id", "_uid", "_name", "_jip", "_owner"];
}];
- 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)
PlayerDisconnected
Executes assigned code when client leaves the mission in MP. Stackable version of onPlayerDisconnected.
addMissionEventHandler ["PlayerDisconnected", {
params ["_id", "_uid", "_name", "_jip", "_owner"];
}];
- 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)
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)
PreloadStarted
Executes assigned code before the mission preload screen. Stackable version of onPreloadStarted.
addMissionEventHandler ["PreloadStarted", {
// no params
}];
PreloadFinished
Executes assigned code after the mission preload screen. Stackable version of onPreloadFinished.
addMissionEventHandler ["PreloadFinished", {
// no params
}];
TeamSwitch
Executes assigned code when player teamswitches. Stackable version of onTeamSwitch.
addMissionEventHandler ["TeamSwitch", {
params ["_previousUnit", "_newUnit"];
}];