{"updated":"2026-10-12T14:41:15Z","source":"https://community.bistudio.com/wiki/Main_Page","count":60,"items":[{"name":"Anything","title":"Anything","type":"topic","url":"https://community.bistudio.com/wiki/Anything","revid":330444,"updated":"2022-09-15T21:31:40Z","aliases":["Any"],"markdown":"A variable of type **Anything** may be of any data types **or** Nothing.\n\n> [!WARNING]\n> Even though some commands list data type **Anything** as possible value, passing nil (Nothing) to a command might cause it not to work:\n>\n> ```sqf\n> str nil; // while the documentation for str states it takes Anything, nil / Nothing will cause it to not execute.\n> ```\n\n### See Also\n\n- nil\n- isNil\n- Nothing","sections":[{"heading":null,"level":1,"markdown":"A variable of type **Anything** may be of any data types **or** Nothing.\n\n> [!WARNING]\n> Even though some commands list data type **Anything** as possible value, passing nil (Nothing) to a command might cause it not to work:\n>\n> ```sqf\n> str nil; // while the documentation for str states it takes Anything, nil / Nothing will cause it to not execute.\n> ```"},{"heading":"See Also","level":3,"markdown":"- nil\n- isNil\n- Nothing"}],"categories":["Magic Types"],"groups":["Data Types"]},{"name":"Arma 3: Actions","title":"Arma 3: Actions","type":"topic","url":"https://community.bistudio.com/wiki/Arma_3:_Actions","revid":376089,"updated":"2025-08-09T20:25:33Z","aliases":["ArmA 3: Actions","Arma 3 Actions","action/Arma 3 Actions List"],"markdown":"> [!NOTE]\n> - See ArmA: Armed Assault: Actions for an introduction to Actions\n> - Not to be confused with playAction\n\n## General Syntax\n\n ***unit* action [*\"actionType\"*, *parameter(s)*]**\n\n| | |\n|---|---|\n| *unit*: | Object. Can be any occupied vehicle or person that is not in a vehicle or also a Game Logic. |\n| *\"actionType\"*: | String. Name of the action, found in the CfgActions class. Not case sensitive. |\n| *parameter(s)*: | Various data types, dependant on the action used. The number of required parameters depends on the action type. |\n\n## Actions\n\n### ActiveSensorsOn\n\n| | |\n|---|---|\n| Description | Activates the vehicle's active sensor (radar). |\n| Syntax | *unit* action [\"ActiveSensorsOn\", *vehicle*] |\n| | |\n| Example | ```sqf*] |\n| | |\n| Example | |\n\n### Disassemble\n\n| | |\n|---|---|\n| Description | Takes assembled weapon to parts (carry bags). Assembled weapon object reference may need to be kept for assembly. See also: enableWeaponDisassembly |\n| Syntax | *unit* action [\"Disassemble\", *weapon*] |\n| | Where *unit* is any unit and *weapon* is assembled weapon |\n| Example | ```sqf*] |\n| | |\n| Example | |\n\n### LadderDown\n\n| | |\n|---|---|\n| Description | Causes a person to play an animation as if mounting the top of a ladder, then instantly teleport onto the specified ladder in the specified position. If the person is controlled by AI, they will automatically climb up or down the ladder. If the 2 parameter syntax is used, the person will become stuck in the ladder mounting animation state until the ladderOff action is executed upon them. It may also crash ArmA (pre 1.09). |\n| Syntax | *unit* action [\"LadderDown\", *targetObject*] |\n| | *unit* action [\"LadderDown\", *targetObject*, *ladderNumber*, *positionNumber*] |\n| | Where *unit* is any person unit, *targetObject* is an object with a ladder, *ladderNumber* is a number defining the desired ladder, and *positionNumber* is a number defining the desired position. |\n| Example | ```sqf] |\n| | |\n| Example | |\n\n### MoveToCargo\n\n| | |\n|---|---|\n| Description | Move a unit to the chosen cargo position within a vehicle. If another unit is already in that position, the units will swap positions.*] |\n| | |\n| Example | |\n\n### NVGoggles\n\n| | |\n|---|---|\n| Description | Causes a unit to put on it is night vision goggles. AI controlled units will automatically put on and take off goggles depending on daylight. |\n| Syntax | *unit* action [\"NvGoggles\", **] |\n| | Where *unit* is the unit to put on NVGoggles, and ** can be anything (it seems to not be used at all, but the action parameter array must contain at least two elements). |\n| Example | ```sqf*] |\n| | Where *unit* is the unit to put on goggles, and ** can be anything (it seems not to be used at all, but the action parameter array must contain at least two elements). |\n| Example | ```sqf will be greyed out in the list and thus unselectable. and can be found with magazinesDetail command (not 100% about but it seems 0 works for all weapons) |\n| Syntax | *logic* action [\"UseMagazine\", *target*, *magazine creator*, **, **] |\n| | |\n| Example | ```sqf, , ] |\n| | |\n| Example | |\n\n### MarkWeapon\n\n| | |\n|---|---|\n| Description | Something to do with campaign. Campaign param \"WeaponPool\" has to be enabled as well as mission param \"MarkWeapons\". Possibly related to \"MarkEntity\" action as well. |\n| Syntax | |\n| | |\n| Example | |\n\n### HandGunOffStand\n\n| | |\n|---|---|\n| Description | |\n| Syntax | |\n| | |\n| Example | |\n\n### HandGunOnStand\n\n| | |\n|---|---|\n| Description | |\n| Syntax | |\n| | |\n| Example | |\n\n### TakeDropMagazine\n\n| | |\n|---|---|\n| **Description**: Redundant even if works, use #TakeMagazine | |\n| Syntax | |\n| | |\n| Example | |\n\n### TakeDropWeapon\n\n| | |\n|---|---|\n| Description | |\n| Syntax | |\n| | |\n| Example | |\n\n### Assemble\n\n| | |\n|---|---|\n| Description | |\n| Syntax | |\n| | |\n| Example | ```sqf*] |\n| | |\n| Example | |"},{"heading":"Disassemble","level":3,"markdown":"| | |\n|---|---|\n| Description | Takes assembled weapon to parts (carry bags). Assembled weapon object reference may need to be kept for assembly. See also: enableWeaponDisassembly |\n| Syntax | *unit* action [\"Disassemble\", *weapon*] |\n| | Where *unit* is any unit and *weapon* is assembled weapon |\n| Example | ```sqf*] |\n| | |\n| Example | |"},{"heading":"LadderDown","level":3,"markdown":"| | |\n|---|---|\n| Description | Causes a person to play an animation as if mounting the top of a ladder, then instantly teleport onto the specified ladder in the specified position. If the person is controlled by AI, they will automatically climb up or down the ladder. If the 2 parameter syntax is used, the person will become stuck in the ladder mounting animation state until the ladderOff action is executed upon them. It may also crash ArmA (pre 1.09). |\n| Syntax | *unit* action [\"LadderDown\", *targetObject*] |\n| | *unit* action [\"LadderDown\", *targetObject*, *ladderNumber*, *positionNumber*] |\n| | Where *unit* is any person unit, *targetObject* is an object with a ladder, *ladderNumber* is a number defining the desired ladder, and *positionNumber* is a number defining the desired position. |\n| Example | ```sqf] |\n| | |\n| Example | |"},{"heading":"MoveToCargo","level":3,"markdown":"| | |\n|---|---|\n| Description | Move a unit to the chosen cargo position within a vehicle. If another unit is already in that position, the units will swap positions.*] |\n| | |\n| Example | |"},{"heading":"NVGoggles","level":3,"markdown":"| | |\n|---|---|\n| Description | Causes a unit to put on it is night vision goggles. AI controlled units will automatically put on and take off goggles depending on daylight. |\n| Syntax | *unit* action [\"NvGoggles\", **] |\n| | Where *unit* is the unit to put on NVGoggles, and ** can be anything (it seems to not be used at all, but the action parameter array must contain at least two elements). |\n| Example | ```sqf*] |\n| | Where *unit* is the unit to put on goggles, and ** can be anything (it seems not to be used at all, but the action parameter array must contain at least two elements). |\n| Example | ```sqf will be greyed out in the list and thus unselectable. and can be found with magazinesDetail command (not 100% about but it seems 0 works for all weapons) |\n| Syntax | *logic* action [\"UseMagazine\", *target*, *magazine creator*, **, **] |\n| | |\n| Example | ```sqf, , ] |\n| | |\n| Example | |"},{"heading":"MarkWeapon","level":3,"markdown":"| | |\n|---|---|\n| Description | Something to do with campaign. Campaign param \"WeaponPool\" has to be enabled as well as mission param \"MarkWeapons\". Possibly related to \"MarkEntity\" action as well. |\n| Syntax | |\n| | |\n| Example | |"},{"heading":"HandGunOffStand","level":3,"markdown":"| | |\n|---|---|\n| Description | |\n| Syntax | |\n| | |\n| Example | |"},{"heading":"HandGunOnStand","level":3,"markdown":"| | |\n|---|---|\n| Description | |\n| Syntax | |\n| | |\n| Example | |"},{"heading":"TakeDropMagazine","level":3,"markdown":"| | |\n|---|---|\n| **Description**: Redundant even if works, use #TakeMagazine | |\n| Syntax | |\n| | |\n| Example | |"},{"heading":"TakeDropWeapon","level":3,"markdown":"| | |\n|---|---|\n| Description | |\n| Syntax | |\n| | |\n| Example | |"},{"heading":"Assemble","level":3,"markdown":"| | |\n|---|---|\n| Description | |\n| Syntax | |\n| | |\n| Example | ```sqfY by default), which results in their name and icon flashing for a short moment.\nCurator can press Space to quickly move the camera to their location.\n\n### Editing Areas\n\nEditing area is a zone in which curator can modify entities. It's used to limit curator into specific area, or restrict him from other (e.g., around players).\n\nIt can be set using *Add Editing Area* and *Restrict Editing Around Players* modules or by following scripting commands:\n- addCuratorEditingArea\n- removeCuratorEditingArea\n- removeAllCuratorEditingAreas\n- curatorEditingArea\n- setCuratorEditingAreaType\n- allowCuratorLogicIgnoreAreas\n\nAreas can be circle only, and can be composed together to build much larger area. Mission designer can set whether editing is allowed only inside them, or only outside them.\nFor performance reasons, it is not possible to define it per individual area.\n\nFor curator, the area is visualized by blue (during day) and green (during night) \"walls\" in the scene and by black icons in the map. Players can't see it.\n\n*Table showing which actions are permitted **outside** of the editing area for each entity type:*\n\n| | Place | Edit | Delete | Destroy | Group | Synchronize |\n|---|---|---|---|---|---|---|\n| Objects | Restricted | Restricted | Restricted | Allowed | Allowed | Allowed |\n| Modules | Based on allowCuratorLogicIgnoreAreas | N/A | N/A | Allowed | | |\n| Markers | Allowed | Allowed | Allowed | N/A | N/A | N/A |\n| Waypoints | Allowed | Allowed | Allowed | N/A | N/A | N/A |\n\n### Camera\n\n#### Camera Area\n\nCamera area defines where can curator move with the camera. It's not visualized in any way, but reaching the border will result in camera \"sliding\" along it, so it can be felt.\nAs with editing areas, camera ones can also be grouped into larger chunks, and designer can set whether they camera can operate only inside or only outside of them.\nAdditionally, it is possible to set maximal camera altitude.\n\nUse *Add Camera Area* or following scripting commands to set the area:\n- addCuratorCameraArea\n- removeCuratorCameraArea\n- removeAllCuratorCameraAreas\n- curatorCameraArea\n- setCuratorCameraAreaCeiling\n\n#### Camera Position\n\nYou can teleport curator camera to specific position using *Set Camera Positon*.\nThe module can be also use to set default camera position after opening curator interface, when *Use as default* module attribute is set to *Enabled*.\n\nIn scripts, you can move curatorCamera around like any other object. However, most camera commands won't work on it.\nThe camera is local to the curator owner, so any changes to it has to be executed locally as well.\n\n**Example:**\n\n```sqf\ncuratorCamera setPos [position player select 0, position player select 1, 30];\ncuratorCamera setVectorDirAndUp [[0, 1, -0.5], [0, 0, 1]];\n```\n\nYou can also call BIS_fnc_setCuratorCamera, which will also let you to transition the camera into desired position smoothly.\n\n### Attributes\n\nAttributes are specific settings available after double-clicking on an entity.\n\nYou can set which attributes will be available for entities by *Set Attributes* modules or using BIS_fnc_setCuratorAttributes. By default, all attributes are shown. Modules are using custom attributes.\n\nAvailable attributes for each entity type are:\n- **Object / Player**\n - Skill\n - UnitPos\n - Rank\n - Damage\n - Fuel\n - Lock\n - RespawnVehicle\n - RespawnPosition\n - Exec *(visible only when debug console is available)*\n- **Group**\n - GroupID\n - Behaviour\n - Formation\n - UnitPos\n- **Marker**\n - Text\n - Color\n- **Waypoint**\n - Behaviour\n - Formation\n\n### Icons\n\nMission designer can show an icon visible only in curator interface\n- Use *Add Icon* module or BIS_fnc_addCuratorIcon and BIS_fnc_removeCuratorIcon to manage custom icons. Icon definition is the same as is used by drawIcon3D command\n- BIS_fnc_drawCuratorDeaths will show a skull icon on position where given unit died (useful for tracking where players are dying in PvP matches)\n- BIS_fnc_drawCuratorLocations shows names of nearby settlements, which can help with navigation on large terrains.\n- BIS_fnc_drawCuratorRespawnMarkers shows an icon on respawn markers\n\n### Compositions\n\nSince Arma 3 v2.06 is it possible to place custom compositions created in Eden Editor in Zeus.\nIn order to enable Zeus to spawn custom compositions *zeusCompositionScriptLevel* needs to be defined in Description.ext#zeusCompositionScriptLevel **or** Arma 3: Server Config File.\n\n#### Notes\n\n- Arma 3: Simple Objects are not supported. They will be placed as normal entities\n- Compositions that use non-whitelisted/non-loaded mods are not shown in the compositions list\n- Some objects cannot be edited after spawning (USS Liberty/Freedom ships), as they only create a dummy object, that then spawns the ship parts afterward\n- Mines are not \"supported\". You can place them but not edit/remove them after placing\n\n#### Shortcuts\n\n- Press Ctrl to make the composition follow the terrain\n- Press Alt to place the composition at its original location where it was created in Eden Editor\n\n### Misc\n\n- [Zeus logo PSD source file](http://temp.moricky.com/zeusLogo.psd)\n\nArma 3 Editing","sections":[{"heading":null,"level":1,"markdown":"**Curator** is a technical name for Arma 3 Zeus game master system. Every involved scripting command, event handler or class name contains the name.\nThe reason for it is to have a generic name which can be passed from project to project without any associations."},{"heading":"Setup","level":3,"markdown":"The central piece of every curator is Game Master module, otherwise referred to as Curator Logic. It stores every setting, like editing areas, available objects or their costs.\n\nYou can find the module in **Systems (F5) > Zeus > Game Master**\n\nIn module arguments, can set the curator unit (either specific unit, player with given UID or server admin) and that's all you need to add game master to your mission.\nWithout any further settings, all objects will be available for free and whole map will be editable.\n\nThere can be multiple modules present in a mission, each with its own settings. As a result, you can have for example two competing curators, or a group of allied curators, each with different abilities.\n\nIn every examples on this page, we'll call the module *myCurator*.\n\n> [!NOTE]\n> - Detailed module descriptions are available in the game after clicking on SHOW INFO button while editing a module.\n> - Function descriptions can be accessed in game using Functions Viewer.\n> - All curator related scripting commands can be found in the Curator command group."},{"heading":"Costs","level":3,"markdown":"Mission designer can assign cost to every object curator can interact with. The cost is applied when performing actions like placing, editing or deleting.\nIt affects curator's resources - **points** - which are in range from 0 (no points) to 1 (full points; can't be larger than this value).\nThe cost can be both negative and positive, so some actions can actually add points (e.g., deleting).\nPoints can be adjusted by addCuratorPoints and returned using curatorPoints, or you can use *Manage Resources* module.\n\nCosts for each entity type are calculated differently:\n- Object costs are defined in the event handler.\n- Modules are perceived as normal objects and are also defined in the handler.\n- Waypoint costs are set by setCuratorWaypointCost command.\n- Markers are always free."},{"heading":"Assigning","level":4,"markdown":""},{"heading":"Manual","level":5,"markdown":"You can assign individual cost for every object in the game using CuratorObjectRegistered event handler.\nIt's executed when player enters curator interface, so individual values cannot be changed on the fly.\nHowever, you can still tweak costs using action coefficients and available objects by unlocking addons.\n\n```sqf\nmyCurator addEventHandler [\"CuratorObjectRegistered\", { /* code here, see below */ }];\n```\n\nArguments passed into the handler are:\n- curator: Object\n- input: Array of Strings - all CfgVehicles classes\n\nExpected returned value is an Array of Arrays of the same size as the input array, with each item belonging to a class with the same array index. Missing or incorrect values will be replaced by default *[true,0,0]*.\n- Input: `[string1, string2, string3, ... classN]`\n- Output: `[array1, array2, array3, ... arrayN]`\n**Example**:\n- Input (3 classes): `[\"B_Soldier_F\", \"B_MRAP_01_F\", \"ModuleLightning_F\"]`\n- Output (3 arrays with settings): `[[true, 0.1], [true, 0.5, 0.6], [false, 0, 0]]`\n\nEvery item in the array is in the following format:\n [show, cost, (costWithCrew)]\n- show: Boolean - true to let the object appear in the CREATE list, false to hide it (costs will still be accepted if an object of the type is already present in the mission and made editable)\n- cost: Number - cost of the object\n- costWithCrew (Optional): Number - cost of the object with crew in it (affects only vehicles). When undefined, normal cost is used.\n\n**Example of the whole event handler:**\n\n```sqf\nmyCurator addEventHandler [\n \"CuratorObjectRegistered\",\n {\n _classes = _this select 1;\n _costs = [];\n {\n _cost = if (_x isKindOf \"Man\") then {[true,0.1]} else { [false, 0] }; // show only objects of type \"Man\", hide everything else\n _costs pushBack _cost;\n } forEach _classes; // go through all classes and assign cost for each of them\n _costs\n }\n];\n```\n\nAlternatively, you can set cost of specific objects by BIS_fnc_curatorObjectRegistered, with crew costs calculated automatically based on vehicle cost + cost of all crew members.\n- When the function is executed multiple times, results are combined together.\n - Example:\n - **Show** value of an object has to be true in all instances (e.g., one false will hide the object)\n - **Cost** values are multiplied together (e.g., one 0 will set the cost to 0)"},{"heading":"Using Cost Tables","level":5,"markdown":"There's a scripted function which will export all objects from specified addons into spreadsheet format, where you can define individual costs and see additional data, like how many objects can be build at one or how long will it take to \"recharge\" points until the object is available. The table also automatically calculates costs of vehicles with crew and of whole groups. As such, it is invaluable tool for balancing curator missions.\n\nSteps how to create the table:\n1. Call BIS_fnc_exportCuratorCostTable to generate the table based on given addons into clipboard\n**Example:** `[\"A3_Characters_F_BLUFOR\", \"A3_Soft_F_MRAP_01\"], \"ods\"] spawn BIS_fnc_exportCuratorCostTable;`\n1. Run OpenOffice Calc (or Microsoft Excel; use \"xls\" as a second param when calling the functions, as both programs are using different formula formatting)\n1. Paste the generated text into the spreadsheet\n\nNow when the table is generated, you can assign specific costs to each objects and watch how it affects vehicles and groups involving the object./\n- Class names in the second column leads to Arma 3 Assets page with further details, like weapons or magazines the object can carry.\n- Display names in the third column are links directly to object preview images.\n\nWhen finished, export the result into the game by following these steps:\n1. Scroll down to \"Export\" field\n1. Copy all cells between *// Generated by BIS_fnc_exportCuratorCostTable* and the document end.\n**Example:**\n\n```sqf\n// Generated by BIS_fnc_exportCuratorCostTable\n// [[\"A3_Characters_F_BLUFOR\",\"A3_Soft_F_MRAP_01\"],\"ods\"] call BIS_fnc_exportCuratorCostTable;\n_BLUFOR_A3_Characters_F_BLUFOR = ['B_Soldier_GL_F',1,'B_soldier_AR_F',1,'B_Soldier_TL_F',1,'B_soldier_LAT_F',1,,0];\n_BLUFOR_A3_Soft_F_MRAP_01 = ['B_MRAP_01_F',3,,0];\n_BLUFOR = _BLUFOR_A3_Characters_F_BLUFOR + _BLUFOR_A3_Soft_F_MRAP_01 + [];\n```\n\n1. Import the result in the game again using BIS_fnc_curatorObjectRegisteredTable\n**Example:**\n\n```sqf\n[myCurator,_BLUFOR] call BIS_fnc_curatorObjectRegisteredTable;\n```"},{"heading":"Action Coefficients","level":4,"markdown":"Once you assigned cost to every object, you can now use it for every action curator can perform.\n\n```sqf\nmyCurator setCuratorCoef [\"place\", -0.2];\n```\n\nIf some object, for example BLUFOR soldier \"B_Soldier_F\" from the previous example, will have assigned cost 0.1, cost for placing will be:\n\n*0.1 * -0.2 = -0.02*\n\nIf curator have full points (value is 1), it means he can build 50 BLUFOR soldiers (*-1 * -0.02 = 50*). While individual object costs cannot be changed on the fly, coefficient can be easily used to tweak all costs.\n\nAvailable actions are:\n- \"place\"\n- \"edit\"\n- \"delete\"\n- \"destroy\"\n- \"group\"\n- \"synchronize\"\n\nAdditionally, while action can be disabled by assigning large negative coefficient, e.g., -10000. Trying to perform the action will then result in onscreen warning for curator.\n\nCoefficients can be also assigned in *Set Editing Costs* module."},{"heading":"Unlocking Addons","level":3,"markdown":"You can set which objects will be available curator by toggling specific addons. This can be done on the fly, and it is primary way how to unlock content for curator during a mission.\n\nSee Arma 3 assets to check which objects belongs to which addon, or use unitAddons to get addons of specific object class.\n\n> [!NOTE]\n> Only activated addons can be added (i.e., addons preloaded by the mission).\n> All official addons are activated by default, but unofficial ones are activated only when an object contained in such addon is present in the mission.\n> If that's not the case, you can use activateAddons or BIS_fnc_activateAddons to activate them. This is however possible only at the mission start - on the fly activation is not possible.\n\nInitial addons can be adjusted in *Game Master* module attributes, with available values being:\n- **All official addons** - default state, includes all activeted addons\n- **Addons present in the mission** - only addons of objects present in the mission upon mission start. E.g., if you inserted only BLUFOR soldiers and MRAPs in the mission, addons will be [\"A3_Characters_F_BLUFOR\",\"A3_Soft_F_MRAP_01\"]\n- **None** - no addons are enabled by the module, mission designer has to add them manually.\n\nDuring the missions, use *Manage Addons* module or scripting commands to toggle addons:\n- addCuratorAddons\n- removeCuratorAddons\n- removeAllCuratorAddons\n- curatorAddons\n\n**Example:**\n\n```sqf\nmyCurator addCuratorAddons [\"A3_Armor_F_AMV\", \"A3_Armor_F_Panther\"];\nmyCurator removeCuratorAddons [\"A3_Soft_F_MRAP_01\"];\n```"},{"heading":"Community Addons","level":4,"markdown":"Curator system relies on correct configuration of object. When you unlock an addon, it will in turn enable all objects defined in *units* array of *CfgPatches*.\nIf the addon author didn't do this, his objects won't be available.\n\n```cpp\nclass CfgPatches\n{\n class TAG_MyAddon\n {\n units[] = { \"TAG_MyObject1\", \"TAG_MyObject2\" }; // here\n weapons[] = {};\n requiredVersion = 1;\n requiredAddons[] = {};\n };\n};\n```"},{"heading":"Editable Objects","level":3,"markdown":"By default, every object placed by curator is immediately made editable. Any other object can be added by *Add Editable Objects* module or using\nscripting commands:\n- addCuratorEditableObjects\n- removeCuratorEditableObjects\n- curatorEditableObjects\n\nEditable players are marked by a red color in the EDIT list and by red circle displayed over their icon. They cannot be moved, rotated, deleted or destroyed, but grouping, syncing and setting attributes works.\nEditable players can also ping their curator by pressing Zeus key (Y by default), which results in their name and icon flashing for a short moment.\nCurator can press Space to quickly move the camera to their location."},{"heading":"Editing Areas","level":3,"markdown":"Editing area is a zone in which curator can modify entities. It's used to limit curator into specific area, or restrict him from other (e.g., around players).\n\nIt can be set using *Add Editing Area* and *Restrict Editing Around Players* modules or by following scripting commands:\n- addCuratorEditingArea\n- removeCuratorEditingArea\n- removeAllCuratorEditingAreas\n- curatorEditingArea\n- setCuratorEditingAreaType\n- allowCuratorLogicIgnoreAreas\n\nAreas can be circle only, and can be composed together to build much larger area. Mission designer can set whether editing is allowed only inside them, or only outside them.\nFor performance reasons, it is not possible to define it per individual area.\n\nFor curator, the area is visualized by blue (during day) and green (during night) \"walls\" in the scene and by black icons in the map. Players can't see it.\n\n*Table showing which actions are permitted **outside** of the editing area for each entity type:*\n\n| | Place | Edit | Delete | Destroy | Group | Synchronize |\n|---|---|---|---|---|---|---|\n| Objects | Restricted | Restricted | Restricted | Allowed | Allowed | Allowed |\n| Modules | Based on allowCuratorLogicIgnoreAreas | N/A | N/A | Allowed | | |\n| Markers | Allowed | Allowed | Allowed | N/A | N/A | N/A |\n| Waypoints | Allowed | Allowed | Allowed | N/A | N/A | N/A |"},{"heading":"Camera","level":3,"markdown":""},{"heading":"Camera Area","level":4,"markdown":"Camera area defines where can curator move with the camera. It's not visualized in any way, but reaching the border will result in camera \"sliding\" along it, so it can be felt.\nAs with editing areas, camera ones can also be grouped into larger chunks, and designer can set whether they camera can operate only inside or only outside of them.\nAdditionally, it is possible to set maximal camera altitude.\n\nUse *Add Camera Area* or following scripting commands to set the area:\n- addCuratorCameraArea\n- removeCuratorCameraArea\n- removeAllCuratorCameraAreas\n- curatorCameraArea\n- setCuratorCameraAreaCeiling"},{"heading":"Camera Position","level":4,"markdown":"You can teleport curator camera to specific position using *Set Camera Positon*.\nThe module can be also use to set default camera position after opening curator interface, when *Use as default* module attribute is set to *Enabled*.\n\nIn scripts, you can move curatorCamera around like any other object. However, most camera commands won't work on it.\nThe camera is local to the curator owner, so any changes to it has to be executed locally as well.\n\n**Example:**\n\n```sqf\ncuratorCamera setPos [position player select 0, position player select 1, 30];\ncuratorCamera setVectorDirAndUp [[0, 1, -0.5], [0, 0, 1]];\n```\n\nYou can also call BIS_fnc_setCuratorCamera, which will also let you to transition the camera into desired position smoothly."},{"heading":"Attributes","level":3,"markdown":"Attributes are specific settings available after double-clicking on an entity.\n\nYou can set which attributes will be available for entities by *Set Attributes* modules or using BIS_fnc_setCuratorAttributes. By default, all attributes are shown. Modules are using custom attributes.\n\nAvailable attributes for each entity type are:\n- **Object / Player**\n - Skill\n - UnitPos\n - Rank\n - Damage\n - Fuel\n - Lock\n - RespawnVehicle\n - RespawnPosition\n - Exec *(visible only when debug console is available)*\n- **Group**\n - GroupID\n - Behaviour\n - Formation\n - UnitPos\n- **Marker**\n - Text\n - Color\n- **Waypoint**\n - Behaviour\n - Formation"},{"heading":"Icons","level":3,"markdown":"Mission designer can show an icon visible only in curator interface\n- Use *Add Icon* module or BIS_fnc_addCuratorIcon and BIS_fnc_removeCuratorIcon to manage custom icons. Icon definition is the same as is used by drawIcon3D command\n- BIS_fnc_drawCuratorDeaths will show a skull icon on position where given unit died (useful for tracking where players are dying in PvP matches)\n- BIS_fnc_drawCuratorLocations shows names of nearby settlements, which can help with navigation on large terrains.\n- BIS_fnc_drawCuratorRespawnMarkers shows an icon on respawn markers"},{"heading":"Compositions","level":3,"markdown":"Since Arma 3 v2.06 is it possible to place custom compositions created in Eden Editor in Zeus.\nIn order to enable Zeus to spawn custom compositions *zeusCompositionScriptLevel* needs to be defined in Description.ext#zeusCompositionScriptLevel **or** Arma 3: Server Config File."},{"heading":"Notes","level":4,"markdown":"- Arma 3: Simple Objects are not supported. They will be placed as normal entities\n- Compositions that use non-whitelisted/non-loaded mods are not shown in the compositions list\n- Some objects cannot be edited after spawning (USS Liberty/Freedom ships), as they only create a dummy object, that then spawns the ship parts afterward\n- Mines are not \"supported\". You can place them but not edit/remove them after placing"},{"heading":"Shortcuts","level":4,"markdown":"- Press Ctrl to make the composition follow the terrain\n- Press Alt to place the composition at its original location where it was created in Eden Editor"},{"heading":"Misc","level":3,"markdown":"- [Zeus logo PSD source file](http://temp.moricky.com/zeusLogo.psd)\n\nArma 3 Editing"}],"categories":["Arma 3: Editing"],"groups":["Scripting"]},{"name":"Arma 3: Event Handlers","title":"Arma 3: Event Handlers","type":"topic","url":"https://community.bistudio.com/wiki/Arma_3:_Event_Handlers","revid":378964,"updated":"2026-09-07T08:29:27Z","aliases":["ArmA 3: Event Handlers"],"markdown":"An Event Handler (abbreviated to EH) allows you to automatically monitor and then execute custom code upon particular events being triggered.\n\nSee also Event Scripts for special event triggered scripts.\n\n### Basic Event Handlers\n\nThe object-based Event Handler is always executed on the computer where it was added.\n\nCommands:\n- addEventHandler\n- removeEventHandler\n- removeAllEventHandlers\n\n#### AmmoExplodedNear (Arma 3 v2.22)\n\nTriggers when ammo explodes in some damage range of the object. This EH triggers where the ammo is 'real', similar to HitPart.\n\n```sqf\nthis addEventHandler [\"AmmoExplodedNear\", {\n params [\"_object\", \"_shot\", \"_position\", \"_velocity\", \"_ammo\", \"_explosive\", \"_indirectHit\", \"_invArmor\", \"_damage\"];\n}];\n```\n\n- object: Object - object the event handler is assigned to\n- shot: Object - shot that has exploded\n- position: Array - world position of the shot\n- velocity: Array - world velocity of the shot\n- ammmo: String - config ammo class name\n- explosive: Number - config value for 'explosive'\n- indirectHit: Number - config value for 'indirectHit'\n- invArmor: Number - calculated inverse armor from config value\n- damage: Number - a rough estimate of the potential damage to the center of the object based on config values and the distance\n\n#### AnimChanged\n\nGlobal Argument\n\nTriggered every time a new animation is started. This EH is only triggered for the 1st animation state in a sequence.\n\n```sqf\nthis addEventHandler [\"AnimChanged\", {\n params [\"_unit\", \"_anim\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- anim: String - name of the anim that is started\n\n#### AnimDone\n\nGlobal Argument\n\nTriggered every time an animation is finished. Triggered for all animation states in a sequence.\n\n```sqf\nthis addEventHandler [\"AnimDone\", {\n params [\"_unit\", \"_anim\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- anim: String - name of the anim that has been finished\n\n#### AnimStateChanged\n\nGlobal Argument\n\nTriggered every time an animation state changes. Triggered for all animation states in a sequence.\n\n```sqf\nthis addEventHandler [\"AnimStateChanged\", {\n params [\"_unit\", \"_anim\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- anim: String - name of the anim that has been started\n\n#### Assembled (Arma 3 v2.18)\n\nLocal Argument\n\nTriggers when weapon that is moved out of the world is assembled again. EH should be attached to the entity.\n\n```sqf\nthis addEventHandler [\"Assembled\", {\n params [\"_entity\", \"_unit\", \"_primaryBag\", \"_secondaryBag\"];\n}];\n```\n\n- entity: Object - weapon this event is assigned to\n- unit: Object - person who assembled the weapon\n- primaryBag: Object - first backpack object which was entity disassembled into (just before it is deleted)\n- secondaryBag: Object - second backpack object which was entity disassembled into (just before it is deleted)\n\n#### Attached (Arma 3 v2.18)\n\nTriggered after an object has been attached to another object (see attachTo).\n\n```sqf\nthis addEventHandler [\"Attached\", {\n params [\"_attachedObj\", \"_parentObj\", \"_isReattach\", \"_offset\", \"_memoryPointIndex\", \"_followBoneRotation\"];\n}];\n```\n\n- attachedObj: Object\n- parentObj: Object\n- isReattach: Boolean - true if `attachedObj` was already attached to `parentObj`, e.g. if only the offset was changed\n- offset: Array format PositionRelative\n- memoryPointIndex: Number\n- followBoneRotation: Boolean\n\n#### CargoLoaded (Arma 3 v2.06)\n\nGlobal Argument\n\nTriggered when a vehicle is loaded into another vehicle (ViV).\n\nIt can be added to either the transport vehicle, or the cargo vehicle, and will fire for both cases.\n\n```sqf\nthis addEventHandler [\"CargoLoaded\", {\n params [\"_parentVehicle\", \"_cargoVehicle\"];\n}];\n```\n\n- parentVehicle: Object - the transport (parent) vehicle\n- cargoVehicle: Object - the cargo (child) vehicle\n\n#### CargoUnloaded (Arma 3 v2.06)\n\nGlobal Argument\n\nTriggered when a vehicle is unloaded from another vehicle (ViV).\n\nIt can be added to either the transport vehicle, or the cargo vehicle, and will fire for both cases.\n\n```sqf\nthis addEventHandler [\"CargoUnloaded\", {\n params [\"_parentVehicle\", \"_cargoVehicle\"];\n}];\n```\n\n- parentVehicle: Object - the transport (parent) vehicle\n- cargoVehicle: Object - the cargo (child) vehicle\n\n#### ContainerClosed (Arma 3 v1.32)\n\nGlobal Argument\n\nTriggers when player finished accessing cargo container.\nThis event handler is similar to InventoryClosed EH, but needs to be assigned to the container rather than the player.\n\n**Note:** will trigger only for the unit opening container.\n\n```sqf\nthis addEventHandler [\"ContainerClosed\", {\n params [\"_container\", \"_unit\"];\n}];\n```\n\n- container: Object - cargo container.\n- unit: Object - unit who accessed the container\n\n#### ContainerOpened (Arma 3 v1.32)\n\nGlobal Argument\n\nTriggers when cargo container is accessed by player.\nThis event handler is similar to InventoryOpened EH, but needs to be assigned to the container rather than the player and cannot be overridden.\n\n**Note:** will trigger only for the unit opening container.\n\n```sqf\nthis addEventHandler [\"ContainerOpened\", {\n params [\"_container\", \"_unit\"];\n}];\n```\n\n- container: Object - cargo container\n- unit: Object - unit who accessed the container\n\n#### ControlsShifted (Arma 3 v1.00)\n\nGlobal ArgumentLocal Effect\n\nTriggers 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. For example, if helicopter is local to the server and co-pilot takes controls, the helicopter changes locality to co-pilot PC.\nThis means that if \"ControlsShifted\" EH was added on both server and client, \"Take Controls\" action will trigger EH on both, client and server PC, but subsequent co-pilot \"Release Controls\" action will trigger only on co-pilot's PC, because vehicle will be local to co-pilot at this point. There is also a slightly better mission version of ControlsShifted event handler.\n\n```sqf\nthis addEventHandler [\"ControlsShifted\", {\n params [\"_vehicle\", \"_activeCoPilot\", \"_oldController\"];\n}];\n```\n\n- vehicle: Object - vehicle which controls were shifted\n- activeCoPilot: Object - co-pilot unit which controls vehicle after this event. objNull if co-pilot is not controlling the vehicle\n- oldController: Object - unit who controlled vehicle before this event\n\n#### Dammaged\n\nGlobal Argument\n\nTriggered when the unit is damaged. In ArmA works with all vehicles not only men like in OFP.\n\n**Notes:**\n- The typo is \"intentional\": it is Da**mm**aged with two \"m\".\n- If simultaneous damage occured (e.g. via grenade) EH might be triggered several times.\n- The Dammaged EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased.\n\n```sqf\nthis addEventHandler [\"Dammaged\", {\n params [\"_unit\", \"_hitSelection\", \"_damage\", \"_hitPartIndex\", \"_hitPoint\", \"_shooter\", \"_projectile\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- hitSelection: String - name of the selection where the unit was damaged\n- damage: Number - resulting level of damage\n- Arma 3 v1.68 hitPartIndex: Number - hit index of the hit selection\n- Arma 3 v1.68 hitPoint: String - hit point Cfg name\n- Arma 3 v1.70 shooter: Object - shooter reference (to get instigator use getShotParents on projectile)\n- Arma 3 v1.70 projectile: Object - the projectile that caused damage\n\n#### Deleted (Entity) (Arma 3 v1.68)\n\nGlobal Argument\n\nTriggered just before the assigned entity is deleted.\n\n```sqf\nthis addEventHandler [\"Deleted\", {\n params [\"_entity\"];\n}];\n```\n\n- entity: Object - object the event handler is assigned to\n\n#### Detached (Arma 3 v2.18)\n\nTriggered after an object has been detached from its parent object (see detach). Does not fire if the parent object was deleted.\n\n```sqf\nthis addEventHandler [\"Detached\", {\n params [\"_attachedObj\", \"_parentObj\"];\n}];\n```\n\n- attachedObj: Object\n- parentObj: Object\n\n#### Disassembled (Arma 3 v2.00)\n\nLocal Argument\n\nTriggers when entity such as weapon/backpack gets disassembled. EH should be attached to the entity.\n\n```sqf\nthis addEventHandler [\"Disassembled\", {\n params [\"_entity\", \"_primaryBag\", \"_secondaryBag\", \"_unit\"];\n}];\n```\n\n- entity: Object - weapon this event is assigned to (just before is is moved out of the world)\n- primaryBag: Object - first backpack object which was entity disassembled into\n- secondaryBag: Object - second backpack object which was entity disassembled into\n- Arma 3 v2.18 unit: Object - person who disassembled the weapon\n\n#### Engine\n\nGlobal Argument\n\nTriggered when the engine of the unit is turned on/off.\n\n> [!NOTE]\n> Although the event is global, on clients (non-server) and applied to remote vehicles, it will fire only if the vehicle is closer than about 6 km from the camera.\n> Should the vehicle be far away, it will fire as soon as the camera and vehicle are close enough together, alongside the isEngineOn flag change.\n\n```sqf\nthis addEventHandler [\"Engine\", {\n params [\"_vehicle\", \"_engineState\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- engineState: Boolean - true when the engine is turned on, false when turned off\n\n#### EpeContact (Arma 3 v1.00)\n\nGlobal Argument\n\nTriggered when object collision (PhysX) is in progress.\n\n```sqf\nthis addEventHandler [\"EpeContact\", {\n params [\"_object1\", \"_object2\", \"_selection1\", \"_selection2\", \"_force\", \"_reactVect\", \"_worldPos\"];\n}];\n```\n\n- object1: Object - object with attached handler\n- object2: Object - object which is colliding with object1\n- selection1: String - selection of object1 which is colliding - not in use at this moment, empty string is always returned\n- selection2: String - selection of object2 which is colliding - not in use at this moment, empty string is always returned\n- force: Number - force of collision\n- Arma 3 v2.12 reactVect: Array - impact reaction force vector\n- Arma 3 v2.12 worldPos: PositionWorld - point of impact in world coordinates\n\n#### EpeContactEnd (Arma 3 v1.00)\n\nGlobal Argument\n\nTriggered when object collision (PhysX) ends.\n\n```sqf\nthis addEventHandler [\"EpeContactEnd\", {\n params [\"_object1\", \"_object2\", \"_selection1\", \"_selection2\", \"_force\"];\n}];\n```\n\n- object1: Object - object with attached handler\n- object2: Object - object which is colliding with object1\n- selection1: String - selection of object1 which is colliding - not in use at this moment, empty string is always returned\n- selection2: String - selection of object2 which is colliding - not in use at this moment, empty string is always returned\n- force: Number - force of collision\n\n#### EpeContactStart (Arma 3 v1.00)\n\nGlobal Argument\n\nTriggered when object collision (PhysX) starts.\n\n```sqf\nthis addEventHandler [\"EpeContactStart\", {\n params [\"_object1\", \"_object2\", \"_selection1\", \"_selection2\", \"_force\", \"_reactForce\", \"_worldPos\"];\n}];\n```\n\n- object1: Object - object with attached handler\n- object2: Object - object which is colliding with object1\n- select1: String - selection of object1 which is colliding - not in use at this moment, empty string is always returned\n- select2: String - selection of object2 which is colliding - not in use at this moment, empty string is always returned\n- force: Number - force of collision\n- Arma 3 v2.12 reactForce: Array - impact reaction force vector\n- Arma 3 v2.12 worldPos: PositionWorld - point of impact in world coordinates\n\n#### Explosion (Arma 3 v0.76)\n\nGlobal Argument\n\nTriggered when a vehicle or unit is damaged by a nearby explosion.\nIt can be assigned to a remote unit or vehicle but will only fire on the PC where EH is added and explosion is local, i.e. it really needs to be added on every PC and JIP and will fire only where the explosion is originated.\n\n```sqf\nthis addEventHandler [\"Explosion\", {\n params [\"_vehicle\", \"_damage\", \"_explosionSource\"];\n}];\n```\n\n- vehicle: Object - object the event handler is assigned to\n- damage: Number - damage inflicted to the object\n- Arma 3 v2.10 explosionSource: Object - the exploding object (NOT the shooter) - may be objNull in some cases\n\n> [!NOTE]\n> This event will fire even for tiniest of explosion damage (which appears as 0 damage argument), while #HitPart (Entity) could ignore such damage and not fire.\n> Example of such event would be a tank firing AP round and hitting ground a meter away from the vehicle, it does not produce an explosion yet its indirectHit could still cause tiny amount of damage to weak hit points (car wheels, headlights, etc.).\n> In such case you might not get any #HitPart (Entity) event fires, get some #HandleDamage events if target is local, and get this Explosion event.\n\n#### Fired\n\nGlobal Argument\n\nTriggered when the unit fires a weapon.\n\nThis EH will not trigger if a unit fires out of a vehicle. For those cases an EH has to be attached to that particular vehicle.\nWhen \"Manual Fire\" is used, the *gunner* is objNull if gunner is not present or the *gunner* is not the one who fires.\nTo check if \"Manual Fire\" is on, use isManualFire. The actual shot instigator could be retrieved with getShotParents command.\n\n> [!WARNING]\n> **Special multiplayer behaviour:** When added to a remote unit or vehicle, this EH will only fire if said entity is within range of the camera.\n> That range is determined by the fired ammo's highest visibleFire and audibleFire config value.\n> In case of units, muzzle attachment coefficients are applied too.\n\n```sqf\nthis addEventHandler [\"Fired\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_mode\", \"_ammo\", \"_magazine\", \"_projectile\", \"_gunner\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- weapon: String - fired weapon\n- muzzle: String - muzzle that was used\n- mode: String - current mode of the fired weapon\n- ammo: String - ammo used\n- magazine: String - magazine name which was used\n- projectile: Object - object of the projectile that was shot out\n- Arma 3 v1.66 gunner: Object - gunner whose weapons are firing.\n\n#### FiredMan (Arma 3 v1.66)\n\nGlobal Argument\n\nTriggered when the unit fires a weapon. This EH must be attached to a soldier and unlike with \"Fired\" EH, it will fire regardless of whether the soldier is on foot or firing vehicle weapon.\nFor remoteControled unit use \"Fired\" EH instead.\n\n> [!WARNING]\n> **Special multiplayer behaviour:** When added to a remote unit or vehicle, this EH will only fire if said entity is within range of the camera.\n> That range is determined by the fired ammo's highest visibleFire and audibleFire config value.\n> In case of units, muzzle attachment coefficients are applied too.\n\n```sqf\nthis addEventHandler [\"FiredMan\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_mode\", \"_ammo\", \"_magazine\", \"_projectile\", \"_vehicle\"];\n}];\n```\n\n- unit: Object - unit the event handler is assigned to (the instigator)\n- weapon: String - fired weapon\n- muzzle: String - muzzle that was used\n- mode: String - current mode of the fired weapon\n- ammo: String - ammo used\n- magazine: String - magazine name which was used\n- projectile: Object - object of the projectile that was shot out\n- vehicle: Object - vehicle, if weapon is vehicle weapon, otherwise objNull\n\n#### FiredNear\n\nGlobal Argument\n\nTriggered when a weapon is fired somewhere *near* the unit or vehicle. It is also triggered if the unit itself is firing.\n\nWhen \"Manual Fire\" is used, the *gunner* is objNull if gunner is not present or the *gunner* is not the one who fires.\nTo check if \"Manual Fire\" is on, use isManualFire. The actual shot instigator can be retrieved with getShotParents command.\n\nArma 3 v1.30 Works with thrown weapons (using the \"Throw\" weapon) like grenades.\n\n```sqf\nthis addEventHandler [\"FiredNear\", {\n params [\"_unit\", \"_firer\", \"_distance\", \"_weapon\", \"_muzzle\", \"_mode\", \"_ammo\", \"_gunner\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- firer: Object - object which fires a weapon near the unit\n- distance: Number - distance in meters between the *unit* and *firer* (max. distance ~69m)\n- weapon: String - fired weapon\n- muzzle: String - muzzle that was used\n- mode: String - current mode of the fired weapon\n- ammo: String - ammo used\n- Arma 3 v1.66 gunner: Object - gunner, whose weapons are fired\n\n#### Fuel\n\nGlobal Argument\n\nTriggered when the vehicle's fuel status changes between non-empty and empty or between empty and non-empty.\n\n```sqf\nthis addEventHandler [\"Fuel\", {\n params [\"_vehicle\", \"_hasFuel\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- hasFuel: Boolean - false when has no fuel, true when has some fuel\n\n#### Gear\n\nGlobal Argument\n\nTriggered when the unit lowers/retracts the landing gear, whether it is a helicopter or a plane.\nAlso triggered for helicopters in landing mode, regardless if they have retractable gear or not.\n\n> [!NOTE]\n> Not to be confused with *InventoryOpened* and *InventoryClosed* events, *Gear* fires when the landing gear state on an aircraft has changed.\n\n```sqf\nthis addEventHandler [\"Gear\", {\n params [\"_vehicle\", \"_gearState\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- gearState: Boolean - true when the gear is lowered, false when retracted\n\n#### GestureChanged (Arma 3 v2.06)\n\nGlobal Argument\n\nTriggered every time a new gesture is played.\n\n```sqf\nthis addEventHandler [\"GestureChanged\", {\n params [\"_unit\", \"_gesture\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- gesture: String - name of the gesture that has started playing\n\n#### GestureDone (Arma 3 v2.06)\n\nGlobal Argument\n\nTriggered every time a gesture is finished.\n\n```sqf\nthis addEventHandler [\"GestureDone\", {\n params [\"_unit\", \"_gesture\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- gesture: String - name of the gesture that has been finished\n\n#### GetIn\n\nGlobal Argument\n\nTriggers when a unit enters the vehicle to which this EH has been added. This EH is triggered by moveInXXXX commands and \"GetInXXXX\" actions, but not upon a seat change within the same vehicle.\n\nIn vehicles with multi-turret setup, entering any turret will show \"gunner\" for position.\n\n```sqf\nthis addEventHandler [\"GetIn\", {\n params [\"_vehicle\", \"_role\", \"_unit\", \"_turret\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- role: String - can be either \"driver\", \"gunner\", \"commander\" or \"cargo\"\n- unit: Object - unit that entered the vehicle\n- Arma 3 v1.36 turret: Array - turret path\n\n#### GetInMan (Arma 3 v1.58)\n\nGlobal Argument\n\nTriggers when a unit enters a vehicle. Similar to \"GetIn\" but must be assigned to a unit and not vehicle.\nPersistent on respawn if assigned where unit was local. This EH is triggered by moveInXXXX commands and \"GetInXXXX\" actions.\n\n```sqf\nthis addEventHandler [\"GetInMan\", {\n params [\"_unit\", \"_role\", \"_vehicle\", \"_turret\"];\n}];\n```\n\n- unit: Object - unit the event handler is assigned to\n- role: String - can be either \"driver\", \"gunner\", \"commander\" or \"cargo\"\n- vehicle: Object - vehicle the unit entered\n- turret: Array - turret path\n\n#### GetOut\n\nGlobal Argument\n\nTriggers when a unit gets out from the vehicle to which this EH has been added.\nThis EH is triggered by moveOut, \"GetOut\" & \"Eject\" actions, if an alive crew member disconnects or is deleted, but not upon a seat change within the same vehicle.\n\n```sqf\nthis addEventHandler [\"GetOut\", {\n params [\"_vehicle\", \"_role\", \"_unit\", \"_turret\", \"_isEject\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- role: String - can be either \"driver\", \"gunner\", \"commander\" or \"cargo\"\n- unit: Object - unit that left the vehicle\n- Arma 3 v1.36 turret: Array - turret path\n- Arma 3 v2.14 isEject: Boolean - true if unit used 'Eject' action\n\n#### GetOutMan (Arma 3 v1.58)\n\nGlobal Argument\n\nTriggers when a unit exits a vehicle. Similar to \"GetOut\" but must be assigned to a unit and not vehicle.\nPersistent on respawn if assigned where unit was local. This EH is triggered by moveOut and \"GetOut\" & \"Eject\" actions.\n\n```sqf\nthis addEventHandler [\"GetOutMan\", {\n params [\"_unit\", \"_role\", \"_vehicle\", \"_turret\", \"_isEject\"];\n}];\n```\n\n- unit: Object - unit the event handler is assigned to\n- role: String - can be either \"driver\", \"gunner\", \"commander\" or \"cargo\"\n- vehicle: Object - vehicle that the unit left\n- turret: Array - turret path\n- Arma 3 v2.14 isEject: Boolean - true if unit used 'Eject' action\n\n#### HandleDamage\n\nGlobal Argument\n\nTriggers when the unit is damaged and fires for each damaged selection separately\nWorks with all vehicles.\nThis EH can accept a remote unit as argument however it will only fire when the unit is local to the PC this event handler was added on.\nFor example, you can add this event handler to one particular vehicle on every PC.\nWhen this vehicle gets hit, only EH on PC where the vehicle is currently local will fire.\n\nIf the provided code returns a numeric value, this value will overwrite the default damage of given selection after processing.\nIf no value is returned, the default damage processing will be done - this allows for safe stacking of this event handler.\nOnly the return value of the last added \"HandleDamage\" EH is considered.\n\n> [!IMPORTANT]\n> A return value of 0 will make the unit **invulnerable** if damage is not scripted in other ways (i.e using setDamage and/or setHit for additional damage handling).\n> The return value is the hit zone's **absolute damage value**, **not** the damage to be *added* to it.\n\n**Notes:**\n- Multiple \"HandleDamage\" EHs can be added to the same unit. If multiple EHs return damage value for custom damage handling, only last returned value will be considered by the engine.\nEHs that do not return value can be safely added after EHs that do return value.\n- You can save the last event as timestamp (diag_tickTime) onto the unit, as well as the current health of the unit/its selections, with setVariable and query it on each \"HandleDamage\" event with getVariable to define a system how to handle the \"HandleDamage\" event.\n- \"HandleDamage\" will continue to trigger even if the unit is already dead.\n- \"HandleDamage\" is persistent. If you add it to the player object, it will continue to exist after player respawned.\n- \"HandleDamage\" can trigger \"twice\" per damage event. Once for direct damage, once for indirect damage (explosive damage). This can happen even in the same frame, but is unlikely.\n- Use setMissionOptions to filter out no damage calls or fake head hit.\n\nAdditional [Celery's explanation (Updated by ShadowRanger for Arma 3)](https://forums.bistudio.com/forums/topic/205515-handledamage-event-handler-explained/).\n\n```sqf\nthis addEventHandler [\"HandleDamage\", {\n params [\"_unit\", \"_selection\", \"_damage\", \"_source\", \"_projectile\", \"_hitPartIndex\", \"_instigator\", \"_hitPoint\", \"_directHit\", \"_context\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- selection: String - name of the selection where the unit was damaged.\n - \"\" for overall structural damage\n - \"?\" for unknown selections\n- damage: Number - resulting level of damage for the selection\n- source: Object - the source unit that caused the damage\n- projectile: String - classname of the projectile that caused inflicted the damage. (\"\" for unknown, such as fall damage)\n- Arma 3 v1.50 hitPartIndex: Number - hit part index of the hit point, -1 otherwise\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n- Arma 3 v1.68 hitPoint: String - hit point Cfg name\n- Arma 3 v2.12 directHit: Boolean - true for direct projectile damage, false for explosion splash damage and all other kinds of damage like fall damage, fire damage, collision damage, etc.\n- Arma 3 v2.16 context: Number - some additional context for the event:\n\n0 : TotalDamage - total damage adjusted before iteration through hitpoints\n\n1 : HitPoint - some hit point processed during iteration\n\n2 : LastHitPoint - the last hitpoint from iteration is processed\n\n3 : FakeHeadHit - head hit that is added/adjusted\n\n4 : TotalDamageBeforeBleeding - total damage is adjusted before calculating bleeding\n\n> [!NOTE]\n> Between an unknown version (confirmed in Arma 3 v1.70) until v1.78 HandleDamage event triggered for every selection of a vehicle, no matter if the section was damaged or not.\n\n#### HandleHeal\n\nGlobal Argument\n\nTriggered when unit starts healing process (player using heal action on self or other unit, scripted action or AI heals after being ordered or on its own).\nThis event handler must be added to the 'injured' (could be added to Init field in editor) and in multiplayer will trigger only on PC where 'healer' is local. If code returns anything but true, engine side healing follows, otherwise healing is aborted.\n\n> [!IMPORTANT]\n> When AI unit is ordered (or acts at own accord) to heal at a medical vehicle and the event handler returns true, the healing is canceled but AI will try again and again and again. The event handler in this case will fire every second until AI unit is healed by other means.\n\n**NOTE**: This Event Handler was broken before Arma 3 v2.18.\n\n```sqf\nthis addEventHandler [\"HandleHeal\", {\n _this spawn {\n params [\"_injured\", \"_healer\", \"_isMedic\", \"_atVehicle\", \"_action\"];\n private _damage = damage _injured;\n if (_injured == _healer) then\n {\n waitUntil { damage _injured != _damage };\n if (damage _injured < _damage) then\n {\n _injured setDamage 0;\n };\n };\n };\n}];\n```\n\n```sqf\nthis addEventHandler [\"HandleHeal\", {\n params [\"_injured\", \"_healer\", \"_isMedic\", \"_atVehicle\", \"_action\"];\n}];\n```\n\n- injured: Object - unit EH is attached to\n- healer: Object - unit that does the healing (could be the same unit as 'injured')\n- isMedic: Boolean - true when healer is 'Medic'\n- Arma 3 v2.18 atVehicle: Object - when healing at medical vehicle, this is the vehicle\n- Arma 3 v2.18 action: String - the action that triggered the event handler, for example \"SoldierHealSelf\"\n\n#### HandleIdentity\n\nGlobal Argument\n\nTriggered whenever an entity is created. Can be used in scripts if EH is added immediately after unit is created in unscheduled environment.\nDoesn't trigger for editor placed units. Does not work in Multiplayer. If EH scope returns true, the default engine identity application is overridden.\n\n```sqf\nbob = group player createUnit [typeOf player, position player, [], 0, \"NONE\"];\nbob addEventHandler [\"HandleIdentity\", {\n params [\"_unit\"];\n hint str _unit;\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n\n#### HandleRating (Arma 3 v1.32)\n\nLocal Argument\n\nTriggered when engine adds rating to overall rating of the unit, usually after a kill or a friendly kill.\nIf EH code returns Number, this will override default engine behaviour and the resulting value added will be the one returned by EH code.\n\n```sqf\nthis addEventHandler [\"HandleRating\", {\n params [\"_unit\", \"_rating\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- rating: Number - rating to be added\n\n#### HandleScore (Arma 3 v1.32)\n\nGlobal ArgumentServer Execution\n\nTriggered when engine adds score to overall score of the unit, usually after a kill.\nIf the EH code returns Nothing or true, the default engine scoreboard update (score, vehicle kills, infantry kills, etc) is applied, if it returns false, the engine update is cancelled. To add or modify score, use addScore and addScoreSide commands.\nFor remote units like players, the event does not persist after respawn, and must be re-added to the new unit.\n\n**Note:** MP only.\n\n```sqf\nthis addEventHandler [\"HandleScore\", {\n params [\"_unit\", \"_object\", \"_score\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- object: Object - object for which score was awarded\n- score: Number - score to be added\n\n#### Hit\n\nLocal Argument\n\nTriggered when the unit is hit/damaged.\n\nIs *not* always triggered when unit is killed by a hit.\n\nMost of the time only the killed event handler is triggered when a unit dies from a hit.\n\nThe hit EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased.\n\nDoes not fire when a unit is set to allowDamage false.\n\n```sqf\nthis addEventHandler [\"Hit\", {\n params [\"_unit\", \"_source\", \"_damage\", \"_instigator\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- source: Object - object that caused the damage – contains *unit* in case of collisions\n- damage: Number - level of damage caused by the hit\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n\n#### HitPart (Entity)\n\nGlobal Argument\n\nTriggered when the object it was added to gets damaged.\nIt returns the position and component that was hit on the object within a nested array, this is because the model may have more than one selection name for the hit component (i.e. a single piece of geometry can be simultaneously part of multiple, overlapping named selections).\n\nWhile you can add \"HitPart\" handler to a remote unit, the respective addEventHandler command must be executed on the shooter's PC and will only fire on shooter's PC as well.\nThe event will not fire if the shooter is not local, even if the target itself is local.\nAdditionally, if the unit gets damaged by any means other than ammunition or explosions, such as fall damage and burning, \"HitPart\" will not fire.\nBecause of this, this event handler is most suitable for when the shooter needs feedback on his shooting, such as target practicing or hitmarker creation.\n\nThis EH returns an array of arrays. Each sub-array contains data for the part that was hit as usually multiple parts are hit at the same time (see HitPart Sample). The structure of the sub-arrays is listed below.\n\n```sqf\nthis addEventHandler [\"HitPart\", {\n {\n _x params [\n \"_target\", \"_shooter\", \"_projectile\", \"_position\", \"_velocity\",\n \"_selection\", \"_ammo\", \"_vector\", \"_radius\", \"_surfaceType\",\n \"_isDirect\", \"_instigator\"\n ];\n } forEach _this;\n}];\n```\n\n- target: Object - object that was damaged\n- shooter: Object - Unit or vehicle that inflicted the damage. If injured by a vehicle collision, the target itself is returned, or objNull in case of explosions. In case of explosives that were planted by someone (e.g. satchel charges), that unit is returned.\n- projectile: Object - object that was fired\n- position: Array format PositionASL - position the bullet impacted\n- velocity: Vector3D - 3D speed at which the bullet impacted\n- selection: Array - array of Strings with named selection of the object that were hit, in the FireGeometry LOD\n- ammo:\n - Array in format [hitValue, indirectHitValue, indirectHitRange, explosiveDamage, ammoClassName] - If the damage was directly or indirectly inflicted by a projectile. Hit and damage values are derived from the projectile's CfgAmmo class, and do not match the actual damage inflicted, which is usually lower due to armor and other factors.\n - Array in format [impulseValue, 0, 0, 0] - if the damage was inflicted by a vehicle collision\n- vector: Vector3D - Vector that is orthogonal (perpendicular) to the surface struck. For example, if a wall was hit, the vector would be pointing out of the wall at a 90 degree angle.\n- radius: Number - radius (size) of component hit\n- surfaceType: String - surface type struck\n- isDirect: Boolean - true if object was directly hit, false if it was hit by indirect / splash damage\n- Arma 3 v2.18 instigator: Object - shot instigator\n\n> [!NOTE]\n> See #HitPart (Projectile) for a similar event handler that is attached to the projectile instead of the entity.\n\n> [!NOTE]\n> This event does not fire when miniscule explosive damage is dealt to the target entity, but the Explosion event will still fire.\n\n#### IncomingMissile\n\nGlobal Argument\n\nTriggered when a unit fires a missile or rocket at the target. For projectiles fired by players this EH only triggers for guided missiles that have locked onto the target.\n\n```sqf\nthis addEventHandler [\"IncomingMissile\", {\n params [\"_target\", \"_ammo\", \"_vehicle\", \"_instigator\", \"_missile\"];\n}];\n```\n\n- target: Object - object the event handler is assigned to\n- ammo: String - ammo type that was fired on the target\n- Arma 3 v1.42 vehicle: Object - vehicle that fired the weapon. In case of soldier, unit is returned\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n- Arma 3 v2.10 missile: Object - the incoming missile\n\n#### Init (Entity)\n\nGlobal Argument\n\nTriggered whenever an entity is created. Cannot be used in scripts, only inside class Eventhandlers in config.\n\n> [!IMPORTANT]\n> It is recommended to use the #PostInit event handler instead of this one when setting entity textures (setObjectTexture, BIS_fnc_initVehicle etc) to avoid networking issues.\n\ne.g:\n\n```cpp\ninit = \"params ['_entity'];\";\n```\n\n```sqf\nparams [\"_entity\"];\n```\n\n- entity: Object - object the event handler is assigned to\n\n#### InventoryClosed (Arma 3 v1.22)\n\nGlobal Argument\n\nTriggered when the unit closes inventory. Said unit can be non-local when adding the EH, but **must** be local for the EH to trigger.\n\n```sqf\nthis addEventHandler [\"InventoryClosed\", {\n params [\"_unit\", \"_container\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- container: Object - connected container or weaponholder\n\n```sqf\n// Delete dropped items when inventory closed\nplayer addEventHandler [\"InventoryClosed\", {\n params [\"_unit\", \"_container\"];\n if (_container isKindOf \"WeaponHolder\") then\n {\n deleteVehicle _container;\n };\n}];\n```\n\n#### InventoryOpened (Arma 3 v1.22)\n\nGlobal Argument\n\nTriggered when unit opens inventory. Said unit can be non-local when adding the EH, but **must** be local for the EH to trigger. End EH main scope with true to override the opening of the inventory in case you wish to handle it yourself:\n\n```sqf\n// Create and open an ammo box when \"Inventory\" button is pressed\nplayer addEventHandler [\"InventoryOpened\", {\n player removeAllEventHandlers \"InventoryOpened\";\n _box = \"Box_NATO_Ammo_F\" createVehicle [0,0,0];\n _box setPosASL (player modelToWorldVisualWorld [0,1.5,0.5]);\n player action [\"Gear\", _box];\n true; // <-- inventory override\n}];\n```\n\nTo return all nearby containers use nearSupplies command.\n\n```sqf\nthis addEventHandler [\"InventoryOpened\", {\n params [\"_unit\", \"_primaryContainer\", \"_secondaryContainer\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- primaryContainer: Object - connected container or weaponholder\n- Arma 3 v1.66 secondaryContainer: Object - second connected container or weaponholder or objNull\n\n#### Killed\n\nLocal Argument\n\nTriggered when the unit is killed.\n\n```sqf\nthis addEventHandler [\"Killed\", {\n params [\"_unit\", \"_killer\", \"_instigator\", \"_useEffects\", \"_shot\", \"_real\"];\n}];\n```\n\n- unit: Object - the object the event handler is assigned to\n- killer: Object - the object that killed the unit. Contains the unit itself in case of collisions.\n- Arma 3 v1.66 instigator: Object - the person who pulled the trigger\n- Arma 3 v1.68 useEffects: Boolean - same as *useEffects* in setDamage alt syntax\n- Arma 3 v2.22 shot: Object - shot that caused damage\n- Arma 3 v2.22 real: Boolean - true when the shot was 'real' where the event handler triggered\n\n#### LandedStopped\n\nGlobal Argument\n\nTriggered when an AI pilot would get out usually. Not executed for player.\n\n```sqf\nthis addEventHandler [\"LandedStopped\", {\n params [\"_plane\", \"_airportID\", \"_airportObject\"];\n}];\n```\n\n- plane: Object - object the event handler is assigned to\n- airportID: Number - ID of the airport (-1 for anything else)\n- Arma 3 v2.12 airportObject: Object - airport object in the event of a Dynamic Airport, otherwise objNull\n\n#### LandedTouchDown\n\nGlobal Argument\n\nTriggered when a plane (AI or player) touches the ground.\n\n```sqf\nthis addEventHandler [\"LandedTouchDown\", {\n params [\"_plane\", \"_airportID\", \"_airportObject\"];\n}];\n```\n\n- plane: Object - object the event handler is assigned to\n- airportID: Number - ID of the airport (-1 for anything else)\n- Arma 3 v2.12 airportObject: Object - airport object in the event of a Dynamic Airport, otherwise objNull\n\n#### Landing (Arma 3 v1.70)\n\nGlobal Argument\n\nTriggered when an AI pilot (or auto-pilot) is preparing for landing. The exact moment of triggering coincides with lowering of the gear (\"Gear\" EH)\n\n```sqf\nthis addEventHandler [\"Landing\", {\n params [\"_plane\", \"_airportID\", \"_isCarrier\"];\n}];\n```\n\n- plane: Object - object the event handler is assigned to\n- airportID: Number or Object - ID of the airport or aircraft carrier object\n- isCarrier: Boolean - true if landing on aircraft carrier\n\n#### LandingCanceled (Arma 3 v1.70)\n\nGlobal Argument\n\nTriggered when AI pilot landing is cancelled (for example new order received to land elsewhere).\nThe exact moment of triggering coincides with retracting of the gear (\"Gear\" EH).\n\n**Note**: Does not trigger if player switches off auto-pilot. Canceled is spelled with one `L`\n\n```sqf\nthis addEventHandler [\"LandingCanceled\", {\n params [\"_plane\", \"_airportID\", \"_isCarrier\"];\n}];\n```\n\n- plane: Object - object the event handler is assigned to\n- airportID: Number or Object - ID of the airport or aircraft carrier object (-1 no airport)\n- isCarrier: Boolean - true if landing on aircraft carrier\n\n#### LaserTargetChanged (Arma 3 v2.22)\n\nTriggered when the laser target changes.\n\n```sqf\nthis addEventHandler [\"LaserTargetChanged\", {\n params [\"_unit\", \"_laserTarget\", \"_designatedTarget\", \"_turretPath\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- laserTarget: Object - the laser target entity that got created at impact point\n- designatedTarget: Object - the object that is targeted by the laser\n- turretPath: Turret Path - the path to the turret that activated the laser. It is empty when the event is triggered by a unit\n\n#### LeaningChanged (Arma 3 v2.18)\n\nGlobal Argument\n\nTriggered when a soldier leaning factor is changed between -1 (extreme left), 0 (not leaning) and 1 (extreme right)\n\n```sqf\nthis addEventHandler [\"LeaningChanged\", {\n params [\"_unit\", \"_newLeaning\", \"_oldLeaning\"];\n}];\n```\n\n- unit: Object - soldier\n- newLeaning: Number from -1 to 1\n- oldLeaning: Number from -1 to 1\n\n#### Local (Entity)\n\nGlobal Argument\n\nTriggers when locality of object in MP is changed. The event handler only triggers on the computers that are directly involved in change of locality.\nSo if EH is added to every computer on network, it will only trigger on 2 computers, on the computer that receives ownership of the object (new owner), in which case _this select 1 will be true,\nand on the computer from which ownership is transferred (old owner), in which case _this select 1 will be false.\n\n```sqf\nthis addEventHandler [\"Local\", {\n params [\"_entity\", \"_isLocal\"];\n}];\n```\n\n- entity: Object - the object that changed locality\n- isLocal: Boolean - if the object is local on given computer\n\n#### MagazineReloading (Arma 3 v2.18)\n\nLocal Argument\n\nTriggers when reloading starts.\n\n```sqf\nthis addEventHandler [\"MagazineReloading\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_magazine\", \"_magazineClass\", \"_ammoCount\", \"_magazineID\", \"_magazineCreator\"];\n}];\n```\n\n- unit: Object - unit or vehicle to which EH is assigned\n- weapon: String - weapon that got unloaded\n- muzzle: String - weapon's muzzle that got unloaded\n- magazine: Array - magazine info in format [magazineClass, ammoCount, magazineID, magazineCreator], where:\n - magazineClass: String - class name of the magazine\n - ammoCount: Number - amount of ammo in magazine\n - magazineID: Number - global magazine id\n - magazineCreator: Number - owner of the magazine creator\n\n#### MagazineUnloaded (Arma 3 v2.18)\n\nLocal Argument\n\nTriggers when a magazine is removed from a weapon manually or via script.\n\n```sqf\nthis addEventHandler [\"MagazineUnloaded\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_magazine\", \"_magazineClass\", \"_ammoCount\", \"_magazineID\", \"_magazineCreator\"];\n}];\n```\n\n- unit: Object - unit or vehicle to which EH is assigned\n- weapon: String - weapon that got unloaded\n- muzzle: String - weapon's muzzle that got unloaded\n- magazine: Array - magazine info in format [magazineClass, ammoCount, magazineID, magazineCreator], where:\n - magazineClass: String - class name of the magazine\n - ammoCount: Number - amount of ammo in magazine\n - magazineID: Number - global magazine id\n - magazineCreator: Number - owner of the magazine creator\n\n#### OpticsModeChanged (Arma 3 v2.10)\n\nLocal Argument\n\nTriggers everytime a local unit changes optic mode. This could be either through the setOpticsMode command or by the player switching to the next optic mode using e.g NUM / or Ctrl +RMB .\n\n```sqf\nthis addEventHandler [\"OpticsModeChanged\", {\n params [\"_unit\", \"_opticsClass\", \"_newMode\", \"_oldMode\", \"_isADS\"];\n}];\n```\n\n- unit: Object - the unit\n- opticsClass: String\n- newMode: String\n- oldMode: String\n- isADS: Boolean - if the new view is GUNNER\n\n#### OpticsSwitch (Arma 3 v2.10)\n\nLocal Argument\n\nTriggers at the start of the camera transition from GUNNER to INTERNAL/EXTERNAL and vice-versa.\nSo anytime the right mouse button is pressed and there is a GUNNER view available or are currently in it, this triggers.\nWorks in vehicles and FFV as well. See also cameraView.\n\n```sqf\nthis addEventHandler [\"OpticsSwitch\", {\n params [\"_unit\", \"_isADS\"];\n}];\n```\n\n- unit: Object - the unit\n- isADS: Boolean - if the new view is GUNNER\n\n#### PathCalculated (Arma 3 v1.94)\n\nLocal Argument\n\nTriggers when a path has been calculated for the unit. Works for both agents and normal AI units.\n\nNote that paths to far destinations are typically calculated in segments.\nWhen the unit completes a segment, a new path is calculated and this is continued until the unit reaches its destination.\n\n```sqf\nthis addEventHandler [\"PathCalculated\", {\n params [\"_unit\", \"_path\"];\n}];\n```\n\n- unit: Object - the unit/agent for which the path was calculated\n- path: Array - the array of positions representing the path (PositionASL)\n\n#### PeriscopeElevationChanged (Arma 3 v2.00)\n\nFires every frame during periscope elevation animation.\n\n```sqf\nthis addEventHandler [\"PeriscopeElevationChanged\", {\n params [\"_vehicle\", \"_turret\", \"_elevation\", \"_direction\", \"_userIsBlocked\"];\n}];\n```\n\n- vehicle: Object - the vehicle this EH is assigned to\n- turret: Array - the turret which periscope is changing elevation\n- elevation: Number - current periscope elevation (changes with each simulation). See also periscopeElevation, elevatePeriscope\n- direction: Number - 1: moves up, 0: stopped, -1: moves down; when `direction` returns 0, this also means the event handler fired for the last time for this elevation.\n- userIsBlocked: Boolean - whether or not the user ability to override is blocked. See also periscopeElevation, elevatePeriscope\n\n#### PostInit (Arma 3 v2.06)\n\nGlobal Argument\n\nTriggered whenever an entity is created and initialized. Cannot be used in scripts, only inside class Eventhandlers in config.\n\n> [!IMPORTANT]\n> It is recommended to use this event handler instead of the #Init one when setting entity textures (setObjectTexture, BIS_fnc_initVehicle etc) to avoid networking issues.\n\ne.g:\n\n```cpp\npostInit = \"params ['_entity'];\";\n```\n\n```cpp\npostinit = \"params ['_entity']; if (local _entity) then { [_entity, '', [], false] call BIS_fnc_initVehicle };\";\n```\n\n```sqf\nparams [\"_entity\"];\n```\n\n- entity: Object - object the event handler is assigned to\n\n#### PostReset\n\n**Obsolete** - triggers after PP effects have been reset by the engine.\n\n#### Put (Arma 3 v0.56)\n\nGlobal Argument\n\nTriggers when a unit puts an item in a container.\n\nArma 3 v2.14 This event handler can be added to a container.\n\n```sqf\nthis addEventHandler [\"Put\", {\n params [\"_unit\", \"_container\", \"_item\"];\n}];\n```\n\n- unit: Object - unit who put the item in the container\n- container: Object - the container into which the item was placed (vehicle, box, etc.)\n- item: String - the class name of the moved item\n\n> [!NOTE]\n> This EH could also trigger when unit replaces magazine in weapon with another magazine from unit containers (uniform, vest, backpack) during reload.\n\n#### PylonChanged (Arma 3 v2.20)\n\nLocal Argument\n\nTriggers when an aircraft's pylon changes magazine type:\n\n```sqf\nvehicle player addEventHandler [\"PylonChanged\", {\n params [\"_vehicle\", \"_pylonIndex\", \"_oldMagazine\", \"_newMagazine\"];\n}];\n```\n\n- vehicle: Object\n- pylonIndex: Number\n- oldMagazine: String\n- newMagazine: String\n\n> [!IMPORTANT]\n> This event generally triggers **twice** for a swap, first unload then load, e.g:\n>\n> ```sqf\n> // [myVehicle, 1, \"oldMagClass\", \"\"]\n> // [myVehicle, 1, \"\", \"newMagClass\"]\n> ```\n\n#### Reloaded (Arma 3 v1.58)\n\nLocal Argument\n\nTriggers once a weapon is reloaded with a new magazine. For more information, see Reloaded.\n\n```sqf\nthis addEventHandler [\"Reloaded\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_newMagazine\", \"_oldMagazine\"];\n}];\n```\n\n- unit: Object - unit or vehicle to which EH is assigned\n- weapon: String - weapon that got reloaded\n- muzzle: String - weapon's muzzle that got reloaded\n- newMagazine: Array - new magazine info\n- oldMagazine: Array or Nothing - old magazine info\n\n#### Respawn\n\nLocal Argument\n\nTriggered when a unit respawns.\n\n```sqf\nthis addEventHandler [\"Respawn\", {\n params [\"_unit\", \"_corpse\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- corpse: Object - object the event handler was assigned to, aka the corpse/unit player was previously controlling\n\n#### RopeAttach (Arma 3 v1.34)\n\nTriggered when a rope is attached to an object.\n\nIn the case of sling loading, this event handler must be assigned to the helicopter and will trigger for each attached rope.\n\n```sqf\nthis addEventHandler [\"RopeAttach\", {\n params [\"_object1\", \"_rope\", \"_object2\"];\n}];\n```\n\n- object1: Object - object to which the event handler is assigned.\n- rope: Object - the rope being attached between object 1 and object 2.\n- object2: Object - the object that is being attached to object 1 via rope.\n\n#### RopeBreak (Arma 3 v1.34)\n\nTriggered when a rope is detached from an object.\n\nIn the case of sling loading, this event handler must be assigned to the helicopter and will trigger for each detached rope.\n\n```sqf\nthis addEventHandler [\"RopeBreak\", {\n params [\"_object1\", \"_rope\", \"_object2\"];\n}];\n```\n\n- object1: Object - object to which the event handler is assigned.\n- rope: Object - the rope that connected object 1 and object 2.\n- object2: Object - the object that was connected to object 1 with a rope.\n\n#### SeatSwitched (Arma 3 v1.50)\n\nGlobal Argument\n\nTriggered when unit changes seat within vehicle. EH returns both units switching seats.\nIf switching seats with an empty seat, one of the returned units will be objNull.\nThe new position can be obtained with assignedVehicleRole.\nThis EH must be assigned to a vehicle.\n\n```sqf\nthis addEventHandler [\"SeatSwitched\", {\n params [\"_vehicle\", \"_unit1\", \"_unit2\"];\n}];\n```\n\n- vehicle: Object - vehicle to which the event handler is assigned.\n- unit1: Object - unit switching seat.\n- unit2: Object - unit switching seat.\n\n#### SeatSwitchedMan (Arma 3 v1.58)\n\nGlobal Argument\n\nTriggered when unit changes seat within vehicle. EH returns both units switching seats.\nIf switching seats with an empty seat, one of the returned units will be objNull.\nThe new position can be obtained with assignedVehicleRole . This EH must be assigned to a unit and not a vehicle.\nThis EH is persistent and will be transferred to the new unit after respawn, but only if it was assigned where unit was local.\n\n```sqf\nthis addEventHandler [\"SeatSwitchedMan\", {\n params [\"_unit1\", \"_unit2\", \"_vehicle\"];\n}];\n```\n\n- unit1: Object - unit switching seat.\n- unit2: Object - unit with which unit1 is switching seat.\n- vehicle: Object - vehicle where switching seats is taking place.\n\n#### SelectedActionChanged\n\nRTM helicopter user action event\n\n```sqf\nthis addEventHandler [\"SelectedActionChanged\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality.\n\n#### SelectedActionPerformed\n\nRTM helicopter user action event\n\n```sqf\nthis addEventHandler [\"SelectedActionPerformed\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality.\n\n#### SelectedRotorLibActionChanged\n\nRTM helicopter user action event\n\n```sqf\nthis addEventHandler [\"SelectedRotorLibActionChanged\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality.\n\n#### SelectedRotorLibActionPerformed\n\nRTM helicopter user action event\n\n```sqf\nthis addEventHandler [\"SelectedRotorLibActionPerformed\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Works only for key press combination RCtrl +W , which is the binding for helicopter wheels brakes.\n> 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:\n> - 0: HelicopterAutoTrimOn\n> - 1: HelicopterAutoTrimOff\n> - 2: HelicopterTrimOn\n> - 3: HelicopterTrimOff\n> - 4: WheelsBrakeOn\n> - 5: WheelsBrakeOff\n\n#### SlotItemChanged (Arma 3 v2.14)\n\nGlobal Argument\n\nTriggered when any of the following slots get assigned or unassigned: *Items* - Map, GPS, Radio, Watch, Compass, Helmet, Goggles, NVG; *Weapon* - Binoculars; *Containers* - Uniform, Vest, Backpack.\n\n```sqf\nthis addEventHandler [\"SlotItemChanged\", {\n params [\"_unit\", \"_name\", \"_slot\", \"_assigned\", \"_weapon\"];\n}];\n```\n\n- unit: Object - unit EH assigned to.\n- name: String - name of the item/weapon/container (see getSlotItemName).\n- slot: Number - slot id (see getSlotItemName).\n- assigned: Boolean - true assign action, false unassign action.\n- Arma 3 v2.18 weapon: String - name of weapon in event that slot changed is a weapon attachment slot\n\n#### SoundPlayed (Arma 3 v0.56)\n\nLocal Argument\n\nTriggered when player is making noises when injured or fatigued for example. The number param passed to the EH code points to the sound origin:\n1. Breath\n1. Breath Injured\n1. Breath Scuba\n1. Injured\n1. Pulsation\n1. Hit Scream\n1. Burning\n1. Drowning\n1. Drown\n1. Gasping\n1. Stabilizing\n1. Healing\n1. Healing With Medikit\n1. Recovered\n1. Breath Held\n\n```sqf\nthis addEventHandler [\"SoundPlayed\", {\n params [\"_unit\", \"_soundID\"];\n}];\n```\n\n- unit: Object - unit to which the event handler is assigned\n- soundID: Number - sound origin\n\n> [!NOTE]\n> Since Arma 3 v2.12 returning a Number from last added EH in range from 0 to 5 will alter the volume of played sound from mute to max volume.\n\n#### Suppressed (Arma 3 v2.02)\n\nLocal Argument\n\nTriggers when enemy projectile is passing by closer than defined suppression radius ammo value in config.\nCan be made to trigger for the same side if the side is set as enemy to itself (with setFriend). For more information see Arma 3: Suppression.\n\n```sqf\nthis addEventHandler [\"Suppressed\", {\n params [\"_unit\", \"_distance\", \"_shooter\", \"_instigator\", \"_ammoObject\", \"_ammoClassName\", \"_ammoConfig\"];\n}];\n```\n\n- unit: Object - unit to which the event is assigned\n- distance: Number - distance of the projectile pass-by\n- shooter: Object - who (or what) fired - vehicle or drone\n- instigator: Object - who pressed the trigger. Instigator is different from the shooter when player is operator of UAV for example\n- ammoObject: Object - the ammunition itself\n- ammoClassName: String - the ammunition's classname\n- ammoConfig: Config - the ammunition's CfgAmmo config path\n\n#### Take (Arma 3 v0.56)\n\nGlobal Argument\n\nTriggers when a unit takes an item from a container.\n\nArma 3 v2.14 This event handler can be added to a container.\n\n```sqf\nthis addEventHandler [\"Take\", {\n params [\"_unit\", \"_container\", \"_item\"];\n}];\n```\n\n- unit: Object - unit who took the item from the container\n- container: Object - the container from which the item was taken (vehicle, box, etc.)\n- item: String - the class name of the taken item\n\n> [!NOTE]\n> This EH could also trigger when unit replaces magazine in weapon with another magazine from unit containers (uniform, vest, backpack) during reload.\n\n#### TaskSetAsCurrent (Arma 3 v1.32)\n\nTriggers when player's current task changes\n\n```sqf\nthis addEventHandler [\"TaskSetAsCurrent\", {\n params [\"_unit\", \"_task\"];\n}];\n```\n\n- unit: Object - the player to whom the event handler is assigned\n- task: Task - the new current task\n\n#### TurnIn (Arma 3 v1.66)\n\nTriggers when member of crew in a vehicle uses Turn In action\n\n```sqf\nthis addEventHandler [\"TurnIn\", {\n params [\"_vehicle\", \"_unit\", \"_turret\"];\n}];\n```\n\n- vehicle: Object - the vehicle the event handler is assigned to\n- unit: Object - the unit performing the Turn In action\n- turret: Array - turret path\n\n#### TurnOut (Arma 3 v1.66)\n\nTriggers when member of crew in a vehicle uses Turn Out action\n\n```sqf\nthis addEventHandler [\"TurnOut\", {\n params [\"_vehicle\", \"_unit\", \"_turret\"];\n}];\n```\n\n- vehicle: Object - the vehicle the event handler is assigned to\n- unit: Object - the unit performing the Turn Out action\n- turret: Array - turret path\n\n#### VisionModeChanged (Arma 3 v2.08)\n\nTriggers when the assigned vehicle/unit's vision mode has changed.\n\n```sqf\nplayer addEventHandler [\"VisionModeChanged\", {\n params [\"_person\", \"_visionMode\", \"_TIindex\", \"_visionModePrev\", \"_TIindexPrev\", \"_vehicle\", \"_turret\"];\n}];\n```\n\n- person: Object - unit for whom the vision mode changes\n- visionMode: Number - vision mode index\n- TIindex: Number - thermal vision mode index; will return -1 when *visionMode* is not 2\n- visionModePrev: Number - last vision mode\n- TIindexPrev: Number - last TI mode; will return -1 when *visionModePrev* is not 2\n- vehicle: Object - if unit is in a vehicle or controlling a UAV, this will be the vehicle\n- turret: Array - turret path to the turret occupied by the unit, or [] if not on turret\n\n#### WeaponAssembled\n\nGlobal Argument\n\nTriggers when a weapon gets assembled. EH must be attached to the unit and not the weapon.\n\n```sqf\nthis addEventHandler [\"WeaponAssembled\", {\n params [\"_unit\", \"_weapon\", \"_primaryBag\", \"_secondaryBag\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- weapon: Object - object of the assembled weapon\n- Arma 3 v2.18 primaryBag: Object - primary bag (just before it is deleted)\n- Arma 3 v2.18 secondaryBag: Object - secondary bag (just before it is deleted)\n\n#### WeaponChanged (Arma 3 v2.18)\n\nFires on weapon switch and firemode switch. Does not fire for player units inside vehicles (but does fire for vehicles with players in them).\n\nThe locality is unknown, but it is known that this EH behaves like currentWeapon, currentWeaponMode and currentMuzzle in terms of locality.\n\nArma 3 v2.22 Fires for \"Throw\" muzzle changes too.\n\n```sqf\nthis addEventHandler [\"WeaponChanged\", {\n params [\"_object\", \"_oldWeapon\", \"_newWeapon\", \"_oldMode\", \"_newMode\", \"_oldMuzzle\", \"_newMuzzle\", \"_turretIndex\"];\n}];\n```\n\n- object: Object - the unit or vehicle the event handler is assigned to\n- oldWeapon: String - the class name of the previous weapon\n- newWeapon: String - the class name of the new weapon (same as currentWeapon)\n- oldMode: String - the previous weapon mode\n- newMode: String - the new weapon mode (same as currentWeaponMode)\n- oldMuzzle: String - the previous weapon muzzle\n- newMuzzle: String - the new weapon muzzle (same as currentMuzzle)\n- turretIndex: Array format Turret Path - the turret path, or empty array if `object` is not a transport vehicle\n\n#### WeaponDeployed (Arma 3 v1.44)\n\nGlobal Argument\n\nTriggers when the deployed state of a weapon or bipod changes.\n\n**Note:** A weapon cannot be rested and deployed at the same time.\n\n```sqf\nthis addEventHandler [\"WeaponDeployed\", {\n params [\"_unit\", \"_isDeployed\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- isDeployed: Boolean - true if deployed\n\n#### WeaponDisassembled\n\nGlobal Argument\n\nTriggers when a weapon gets disassembled. EH must be attached to the unit and not the weapon.\n\n**Note:** As of Arma 3 v1.32, this event does not fire if the weapon is not local.\n\n```sqf\nthis addEventHandler [\"WeaponDisassembled\", {\n params [\"_unit\", \"_primaryBag\", \"_secondaryBag\", \"_weapon\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- primaryBag: Object - first backpack object which was weapon disassembled into\n- secondaryBag: Object - second backpack object which was weapon disassembled into\n- Arma 3 v2.18 weapon: Object - disassembled weapon (just before it is moved out of the world)\n\n#### WeaponRested (Arma 3 v1.44)\n\nLocal Argument\n\nTriggers when weapon rested state changes (weapon near a surface that can provide weapon support).\n\n**Note:** A weapon cannot be rested and deployed at the same time.\n\n```sqf\nthis addEventHandler [\"WeaponRested\", {\n params [\"_unit\", \"_isRested\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- isRested: Boolean - true if rested\n\n### Multiplayer Event Handlers\n\nGlobal object event handler, executed on every connected machine.\n\nCommands:\n- addMPEventHandler\n- removeMPEventHandler\n- removeAllMPEventHandlers\n\n> [!IMPORTANT]\n> A Multiplayer Event Handler is **not** saved in a save file and therefore will not be restored on load - use it accordingly.\n\n#### MPHit\n\nGlobal ArgumentGlobal Effect\n\nTriggered when the unit is hit/damaged. EH can be added on any machine and EH code will trigger globally on every connected client and server.\nThis EH is clever enough to be triggered globally only once even if added on all clients or a single client that is then disconnected, EH will still trigger globally only once.\n\nIs *not* always triggered when unit is killed by a hit.\nMost of the time only the killed event handler is triggered when a unit dies from a hit.\nThe hit EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased.\nCan also trigger several times for an explosion (direct and indirect damage). Does not fire when a unit is set to allowDamage false.\nHowever it will fire with \"HandleDamage\" EH added alongside stopping unit from taking damage (`unit addEventHandler [\"HandleDamage\", { 0 }];`.\nWill not trigger once the unit is dead.\n\n**Note:** call a function from the MPHit EH code space rather than defining the full code in there directly.\nThe reason is the code space will be transferred over network on each event activation - so keep the data as small as possible!\n\n```sqf\nthis addMPEventHandler [\"MPHit\", {\n params [\"_unit\", \"_causedBy\", \"_damage\", \"_instigator\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n\n- causedBy: Object - object that caused the damage. Contains the unit itself in case of collisions.\n\n- damage: Number - level of damage caused by the hit\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n\n#### MPKilled\n\nGlobal ArgumentGlobal Effect\n\nTriggered when the unit is killed. EH can be added on any machine and EH code will trigger globally **on every connected client and server**.\nThis EH has a safeguard measure so that even if it's added on all clients or a single client that is then disconnected, EH will still trigger globally only once per client.\n\n```sqf\nthis addMPEventHandler [\"MPKilled\", {\n params [\"_unit\", \"_killer\", \"_instigator\", \"_useEffects\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- killer: Object - object that killed the unit. Contains the unit itself in case of collisions\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n- Arma 3 v1.68 useEffects: Boolean - same as *useEffects* in setDamage alt syntax\n\n#### MPRespawn\n\nGlobal ArgumentLocal Effect\n\nTriggered when a unit, it is assigned to, respawns. This EH does not work as one would expect MP EH should work like.\nIt is only triggered on one machine where the unit it was assigned to is local.\nThe only difference between **Respawn** and **MPRespawn** is that **MPRespawn** can be assigned from anywhere while **Respawn** requires the unit to be local.\n\nMPRespawn EH expects the EH code to return an array in Position format which will be used to place the respawned unit at the desired coordinates.\n\nFor example: `player addMPEventHandler [\"MPRespawn\", { [1234, 1234, 0] }];` will place player at [1234,1234,0] immediately on respawn.\n\n```sqf\nthis addMPEventHandler [\"MPRespawn\", {\n params [\"_unit\", \"_corpse\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- corpse: Object - object the event handler was assigned to, aka the corpse/unit player was previously controlling.\n\n### Mission Event Handlers\n\nMission Event Handlers are specific EHs that are anchored to the running mission and automatically removed when mission is over.\n\nCommands:\n- addMissionEventHandler\n- removeMissionEventHandler\n\n> [!NOTE]\n> See Arma 3: Mission Event Handlers.\n\n### Curator Event Handlers (Arma 3 v1.16)\n\nLocal ArgumentLocal Effect\n\nArma 3: Curator Event Handlers are also added with the addEventHandler command. They are executed only where the curator is local - on the machine that is in control of it.\n\n> [!IMPORTANT]\n> These Event Handlers must be added to the curator object/module, **not** the player!\n\nCommands:\n- addEventHandler\n- removeEventHandler\n- removeAllEventHandlers\n\n#### CuratorFeedbackMessage\n\nLocal Argument\n\nTriggered when curator attempts invalid action in curator interface.\n\nEach error has its own unique ID, recognized values are:\n\n- 003 - when trying to teleport camera outside of curatorCameraArea\n- 101 - trying to place an object when placing is disabled using setCuratorCoef \"place\"\n- 102 - trying to place an object which is too expensive (cost set in *curatorObjectRegistered* multiplied by setCuratorCoef \"place\" is larger than curatorPoints)\n- 103 - trying to place an object outside of curatorEditingArea\n- 104 - items of a placed composition were skipped / could not be placed (since Arma 3 v2.06)\n- 201 - trying to place a waypoint when waypoint placing is disabled\n- 202 - trying to place a waypoint which is too expensive (cost set by setCuratorWaypointCost multiplied by setCuratorCoef \"place\" is larger than curatorPoints)\n- 206 - trying to place a waypoint when no AI unit is selected\n- 301 - trying to move or rotate an entity when editing is disabled using setCuratorCoef \"edit\"\n- 302 - trying to move or rotate an entity when it is too expensive (entity cost multiplied by setCuratorCoef \"edit\" is larger than curatorPoints)\n- 303 - trying to move an entity outside of curatorEditingArea\n- 304 - trying to move or rotate an entity which is outside of curatorEditingArea\n- 307 - trying to move or rotate a player (players cannot be manipulated with)\n- 401 - trying to delete an entity when deleting is disabled using setCuratorCoef \"delete\"\n- 402 - trying to delete an entity which is too expensive (cost multiplied by setCuratorCoef \"delete\" is larger than curatorPoints)\n- 404 - trying to delete an entity which is outside of curatorEditingArea\n- 405 - trying to delete an entity which has non-editable crew in it\n- 407 - trying to delete a player (players cannot be manipulated with)\n- 501 - trying to destroy an object when destroying is disabled using setCuratorCoef \"destroy\"\n- 502 - trying to destroy an object which is too expensive (cost multiplied by setCuratorCoef \"destroy\" is larger than curatorPoints)\n- 504 - trying to destroy an object which is outside of curatorEditingArea\n- 505 - trying to destroy an object which has non-editable crew in it\n- 506 - trying to destroy an object when no object is selected\n- 507 - trying to destroy a player (players cannot be manipulated with)\n\n```sqf\nthis addEventHandler [\"CuratorFeedbackMessage\", {\n params [\"_curator\", \"_errorID\"];\n}];\n```\n\n- curator: Object\n- errorID: Number\n\n#### CuratorGroupDoubleClicked\n\nLocal Argument\n\nTriggered when a group is double-clicked on in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorGroupDoubleClicked\", {\n params [\"_curator\", \"_group\"];\n}];\n```\n\n- curator: Object\n- group: Group\n\n#### CuratorGroupPlaced\n\nLocal Argument\n\nTriggered when new group is placed in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorGroupPlaced\", {\n params [\"_curator\", \"_group\"];\n}];\n```\n\n- curator: Object\n- group: Group\n\n#### CuratorGroupSelectionChanged\n\nLocal Argument\n\nTriggered when a group is selected in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorGroupSelectionChanged\", {\n params [\"_curator\", \"_group\"];\n}];\n```\n\n- curator: Object\n- group: Group\n\n#### CuratorMarkerDeleted\n\nLocal Argument\n\nTriggered when a marker is deleted in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerDeleted\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String\n\n#### CuratorMarkerDoubleClicked\n\nLocal Argument\n\nTriggered when a marker is double-clicked on in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerDoubleClicked\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String\n\n#### CuratorMarkerEdited\n\nLocal Argument\n\nTriggered when a marker is moved in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerEdited\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String\n\n#### CuratorMarkerPlaced\n\nLocal Argument\n\nTriggered when new marker is placed in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerPlaced\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String\n\n#### CuratorMarkerSelectionChanged\n\nLocal Argument\n\nTriggered when a marker is selected in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerSelectionChanged\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String\n\n#### CuratorObjectDeleted\n\nLocal Argument\n\nTriggered when an object is deleted in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorObjectDeleted\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object\n\n#### CuratorObjectDoubleClicked\n\nLocal Argument\n\nTriggered when an object is double-clicked on in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorObjectDoubleClicked\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object\n\n#### CuratorObjectEdited\n\nLocal Argument\n\nTriggered when an object is moved or rotated in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorObjectEdited\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object\n\n#### CuratorObjectPlaced\n\nLocal Argument\n\nTriggered when new object is placed in curator interface.\nThis event handler will trigger individually for each unit in a placed group - excluding the crew in vehicles.\n\n```sqf\nthis addEventHandler [\"CuratorObjectPlaced\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object\n\n#### CuratorObjectRegistered\n\nLocal Argument\n\nTriggered when player enters curator interface. Assign curator cost to every object in the game.\nThis is the primary method that a mission designer can use to limit the objects a curator can place.\n\n> [!NOTE]\n> See Curator#Manual Assigning.\n\n```sqf\nthis addEventHandler [\"CuratorObjectRegistered\", {\n params [\"_curator\", \"_input\"];\n}];\n```\n\n- curator: Object\n- input: Array of Strings - all CfgVehicles classes\n\n#### CuratorObjectSelectionChanged\n\nLocal Argument\n\nTriggered when an object is selected in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorObjectSelectionChanged\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object\n\n#### CuratorPinged\n\nLocal Argument\n\nTriggered when a player pings his curator(s) by pressing the *Zeus* key.\n\n```sqf\nthis addEventHandler [\"CuratorPinged\", {\n params [\"_curator\", \"_player\"];\n}];\n```\n\n- curator: Object\n- player: Object\n\n#### CuratorSelectionPresetLoaded (Arma 3 v2.14)\n\nLocal Argument\n\nTriggered when a selection preset is loaded using the respective number key or through script.\n\n```sqf\nthis addEventHandler [\"CuratorSelectionPresetLoaded\", {\n params [\"_curator\", \"_numkey\"];\n}];\n```\n\n- curator: Object\n- numkey: Number\n\n#### CuratorSelectionPresetSaved (Arma 3 v2.14)\n\nLocal Argument\n\nTriggered when a selection preset is saved using the respective CTRL + number key or set through script.\n\n```sqf\nthis addEventHandler [\"CuratorSelectionPresetSaved\", {\n params [\"_curator\", \"_numkey\"];\n}];\n```\n\n- curator: Object\n- numkey: Number\n\n#### CuratorWaypointDeleted\n\nLocal Argument\n\nTriggered when a waypoint is deleted in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointDeleted\", {\n params [\"_curator\", \"_waypoint\"];\n}];\n```\n\n- curator: Object\n- waypoint: Array\n\n#### CuratorWaypointDoubleClicked\n\nLocal Argument\n\nTriggered when a waypoint is double-clicked on in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointDoubleClicked\", {\n params [\"_curator\", \"_waypoint\"];\n}];\n```\n\n- curator: Object\n- waypoint: Array\n\n#### CuratorWaypointEdited\n\nLocal Argument\n\nTriggered when a waypoint is moved in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointEdited\", {\n params [\"_curator\", \"_group\", \"_waypointID\"];\n}];\n```\n\n- curator: Object\n- group: Group\n- waypointID: Number\n\n#### CuratorWaypointPlaced\n\nLocal Argument\n\nTriggered when new waypoint is placed in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointPlaced\", {\n params [\"_curator\", \"_group\", \"_waypointID\"];\n}];\n```\n\n- curator: Object\n- group: Group\n- waypointID: Number\n\n#### CuratorWaypointSelectionChanged\n\nLocal Argument\n\nTriggered when a waypoint is selected in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointSelectionChanged\", {\n params [\"_curator\", \"_waypoint\"];\n}];\n```\n\n- curator: Object\n- waypoint: Array\n\n### UserAction Event Handlers (Arma 3 v2.06)\n\nUserAction Event Handlers are events that trigger on user action.\n\nCommands:\n- addUserActionEventHandler\n- removeUserActionEventHandler\n\n> [!NOTE]\n> See Arma 3: Modded Keybinding.\n\n#### Activate\n\n```sqf\naddUserActionEventHandler [\"KeyName\", \"Activate\", {\n params [\"_activated\"];\n}];\n```\n\n- activated: Boolean - always returns true\n\n#### Deactivate\n\n```sqf\naddUserActionEventHandler [\"KeyName\", \"Deactivate\", {\n params [\"_activated\"];\n}];\n```\n\n- activated: Boolean - always returns false\n\n#### Analog\n\n```sqf\naddUserActionEventHandler [\"KeyName\", \"Analog\", {\n params [\"_value\"];\n}];\n```\n\n- value: Number - input device's analog value\n\n### Projectile Event Handlers (Arma 3 v2.10)\n\nCommands:\n- addEventHandler\n- removeEventHandler\n- removeAllEventHandlers\n\n#### Deleted (Projectile)\n\n```sqf\n_projectile addEventHandler [\"Deleted\", {\n params [\"_projectile\"];\n}];\n```\n\n- projectile: Object\n\n#### Deflected\n\n```sqf\n_projectile addEventHandler [\"Deflected\", {\n params [\"_projectile\", \"_position\", \"_velocity\", \"_hitObject\"];\n}];\n```\n\n- projectile: Object\n- position: Array format PositionASL\n- velocity: Array format Vector3D\n- hitObject: Object - the object that deflected the projectile\n\n#### Explode\n\nLocal Argument\n\n```sqf\n_projectile addEventHandler [\"Explode\", {\n params [\"_projectile\", \"_position\", \"_velocity\"];\n}];\n```\n\n- projectile: Object\n- position: Array format PositionASL\n- velocity: Array format Vector3D\n\n#### HitExplosion\n\n```sqf\n_projectile addEventHandler [\"HitExplosion\", {\n params [\"_projectile\", \"_hitEntity\", \"_projectileOwner\", \"_hitSelections\", \"_instigator\"];\n}];\n```\n\n- projectile: Object\n- hitEntity: Object\n- projectileOwner: Object\n- hitSelections: Array of Arrays - same list of FireGeometry components that #HitPart (Entity) gets but only contains:\n - position: Array format PositionASL - position of impact\n - vector: Array format Vector3D - vector that is orthogonal (perpendicular) to the surface struck. For example, if a wall was hit, vector would be pointing out of the wall at a 90 degree angle\n - selection: String - named selection of the object that was hit, in the FireGeometry LOD.\n - radius: Number - radius (size) of component hit\n - surface: String - surface type struck\n- Arma 3 v2.18 instigator: Object - shot instigator\n\n#### HitPart (Projectile)\n\nTriggered when the projectile hits any surface.\n\n```sqf\n_projectile addEventHandler [\"HitPart\", {\n params [\"_projectile\", \"_hitEntity\", \"_projectileOwner\", \"_pos\", \"_velocity\", \"_normal\", \"_components\", \"_radius\" ,\"_surfaceType\", \"_instigator\"];\n}];\n```\n\n- projectile: Object\n- hitEntity: Object\n- projectileOwner: Object\n- pos: Array format PositionASL\n- velocity: Array format Vector3D\n- normal: Array format Vector3D\n- components: Array of Strings - the selections that were hit, in the FireGeometry LOD.\n- radius: Number - radius (size) of the hitPoint\n- surfaceType: String\n- Arma 3 v2.18 instigator: Object - shot instigator\n\n> [!IMPORTANT]\n> This event handler only triggers for direct hits and not splash damage, unlike #HitPart (Entity). For splash damage, use #HitExplosion.\n\n#### Init (Projectile)\n\nTriggered whenever a projectile is created. Cannot be used in scripts, only inside class Eventhandlers in config.\n\n```cpp\ninit = \"params ['_projectile'];\";\n```\n\n```sqf\nparams [\"_projectile\"];\n```\n\n- projectile: Object - object the event handler is assigned to\n\n#### MineActivated (Arma 3 v2.14)\n\nLocal Argument\nLocal Effect\n\n```sqf\n_projectile addEventHandler [\"MineActivated\", {\n params [\"_projectile\", \"_isActive\"];\n}];\n```\n\n- projectile: Object\n- isActive: Boolean - new active state of the mine\n\n#### Penetrated\n\nThis event fires as many times as the projectile penetrates a surface.\n\n```sqf\n_projectile addEventHandler [\"Penetrated\", {\n params [\"_projectile\", \"_hitObject\", \"_surfaceType\", \"_entryPoint\", \"_exitPoint\", \"_exitVector\"];\n}];\n```\n\n- projectile: Object\n- hitObject: Object\n- surfaceType: String - see surfaceType\n- entryPoint: Array format PositionASL - the projectile's entry point\n- exitPoint: Array format PositionASL - the projectile's exit point\n- exitVector: Array format Vector3D - speed/angle exit vector (see vectorMagnitude to obtain the speed, in metre per second)\n\n#### SubmunitionCreated\n\nThis event fires as many times as submunitions are created.\n\n```sqf\n_projectile addEventHandler [\"SubmunitionCreated\", {\n params [\"_projectile\", \"_submunitionProjectile\", \"_position\", \"_velocity\"];\n}];\n```\n\n- projectile: Object\n- subMunitionProjectile: Object\n- position: Array format PositionASL\n- velocity: Array format Vector3D\n\n### Group Event Handlers (Arma 3 v2.10)\n\nCommands:\n- addEventHandler\n- removeEventHandler\n- removeAllEventHandlers\n\n#### CombatModeChanged\n\nTriggers when the group's **behaviour** changes (see behaviour, setBehaviour)\n\n```sqf\n_group addEventHandler [\"CombatModeChanged\", {\n params [\"_group\", \"_newMode\"];\n}];\n```\n\n- group: Group\n- newMode: String - see AI Behaviour (**not** Combat Modes!)\n\n#### CommandChanged\n\n```sqf\n_group addEventHandler [\"CommandChanged\", {\n params [\"_group\", \"_newCommand\"];\n}];\n```\n\n- group: Group\n- newCommand: String, can be one of:\n\n| | |\n|---|---|\n| \"NO CMD\" | NoCommand |\n| \"WAIT\" | Wait |\n| \"ATTACK\" | Attack |\n| \"Suppress\" | Suppress |\n| \"HIDE\" | Hide |\n| \"MOVE\" | Move |\n| \"HOOK CARGO\" | HookCargo |\n| \"UNHOOK CARGO\" | UnhookCargo |\n| \"VIV GETIN\" | ViVGetIn |\n| \"VIV GETOUT\" | ViVGetOut |\n| \"VIV UNLOAD\" | ViVUnload |\n| \"HEAL\" | Heal |\n| \"REPAIR\" | Repair |\n| \"REFUEL\" | Refuel |\n| \"REARM\" | Rearm |\n| \"SUPPORT\" | Support |\n| \"JOIN\" | Join |\n| \"GET IN\" | GetIn |\n| \"FIRE\" | Fire |\n| \"GET OUT\" | GetOut |\n| \"STOP\" | Stop |\n| \"EXPECT\" | Expect |\n| \"ACTION\" | Action |\n| \"SCRIPTED\" | Scripted |\n| \"DISMISS\" | Dismiss |\n| \"HEAL SOLDIER\" | HealSoldier |\n| \"PATCH SOLDIER\" | PatchSoldier |\n| \"FIRST AID\" | FirstAid |\n| \"HEAL SELF\" | HealSoldierSelf |\n| \"ATTACK AND FIRE\" | AttackAndFire |\n| \"CARRY SOLDIER\" | CarrySoldier |\n| \"DROP CARRIED\" | DropCarried |\n| \"TAKE BAG\" | TakeBag |\n| \"ASSEMBLE\" | Assemble |\n| \"DISASSEMBLE\" | DisAssemble |\n| \"DROP BAG\" | DropBag |\n| \"OPEN BAG\" | OpenBag |\n| \"IRLASER ON\" | IRLaserOn |\n| \"IRLASER OFF\" | IRLaserOff |\n| \"GUN LIGHT ON\" | GunLightOn |\n| \"GUN LIGHT OFF\" | GunLightOff |\n| \"FIRE AT POSITION\" | FireAtPosition |\n| \"REPAIR VEHICLE\" | RepairVehicle |\n| \"OPEN PARA\" | OpenParachute |\n| \"KEEP DEPTH LEADER\" | KeepDepthLeader |\n| \"KEEP DEPTH UND SURF\" | KeepDepthUnderSurface |\n| \"KEEP DEPTH ABV SURF\" | KeepDepthAboveSurface |\n| \"KEEP DEPTH BOTTOM\" | KeepDepthBottom |\n| \"PUT IN\" | PutIn |\n| \"UNLOAD FROM\" | UnloadFrom |\n| \"USE CONTAINER MAGAZINE\" | UseContainerMagazine |\n| \"ACTIVATE MINE\" | ActivateMine |\n| \"DISABLE MINE\" | DisableMine |\n\n#### Deleted (Group)\n\n```sqf\n_group addEventHandler [\"Deleted\", {\n params [\"_group\"];\n}];\n```\n\n- group: Group\n\n#### Empty\n\n```sqf\n_group addEventHandler [\"Empty\", {\n params [\"_group\"];\n}];\n```\n\n- group: Group\n\n#### EnableAttackChanged\n\n```sqf\n_group addEventHandler [\"EnableAttackChanged\", {\n params [\"_group\", \"_attackEnabled\"];\n}];\n```\n\n- group: Group\n- attackEnabled: Boolean\n\n#### EnemyDetected\n\n```sqf\n_group addEventHandler [\"EnemyDetected\", {\n params [\"_group\", \"_newTarget\"];\n}];\n```\n\n- group: Group\n- newTarget: Object\n\n#### Fleeing\n\n```sqf\n_group addEventHandler [\"Fleeing\", {\n params [\"_group\", \"_fleeingNow\"];\n}];\n```\n\n- group: Group\n- fleeingNow: Boolean\n\n#### FormationChanged\n\n```sqf\n_group addEventHandler [\"FormationChanged\", {\n params [\"_group\", \"_newFormation\"];\n}];\n```\n\n- group: Group\n- newFormation: String - see setFormation\n\n#### GroupIdChanged\n\n```sqf\n_group addEventHandler [\"GroupIdChanged\", {\n params [\"_group\", \"_newGroupId\"];\n}];\n```\n\n- group: Group\n- newGroupId: String\n\n#### KnowsAboutChanged\n\n```sqf\n_group addEventHandler [\"KnowsAboutChanged\", {\n params [\"_group\", \"_targetUnit\", \"_newKnowsAbout\", \"_oldKnowsAbout\"];\n}];\n```\n\n- group: Group\n- targetUnit: Object\n- newKnowsAbout: Number\n- oldKnowsAbout: Number\n\n#### LeaderChanged\n\n```sqf\n_group addEventHandler [\"LeaderChanged\", {\n params [\"_group\", \"_newLeader\"];\n}];\n```\n\n- group: Group\n- newLeader: Object\n\n#### Local (Group)\n\n```sqf\n_group addEventHandler [\"Local\", {\n params [\"_group\", \"_isLocal\"];\n}];\n```\n\n- group: Group\n\n#### SpeedModeChanged\n\n```sqf\n_group addEventHandler [\"SpeedModeChanged\", {\n params [\"_group\", \"_newSpeedMode\"];\n}];\n```\n\n- group: Group\n- newSpeedMode: String - see setSpeedMode\n\n#### UnitJoined\n\n```sqf\n_group addEventHandler [\"UnitJoined\", {\n params [\"_group\", \"_newUnit\"];\n}];\n```\n\n- group: Group\n- newUnit: Object\n\n#### UnitKilled (Arma 3 v2.18)\n\nLocal Argument\n\nTriggered when a unit in the group is killed.\n\n```sqf\n_group addEventHandler [\"UnitKilled\", {\n params [\"_group\", \"_unit\", \"_killer\", \"_instigator\", \"_useEffects\"];\n}];\n```\n\n- group: Group - the group the event handler is assigned to\n- unit: Object - the unit that was killed\n- killer: Object - the object that killed the unit. Contains the unit itself in case of collisions.\n- instigator: Object - the person who pulled the trigger\n- useEffects: Boolean - same as *useEffects* in setDamage alt syntax\n\n#### UnitLeft\n\n```sqf\n_group addEventHandler [\"UnitLeft\", {\n params [\"_group\", \"_oldUnit\"];\n}];\n```\n\n- group: Group\n- oldUnit: Object\n\n#### VehicleAdded\n\n```sqf\n_group addEventHandler [\"VehicleAdded\", {\n params [\"_group\", \"_newVehicle\"];\n}];\n```\n\n- group: Group\n- newVehicle: Object\n\n#### VehicleRemoved\n\n```sqf\n_group addEventHandler [\"VehicleRemoved\", {\n params [\"_group\", \"_oldVehicle\"];\n}];\n```\n\n- group: Group\n- oldVehicle: Object\n\n#### WaypointComplete\n\n```sqf\n_group addEventHandler [\"WaypointComplete\", {\n params [\"_group\", \"_waypointIndex\"];\n}];\n```\n\n- group: Group\n- waypointIndex: Number\n\n### Game UI Event Handlers\n\nIn Game UI Event Handlers trigger when user scrolls or activates in game action menu.\n\nThe following mission EHs are available in Arma 3:\n- PrevAction - action menu scroll up event\n- Action - action menu action event\n- NextAction - action menu scroll down event\n\n> [!IMPORTANT]\n> Only one event of each kind can exist, adding another will overwrite the existing one.\n\nCommands:\n- inGameUISetEventHandler\n\n> [!NOTE]\n> See Arma 3: Event Handlers/inGameUISetEventHandler.\n\n### Control/Display UI Event Handlers\n\nCommands:\n- ctrlAddEventHandler\n- ctrlRemoveEventHandler\n- ctrlRemoveAllEventHandlers\n- displayAddEventHandler\n- displayRemoveEventHandler\n- displayRemoveAllEventHandlers\n\n> [!NOTE]\n> See User Interface Event Handlers.\n\n### Music Event Handlers\n\nMusic event handler, always executed on the computer where it was added.\n\n> [!NOTE]\n> Does not apply to interface-less machines (dedicated server, headless client).\n\nCommands:\n- setMusicEventHandler\n- addMusicEventHandler\n- removeMusicEventHandler\n- removeAllMusicEventHandlers\n\n#### MusicStart (Arma 3 v0.50)\n\nTriggers when CfgMusic sound starts playing, after being executed with playMusic command.\n\n```sqf\naddMusicEventHandler [\"MusicStart\", {\n params [\"_musicClassname\", \"_eventHandlerID\", \"_currentPosition\", \"_totalLength\"];\n}];\n```\n\n- musicClassName: String - CfgMusic class name of the music that started\n- eventHandlerID: Number - EH id returned by addMusicEventHandler\n- Arma 3 v2.18 currentPosition: Number - current playback position in 0...1 range (see also: getMusicPlayedTime)\n- Arma 3 v2.18 totalLength: Number - track total length in seconds\n\n#### MusicStop (Arma 3 v0.50)\n\nTriggers when CfgMusic sound finished playing, after being executed with playMusic command.\n\nArma 3 v2.14 `playMusic \"\"` triggers this event if a music is currently playing.\n\n```sqf\naddMusicEventHandler [\"MusicStop\", {\n params [\"_musicClassname\", \"_eventHandlerID\", \"_currentPosition\", \"_totalLength\"];\n}];\n```\n\n- musicClassName: String - CfgMusic class name of the music that stopped\n- eventHandlerID: Number - EH id returned by addMusicEventHandler\n- Arma 3 v2.18 currentPosition: Number - current playback position in 0...1 range (see also: getMusicPlayedTime)\n- Arma 3 v2.18 totalLength: Number - track total length in seconds\n\n### Eden Editor\n\nCommands:\n- add3DENEventHandler\n- remove3DENEventHandler\n- removeAll3DENEventHandlers\n\n> [!NOTE]\n> See also:\n> - Arma 3: Event Handlers: Eden Editor\n> - its sub-category Object Event Handlers\n> - Eden Editor\n\n### Public Variable Broadcast Event\n\nCommands:\n- addPublicVariableEventHandler\n\nTriggers when missionNamespace variable EH is associated with is sent over network via publicVariable, publicVariableServer or publicVariableClient commands.\n\n> [!NOTE]\n> Unlike with other types of EHs, there is no way of removing added public variable event handler\n\n### Weapon Muzzle Config Events\n\nThere are six event handlers that can be set on weapon in config. Their parameters are the same as their entity EH equivalents.\n- \"Fired\" - when muzzle fired - see Fired\n- \"Reload\" - before muzzle is reloaded - see MagazineReloading\n- \"Reloaded\" - after muzzle is reloaded - see Reloaded\n- \"MagazineUnloaded\" - when the magazine is removed - see MagazineUnloaded\n- \"WeaponChanged\" - when the weapon is switched to or from - see WeaponChanged\n- \"SlotItemChanged\" - when one of the weapon's attachments is changed - see SlotItemChanged\n\n```cpp\nclass CfgWeapons\n{\n class RifleCore;\n class TAG_Rifle : RifleCore\n {\n class EventHandlers\n {\n fired = \"systemChat format ['fired weapon EH output: %1 [time: %2]', _this, time]\";\n reload = \"systemChat format ['reload weapon EH output: %1 [time: %2]', _this, time]\";\n reloaded = \"systemChat format ['reloaded weapon EH output: %1 [time: %2]', _this, time]\";\n magazineunloaded = \"systemChat format ['magazineunloaded weapon EH output: %1 [time: %2]', _this, time]\";\n slotitemchanged = \"systemChat format ['slotitemchanged weapon EH output: %1 [time: %2]', _this, time]\";\n weaponchanged = \"systemChat format ['weaponchanged weapon EH output: %1 [time: %2]', _this, time]\";\n };\n };\n};\n```\n\n### Ammo Config Events\n\nThere are three event handlers that can be set on ammo in config:\n- \"init\" - when the ammo is created, by any mean (fired, created, etc). Params: [shot]\n- \"fired\" - when the ammo is fired (legacy). Params: same as in entity EH \"Fired\".\n- \"ammoHit\" - when the ammo hits anything (can trigger multiple times). Params: [shot, shooter, hitobj, pos, velocity, hitComponents, [hit, indirecthit, indirecthitrange, explosive, name], normal, explode, instigator (since Arma 3 v2.18)]\n\n```cpp\nclass CfgAmmo\n{\n class BulletCore;\n class TAG_Bullet : BulletCore\n {\n class EventHandlers\n {\n init = \"systemChat format ['init ammo EH output: %1 [time: %2]', _this, time]\";\n fired = \"systemChat format ['fired ammo EH output: %1 [time: %2]', _this, time]\";\n ammoHit = \"systemChat format ['ammoHit EH output: %1 [time: %2]', _this, time]\";\n };\n };\n};\n```\n\n### BI Scripted Events\n\nCommands:\n- BIS_fnc_addScriptedEventHandler\n- BIS_fnc_removeScriptedEventHandler\n- BIS_fnc_removeAllScriptedEventHandlers\n- BIS_fnc_callScriptedEventHandler\n\n> [!NOTE]\n> See also Arma 3: Scripted Event Handlers.\n\nJump to the top of the page","sections":[{"heading":null,"level":1,"markdown":"An Event Handler (abbreviated to EH) allows you to automatically monitor and then execute custom code upon particular events being triggered.\n\nSee also Event Scripts for special event triggered scripts."},{"heading":"Basic Event Handlers","level":3,"markdown":"The object-based Event Handler is always executed on the computer where it was added.\n\nCommands:\n- addEventHandler\n- removeEventHandler\n- removeAllEventHandlers"},{"heading":"AmmoExplodedNear (Arma 3 v2.22)","level":4,"markdown":"Triggers when ammo explodes in some damage range of the object. This EH triggers where the ammo is 'real', similar to HitPart.\n\n```sqf\nthis addEventHandler [\"AmmoExplodedNear\", {\n params [\"_object\", \"_shot\", \"_position\", \"_velocity\", \"_ammo\", \"_explosive\", \"_indirectHit\", \"_invArmor\", \"_damage\"];\n}];\n```\n\n- object: Object - object the event handler is assigned to\n- shot: Object - shot that has exploded\n- position: Array - world position of the shot\n- velocity: Array - world velocity of the shot\n- ammmo: String - config ammo class name\n- explosive: Number - config value for 'explosive'\n- indirectHit: Number - config value for 'indirectHit'\n- invArmor: Number - calculated inverse armor from config value\n- damage: Number - a rough estimate of the potential damage to the center of the object based on config values and the distance"},{"heading":"AnimChanged","level":4,"markdown":"Global Argument\n\nTriggered every time a new animation is started. This EH is only triggered for the 1st animation state in a sequence.\n\n```sqf\nthis addEventHandler [\"AnimChanged\", {\n params [\"_unit\", \"_anim\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- anim: String - name of the anim that is started"},{"heading":"AnimDone","level":4,"markdown":"Global Argument\n\nTriggered every time an animation is finished. Triggered for all animation states in a sequence.\n\n```sqf\nthis addEventHandler [\"AnimDone\", {\n params [\"_unit\", \"_anim\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- anim: String - name of the anim that has been finished"},{"heading":"AnimStateChanged","level":4,"markdown":"Global Argument\n\nTriggered every time an animation state changes. Triggered for all animation states in a sequence.\n\n```sqf\nthis addEventHandler [\"AnimStateChanged\", {\n params [\"_unit\", \"_anim\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- anim: String - name of the anim that has been started"},{"heading":"Assembled (Arma 3 v2.18)","level":4,"markdown":"Local Argument\n\nTriggers when weapon that is moved out of the world is assembled again. EH should be attached to the entity.\n\n```sqf\nthis addEventHandler [\"Assembled\", {\n params [\"_entity\", \"_unit\", \"_primaryBag\", \"_secondaryBag\"];\n}];\n```\n\n- entity: Object - weapon this event is assigned to\n- unit: Object - person who assembled the weapon\n- primaryBag: Object - first backpack object which was entity disassembled into (just before it is deleted)\n- secondaryBag: Object - second backpack object which was entity disassembled into (just before it is deleted)"},{"heading":"Attached (Arma 3 v2.18)","level":4,"markdown":"Triggered after an object has been attached to another object (see attachTo).\n\n```sqf\nthis addEventHandler [\"Attached\", {\n params [\"_attachedObj\", \"_parentObj\", \"_isReattach\", \"_offset\", \"_memoryPointIndex\", \"_followBoneRotation\"];\n}];\n```\n\n- attachedObj: Object\n- parentObj: Object\n- isReattach: Boolean - true if `attachedObj` was already attached to `parentObj`, e.g. if only the offset was changed\n- offset: Array format PositionRelative\n- memoryPointIndex: Number\n- followBoneRotation: Boolean"},{"heading":"CargoLoaded (Arma 3 v2.06)","level":4,"markdown":"Global Argument\n\nTriggered when a vehicle is loaded into another vehicle (ViV).\n\nIt can be added to either the transport vehicle, or the cargo vehicle, and will fire for both cases.\n\n```sqf\nthis addEventHandler [\"CargoLoaded\", {\n params [\"_parentVehicle\", \"_cargoVehicle\"];\n}];\n```\n\n- parentVehicle: Object - the transport (parent) vehicle\n- cargoVehicle: Object - the cargo (child) vehicle"},{"heading":"CargoUnloaded (Arma 3 v2.06)","level":4,"markdown":"Global Argument\n\nTriggered when a vehicle is unloaded from another vehicle (ViV).\n\nIt can be added to either the transport vehicle, or the cargo vehicle, and will fire for both cases.\n\n```sqf\nthis addEventHandler [\"CargoUnloaded\", {\n params [\"_parentVehicle\", \"_cargoVehicle\"];\n}];\n```\n\n- parentVehicle: Object - the transport (parent) vehicle\n- cargoVehicle: Object - the cargo (child) vehicle"},{"heading":"ContainerClosed (Arma 3 v1.32)","level":4,"markdown":"Global Argument\n\nTriggers when player finished accessing cargo container.\nThis event handler is similar to InventoryClosed EH, but needs to be assigned to the container rather than the player.\n\n**Note:** will trigger only for the unit opening container.\n\n```sqf\nthis addEventHandler [\"ContainerClosed\", {\n params [\"_container\", \"_unit\"];\n}];\n```\n\n- container: Object - cargo container.\n- unit: Object - unit who accessed the container"},{"heading":"ContainerOpened (Arma 3 v1.32)","level":4,"markdown":"Global Argument\n\nTriggers when cargo container is accessed by player.\nThis event handler is similar to InventoryOpened EH, but needs to be assigned to the container rather than the player and cannot be overridden.\n\n**Note:** will trigger only for the unit opening container.\n\n```sqf\nthis addEventHandler [\"ContainerOpened\", {\n params [\"_container\", \"_unit\"];\n}];\n```\n\n- container: Object - cargo container\n- unit: Object - unit who accessed the container"},{"heading":"ControlsShifted (Arma 3 v1.00)","level":4,"markdown":"Global ArgumentLocal Effect\n\nTriggers 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. For example, if helicopter is local to the server and co-pilot takes controls, the helicopter changes locality to co-pilot PC.\nThis means that if \"ControlsShifted\" EH was added on both server and client, \"Take Controls\" action will trigger EH on both, client and server PC, but subsequent co-pilot \"Release Controls\" action will trigger only on co-pilot's PC, because vehicle will be local to co-pilot at this point. There is also a slightly better mission version of ControlsShifted event handler.\n\n```sqf\nthis addEventHandler [\"ControlsShifted\", {\n params [\"_vehicle\", \"_activeCoPilot\", \"_oldController\"];\n}];\n```\n\n- vehicle: Object - vehicle which controls were shifted\n- activeCoPilot: Object - co-pilot unit which controls vehicle after this event. objNull if co-pilot is not controlling the vehicle\n- oldController: Object - unit who controlled vehicle before this event"},{"heading":"Dammaged","level":4,"markdown":"Global Argument\n\nTriggered when the unit is damaged. In ArmA works with all vehicles not only men like in OFP.\n\n**Notes:**\n- The typo is \"intentional\": it is Da**mm**aged with two \"m\".\n- If simultaneous damage occured (e.g. via grenade) EH might be triggered several times.\n- The Dammaged EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased.\n\n```sqf\nthis addEventHandler [\"Dammaged\", {\n params [\"_unit\", \"_hitSelection\", \"_damage\", \"_hitPartIndex\", \"_hitPoint\", \"_shooter\", \"_projectile\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- hitSelection: String - name of the selection where the unit was damaged\n- damage: Number - resulting level of damage\n- Arma 3 v1.68 hitPartIndex: Number - hit index of the hit selection\n- Arma 3 v1.68 hitPoint: String - hit point Cfg name\n- Arma 3 v1.70 shooter: Object - shooter reference (to get instigator use getShotParents on projectile)\n- Arma 3 v1.70 projectile: Object - the projectile that caused damage"},{"heading":"Deleted (Entity) (Arma 3 v1.68)","level":4,"markdown":"Global Argument\n\nTriggered just before the assigned entity is deleted.\n\n```sqf\nthis addEventHandler [\"Deleted\", {\n params [\"_entity\"];\n}];\n```\n\n- entity: Object - object the event handler is assigned to"},{"heading":"Detached (Arma 3 v2.18)","level":4,"markdown":"Triggered after an object has been detached from its parent object (see detach). Does not fire if the parent object was deleted.\n\n```sqf\nthis addEventHandler [\"Detached\", {\n params [\"_attachedObj\", \"_parentObj\"];\n}];\n```\n\n- attachedObj: Object\n- parentObj: Object"},{"heading":"Disassembled (Arma 3 v2.00)","level":4,"markdown":"Local Argument\n\nTriggers when entity such as weapon/backpack gets disassembled. EH should be attached to the entity.\n\n```sqf\nthis addEventHandler [\"Disassembled\", {\n params [\"_entity\", \"_primaryBag\", \"_secondaryBag\", \"_unit\"];\n}];\n```\n\n- entity: Object - weapon this event is assigned to (just before is is moved out of the world)\n- primaryBag: Object - first backpack object which was entity disassembled into\n- secondaryBag: Object - second backpack object which was entity disassembled into\n- Arma 3 v2.18 unit: Object - person who disassembled the weapon"},{"heading":"Engine","level":4,"markdown":"Global Argument\n\nTriggered when the engine of the unit is turned on/off.\n\n> [!NOTE]\n> Although the event is global, on clients (non-server) and applied to remote vehicles, it will fire only if the vehicle is closer than about 6 km from the camera.\n> Should the vehicle be far away, it will fire as soon as the camera and vehicle are close enough together, alongside the isEngineOn flag change.\n\n```sqf\nthis addEventHandler [\"Engine\", {\n params [\"_vehicle\", \"_engineState\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- engineState: Boolean - true when the engine is turned on, false when turned off"},{"heading":"EpeContact (Arma 3 v1.00)","level":4,"markdown":"Global Argument\n\nTriggered when object collision (PhysX) is in progress.\n\n```sqf\nthis addEventHandler [\"EpeContact\", {\n params [\"_object1\", \"_object2\", \"_selection1\", \"_selection2\", \"_force\", \"_reactVect\", \"_worldPos\"];\n}];\n```\n\n- object1: Object - object with attached handler\n- object2: Object - object which is colliding with object1\n- selection1: String - selection of object1 which is colliding - not in use at this moment, empty string is always returned\n- selection2: String - selection of object2 which is colliding - not in use at this moment, empty string is always returned\n- force: Number - force of collision\n- Arma 3 v2.12 reactVect: Array - impact reaction force vector\n- Arma 3 v2.12 worldPos: PositionWorld - point of impact in world coordinates"},{"heading":"EpeContactEnd (Arma 3 v1.00)","level":4,"markdown":"Global Argument\n\nTriggered when object collision (PhysX) ends.\n\n```sqf\nthis addEventHandler [\"EpeContactEnd\", {\n params [\"_object1\", \"_object2\", \"_selection1\", \"_selection2\", \"_force\"];\n}];\n```\n\n- object1: Object - object with attached handler\n- object2: Object - object which is colliding with object1\n- selection1: String - selection of object1 which is colliding - not in use at this moment, empty string is always returned\n- selection2: String - selection of object2 which is colliding - not in use at this moment, empty string is always returned\n- force: Number - force of collision"},{"heading":"EpeContactStart (Arma 3 v1.00)","level":4,"markdown":"Global Argument\n\nTriggered when object collision (PhysX) starts.\n\n```sqf\nthis addEventHandler [\"EpeContactStart\", {\n params [\"_object1\", \"_object2\", \"_selection1\", \"_selection2\", \"_force\", \"_reactForce\", \"_worldPos\"];\n}];\n```\n\n- object1: Object - object with attached handler\n- object2: Object - object which is colliding with object1\n- select1: String - selection of object1 which is colliding - not in use at this moment, empty string is always returned\n- select2: String - selection of object2 which is colliding - not in use at this moment, empty string is always returned\n- force: Number - force of collision\n- Arma 3 v2.12 reactForce: Array - impact reaction force vector\n- Arma 3 v2.12 worldPos: PositionWorld - point of impact in world coordinates"},{"heading":"Explosion (Arma 3 v0.76)","level":4,"markdown":"Global Argument\n\nTriggered when a vehicle or unit is damaged by a nearby explosion.\nIt can be assigned to a remote unit or vehicle but will only fire on the PC where EH is added and explosion is local, i.e. it really needs to be added on every PC and JIP and will fire only where the explosion is originated.\n\n```sqf\nthis addEventHandler [\"Explosion\", {\n params [\"_vehicle\", \"_damage\", \"_explosionSource\"];\n}];\n```\n\n- vehicle: Object - object the event handler is assigned to\n- damage: Number - damage inflicted to the object\n- Arma 3 v2.10 explosionSource: Object - the exploding object (NOT the shooter) - may be objNull in some cases\n\n> [!NOTE]\n> This event will fire even for tiniest of explosion damage (which appears as 0 damage argument), while #HitPart (Entity) could ignore such damage and not fire.\n> Example of such event would be a tank firing AP round and hitting ground a meter away from the vehicle, it does not produce an explosion yet its indirectHit could still cause tiny amount of damage to weak hit points (car wheels, headlights, etc.).\n> In such case you might not get any #HitPart (Entity) event fires, get some #HandleDamage events if target is local, and get this Explosion event."},{"heading":"Fired","level":4,"markdown":"Global Argument\n\nTriggered when the unit fires a weapon.\n\nThis EH will not trigger if a unit fires out of a vehicle. For those cases an EH has to be attached to that particular vehicle.\nWhen \"Manual Fire\" is used, the *gunner* is objNull if gunner is not present or the *gunner* is not the one who fires.\nTo check if \"Manual Fire\" is on, use isManualFire. The actual shot instigator could be retrieved with getShotParents command.\n\n> [!WARNING]\n> **Special multiplayer behaviour:** When added to a remote unit or vehicle, this EH will only fire if said entity is within range of the camera.\n> That range is determined by the fired ammo's highest visibleFire and audibleFire config value.\n> In case of units, muzzle attachment coefficients are applied too.\n\n```sqf\nthis addEventHandler [\"Fired\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_mode\", \"_ammo\", \"_magazine\", \"_projectile\", \"_gunner\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- weapon: String - fired weapon\n- muzzle: String - muzzle that was used\n- mode: String - current mode of the fired weapon\n- ammo: String - ammo used\n- magazine: String - magazine name which was used\n- projectile: Object - object of the projectile that was shot out\n- Arma 3 v1.66 gunner: Object - gunner whose weapons are firing."},{"heading":"FiredMan (Arma 3 v1.66)","level":4,"markdown":"Global Argument\n\nTriggered when the unit fires a weapon. This EH must be attached to a soldier and unlike with \"Fired\" EH, it will fire regardless of whether the soldier is on foot or firing vehicle weapon.\nFor remoteControled unit use \"Fired\" EH instead.\n\n> [!WARNING]\n> **Special multiplayer behaviour:** When added to a remote unit or vehicle, this EH will only fire if said entity is within range of the camera.\n> That range is determined by the fired ammo's highest visibleFire and audibleFire config value.\n> In case of units, muzzle attachment coefficients are applied too.\n\n```sqf\nthis addEventHandler [\"FiredMan\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_mode\", \"_ammo\", \"_magazine\", \"_projectile\", \"_vehicle\"];\n}];\n```\n\n- unit: Object - unit the event handler is assigned to (the instigator)\n- weapon: String - fired weapon\n- muzzle: String - muzzle that was used\n- mode: String - current mode of the fired weapon\n- ammo: String - ammo used\n- magazine: String - magazine name which was used\n- projectile: Object - object of the projectile that was shot out\n- vehicle: Object - vehicle, if weapon is vehicle weapon, otherwise objNull"},{"heading":"FiredNear","level":4,"markdown":"Global Argument\n\nTriggered when a weapon is fired somewhere *near* the unit or vehicle. It is also triggered if the unit itself is firing.\n\nWhen \"Manual Fire\" is used, the *gunner* is objNull if gunner is not present or the *gunner* is not the one who fires.\nTo check if \"Manual Fire\" is on, use isManualFire. The actual shot instigator can be retrieved with getShotParents command.\n\nArma 3 v1.30 Works with thrown weapons (using the \"Throw\" weapon) like grenades.\n\n```sqf\nthis addEventHandler [\"FiredNear\", {\n params [\"_unit\", \"_firer\", \"_distance\", \"_weapon\", \"_muzzle\", \"_mode\", \"_ammo\", \"_gunner\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- firer: Object - object which fires a weapon near the unit\n- distance: Number - distance in meters between the *unit* and *firer* (max. distance ~69m)\n- weapon: String - fired weapon\n- muzzle: String - muzzle that was used\n- mode: String - current mode of the fired weapon\n- ammo: String - ammo used\n- Arma 3 v1.66 gunner: Object - gunner, whose weapons are fired"},{"heading":"Fuel","level":4,"markdown":"Global Argument\n\nTriggered when the vehicle's fuel status changes between non-empty and empty or between empty and non-empty.\n\n```sqf\nthis addEventHandler [\"Fuel\", {\n params [\"_vehicle\", \"_hasFuel\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- hasFuel: Boolean - false when has no fuel, true when has some fuel"},{"heading":"Gear","level":4,"markdown":"Global Argument\n\nTriggered when the unit lowers/retracts the landing gear, whether it is a helicopter or a plane.\nAlso triggered for helicopters in landing mode, regardless if they have retractable gear or not.\n\n> [!NOTE]\n> Not to be confused with *InventoryOpened* and *InventoryClosed* events, *Gear* fires when the landing gear state on an aircraft has changed.\n\n```sqf\nthis addEventHandler [\"Gear\", {\n params [\"_vehicle\", \"_gearState\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- gearState: Boolean - true when the gear is lowered, false when retracted"},{"heading":"GestureChanged (Arma 3 v2.06)","level":4,"markdown":"Global Argument\n\nTriggered every time a new gesture is played.\n\n```sqf\nthis addEventHandler [\"GestureChanged\", {\n params [\"_unit\", \"_gesture\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- gesture: String - name of the gesture that has started playing"},{"heading":"GestureDone (Arma 3 v2.06)","level":4,"markdown":"Global Argument\n\nTriggered every time a gesture is finished.\n\n```sqf\nthis addEventHandler [\"GestureDone\", {\n params [\"_unit\", \"_gesture\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- gesture: String - name of the gesture that has been finished"},{"heading":"GetIn","level":4,"markdown":"Global Argument\n\nTriggers when a unit enters the vehicle to which this EH has been added. This EH is triggered by moveInXXXX commands and \"GetInXXXX\" actions, but not upon a seat change within the same vehicle.\n\nIn vehicles with multi-turret setup, entering any turret will show \"gunner\" for position.\n\n```sqf\nthis addEventHandler [\"GetIn\", {\n params [\"_vehicle\", \"_role\", \"_unit\", \"_turret\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- role: String - can be either \"driver\", \"gunner\", \"commander\" or \"cargo\"\n- unit: Object - unit that entered the vehicle\n- Arma 3 v1.36 turret: Array - turret path"},{"heading":"GetInMan (Arma 3 v1.58)","level":4,"markdown":"Global Argument\n\nTriggers when a unit enters a vehicle. Similar to \"GetIn\" but must be assigned to a unit and not vehicle.\nPersistent on respawn if assigned where unit was local. This EH is triggered by moveInXXXX commands and \"GetInXXXX\" actions.\n\n```sqf\nthis addEventHandler [\"GetInMan\", {\n params [\"_unit\", \"_role\", \"_vehicle\", \"_turret\"];\n}];\n```\n\n- unit: Object - unit the event handler is assigned to\n- role: String - can be either \"driver\", \"gunner\", \"commander\" or \"cargo\"\n- vehicle: Object - vehicle the unit entered\n- turret: Array - turret path"},{"heading":"GetOut","level":4,"markdown":"Global Argument\n\nTriggers when a unit gets out from the vehicle to which this EH has been added.\nThis EH is triggered by moveOut, \"GetOut\" & \"Eject\" actions, if an alive crew member disconnects or is deleted, but not upon a seat change within the same vehicle.\n\n```sqf\nthis addEventHandler [\"GetOut\", {\n params [\"_vehicle\", \"_role\", \"_unit\", \"_turret\", \"_isEject\"];\n}];\n```\n\n- vehicle: Object - vehicle the event handler is assigned to\n- role: String - can be either \"driver\", \"gunner\", \"commander\" or \"cargo\"\n- unit: Object - unit that left the vehicle\n- Arma 3 v1.36 turret: Array - turret path\n- Arma 3 v2.14 isEject: Boolean - true if unit used 'Eject' action"},{"heading":"GetOutMan (Arma 3 v1.58)","level":4,"markdown":"Global Argument\n\nTriggers when a unit exits a vehicle. Similar to \"GetOut\" but must be assigned to a unit and not vehicle.\nPersistent on respawn if assigned where unit was local. This EH is triggered by moveOut and \"GetOut\" & \"Eject\" actions.\n\n```sqf\nthis addEventHandler [\"GetOutMan\", {\n params [\"_unit\", \"_role\", \"_vehicle\", \"_turret\", \"_isEject\"];\n}];\n```\n\n- unit: Object - unit the event handler is assigned to\n- role: String - can be either \"driver\", \"gunner\", \"commander\" or \"cargo\"\n- vehicle: Object - vehicle that the unit left\n- turret: Array - turret path\n- Arma 3 v2.14 isEject: Boolean - true if unit used 'Eject' action"},{"heading":"HandleDamage","level":4,"markdown":"Global Argument\n\nTriggers when the unit is damaged and fires for each damaged selection separately\nWorks with all vehicles.\nThis EH can accept a remote unit as argument however it will only fire when the unit is local to the PC this event handler was added on.\nFor example, you can add this event handler to one particular vehicle on every PC.\nWhen this vehicle gets hit, only EH on PC where the vehicle is currently local will fire.\n\nIf the provided code returns a numeric value, this value will overwrite the default damage of given selection after processing.\nIf no value is returned, the default damage processing will be done - this allows for safe stacking of this event handler.\nOnly the return value of the last added \"HandleDamage\" EH is considered.\n\n> [!IMPORTANT]\n> A return value of 0 will make the unit **invulnerable** if damage is not scripted in other ways (i.e using setDamage and/or setHit for additional damage handling).\n> The return value is the hit zone's **absolute damage value**, **not** the damage to be *added* to it.\n\n**Notes:**\n- Multiple \"HandleDamage\" EHs can be added to the same unit. If multiple EHs return damage value for custom damage handling, only last returned value will be considered by the engine.\nEHs that do not return value can be safely added after EHs that do return value.\n- You can save the last event as timestamp (diag_tickTime) onto the unit, as well as the current health of the unit/its selections, with setVariable and query it on each \"HandleDamage\" event with getVariable to define a system how to handle the \"HandleDamage\" event.\n- \"HandleDamage\" will continue to trigger even if the unit is already dead.\n- \"HandleDamage\" is persistent. If you add it to the player object, it will continue to exist after player respawned.\n- \"HandleDamage\" can trigger \"twice\" per damage event. Once for direct damage, once for indirect damage (explosive damage). This can happen even in the same frame, but is unlikely.\n- Use setMissionOptions to filter out no damage calls or fake head hit.\n\nAdditional [Celery's explanation (Updated by ShadowRanger for Arma 3)](https://forums.bistudio.com/forums/topic/205515-handledamage-event-handler-explained/).\n\n```sqf\nthis addEventHandler [\"HandleDamage\", {\n params [\"_unit\", \"_selection\", \"_damage\", \"_source\", \"_projectile\", \"_hitPartIndex\", \"_instigator\", \"_hitPoint\", \"_directHit\", \"_context\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- selection: String - name of the selection where the unit was damaged.\n - \"\" for overall structural damage\n - \"?\" for unknown selections\n- damage: Number - resulting level of damage for the selection\n- source: Object - the source unit that caused the damage\n- projectile: String - classname of the projectile that caused inflicted the damage. (\"\" for unknown, such as fall damage)\n- Arma 3 v1.50 hitPartIndex: Number - hit part index of the hit point, -1 otherwise\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n- Arma 3 v1.68 hitPoint: String - hit point Cfg name\n- Arma 3 v2.12 directHit: Boolean - true for direct projectile damage, false for explosion splash damage and all other kinds of damage like fall damage, fire damage, collision damage, etc.\n- Arma 3 v2.16 context: Number - some additional context for the event:\n\n0 : TotalDamage - total damage adjusted before iteration through hitpoints\n\n1 : HitPoint - some hit point processed during iteration\n\n2 : LastHitPoint - the last hitpoint from iteration is processed\n\n3 : FakeHeadHit - head hit that is added/adjusted\n\n4 : TotalDamageBeforeBleeding - total damage is adjusted before calculating bleeding\n\n> [!NOTE]\n> Between an unknown version (confirmed in Arma 3 v1.70) until v1.78 HandleDamage event triggered for every selection of a vehicle, no matter if the section was damaged or not."},{"heading":"HandleHeal","level":4,"markdown":"Global Argument\n\nTriggered when unit starts healing process (player using heal action on self or other unit, scripted action or AI heals after being ordered or on its own).\nThis event handler must be added to the 'injured' (could be added to Init field in editor) and in multiplayer will trigger only on PC where 'healer' is local. If code returns anything but true, engine side healing follows, otherwise healing is aborted.\n\n> [!IMPORTANT]\n> When AI unit is ordered (or acts at own accord) to heal at a medical vehicle and the event handler returns true, the healing is canceled but AI will try again and again and again. The event handler in this case will fire every second until AI unit is healed by other means.\n\n**NOTE**: This Event Handler was broken before Arma 3 v2.18.\n\n```sqf\nthis addEventHandler [\"HandleHeal\", {\n _this spawn {\n params [\"_injured\", \"_healer\", \"_isMedic\", \"_atVehicle\", \"_action\"];\n private _damage = damage _injured;\n if (_injured == _healer) then\n {\n waitUntil { damage _injured != _damage };\n if (damage _injured < _damage) then\n {\n _injured setDamage 0;\n };\n };\n };\n}];\n```\n\n```sqf\nthis addEventHandler [\"HandleHeal\", {\n params [\"_injured\", \"_healer\", \"_isMedic\", \"_atVehicle\", \"_action\"];\n}];\n```\n\n- injured: Object - unit EH is attached to\n- healer: Object - unit that does the healing (could be the same unit as 'injured')\n- isMedic: Boolean - true when healer is 'Medic'\n- Arma 3 v2.18 atVehicle: Object - when healing at medical vehicle, this is the vehicle\n- Arma 3 v2.18 action: String - the action that triggered the event handler, for example \"SoldierHealSelf\""},{"heading":"HandleIdentity","level":4,"markdown":"Global Argument\n\nTriggered whenever an entity is created. Can be used in scripts if EH is added immediately after unit is created in unscheduled environment.\nDoesn't trigger for editor placed units. Does not work in Multiplayer. If EH scope returns true, the default engine identity application is overridden.\n\n```sqf\nbob = group player createUnit [typeOf player, position player, [], 0, \"NONE\"];\nbob addEventHandler [\"HandleIdentity\", {\n params [\"_unit\"];\n hint str _unit;\n}];\n```\n\n- unit: Object - object the event handler is assigned to"},{"heading":"HandleRating (Arma 3 v1.32)","level":4,"markdown":"Local Argument\n\nTriggered when engine adds rating to overall rating of the unit, usually after a kill or a friendly kill.\nIf EH code returns Number, this will override default engine behaviour and the resulting value added will be the one returned by EH code.\n\n```sqf\nthis addEventHandler [\"HandleRating\", {\n params [\"_unit\", \"_rating\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- rating: Number - rating to be added"},{"heading":"HandleScore (Arma 3 v1.32)","level":4,"markdown":"Global ArgumentServer Execution\n\nTriggered when engine adds score to overall score of the unit, usually after a kill.\nIf the EH code returns Nothing or true, the default engine scoreboard update (score, vehicle kills, infantry kills, etc) is applied, if it returns false, the engine update is cancelled. To add or modify score, use addScore and addScoreSide commands.\nFor remote units like players, the event does not persist after respawn, and must be re-added to the new unit.\n\n**Note:** MP only.\n\n```sqf\nthis addEventHandler [\"HandleScore\", {\n params [\"_unit\", \"_object\", \"_score\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- object: Object - object for which score was awarded\n- score: Number - score to be added"},{"heading":"Hit","level":4,"markdown":"Local Argument\n\nTriggered when the unit is hit/damaged.\n\nIs *not* always triggered when unit is killed by a hit.\n\nMost of the time only the killed event handler is triggered when a unit dies from a hit.\n\nThe hit EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased.\n\nDoes not fire when a unit is set to allowDamage false.\n\n```sqf\nthis addEventHandler [\"Hit\", {\n params [\"_unit\", \"_source\", \"_damage\", \"_instigator\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- source: Object - object that caused the damage – contains *unit* in case of collisions\n- damage: Number - level of damage caused by the hit\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger"},{"heading":"HitPart (Entity)","level":4,"markdown":"Global Argument\n\nTriggered when the object it was added to gets damaged.\nIt returns the position and component that was hit on the object within a nested array, this is because the model may have more than one selection name for the hit component (i.e. a single piece of geometry can be simultaneously part of multiple, overlapping named selections).\n\nWhile you can add \"HitPart\" handler to a remote unit, the respective addEventHandler command must be executed on the shooter's PC and will only fire on shooter's PC as well.\nThe event will not fire if the shooter is not local, even if the target itself is local.\nAdditionally, if the unit gets damaged by any means other than ammunition or explosions, such as fall damage and burning, \"HitPart\" will not fire.\nBecause of this, this event handler is most suitable for when the shooter needs feedback on his shooting, such as target practicing or hitmarker creation.\n\nThis EH returns an array of arrays. Each sub-array contains data for the part that was hit as usually multiple parts are hit at the same time (see HitPart Sample). The structure of the sub-arrays is listed below.\n\n```sqf\nthis addEventHandler [\"HitPart\", {\n {\n _x params [\n \"_target\", \"_shooter\", \"_projectile\", \"_position\", \"_velocity\",\n \"_selection\", \"_ammo\", \"_vector\", \"_radius\", \"_surfaceType\",\n \"_isDirect\", \"_instigator\"\n ];\n } forEach _this;\n}];\n```\n\n- target: Object - object that was damaged\n- shooter: Object - Unit or vehicle that inflicted the damage. If injured by a vehicle collision, the target itself is returned, or objNull in case of explosions. In case of explosives that were planted by someone (e.g. satchel charges), that unit is returned.\n- projectile: Object - object that was fired\n- position: Array format PositionASL - position the bullet impacted\n- velocity: Vector3D - 3D speed at which the bullet impacted\n- selection: Array - array of Strings with named selection of the object that were hit, in the FireGeometry LOD\n- ammo:\n - Array in format [hitValue, indirectHitValue, indirectHitRange, explosiveDamage, ammoClassName] - If the damage was directly or indirectly inflicted by a projectile. Hit and damage values are derived from the projectile's CfgAmmo class, and do not match the actual damage inflicted, which is usually lower due to armor and other factors.\n - Array in format [impulseValue, 0, 0, 0] - if the damage was inflicted by a vehicle collision\n- vector: Vector3D - Vector that is orthogonal (perpendicular) to the surface struck. For example, if a wall was hit, the vector would be pointing out of the wall at a 90 degree angle.\n- radius: Number - radius (size) of component hit\n- surfaceType: String - surface type struck\n- isDirect: Boolean - true if object was directly hit, false if it was hit by indirect / splash damage\n- Arma 3 v2.18 instigator: Object - shot instigator\n\n> [!NOTE]\n> See #HitPart (Projectile) for a similar event handler that is attached to the projectile instead of the entity.\n\n> [!NOTE]\n> This event does not fire when miniscule explosive damage is dealt to the target entity, but the Explosion event will still fire."},{"heading":"IncomingMissile","level":4,"markdown":"Global Argument\n\nTriggered when a unit fires a missile or rocket at the target. For projectiles fired by players this EH only triggers for guided missiles that have locked onto the target.\n\n```sqf\nthis addEventHandler [\"IncomingMissile\", {\n params [\"_target\", \"_ammo\", \"_vehicle\", \"_instigator\", \"_missile\"];\n}];\n```\n\n- target: Object - object the event handler is assigned to\n- ammo: String - ammo type that was fired on the target\n- Arma 3 v1.42 vehicle: Object - vehicle that fired the weapon. In case of soldier, unit is returned\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n- Arma 3 v2.10 missile: Object - the incoming missile"},{"heading":"Init (Entity)","level":4,"markdown":"Global Argument\n\nTriggered whenever an entity is created. Cannot be used in scripts, only inside class Eventhandlers in config.\n\n> [!IMPORTANT]\n> It is recommended to use the #PostInit event handler instead of this one when setting entity textures (setObjectTexture, BIS_fnc_initVehicle etc) to avoid networking issues.\n\ne.g:\n\n```cpp\ninit = \"params ['_entity'];\";\n```\n\n```sqf\nparams [\"_entity\"];\n```\n\n- entity: Object - object the event handler is assigned to"},{"heading":"InventoryClosed (Arma 3 v1.22)","level":4,"markdown":"Global Argument\n\nTriggered when the unit closes inventory. Said unit can be non-local when adding the EH, but **must** be local for the EH to trigger.\n\n```sqf\nthis addEventHandler [\"InventoryClosed\", {\n params [\"_unit\", \"_container\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- container: Object - connected container or weaponholder\n\n```sqf\n// Delete dropped items when inventory closed\nplayer addEventHandler [\"InventoryClosed\", {\n params [\"_unit\", \"_container\"];\n if (_container isKindOf \"WeaponHolder\") then\n {\n deleteVehicle _container;\n };\n}];\n```"},{"heading":"InventoryOpened (Arma 3 v1.22)","level":4,"markdown":"Global Argument\n\nTriggered when unit opens inventory. Said unit can be non-local when adding the EH, but **must** be local for the EH to trigger. End EH main scope with true to override the opening of the inventory in case you wish to handle it yourself:\n\n```sqf\n// Create and open an ammo box when \"Inventory\" button is pressed\nplayer addEventHandler [\"InventoryOpened\", {\n player removeAllEventHandlers \"InventoryOpened\";\n _box = \"Box_NATO_Ammo_F\" createVehicle [0,0,0];\n _box setPosASL (player modelToWorldVisualWorld [0,1.5,0.5]);\n player action [\"Gear\", _box];\n true; // <-- inventory override\n}];\n```\n\nTo return all nearby containers use nearSupplies command.\n\n```sqf\nthis addEventHandler [\"InventoryOpened\", {\n params [\"_unit\", \"_primaryContainer\", \"_secondaryContainer\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- primaryContainer: Object - connected container or weaponholder\n- Arma 3 v1.66 secondaryContainer: Object - second connected container or weaponholder or objNull"},{"heading":"Killed","level":4,"markdown":"Local Argument\n\nTriggered when the unit is killed.\n\n```sqf\nthis addEventHandler [\"Killed\", {\n params [\"_unit\", \"_killer\", \"_instigator\", \"_useEffects\", \"_shot\", \"_real\"];\n}];\n```\n\n- unit: Object - the object the event handler is assigned to\n- killer: Object - the object that killed the unit. Contains the unit itself in case of collisions.\n- Arma 3 v1.66 instigator: Object - the person who pulled the trigger\n- Arma 3 v1.68 useEffects: Boolean - same as *useEffects* in setDamage alt syntax\n- Arma 3 v2.22 shot: Object - shot that caused damage\n- Arma 3 v2.22 real: Boolean - true when the shot was 'real' where the event handler triggered"},{"heading":"LandedStopped","level":4,"markdown":"Global Argument\n\nTriggered when an AI pilot would get out usually. Not executed for player.\n\n```sqf\nthis addEventHandler [\"LandedStopped\", {\n params [\"_plane\", \"_airportID\", \"_airportObject\"];\n}];\n```\n\n- plane: Object - object the event handler is assigned to\n- airportID: Number - ID of the airport (-1 for anything else)\n- Arma 3 v2.12 airportObject: Object - airport object in the event of a Dynamic Airport, otherwise objNull"},{"heading":"LandedTouchDown","level":4,"markdown":"Global Argument\n\nTriggered when a plane (AI or player) touches the ground.\n\n```sqf\nthis addEventHandler [\"LandedTouchDown\", {\n params [\"_plane\", \"_airportID\", \"_airportObject\"];\n}];\n```\n\n- plane: Object - object the event handler is assigned to\n- airportID: Number - ID of the airport (-1 for anything else)\n- Arma 3 v2.12 airportObject: Object - airport object in the event of a Dynamic Airport, otherwise objNull"},{"heading":"Landing (Arma 3 v1.70)","level":4,"markdown":"Global Argument\n\nTriggered when an AI pilot (or auto-pilot) is preparing for landing. The exact moment of triggering coincides with lowering of the gear (\"Gear\" EH)\n\n```sqf\nthis addEventHandler [\"Landing\", {\n params [\"_plane\", \"_airportID\", \"_isCarrier\"];\n}];\n```\n\n- plane: Object - object the event handler is assigned to\n- airportID: Number or Object - ID of the airport or aircraft carrier object\n- isCarrier: Boolean - true if landing on aircraft carrier"},{"heading":"LandingCanceled (Arma 3 v1.70)","level":4,"markdown":"Global Argument\n\nTriggered when AI pilot landing is cancelled (for example new order received to land elsewhere).\nThe exact moment of triggering coincides with retracting of the gear (\"Gear\" EH).\n\n**Note**: Does not trigger if player switches off auto-pilot. Canceled is spelled with one `L`\n\n```sqf\nthis addEventHandler [\"LandingCanceled\", {\n params [\"_plane\", \"_airportID\", \"_isCarrier\"];\n}];\n```\n\n- plane: Object - object the event handler is assigned to\n- airportID: Number or Object - ID of the airport or aircraft carrier object (-1 no airport)\n- isCarrier: Boolean - true if landing on aircraft carrier"},{"heading":"LaserTargetChanged (Arma 3 v2.22)","level":4,"markdown":"Triggered when the laser target changes.\n\n```sqf\nthis addEventHandler [\"LaserTargetChanged\", {\n params [\"_unit\", \"_laserTarget\", \"_designatedTarget\", \"_turretPath\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- laserTarget: Object - the laser target entity that got created at impact point\n- designatedTarget: Object - the object that is targeted by the laser\n- turretPath: Turret Path - the path to the turret that activated the laser. It is empty when the event is triggered by a unit"},{"heading":"LeaningChanged (Arma 3 v2.18)","level":4,"markdown":"Global Argument\n\nTriggered when a soldier leaning factor is changed between -1 (extreme left), 0 (not leaning) and 1 (extreme right)\n\n```sqf\nthis addEventHandler [\"LeaningChanged\", {\n params [\"_unit\", \"_newLeaning\", \"_oldLeaning\"];\n}];\n```\n\n- unit: Object - soldier\n- newLeaning: Number from -1 to 1\n- oldLeaning: Number from -1 to 1"},{"heading":"Local (Entity)","level":4,"markdown":"Global Argument\n\nTriggers when locality of object in MP is changed. The event handler only triggers on the computers that are directly involved in change of locality.\nSo if EH is added to every computer on network, it will only trigger on 2 computers, on the computer that receives ownership of the object (new owner), in which case _this select 1 will be true,\nand on the computer from which ownership is transferred (old owner), in which case _this select 1 will be false.\n\n```sqf\nthis addEventHandler [\"Local\", {\n params [\"_entity\", \"_isLocal\"];\n}];\n```\n\n- entity: Object - the object that changed locality\n- isLocal: Boolean - if the object is local on given computer"},{"heading":"MagazineReloading (Arma 3 v2.18)","level":4,"markdown":"Local Argument\n\nTriggers when reloading starts.\n\n```sqf\nthis addEventHandler [\"MagazineReloading\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_magazine\", \"_magazineClass\", \"_ammoCount\", \"_magazineID\", \"_magazineCreator\"];\n}];\n```\n\n- unit: Object - unit or vehicle to which EH is assigned\n- weapon: String - weapon that got unloaded\n- muzzle: String - weapon's muzzle that got unloaded\n- magazine: Array - magazine info in format [magazineClass, ammoCount, magazineID, magazineCreator], where:\n - magazineClass: String - class name of the magazine\n - ammoCount: Number - amount of ammo in magazine\n - magazineID: Number - global magazine id\n - magazineCreator: Number - owner of the magazine creator"},{"heading":"MagazineUnloaded (Arma 3 v2.18)","level":4,"markdown":"Local Argument\n\nTriggers when a magazine is removed from a weapon manually or via script.\n\n```sqf\nthis addEventHandler [\"MagazineUnloaded\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_magazine\", \"_magazineClass\", \"_ammoCount\", \"_magazineID\", \"_magazineCreator\"];\n}];\n```\n\n- unit: Object - unit or vehicle to which EH is assigned\n- weapon: String - weapon that got unloaded\n- muzzle: String - weapon's muzzle that got unloaded\n- magazine: Array - magazine info in format [magazineClass, ammoCount, magazineID, magazineCreator], where:\n - magazineClass: String - class name of the magazine\n - ammoCount: Number - amount of ammo in magazine\n - magazineID: Number - global magazine id\n - magazineCreator: Number - owner of the magazine creator"},{"heading":"OpticsModeChanged (Arma 3 v2.10)","level":4,"markdown":"Local Argument\n\nTriggers everytime a local unit changes optic mode. This could be either through the setOpticsMode command or by the player switching to the next optic mode using e.g NUM / or Ctrl +RMB .\n\n```sqf\nthis addEventHandler [\"OpticsModeChanged\", {\n params [\"_unit\", \"_opticsClass\", \"_newMode\", \"_oldMode\", \"_isADS\"];\n}];\n```\n\n- unit: Object - the unit\n- opticsClass: String\n- newMode: String\n- oldMode: String\n- isADS: Boolean - if the new view is GUNNER"},{"heading":"OpticsSwitch (Arma 3 v2.10)","level":4,"markdown":"Local Argument\n\nTriggers at the start of the camera transition from GUNNER to INTERNAL/EXTERNAL and vice-versa.\nSo anytime the right mouse button is pressed and there is a GUNNER view available or are currently in it, this triggers.\nWorks in vehicles and FFV as well. See also cameraView.\n\n```sqf\nthis addEventHandler [\"OpticsSwitch\", {\n params [\"_unit\", \"_isADS\"];\n}];\n```\n\n- unit: Object - the unit\n- isADS: Boolean - if the new view is GUNNER"},{"heading":"PathCalculated (Arma 3 v1.94)","level":4,"markdown":"Local Argument\n\nTriggers when a path has been calculated for the unit. Works for both agents and normal AI units.\n\nNote that paths to far destinations are typically calculated in segments.\nWhen the unit completes a segment, a new path is calculated and this is continued until the unit reaches its destination.\n\n```sqf\nthis addEventHandler [\"PathCalculated\", {\n params [\"_unit\", \"_path\"];\n}];\n```\n\n- unit: Object - the unit/agent for which the path was calculated\n- path: Array - the array of positions representing the path (PositionASL)"},{"heading":"PeriscopeElevationChanged (Arma 3 v2.00)","level":4,"markdown":"Fires every frame during periscope elevation animation.\n\n```sqf\nthis addEventHandler [\"PeriscopeElevationChanged\", {\n params [\"_vehicle\", \"_turret\", \"_elevation\", \"_direction\", \"_userIsBlocked\"];\n}];\n```\n\n- vehicle: Object - the vehicle this EH is assigned to\n- turret: Array - the turret which periscope is changing elevation\n- elevation: Number - current periscope elevation (changes with each simulation). See also periscopeElevation, elevatePeriscope\n- direction: Number - 1: moves up, 0: stopped, -1: moves down; when `direction` returns 0, this also means the event handler fired for the last time for this elevation.\n- userIsBlocked: Boolean - whether or not the user ability to override is blocked. See also periscopeElevation, elevatePeriscope"},{"heading":"PostInit (Arma 3 v2.06)","level":4,"markdown":"Global Argument\n\nTriggered whenever an entity is created and initialized. Cannot be used in scripts, only inside class Eventhandlers in config.\n\n> [!IMPORTANT]\n> It is recommended to use this event handler instead of the #Init one when setting entity textures (setObjectTexture, BIS_fnc_initVehicle etc) to avoid networking issues.\n\ne.g:\n\n```cpp\npostInit = \"params ['_entity'];\";\n```\n\n```cpp\npostinit = \"params ['_entity']; if (local _entity) then { [_entity, '', [], false] call BIS_fnc_initVehicle };\";\n```\n\n```sqf\nparams [\"_entity\"];\n```\n\n- entity: Object - object the event handler is assigned to"},{"heading":"PostReset","level":4,"markdown":"**Obsolete** - triggers after PP effects have been reset by the engine."},{"heading":"Put (Arma 3 v0.56)","level":4,"markdown":"Global Argument\n\nTriggers when a unit puts an item in a container.\n\nArma 3 v2.14 This event handler can be added to a container.\n\n```sqf\nthis addEventHandler [\"Put\", {\n params [\"_unit\", \"_container\", \"_item\"];\n}];\n```\n\n- unit: Object - unit who put the item in the container\n- container: Object - the container into which the item was placed (vehicle, box, etc.)\n- item: String - the class name of the moved item\n\n> [!NOTE]\n> This EH could also trigger when unit replaces magazine in weapon with another magazine from unit containers (uniform, vest, backpack) during reload."},{"heading":"PylonChanged (Arma 3 v2.20)","level":4,"markdown":"Local Argument\n\nTriggers when an aircraft's pylon changes magazine type:\n\n```sqf\nvehicle player addEventHandler [\"PylonChanged\", {\n params [\"_vehicle\", \"_pylonIndex\", \"_oldMagazine\", \"_newMagazine\"];\n}];\n```\n\n- vehicle: Object\n- pylonIndex: Number\n- oldMagazine: String\n- newMagazine: String\n\n> [!IMPORTANT]\n> This event generally triggers **twice** for a swap, first unload then load, e.g:\n>\n> ```sqf\n> // [myVehicle, 1, \"oldMagClass\", \"\"]\n> // [myVehicle, 1, \"\", \"newMagClass\"]\n> ```"},{"heading":"Reloaded (Arma 3 v1.58)","level":4,"markdown":"Local Argument\n\nTriggers once a weapon is reloaded with a new magazine. For more information, see Reloaded.\n\n```sqf\nthis addEventHandler [\"Reloaded\", {\n params [\"_unit\", \"_weapon\", \"_muzzle\", \"_newMagazine\", \"_oldMagazine\"];\n}];\n```\n\n- unit: Object - unit or vehicle to which EH is assigned\n- weapon: String - weapon that got reloaded\n- muzzle: String - weapon's muzzle that got reloaded\n- newMagazine: Array - new magazine info\n- oldMagazine: Array or Nothing - old magazine info"},{"heading":"Respawn","level":4,"markdown":"Local Argument\n\nTriggered when a unit respawns.\n\n```sqf\nthis addEventHandler [\"Respawn\", {\n params [\"_unit\", \"_corpse\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- corpse: Object - object the event handler was assigned to, aka the corpse/unit player was previously controlling"},{"heading":"RopeAttach (Arma 3 v1.34)","level":4,"markdown":"Triggered when a rope is attached to an object.\n\nIn the case of sling loading, this event handler must be assigned to the helicopter and will trigger for each attached rope.\n\n```sqf\nthis addEventHandler [\"RopeAttach\", {\n params [\"_object1\", \"_rope\", \"_object2\"];\n}];\n```\n\n- object1: Object - object to which the event handler is assigned.\n- rope: Object - the rope being attached between object 1 and object 2.\n- object2: Object - the object that is being attached to object 1 via rope."},{"heading":"RopeBreak (Arma 3 v1.34)","level":4,"markdown":"Triggered when a rope is detached from an object.\n\nIn the case of sling loading, this event handler must be assigned to the helicopter and will trigger for each detached rope.\n\n```sqf\nthis addEventHandler [\"RopeBreak\", {\n params [\"_object1\", \"_rope\", \"_object2\"];\n}];\n```\n\n- object1: Object - object to which the event handler is assigned.\n- rope: Object - the rope that connected object 1 and object 2.\n- object2: Object - the object that was connected to object 1 with a rope."},{"heading":"SeatSwitched (Arma 3 v1.50)","level":4,"markdown":"Global Argument\n\nTriggered when unit changes seat within vehicle. EH returns both units switching seats.\nIf switching seats with an empty seat, one of the returned units will be objNull.\nThe new position can be obtained with assignedVehicleRole.\nThis EH must be assigned to a vehicle.\n\n```sqf\nthis addEventHandler [\"SeatSwitched\", {\n params [\"_vehicle\", \"_unit1\", \"_unit2\"];\n}];\n```\n\n- vehicle: Object - vehicle to which the event handler is assigned.\n- unit1: Object - unit switching seat.\n- unit2: Object - unit switching seat."},{"heading":"SeatSwitchedMan (Arma 3 v1.58)","level":4,"markdown":"Global Argument\n\nTriggered when unit changes seat within vehicle. EH returns both units switching seats.\nIf switching seats with an empty seat, one of the returned units will be objNull.\nThe new position can be obtained with assignedVehicleRole . This EH must be assigned to a unit and not a vehicle.\nThis EH is persistent and will be transferred to the new unit after respawn, but only if it was assigned where unit was local.\n\n```sqf\nthis addEventHandler [\"SeatSwitchedMan\", {\n params [\"_unit1\", \"_unit2\", \"_vehicle\"];\n}];\n```\n\n- unit1: Object - unit switching seat.\n- unit2: Object - unit with which unit1 is switching seat.\n- vehicle: Object - vehicle where switching seats is taking place."},{"heading":"SelectedActionChanged","level":4,"markdown":"RTM helicopter user action event\n\n```sqf\nthis addEventHandler [\"SelectedActionChanged\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality."},{"heading":"SelectedActionPerformed","level":4,"markdown":"RTM helicopter user action event\n\n```sqf\nthis addEventHandler [\"SelectedActionPerformed\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality."},{"heading":"SelectedRotorLibActionChanged","level":4,"markdown":"RTM helicopter user action event\n\n```sqf\nthis addEventHandler [\"SelectedRotorLibActionChanged\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality."},{"heading":"SelectedRotorLibActionPerformed","level":4,"markdown":"RTM helicopter user action event\n\n```sqf\nthis addEventHandler [\"SelectedRotorLibActionPerformed\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Works only for key press combination RCtrl +W , which is the binding for helicopter wheels brakes.\n> 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:\n> - 0: HelicopterAutoTrimOn\n> - 1: HelicopterAutoTrimOff\n> - 2: HelicopterTrimOn\n> - 3: HelicopterTrimOff\n> - 4: WheelsBrakeOn\n> - 5: WheelsBrakeOff"},{"heading":"SlotItemChanged (Arma 3 v2.14)","level":4,"markdown":"Global Argument\n\nTriggered when any of the following slots get assigned or unassigned: *Items* - Map, GPS, Radio, Watch, Compass, Helmet, Goggles, NVG; *Weapon* - Binoculars; *Containers* - Uniform, Vest, Backpack.\n\n```sqf\nthis addEventHandler [\"SlotItemChanged\", {\n params [\"_unit\", \"_name\", \"_slot\", \"_assigned\", \"_weapon\"];\n}];\n```\n\n- unit: Object - unit EH assigned to.\n- name: String - name of the item/weapon/container (see getSlotItemName).\n- slot: Number - slot id (see getSlotItemName).\n- assigned: Boolean - true assign action, false unassign action.\n- Arma 3 v2.18 weapon: String - name of weapon in event that slot changed is a weapon attachment slot"},{"heading":"SoundPlayed (Arma 3 v0.56)","level":4,"markdown":"Local Argument\n\nTriggered when player is making noises when injured or fatigued for example. The number param passed to the EH code points to the sound origin:\n1. Breath\n1. Breath Injured\n1. Breath Scuba\n1. Injured\n1. Pulsation\n1. Hit Scream\n1. Burning\n1. Drowning\n1. Drown\n1. Gasping\n1. Stabilizing\n1. Healing\n1. Healing With Medikit\n1. Recovered\n1. Breath Held\n\n```sqf\nthis addEventHandler [\"SoundPlayed\", {\n params [\"_unit\", \"_soundID\"];\n}];\n```\n\n- unit: Object - unit to which the event handler is assigned\n- soundID: Number - sound origin\n\n> [!NOTE]\n> Since Arma 3 v2.12 returning a Number from last added EH in range from 0 to 5 will alter the volume of played sound from mute to max volume."},{"heading":"Suppressed (Arma 3 v2.02)","level":4,"markdown":"Local Argument\n\nTriggers when enemy projectile is passing by closer than defined suppression radius ammo value in config.\nCan be made to trigger for the same side if the side is set as enemy to itself (with setFriend). For more information see Arma 3: Suppression.\n\n```sqf\nthis addEventHandler [\"Suppressed\", {\n params [\"_unit\", \"_distance\", \"_shooter\", \"_instigator\", \"_ammoObject\", \"_ammoClassName\", \"_ammoConfig\"];\n}];\n```\n\n- unit: Object - unit to which the event is assigned\n- distance: Number - distance of the projectile pass-by\n- shooter: Object - who (or what) fired - vehicle or drone\n- instigator: Object - who pressed the trigger. Instigator is different from the shooter when player is operator of UAV for example\n- ammoObject: Object - the ammunition itself\n- ammoClassName: String - the ammunition's classname\n- ammoConfig: Config - the ammunition's CfgAmmo config path"},{"heading":"Take (Arma 3 v0.56)","level":4,"markdown":"Global Argument\n\nTriggers when a unit takes an item from a container.\n\nArma 3 v2.14 This event handler can be added to a container.\n\n```sqf\nthis addEventHandler [\"Take\", {\n params [\"_unit\", \"_container\", \"_item\"];\n}];\n```\n\n- unit: Object - unit who took the item from the container\n- container: Object - the container from which the item was taken (vehicle, box, etc.)\n- item: String - the class name of the taken item\n\n> [!NOTE]\n> This EH could also trigger when unit replaces magazine in weapon with another magazine from unit containers (uniform, vest, backpack) during reload."},{"heading":"TaskSetAsCurrent (Arma 3 v1.32)","level":4,"markdown":"Triggers when player's current task changes\n\n```sqf\nthis addEventHandler [\"TaskSetAsCurrent\", {\n params [\"_unit\", \"_task\"];\n}];\n```\n\n- unit: Object - the player to whom the event handler is assigned\n- task: Task - the new current task"},{"heading":"TurnIn (Arma 3 v1.66)","level":4,"markdown":"Triggers when member of crew in a vehicle uses Turn In action\n\n```sqf\nthis addEventHandler [\"TurnIn\", {\n params [\"_vehicle\", \"_unit\", \"_turret\"];\n}];\n```\n\n- vehicle: Object - the vehicle the event handler is assigned to\n- unit: Object - the unit performing the Turn In action\n- turret: Array - turret path"},{"heading":"TurnOut (Arma 3 v1.66)","level":4,"markdown":"Triggers when member of crew in a vehicle uses Turn Out action\n\n```sqf\nthis addEventHandler [\"TurnOut\", {\n params [\"_vehicle\", \"_unit\", \"_turret\"];\n}];\n```\n\n- vehicle: Object - the vehicle the event handler is assigned to\n- unit: Object - the unit performing the Turn Out action\n- turret: Array - turret path"},{"heading":"VisionModeChanged (Arma 3 v2.08)","level":4,"markdown":"Triggers when the assigned vehicle/unit's vision mode has changed.\n\n```sqf\nplayer addEventHandler [\"VisionModeChanged\", {\n params [\"_person\", \"_visionMode\", \"_TIindex\", \"_visionModePrev\", \"_TIindexPrev\", \"_vehicle\", \"_turret\"];\n}];\n```\n\n- person: Object - unit for whom the vision mode changes\n- visionMode: Number - vision mode index\n- TIindex: Number - thermal vision mode index; will return -1 when *visionMode* is not 2\n- visionModePrev: Number - last vision mode\n- TIindexPrev: Number - last TI mode; will return -1 when *visionModePrev* is not 2\n- vehicle: Object - if unit is in a vehicle or controlling a UAV, this will be the vehicle\n- turret: Array - turret path to the turret occupied by the unit, or [] if not on turret"},{"heading":"WeaponAssembled","level":4,"markdown":"Global Argument\n\nTriggers when a weapon gets assembled. EH must be attached to the unit and not the weapon.\n\n```sqf\nthis addEventHandler [\"WeaponAssembled\", {\n params [\"_unit\", \"_weapon\", \"_primaryBag\", \"_secondaryBag\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- weapon: Object - object of the assembled weapon\n- Arma 3 v2.18 primaryBag: Object - primary bag (just before it is deleted)\n- Arma 3 v2.18 secondaryBag: Object - secondary bag (just before it is deleted)"},{"heading":"WeaponChanged (Arma 3 v2.18)","level":4,"markdown":"Fires on weapon switch and firemode switch. Does not fire for player units inside vehicles (but does fire for vehicles with players in them).\n\nThe locality is unknown, but it is known that this EH behaves like currentWeapon, currentWeaponMode and currentMuzzle in terms of locality.\n\nArma 3 v2.22 Fires for \"Throw\" muzzle changes too.\n\n```sqf\nthis addEventHandler [\"WeaponChanged\", {\n params [\"_object\", \"_oldWeapon\", \"_newWeapon\", \"_oldMode\", \"_newMode\", \"_oldMuzzle\", \"_newMuzzle\", \"_turretIndex\"];\n}];\n```\n\n- object: Object - the unit or vehicle the event handler is assigned to\n- oldWeapon: String - the class name of the previous weapon\n- newWeapon: String - the class name of the new weapon (same as currentWeapon)\n- oldMode: String - the previous weapon mode\n- newMode: String - the new weapon mode (same as currentWeaponMode)\n- oldMuzzle: String - the previous weapon muzzle\n- newMuzzle: String - the new weapon muzzle (same as currentMuzzle)\n- turretIndex: Array format Turret Path - the turret path, or empty array if `object` is not a transport vehicle"},{"heading":"WeaponDeployed (Arma 3 v1.44)","level":4,"markdown":"Global Argument\n\nTriggers when the deployed state of a weapon or bipod changes.\n\n**Note:** A weapon cannot be rested and deployed at the same time.\n\n```sqf\nthis addEventHandler [\"WeaponDeployed\", {\n params [\"_unit\", \"_isDeployed\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- isDeployed: Boolean - true if deployed"},{"heading":"WeaponDisassembled","level":4,"markdown":"Global Argument\n\nTriggers when a weapon gets disassembled. EH must be attached to the unit and not the weapon.\n\n**Note:** As of Arma 3 v1.32, this event does not fire if the weapon is not local.\n\n```sqf\nthis addEventHandler [\"WeaponDisassembled\", {\n params [\"_unit\", \"_primaryBag\", \"_secondaryBag\", \"_weapon\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- primaryBag: Object - first backpack object which was weapon disassembled into\n- secondaryBag: Object - second backpack object which was weapon disassembled into\n- Arma 3 v2.18 weapon: Object - disassembled weapon (just before it is moved out of the world)"},{"heading":"WeaponRested (Arma 3 v1.44)","level":4,"markdown":"Local Argument\n\nTriggers when weapon rested state changes (weapon near a surface that can provide weapon support).\n\n**Note:** A weapon cannot be rested and deployed at the same time.\n\n```sqf\nthis addEventHandler [\"WeaponRested\", {\n params [\"_unit\", \"_isRested\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- isRested: Boolean - true if rested"},{"heading":"Multiplayer Event Handlers","level":3,"markdown":"Global object event handler, executed on every connected machine.\n\nCommands:\n- addMPEventHandler\n- removeMPEventHandler\n- removeAllMPEventHandlers\n\n> [!IMPORTANT]\n> A Multiplayer Event Handler is **not** saved in a save file and therefore will not be restored on load - use it accordingly."},{"heading":"MPHit","level":4,"markdown":"Global ArgumentGlobal Effect\n\nTriggered when the unit is hit/damaged. EH can be added on any machine and EH code will trigger globally on every connected client and server.\nThis EH is clever enough to be triggered globally only once even if added on all clients or a single client that is then disconnected, EH will still trigger globally only once.\n\nIs *not* always triggered when unit is killed by a hit.\nMost of the time only the killed event handler is triggered when a unit dies from a hit.\nThe hit EH will not necessarily fire if only minor damage occurred (e.g. firing a bullet at a tank), even though the damage increased.\nCan also trigger several times for an explosion (direct and indirect damage). Does not fire when a unit is set to allowDamage false.\nHowever it will fire with \"HandleDamage\" EH added alongside stopping unit from taking damage (`unit addEventHandler [\"HandleDamage\", { 0 }];`.\nWill not trigger once the unit is dead.\n\n**Note:** call a function from the MPHit EH code space rather than defining the full code in there directly.\nThe reason is the code space will be transferred over network on each event activation - so keep the data as small as possible!\n\n```sqf\nthis addMPEventHandler [\"MPHit\", {\n params [\"_unit\", \"_causedBy\", \"_damage\", \"_instigator\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n\n- causedBy: Object - object that caused the damage. Contains the unit itself in case of collisions.\n\n- damage: Number - level of damage caused by the hit\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger"},{"heading":"MPKilled","level":4,"markdown":"Global ArgumentGlobal Effect\n\nTriggered when the unit is killed. EH can be added on any machine and EH code will trigger globally **on every connected client and server**.\nThis EH has a safeguard measure so that even if it's added on all clients or a single client that is then disconnected, EH will still trigger globally only once per client.\n\n```sqf\nthis addMPEventHandler [\"MPKilled\", {\n params [\"_unit\", \"_killer\", \"_instigator\", \"_useEffects\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- killer: Object - object that killed the unit. Contains the unit itself in case of collisions\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n- Arma 3 v1.68 useEffects: Boolean - same as *useEffects* in setDamage alt syntax"},{"heading":"MPRespawn","level":4,"markdown":"Global ArgumentLocal Effect\n\nTriggered when a unit, it is assigned to, respawns. This EH does not work as one would expect MP EH should work like.\nIt is only triggered on one machine where the unit it was assigned to is local.\nThe only difference between **Respawn** and **MPRespawn** is that **MPRespawn** can be assigned from anywhere while **Respawn** requires the unit to be local.\n\nMPRespawn EH expects the EH code to return an array in Position format which will be used to place the respawned unit at the desired coordinates.\n\nFor example: `player addMPEventHandler [\"MPRespawn\", { [1234, 1234, 0] }];` will place player at [1234,1234,0] immediately on respawn.\n\n```sqf\nthis addMPEventHandler [\"MPRespawn\", {\n params [\"_unit\", \"_corpse\"];\n}];\n```\n\n- unit: Object - object the event handler is assigned to\n- corpse: Object - object the event handler was assigned to, aka the corpse/unit player was previously controlling."},{"heading":"Mission Event Handlers","level":3,"markdown":"Mission Event Handlers are specific EHs that are anchored to the running mission and automatically removed when mission is over.\n\nCommands:\n- addMissionEventHandler\n- removeMissionEventHandler\n\n> [!NOTE]\n> See Arma 3: Mission Event Handlers."},{"heading":"Curator Event Handlers (Arma 3 v1.16)","level":3,"markdown":"Local ArgumentLocal Effect\n\nArma 3: Curator Event Handlers are also added with the addEventHandler command. They are executed only where the curator is local - on the machine that is in control of it.\n\n> [!IMPORTANT]\n> These Event Handlers must be added to the curator object/module, **not** the player!\n\nCommands:\n- addEventHandler\n- removeEventHandler\n- removeAllEventHandlers"},{"heading":"CuratorFeedbackMessage","level":4,"markdown":"Local Argument\n\nTriggered when curator attempts invalid action in curator interface.\n\nEach error has its own unique ID, recognized values are:\n\n- 003 - when trying to teleport camera outside of curatorCameraArea\n- 101 - trying to place an object when placing is disabled using setCuratorCoef \"place\"\n- 102 - trying to place an object which is too expensive (cost set in *curatorObjectRegistered* multiplied by setCuratorCoef \"place\" is larger than curatorPoints)\n- 103 - trying to place an object outside of curatorEditingArea\n- 104 - items of a placed composition were skipped / could not be placed (since Arma 3 v2.06)\n- 201 - trying to place a waypoint when waypoint placing is disabled\n- 202 - trying to place a waypoint which is too expensive (cost set by setCuratorWaypointCost multiplied by setCuratorCoef \"place\" is larger than curatorPoints)\n- 206 - trying to place a waypoint when no AI unit is selected\n- 301 - trying to move or rotate an entity when editing is disabled using setCuratorCoef \"edit\"\n- 302 - trying to move or rotate an entity when it is too expensive (entity cost multiplied by setCuratorCoef \"edit\" is larger than curatorPoints)\n- 303 - trying to move an entity outside of curatorEditingArea\n- 304 - trying to move or rotate an entity which is outside of curatorEditingArea\n- 307 - trying to move or rotate a player (players cannot be manipulated with)\n- 401 - trying to delete an entity when deleting is disabled using setCuratorCoef \"delete\"\n- 402 - trying to delete an entity which is too expensive (cost multiplied by setCuratorCoef \"delete\" is larger than curatorPoints)\n- 404 - trying to delete an entity which is outside of curatorEditingArea\n- 405 - trying to delete an entity which has non-editable crew in it\n- 407 - trying to delete a player (players cannot be manipulated with)\n- 501 - trying to destroy an object when destroying is disabled using setCuratorCoef \"destroy\"\n- 502 - trying to destroy an object which is too expensive (cost multiplied by setCuratorCoef \"destroy\" is larger than curatorPoints)\n- 504 - trying to destroy an object which is outside of curatorEditingArea\n- 505 - trying to destroy an object which has non-editable crew in it\n- 506 - trying to destroy an object when no object is selected\n- 507 - trying to destroy a player (players cannot be manipulated with)\n\n```sqf\nthis addEventHandler [\"CuratorFeedbackMessage\", {\n params [\"_curator\", \"_errorID\"];\n}];\n```\n\n- curator: Object\n- errorID: Number"},{"heading":"CuratorGroupDoubleClicked","level":4,"markdown":"Local Argument\n\nTriggered when a group is double-clicked on in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorGroupDoubleClicked\", {\n params [\"_curator\", \"_group\"];\n}];\n```\n\n- curator: Object\n- group: Group"},{"heading":"CuratorGroupPlaced","level":4,"markdown":"Local Argument\n\nTriggered when new group is placed in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorGroupPlaced\", {\n params [\"_curator\", \"_group\"];\n}];\n```\n\n- curator: Object\n- group: Group"},{"heading":"CuratorGroupSelectionChanged","level":4,"markdown":"Local Argument\n\nTriggered when a group is selected in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorGroupSelectionChanged\", {\n params [\"_curator\", \"_group\"];\n}];\n```\n\n- curator: Object\n- group: Group"},{"heading":"CuratorMarkerDeleted","level":4,"markdown":"Local Argument\n\nTriggered when a marker is deleted in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerDeleted\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String"},{"heading":"CuratorMarkerDoubleClicked","level":4,"markdown":"Local Argument\n\nTriggered when a marker is double-clicked on in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerDoubleClicked\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String"},{"heading":"CuratorMarkerEdited","level":4,"markdown":"Local Argument\n\nTriggered when a marker is moved in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerEdited\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String"},{"heading":"CuratorMarkerPlaced","level":4,"markdown":"Local Argument\n\nTriggered when new marker is placed in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerPlaced\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String"},{"heading":"CuratorMarkerSelectionChanged","level":4,"markdown":"Local Argument\n\nTriggered when a marker is selected in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorMarkerSelectionChanged\", {\n params [\"_curator\", \"_marker\"];\n}];\n```\n\n- curator: Object\n- marker: String"},{"heading":"CuratorObjectDeleted","level":4,"markdown":"Local Argument\n\nTriggered when an object is deleted in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorObjectDeleted\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object"},{"heading":"CuratorObjectDoubleClicked","level":4,"markdown":"Local Argument\n\nTriggered when an object is double-clicked on in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorObjectDoubleClicked\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object"},{"heading":"CuratorObjectEdited","level":4,"markdown":"Local Argument\n\nTriggered when an object is moved or rotated in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorObjectEdited\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object"},{"heading":"CuratorObjectPlaced","level":4,"markdown":"Local Argument\n\nTriggered when new object is placed in curator interface.\nThis event handler will trigger individually for each unit in a placed group - excluding the crew in vehicles.\n\n```sqf\nthis addEventHandler [\"CuratorObjectPlaced\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object"},{"heading":"CuratorObjectRegistered","level":4,"markdown":"Local Argument\n\nTriggered when player enters curator interface. Assign curator cost to every object in the game.\nThis is the primary method that a mission designer can use to limit the objects a curator can place.\n\n> [!NOTE]\n> See Curator#Manual Assigning.\n\n```sqf\nthis addEventHandler [\"CuratorObjectRegistered\", {\n params [\"_curator\", \"_input\"];\n}];\n```\n\n- curator: Object\n- input: Array of Strings - all CfgVehicles classes"},{"heading":"CuratorObjectSelectionChanged","level":4,"markdown":"Local Argument\n\nTriggered when an object is selected in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorObjectSelectionChanged\", {\n params [\"_curator\", \"_entity\"];\n}];\n```\n\n- curator: Object\n- entity: Object"},{"heading":"CuratorPinged","level":4,"markdown":"Local Argument\n\nTriggered when a player pings his curator(s) by pressing the *Zeus* key.\n\n```sqf\nthis addEventHandler [\"CuratorPinged\", {\n params [\"_curator\", \"_player\"];\n}];\n```\n\n- curator: Object\n- player: Object"},{"heading":"CuratorSelectionPresetLoaded (Arma 3 v2.14)","level":4,"markdown":"Local Argument\n\nTriggered when a selection preset is loaded using the respective number key or through script.\n\n```sqf\nthis addEventHandler [\"CuratorSelectionPresetLoaded\", {\n params [\"_curator\", \"_numkey\"];\n}];\n```\n\n- curator: Object\n- numkey: Number"},{"heading":"CuratorSelectionPresetSaved (Arma 3 v2.14)","level":4,"markdown":"Local Argument\n\nTriggered when a selection preset is saved using the respective CTRL + number key or set through script.\n\n```sqf\nthis addEventHandler [\"CuratorSelectionPresetSaved\", {\n params [\"_curator\", \"_numkey\"];\n}];\n```\n\n- curator: Object\n- numkey: Number"},{"heading":"CuratorWaypointDeleted","level":4,"markdown":"Local Argument\n\nTriggered when a waypoint is deleted in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointDeleted\", {\n params [\"_curator\", \"_waypoint\"];\n}];\n```\n\n- curator: Object\n- waypoint: Array"},{"heading":"CuratorWaypointDoubleClicked","level":4,"markdown":"Local Argument\n\nTriggered when a waypoint is double-clicked on in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointDoubleClicked\", {\n params [\"_curator\", \"_waypoint\"];\n}];\n```\n\n- curator: Object\n- waypoint: Array"},{"heading":"CuratorWaypointEdited","level":4,"markdown":"Local Argument\n\nTriggered when a waypoint is moved in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointEdited\", {\n params [\"_curator\", \"_group\", \"_waypointID\"];\n}];\n```\n\n- curator: Object\n- group: Group\n- waypointID: Number"},{"heading":"CuratorWaypointPlaced","level":4,"markdown":"Local Argument\n\nTriggered when new waypoint is placed in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointPlaced\", {\n params [\"_curator\", \"_group\", \"_waypointID\"];\n}];\n```\n\n- curator: Object\n- group: Group\n- waypointID: Number"},{"heading":"CuratorWaypointSelectionChanged","level":4,"markdown":"Local Argument\n\nTriggered when a waypoint is selected in curator interface.\n\n```sqf\nthis addEventHandler [\"CuratorWaypointSelectionChanged\", {\n params [\"_curator\", \"_waypoint\"];\n}];\n```\n\n- curator: Object\n- waypoint: Array"},{"heading":"UserAction Event Handlers (Arma 3 v2.06)","level":3,"markdown":"UserAction Event Handlers are events that trigger on user action.\n\nCommands:\n- addUserActionEventHandler\n- removeUserActionEventHandler\n\n> [!NOTE]\n> See Arma 3: Modded Keybinding."},{"heading":"Activate","level":4,"markdown":"```sqf\naddUserActionEventHandler [\"KeyName\", \"Activate\", {\n params [\"_activated\"];\n}];\n```\n\n- activated: Boolean - always returns true"},{"heading":"Deactivate","level":4,"markdown":"```sqf\naddUserActionEventHandler [\"KeyName\", \"Deactivate\", {\n params [\"_activated\"];\n}];\n```\n\n- activated: Boolean - always returns false"},{"heading":"Analog","level":4,"markdown":"```sqf\naddUserActionEventHandler [\"KeyName\", \"Analog\", {\n params [\"_value\"];\n}];\n```\n\n- value: Number - input device's analog value"},{"heading":"Projectile Event Handlers (Arma 3 v2.10)","level":3,"markdown":"Commands:\n- addEventHandler\n- removeEventHandler\n- removeAllEventHandlers"},{"heading":"Deleted (Projectile)","level":4,"markdown":"```sqf\n_projectile addEventHandler [\"Deleted\", {\n params [\"_projectile\"];\n}];\n```\n\n- projectile: Object"},{"heading":"Deflected","level":4,"markdown":"```sqf\n_projectile addEventHandler [\"Deflected\", {\n params [\"_projectile\", \"_position\", \"_velocity\", \"_hitObject\"];\n}];\n```\n\n- projectile: Object\n- position: Array format PositionASL\n- velocity: Array format Vector3D\n- hitObject: Object - the object that deflected the projectile"},{"heading":"Explode","level":4,"markdown":"Local Argument\n\n```sqf\n_projectile addEventHandler [\"Explode\", {\n params [\"_projectile\", \"_position\", \"_velocity\"];\n}];\n```\n\n- projectile: Object\n- position: Array format PositionASL\n- velocity: Array format Vector3D"},{"heading":"HitExplosion","level":4,"markdown":"```sqf\n_projectile addEventHandler [\"HitExplosion\", {\n params [\"_projectile\", \"_hitEntity\", \"_projectileOwner\", \"_hitSelections\", \"_instigator\"];\n}];\n```\n\n- projectile: Object\n- hitEntity: Object\n- projectileOwner: Object\n- hitSelections: Array of Arrays - same list of FireGeometry components that #HitPart (Entity) gets but only contains:\n - position: Array format PositionASL - position of impact\n - vector: Array format Vector3D - vector that is orthogonal (perpendicular) to the surface struck. For example, if a wall was hit, vector would be pointing out of the wall at a 90 degree angle\n - selection: String - named selection of the object that was hit, in the FireGeometry LOD.\n - radius: Number - radius (size) of component hit\n - surface: String - surface type struck\n- Arma 3 v2.18 instigator: Object - shot instigator"},{"heading":"HitPart (Projectile)","level":4,"markdown":"Triggered when the projectile hits any surface.\n\n```sqf\n_projectile addEventHandler [\"HitPart\", {\n params [\"_projectile\", \"_hitEntity\", \"_projectileOwner\", \"_pos\", \"_velocity\", \"_normal\", \"_components\", \"_radius\" ,\"_surfaceType\", \"_instigator\"];\n}];\n```\n\n- projectile: Object\n- hitEntity: Object\n- projectileOwner: Object\n- pos: Array format PositionASL\n- velocity: Array format Vector3D\n- normal: Array format Vector3D\n- components: Array of Strings - the selections that were hit, in the FireGeometry LOD.\n- radius: Number - radius (size) of the hitPoint\n- surfaceType: String\n- Arma 3 v2.18 instigator: Object - shot instigator\n\n> [!IMPORTANT]\n> This event handler only triggers for direct hits and not splash damage, unlike #HitPart (Entity). For splash damage, use #HitExplosion."},{"heading":"Init (Projectile)","level":4,"markdown":"Triggered whenever a projectile is created. Cannot be used in scripts, only inside class Eventhandlers in config.\n\n```cpp\ninit = \"params ['_projectile'];\";\n```\n\n```sqf\nparams [\"_projectile\"];\n```\n\n- projectile: Object - object the event handler is assigned to"},{"heading":"MineActivated (Arma 3 v2.14)","level":4,"markdown":"Local Argument\nLocal Effect\n\n```sqf\n_projectile addEventHandler [\"MineActivated\", {\n params [\"_projectile\", \"_isActive\"];\n}];\n```\n\n- projectile: Object\n- isActive: Boolean - new active state of the mine"},{"heading":"Penetrated","level":4,"markdown":"This event fires as many times as the projectile penetrates a surface.\n\n```sqf\n_projectile addEventHandler [\"Penetrated\", {\n params [\"_projectile\", \"_hitObject\", \"_surfaceType\", \"_entryPoint\", \"_exitPoint\", \"_exitVector\"];\n}];\n```\n\n- projectile: Object\n- hitObject: Object\n- surfaceType: String - see surfaceType\n- entryPoint: Array format PositionASL - the projectile's entry point\n- exitPoint: Array format PositionASL - the projectile's exit point\n- exitVector: Array format Vector3D - speed/angle exit vector (see vectorMagnitude to obtain the speed, in metre per second)"},{"heading":"SubmunitionCreated","level":4,"markdown":"This event fires as many times as submunitions are created.\n\n```sqf\n_projectile addEventHandler [\"SubmunitionCreated\", {\n params [\"_projectile\", \"_submunitionProjectile\", \"_position\", \"_velocity\"];\n}];\n```\n\n- projectile: Object\n- subMunitionProjectile: Object\n- position: Array format PositionASL\n- velocity: Array format Vector3D"},{"heading":"Group Event Handlers (Arma 3 v2.10)","level":3,"markdown":"Commands:\n- addEventHandler\n- removeEventHandler\n- removeAllEventHandlers"},{"heading":"CombatModeChanged","level":4,"markdown":"Triggers when the group's **behaviour** changes (see behaviour, setBehaviour)\n\n```sqf\n_group addEventHandler [\"CombatModeChanged\", {\n params [\"_group\", \"_newMode\"];\n}];\n```\n\n- group: Group\n- newMode: String - see AI Behaviour (**not** Combat Modes!)"},{"heading":"CommandChanged","level":4,"markdown":"```sqf\n_group addEventHandler [\"CommandChanged\", {\n params [\"_group\", \"_newCommand\"];\n}];\n```\n\n- group: Group\n- newCommand: String, can be one of:\n\n| | |\n|---|---|\n| \"NO CMD\" | NoCommand |\n| \"WAIT\" | Wait |\n| \"ATTACK\" | Attack |\n| \"Suppress\" | Suppress |\n| \"HIDE\" | Hide |\n| \"MOVE\" | Move |\n| \"HOOK CARGO\" | HookCargo |\n| \"UNHOOK CARGO\" | UnhookCargo |\n| \"VIV GETIN\" | ViVGetIn |\n| \"VIV GETOUT\" | ViVGetOut |\n| \"VIV UNLOAD\" | ViVUnload |\n| \"HEAL\" | Heal |\n| \"REPAIR\" | Repair |\n| \"REFUEL\" | Refuel |\n| \"REARM\" | Rearm |\n| \"SUPPORT\" | Support |\n| \"JOIN\" | Join |\n| \"GET IN\" | GetIn |\n| \"FIRE\" | Fire |\n| \"GET OUT\" | GetOut |\n| \"STOP\" | Stop |\n| \"EXPECT\" | Expect |\n| \"ACTION\" | Action |\n| \"SCRIPTED\" | Scripted |\n| \"DISMISS\" | Dismiss |\n| \"HEAL SOLDIER\" | HealSoldier |\n| \"PATCH SOLDIER\" | PatchSoldier |\n| \"FIRST AID\" | FirstAid |\n| \"HEAL SELF\" | HealSoldierSelf |\n| \"ATTACK AND FIRE\" | AttackAndFire |\n| \"CARRY SOLDIER\" | CarrySoldier |\n| \"DROP CARRIED\" | DropCarried |\n| \"TAKE BAG\" | TakeBag |\n| \"ASSEMBLE\" | Assemble |\n| \"DISASSEMBLE\" | DisAssemble |\n| \"DROP BAG\" | DropBag |\n| \"OPEN BAG\" | OpenBag |\n| \"IRLASER ON\" | IRLaserOn |\n| \"IRLASER OFF\" | IRLaserOff |\n| \"GUN LIGHT ON\" | GunLightOn |\n| \"GUN LIGHT OFF\" | GunLightOff |\n| \"FIRE AT POSITION\" | FireAtPosition |\n| \"REPAIR VEHICLE\" | RepairVehicle |\n| \"OPEN PARA\" | OpenParachute |\n| \"KEEP DEPTH LEADER\" | KeepDepthLeader |\n| \"KEEP DEPTH UND SURF\" | KeepDepthUnderSurface |\n| \"KEEP DEPTH ABV SURF\" | KeepDepthAboveSurface |\n| \"KEEP DEPTH BOTTOM\" | KeepDepthBottom |\n| \"PUT IN\" | PutIn |\n| \"UNLOAD FROM\" | UnloadFrom |\n| \"USE CONTAINER MAGAZINE\" | UseContainerMagazine |\n| \"ACTIVATE MINE\" | ActivateMine |\n| \"DISABLE MINE\" | DisableMine |"},{"heading":"Deleted (Group)","level":4,"markdown":"```sqf\n_group addEventHandler [\"Deleted\", {\n params [\"_group\"];\n}];\n```\n\n- group: Group"},{"heading":"Empty","level":4,"markdown":"```sqf\n_group addEventHandler [\"Empty\", {\n params [\"_group\"];\n}];\n```\n\n- group: Group"},{"heading":"EnableAttackChanged","level":4,"markdown":"```sqf\n_group addEventHandler [\"EnableAttackChanged\", {\n params [\"_group\", \"_attackEnabled\"];\n}];\n```\n\n- group: Group\n- attackEnabled: Boolean"},{"heading":"EnemyDetected","level":4,"markdown":"```sqf\n_group addEventHandler [\"EnemyDetected\", {\n params [\"_group\", \"_newTarget\"];\n}];\n```\n\n- group: Group\n- newTarget: Object"},{"heading":"Fleeing","level":4,"markdown":"```sqf\n_group addEventHandler [\"Fleeing\", {\n params [\"_group\", \"_fleeingNow\"];\n}];\n```\n\n- group: Group\n- fleeingNow: Boolean"},{"heading":"FormationChanged","level":4,"markdown":"```sqf\n_group addEventHandler [\"FormationChanged\", {\n params [\"_group\", \"_newFormation\"];\n}];\n```\n\n- group: Group\n- newFormation: String - see setFormation"},{"heading":"GroupIdChanged","level":4,"markdown":"```sqf\n_group addEventHandler [\"GroupIdChanged\", {\n params [\"_group\", \"_newGroupId\"];\n}];\n```\n\n- group: Group\n- newGroupId: String"},{"heading":"KnowsAboutChanged","level":4,"markdown":"```sqf\n_group addEventHandler [\"KnowsAboutChanged\", {\n params [\"_group\", \"_targetUnit\", \"_newKnowsAbout\", \"_oldKnowsAbout\"];\n}];\n```\n\n- group: Group\n- targetUnit: Object\n- newKnowsAbout: Number\n- oldKnowsAbout: Number"},{"heading":"LeaderChanged","level":4,"markdown":"```sqf\n_group addEventHandler [\"LeaderChanged\", {\n params [\"_group\", \"_newLeader\"];\n}];\n```\n\n- group: Group\n- newLeader: Object"},{"heading":"Local (Group)","level":4,"markdown":"```sqf\n_group addEventHandler [\"Local\", {\n params [\"_group\", \"_isLocal\"];\n}];\n```\n\n- group: Group"},{"heading":"SpeedModeChanged","level":4,"markdown":"```sqf\n_group addEventHandler [\"SpeedModeChanged\", {\n params [\"_group\", \"_newSpeedMode\"];\n}];\n```\n\n- group: Group\n- newSpeedMode: String - see setSpeedMode"},{"heading":"UnitJoined","level":4,"markdown":"```sqf\n_group addEventHandler [\"UnitJoined\", {\n params [\"_group\", \"_newUnit\"];\n}];\n```\n\n- group: Group\n- newUnit: Object"},{"heading":"UnitKilled (Arma 3 v2.18)","level":4,"markdown":"Local Argument\n\nTriggered when a unit in the group is killed.\n\n```sqf\n_group addEventHandler [\"UnitKilled\", {\n params [\"_group\", \"_unit\", \"_killer\", \"_instigator\", \"_useEffects\"];\n}];\n```\n\n- group: Group - the group the event handler is assigned to\n- unit: Object - the unit that was killed\n- killer: Object - the object that killed the unit. Contains the unit itself in case of collisions.\n- instigator: Object - the person who pulled the trigger\n- useEffects: Boolean - same as *useEffects* in setDamage alt syntax"},{"heading":"UnitLeft","level":4,"markdown":"```sqf\n_group addEventHandler [\"UnitLeft\", {\n params [\"_group\", \"_oldUnit\"];\n}];\n```\n\n- group: Group\n- oldUnit: Object"},{"heading":"VehicleAdded","level":4,"markdown":"```sqf\n_group addEventHandler [\"VehicleAdded\", {\n params [\"_group\", \"_newVehicle\"];\n}];\n```\n\n- group: Group\n- newVehicle: Object"},{"heading":"VehicleRemoved","level":4,"markdown":"```sqf\n_group addEventHandler [\"VehicleRemoved\", {\n params [\"_group\", \"_oldVehicle\"];\n}];\n```\n\n- group: Group\n- oldVehicle: Object"},{"heading":"WaypointComplete","level":4,"markdown":"```sqf\n_group addEventHandler [\"WaypointComplete\", {\n params [\"_group\", \"_waypointIndex\"];\n}];\n```\n\n- group: Group\n- waypointIndex: Number"},{"heading":"Game UI Event Handlers","level":3,"markdown":"In Game UI Event Handlers trigger when user scrolls or activates in game action menu.\n\nThe following mission EHs are available in Arma 3:\n- PrevAction - action menu scroll up event\n- Action - action menu action event\n- NextAction - action menu scroll down event\n\n> [!IMPORTANT]\n> Only one event of each kind can exist, adding another will overwrite the existing one.\n\nCommands:\n- inGameUISetEventHandler\n\n> [!NOTE]\n> See Arma 3: Event Handlers/inGameUISetEventHandler."},{"heading":"Control/Display UI Event Handlers","level":3,"markdown":"Commands:\n- ctrlAddEventHandler\n- ctrlRemoveEventHandler\n- ctrlRemoveAllEventHandlers\n- displayAddEventHandler\n- displayRemoveEventHandler\n- displayRemoveAllEventHandlers\n\n> [!NOTE]\n> See User Interface Event Handlers."},{"heading":"Music Event Handlers","level":3,"markdown":"Music event handler, always executed on the computer where it was added.\n\n> [!NOTE]\n> Does not apply to interface-less machines (dedicated server, headless client).\n\nCommands:\n- setMusicEventHandler\n- addMusicEventHandler\n- removeMusicEventHandler\n- removeAllMusicEventHandlers"},{"heading":"MusicStart (Arma 3 v0.50)","level":4,"markdown":"Triggers when CfgMusic sound starts playing, after being executed with playMusic command.\n\n```sqf\naddMusicEventHandler [\"MusicStart\", {\n params [\"_musicClassname\", \"_eventHandlerID\", \"_currentPosition\", \"_totalLength\"];\n}];\n```\n\n- musicClassName: String - CfgMusic class name of the music that started\n- eventHandlerID: Number - EH id returned by addMusicEventHandler\n- Arma 3 v2.18 currentPosition: Number - current playback position in 0...1 range (see also: getMusicPlayedTime)\n- Arma 3 v2.18 totalLength: Number - track total length in seconds"},{"heading":"MusicStop (Arma 3 v0.50)","level":4,"markdown":"Triggers when CfgMusic sound finished playing, after being executed with playMusic command.\n\nArma 3 v2.14 `playMusic \"\"` triggers this event if a music is currently playing.\n\n```sqf\naddMusicEventHandler [\"MusicStop\", {\n params [\"_musicClassname\", \"_eventHandlerID\", \"_currentPosition\", \"_totalLength\"];\n}];\n```\n\n- musicClassName: String - CfgMusic class name of the music that stopped\n- eventHandlerID: Number - EH id returned by addMusicEventHandler\n- Arma 3 v2.18 currentPosition: Number - current playback position in 0...1 range (see also: getMusicPlayedTime)\n- Arma 3 v2.18 totalLength: Number - track total length in seconds"},{"heading":"Eden Editor","level":3,"markdown":"Commands:\n- add3DENEventHandler\n- remove3DENEventHandler\n- removeAll3DENEventHandlers\n\n> [!NOTE]\n> See also:\n> - Arma 3: Event Handlers: Eden Editor\n> - its sub-category Object Event Handlers\n> - Eden Editor"},{"heading":"Public Variable Broadcast Event","level":3,"markdown":"Commands:\n- addPublicVariableEventHandler\n\nTriggers when missionNamespace variable EH is associated with is sent over network via publicVariable, publicVariableServer or publicVariableClient commands.\n\n> [!NOTE]\n> Unlike with other types of EHs, there is no way of removing added public variable event handler"},{"heading":"Weapon Muzzle Config Events","level":3,"markdown":"There are six event handlers that can be set on weapon in config. Their parameters are the same as their entity EH equivalents.\n- \"Fired\" - when muzzle fired - see Fired\n- \"Reload\" - before muzzle is reloaded - see MagazineReloading\n- \"Reloaded\" - after muzzle is reloaded - see Reloaded\n- \"MagazineUnloaded\" - when the magazine is removed - see MagazineUnloaded\n- \"WeaponChanged\" - when the weapon is switched to or from - see WeaponChanged\n- \"SlotItemChanged\" - when one of the weapon's attachments is changed - see SlotItemChanged\n\n```cpp\nclass CfgWeapons\n{\n class RifleCore;\n class TAG_Rifle : RifleCore\n {\n class EventHandlers\n {\n fired = \"systemChat format ['fired weapon EH output: %1 [time: %2]', _this, time]\";\n reload = \"systemChat format ['reload weapon EH output: %1 [time: %2]', _this, time]\";\n reloaded = \"systemChat format ['reloaded weapon EH output: %1 [time: %2]', _this, time]\";\n magazineunloaded = \"systemChat format ['magazineunloaded weapon EH output: %1 [time: %2]', _this, time]\";\n slotitemchanged = \"systemChat format ['slotitemchanged weapon EH output: %1 [time: %2]', _this, time]\";\n weaponchanged = \"systemChat format ['weaponchanged weapon EH output: %1 [time: %2]', _this, time]\";\n };\n };\n};\n```"},{"heading":"Ammo Config Events","level":3,"markdown":"There are three event handlers that can be set on ammo in config:\n- \"init\" - when the ammo is created, by any mean (fired, created, etc). Params: [shot]\n- \"fired\" - when the ammo is fired (legacy). Params: same as in entity EH \"Fired\".\n- \"ammoHit\" - when the ammo hits anything (can trigger multiple times). Params: [shot, shooter, hitobj, pos, velocity, hitComponents, [hit, indirecthit, indirecthitrange, explosive, name], normal, explode, instigator (since Arma 3 v2.18)]\n\n```cpp\nclass CfgAmmo\n{\n class BulletCore;\n class TAG_Bullet : BulletCore\n {\n class EventHandlers\n {\n init = \"systemChat format ['init ammo EH output: %1 [time: %2]', _this, time]\";\n fired = \"systemChat format ['fired ammo EH output: %1 [time: %2]', _this, time]\";\n ammoHit = \"systemChat format ['ammoHit EH output: %1 [time: %2]', _this, time]\";\n };\n };\n};\n```"},{"heading":"BI Scripted Events","level":3,"markdown":"Commands:\n- BIS_fnc_addScriptedEventHandler\n- BIS_fnc_removeScriptedEventHandler\n- BIS_fnc_removeAllScriptedEventHandlers\n- BIS_fnc_callScriptedEventHandler\n\n> [!NOTE]\n> See also Arma 3: Scripted Event Handlers.\n\nJump to the top of the page"}],"categories":["Event Handlers"],"groups":["Event Handlers"]},{"name":"Arma 3: Functions Library","title":"Arma 3: Functions Library","type":"topic","url":"https://community.bistudio.com/wiki/Arma_3:_Functions_Library","revid":379070,"updated":"2026-09-25T10:49:19Z","aliases":["Arma 3 Functions Library","CfgFunctions","Functions Library (Arma 3)"],"markdown":"Arma 3's **Functions Library** is the way to declare mission, campaign or addon's Functions. The main difference from older Function Libraries is that it runs automatically and does not require a Functions module.\n\nThe advantages of using the Functions Library over e.g execVM an SQF file are as follow:\n1. **Automatic compilation upon mission start** into a global variable - no need to remember direct paths to files.\n1. **Anti-hack protection** using compileFinal (see Arma 3: Writing a Function#Recompiling and BIS_fnc_recompile)\n1. **Listing in the Functions Viewer**\n1. **Advanced debugging options**\n1. **Optional immediate execution upon mission start**, without need for manual call\n1. **Potential performance improvements**\n\n> [!IMPORTANT]\n> This page is about Arma 3 Functions Library.\n> - For Arma 2/Arma 2:OA, see Arma 2: Functions Library.\n> - For Take On Helicopters, see Take On Helicopters: Functions Library.\n\n### Function Declaration\n\nFunctions are configured within the `CfgFunctions` class.\n\nMission and campaign specific functions can be configured in Description.ext/Campaign Description.ext, while addon functions are defined in Config.cpp.\nConfiguration structure is the same in both cases.\n\n> [!NOTE]\n> The root directory (noted as **** on this page) is the origin from which the game will try to load function files. It depends on `CfgFunctions`' location:\n> - if Description.ext, **** means the mission's root directory\n> - if Campaign Description.ext, **** means the campaign's root directory\n> - if in config, **** means the **game**'s root directory. The addon path needs to be set manually.\n\nSee a basic example config:\n class **CfgFunctions**\n {\n \tclass TAG\n \t{\n \t\tclass Category\n \t\t{\n \t\t\tclass functionName {};\n \t\t};\n \t};\n };\n- The function's name will be **TAG**_fnc_**functionName**\n- The function will be loaded:\n - from config: `****\\Category\\**fn_**functionName**.sqf**`\n - from description.ext: `****\\**functions**\\Category\\**fn_**functionName**.sqf**`\n\n> [!IMPORTANT]\n> **config.cpp only**:\n> - `` in mods is defined by the `file` mandatory attribute - see the #file section below.\n> - Anywhere outside of running mission, refer to the functions stored in uiNamespace. e.g: \n>\n> ```sqf\n> arguments call (uiNamespace getVariable \"TAG_fnc_functionName\");\n> ```\n\n#### Config Levels\n\nA **CfgFunctions** config is made of three levels: Tag, Category, and Function.\n\n##### Tag\n\nTo prevent duplicates, every author must create a subclass with a unique tag and create functions under it.\nThe tag name will be used when composing a function name (e.g **BIS**_fnc_spawnGroup).\n class CfgFunctions\n {\n \tclass TAG\n \t{\n \t\tclass Category\n \t\t{\n \t\t\tclass myFunction {};\n \t\t};\n \t};\n\n \tclass TAG_WeaponManagement\n \t{\n \t\t**tag** = \"TAG\"; `// the function will be named **TAG_fnc_myOtherFunction**`\n \t\tclass Category\n \t\t{\n \t\t\tclass myOtherFunction {};\n \t\t};\n \t};\n };\n\n###### Attributes\n\n###### tag\n\nThe `tag` attribute can override the config tag set differently.\n\n##### Category\n\nThe category name changes the function's category in the Functions Viewer. It does not change the function's name, only the loading path.\n class CfgFunctions\n {\n \tclass TAG\n \t{\n \t\tclass Category\n \t\t{\n \t\t\tclass myFunction {};\n \t\t};\n\n \t\tclass OtherCategory\n \t\t{\n \t\t\t**file** = \"My\\Category\\Path\";\n \t\t\tclass myFunction {}; `// file path will be ****\\My\\Category\\Path\\fn_myFunction.sqf\";`\n \t\t};\n\n \t\tclass DataCategory\n \t\t{\n \t\t\t**requiredAddons[]** = { \"A3_Data_F\" }; `// Optional requirements of CfgPatches classes. If some addons are missing, category functions will not be compiled.`\n \t\t\tclass myDataFunction {};\n \t\t};\n \t};\n };\n\n###### Attributes\n\n###### file\n\nThe `file` attribute can override the category's loading path segment - it is required for mods.\n\n###### requiredAddons\n\nThe category can skip loading if a required addon is missing by setting its dependency with the `requiredAddons` attribute.\n\n##### Function\n\n> [!NOTE]\n> By convention, the function class should be named in **camelCase** and not have its first letter capitalised (e.g PascalCase):\n> - ✓ TAG_fnc_myFunction\n> - ✗ TAG_fnc_MyFunction\n> - ✓ TAG_fnc_POWRescue\n\n class CfgFunctions\n {\n \tclass TAG\n \t{\n \t\tclass Category1\n \t\t{\n \t\t\tclass myFunction {};\n \t\t};\n\n \t\tclass Category2\n \t\t{\n \t\t\tfile = \"Path\\To\\Category\";\n \t\t\tclass myFunction\n \t\t\t{\n \t\t\t\t**file** = \"My\\Function\\Filepath.sqf\"; `// file path will be ****\\My\\Function\\Filepath.sqf\", ignoring \"Path\\To\\Category\"`\n \t\t\t};\n\n \t\t\tclass myFSMFunction\n \t\t\t{\n \t\t\t\t**preInit**\t\t= 1;\n \t\t\t\t**postInit**\t= 1;\n \t\t\t\t**ext**\t\t\t= \".fsm\";\n \t\t\t\t**preStart**\t= 1;\n \t\t\t\t**recompile**\t= 1;\n \t\t\t};\n \t\t};\n \t};\n };\n\n###### Attributes\n\n| Attribute | Description | Available in | |\n|---|---|---|---|\n| Description.ext | config.cpp | | |\n| file | the `file` attribute can be used to manually set the file path.** on this page) is the origin from which the game will try to load function files. It depends on `CfgFunctions`' location:\n> - if Description.ext, **** means the mission's root directory\n> - if Campaign Description.ext, **** means the campaign's root directory\n> - if in config, **** means the **game**'s root directory. The addon path needs to be set manually.\n\nSee a basic example config:\n class **CfgFunctions**\n {\n \tclass TAG\n \t{\n \t\tclass Category\n \t\t{\n \t\t\tclass functionName {};\n \t\t};\n \t};\n };\n- The function's name will be **TAG**_fnc_**functionName**\n- The function will be loaded:\n - from config: `****\\Category\\**fn_**functionName**.sqf**`\n - from description.ext: `****\\**functions**\\Category\\**fn_**functionName**.sqf**`\n\n> [!IMPORTANT]\n> **config.cpp only**:\n> - `` in mods is defined by the `file` mandatory attribute - see the #file section below.\n> - Anywhere outside of running mission, refer to the functions stored in uiNamespace. e.g: \n>\n> ```sqf\n> arguments call (uiNamespace getVariable \"TAG_fnc_functionName\");\n> ```"},{"heading":"Config Levels","level":4,"markdown":"A **CfgFunctions** config is made of three levels: Tag, Category, and Function."},{"heading":"Tag","level":5,"markdown":"To prevent duplicates, every author must create a subclass with a unique tag and create functions under it.\nThe tag name will be used when composing a function name (e.g **BIS**_fnc_spawnGroup).\n class CfgFunctions\n {\n \tclass TAG\n \t{\n \t\tclass Category\n \t\t{\n \t\t\tclass myFunction {};\n \t\t};\n \t};\n\n \tclass TAG_WeaponManagement\n \t{\n \t\t**tag** = \"TAG\"; `// the function will be named **TAG_fnc_myOtherFunction**`\n \t\tclass Category\n \t\t{\n \t\t\tclass myOtherFunction {};\n \t\t};\n \t};\n };"},{"heading":"Attributes","level":6,"markdown":""},{"heading":"tag","level":6,"markdown":"The `tag` attribute can override the config tag set differently."},{"heading":"Category","level":5,"markdown":"The category name changes the function's category in the Functions Viewer. It does not change the function's name, only the loading path.\n class CfgFunctions\n {\n \tclass TAG\n \t{\n \t\tclass Category\n \t\t{\n \t\t\tclass myFunction {};\n \t\t};\n\n \t\tclass OtherCategory\n \t\t{\n \t\t\t**file** = \"My\\Category\\Path\";\n \t\t\tclass myFunction {}; `// file path will be ****\\My\\Category\\Path\\fn_myFunction.sqf\";`\n \t\t};\n\n \t\tclass DataCategory\n \t\t{\n \t\t\t**requiredAddons[]** = { \"A3_Data_F\" }; `// Optional requirements of CfgPatches classes. If some addons are missing, category functions will not be compiled.`\n \t\t\tclass myDataFunction {};\n \t\t};\n \t};\n };"},{"heading":"Attributes","level":6,"markdown":""},{"heading":"file","level":6,"markdown":"The `file` attribute can override the category's loading path segment - it is required for mods."},{"heading":"requiredAddons","level":6,"markdown":"The category can skip loading if a required addon is missing by setting its dependency with the `requiredAddons` attribute."},{"heading":"Function","level":5,"markdown":"> [!NOTE]\n> By convention, the function class should be named in **camelCase** and not have its first letter capitalised (e.g PascalCase):\n> - ✓ TAG_fnc_myFunction\n> - ✗ TAG_fnc_MyFunction\n> - ✓ TAG_fnc_POWRescue\n\n class CfgFunctions\n {\n \tclass TAG\n \t{\n \t\tclass Category1\n \t\t{\n \t\t\tclass myFunction {};\n \t\t};\n\n \t\tclass Category2\n \t\t{\n \t\t\tfile = \"Path\\To\\Category\";\n \t\t\tclass myFunction\n \t\t\t{\n \t\t\t\t**file** = \"My\\Function\\Filepath.sqf\"; `// file path will be ****\\My\\Function\\Filepath.sqf\", ignoring \"Path\\To\\Category\"`\n \t\t\t};\n\n \t\t\tclass myFSMFunction\n \t\t\t{\n \t\t\t\t**preInit**\t\t= 1;\n \t\t\t\t**postInit**\t= 1;\n \t\t\t\t**ext**\t\t\t= \".fsm\";\n \t\t\t\t**preStart**\t= 1;\n \t\t\t\t**recompile**\t= 1;\n \t\t\t};\n \t\t};\n \t};\n };"},{"heading":"Attributes","level":6,"markdown":"| Attribute | Description | Available in | |\n|---|---|---|---|\n| Description.ext | config.cpp | | |\n| file | the `file` attribute can be used to manually set the file path.LShift +Space ). Stackable version of onCommandModeChanged.\n\n```sqf\naddMissionEventHandler [\"CommandModeChanged\", {\n params [\"_isHighCommand\", \"_isForced\"];\n}];\n```\n\n- isHighCommand: Boolean - same as `_isHighCommand` param\n- isForced: Boolean - true if command mode was forced\n\n##### ControlsShifted (Arma 3 v1.00)\n\nTriggers 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.\n\n```sqf\naddMissionEventHandler [\"ControlsShifted\", {\n params [\"_newController\", \"_oldController\", \"_vehicle\", \"_copilotEnabled\", \"_controlsUnlocked\"];\n}];\n```\n\n- newController: Object - unit currently controlling the vehicle\n- oldController: Object - unit previously controlling the vehicle\n- vehicle: Object - the vehicle for which controls shifted\n- copilotEnabled: Boolean - true if copilot is enabled\n- controlsUnlocked: Boolean - true if controls are unlocked\n\n##### DisplayOpened (Arma 3 v2.22)\n\nExecutes when any display is opened.\n\n```sqf\naddMissionEventHandler [\"DisplayOpened\", {\n params [\"_display\", \"_configClass\"];\n}];\n```\n\n- display: Display\n- configClass: Config\n\n##### Draw2D (Arma 3 v2.18)\n\nRuns after all UI has been drawn. Runs the EH code each frame in unscheduled environment. Client side EH only (presence of UI).\nWill stop executing when UI loses focus (Alt +Tab for example). Usually used with drawIcon.\n\n```sqf\naddMissionEventHandler [\"Draw2D\", {\n // no params\n}];\n```\n\n##### Draw3D (Arma 3 v0.50)\n\nRuns the EH code each frame in unscheduled environment. Client side EH only (presence of UI).\nWill stop executing when UI loses focus (Alt +Tab for example). Usually used with drawIcon3D, drawLine3D.\n\n```sqf\naddMissionEventHandler [\"Draw3D\", {\n // no params\n}];\n```\n\n##### Drowned (Arma 3 v2.14)\n\nRuns 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.\n\n```sqf\naddMissionEventHandler [\"Drowned\", {\n params [\"_vehicle\", \"_drowned\"];\n}];\n```\n\n##### EachFrame (Arma 3 v1.58)\n\nExecutes assigned code each frame. Stackable version of onEachFrame.\n\n```sqf\naddMissionEventHandler [\"EachFrame\", {\n // no params\n}];\n```\n\n##### Ended (Arma 3 v0.50)\n\nTriggered when mission ends, either using trigger of type \"End\", endMission command, BIS_fnc_endMission function or ENDMISSION cheat.\n\n```sqf\naddMissionEventHandler [\"Ended\", {\n params [\"_endType\"];\n}];\n```\n\n- endType: String - mission end type. Used in Debriefing among other things\n\n##### MPEnded (Arma 3 v1.60)\n\nTriggered 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.\n\n```sqf\naddMissionEventHandler [\"MPEnded\", {\n // no params\n}];\n```\n\nIf client code must be executed on disconnect, this code can be used instead:\n\n```sqf\n0 spawn\n{\n waitUntil { !isNull findDisplay 46 };\n findDisplay 46 displayAddEventHandler [\"Unload\",\n {\n // code here gets executed on the client at end of mission, whether due to player abort, loss of connection, or mission ended by server\n // might not work on headless clients\n }];\n};\n```\n\n##### EntityCreated (Arma 3 v2.10)\n\nTriggered when an entity is created.\n\n> [!NOTE]\n> 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.\n\n> [!IMPORTANT]\n> 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.\n\n```sqf\naddMissionEventHandler [\"EntityCreated\", {\n params [\"_entity\"];\n}];\n```\n\n##### EntityDeleted (Arma 3 v2.18)\n\nTriggered 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.\n\n> [!NOTE]\n> 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.\n\n```sqf\naddMissionEventHandler [\"EntityDeleted\", {\n params [\"_entity\"];\n}];\n```\n\n##### EntityKilled (Arma 3 v1.56)\n\nTriggered when an entity is killed.\n\n```sqf\naddMissionEventHandler [\"EntityKilled\", {\n params [\"_unit\", \"_killer\", \"_instigator\", \"_useEffects\"];\n}];\n```\n\n- unit: Object - entity that was killed\n- killer: Object - the killer (vehicle or person)\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n- Arma 3 v1.68 useEffects: Boolean - same as *useEffects* in setDamage alt syntax\n\n---\n\nIt's worth noting that *instigator* param is objNull during road kill. To work around this issue try:\n\n```sqf\naddMissionEventHandler [\"EntityKilled\", {\n params [\"_killed\", \"_killer\", \"_instigator\"];\n if (isNull _instigator) then { _instigator = UAVControl vehicle _killer select 0 }; // UAV/UGV player operated road kill\n if (isNull _instigator) then { _instigator = _killer }; // player driven vehicle road kill\n hint format [\"Killed By %1\", name _instigator];\n}];\n```\n\n##### EntityRespawned (Arma 3 v1.56)\n\nTriggered when an entity is respawned.\n\n```sqf\naddMissionEventHandler [\"EntityRespawned\", {\n params [\"_newEntity\", \"_oldEntity\"];\n}];\n```\n\n- newEntity: Object - respawned entity\n- oldEntity: Object - corpse/wreck\n\n##### ExtensionCallback (Arma 3 v1.96)\n\nTriggered when an extension calls provided function pointer with 3 params.\n\n```sqf\naddMissionEventHandler [\"ExtensionCallback\", {\n params [\"_name\", \"_function\", \"_data\"];\n}];\n```\n\n- name: String - user provided param\n- function: String - user provided param\n- data: String - user provided param\n\n##### GroupCreated (Arma 3 v2.04)\n\nTriggered when a Group is created. Note that the group contains **no** units at that point!\n\n```sqf\naddMissionEventHandler [\"GroupCreated\", {\n params [\"_group\"];\n}];\n```\n\n- group: Group - the created group\n\n##### GroupDeleted (Arma 3 v2.04)\n\nTriggered when a Group is manually or automatically deleted.\n\n```sqf\naddMissionEventHandler [\"GroupDeleted\", {\n params [\"_group\"];\n}];\n```\n\n- group: Group - the deleted group\n\n##### GroupIconClick (Arma 3 v1.58)\n\nExecutes 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.\n\n```sqf\naddMissionEventHandler [\"GroupIconClick\", {\n params [\n \"_is3D\", \"_group\", \"_waypointId\",\n \"_mouseButton\", \"_posX\", \"_posY\",\n \"_shift\", \"_control\", \"_alt\"\n ];\n}];\n```\n\n- is3D: Boolean - true if HUD icon, false if main map icon\n- group: Group - group the icon belonds to\n- waypointId: Number - waypoint ID\n- mouseButton: Number - mouse button: 0 - LMB , 1 - RMB (only applicable to IconClick)\n- posX: Number - screen X of the mouse\n- posY: Number - screen Y of the mouse\n- shift: Boolean - true if Shift key was pressed\n- ctrl: Boolean - true if Ctrl key was pressed\n- alt: Boolean - true if Alt key was pressed\n\n##### GroupIconOverEnter (Arma 3 v1.58)\n\n**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.\n\n```sqf\naddMissionEventHandler [\"GroupIconOverEnter\", {\n params [\n \"_is3D\", \"_group\", \"_waypointId\",\n \"_posX\", \"_posY\",\n \"_shift\", \"_control\", \"_alt\"\n ];\n}];\n```\n\n- is3D: Boolean - true if HUD icon, false if main map icon\n- group: Group - group the icon belonds to\n- waypointId: Number - waypoint ID\n- posX: Number - screen X of the mouse\n- posY: Number - screen Y of the mouse\n- shift: Boolean - true if Shift key was pressed\n- ctrl: Boolean - true if Ctrl key was pressed\n- alt: Boolean - true if Alt key was pressed\n\n##### GroupIconOverLeave (Arma 3 v1.58)\n\nExecutes 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.\n\n```sqf\naddMissionEventHandler [\"GroupIconOverLeave\", {\n params [\n \"_is3D\", \"_group\", \"_waypointId\",\n \"_posX\", \"_posY\",\n \"_shift\", \"_control\", \"_alt\"\n ];\n}];\n```\n\n- is3D: Boolean - true if HUD icon, false if main map icon\n- group: Group - group the icon belonds to\n- waypointId: Number - waypoint ID\n- posX: Number - screen X of the mouse\n- posY: Number - screen Y of the mouse (Y is always 0 when leaving HUD icon for some reason)\n- shift: Boolean - true if Shift key was pressed\n- ctrl: Boolean - true if Ctrl key was pressed\n- alt: Boolean - true if Alt key was pressed\n\n##### HandleAccTime (Arma 3 v1.90)\n\nFires 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.\n\n```sqf\naddMissionEventHandler [\"HandleAccTime\", {\n params [\"_currentTimeAcc\", \"_prevTimeAcc\", \"_messageSuppressed\"];\n}];\n```\n\n- currentTimeAcc: Number - current value\n- prevTimeAcc: Number - previous value\n- messageSuppressed: Boolean - true if on-screen message was suppressed\n\n##### HandleChatMessage (Arma 3 v2.00)\n\nFires when a message is received, before adding it to the chat feed. Fires clientside.\n\n> [!NOTE]\n> - On a dedicated server and headless client it fires only for global (channel 0) and system messages (channel 16).\n> - The HandleChatMessage EH can be used to disable/modify system messages like \"Player NAME connecting/is losing connection\".\n\n> [!IMPORTANT]\n> Does not trigger for any of the chat related script command such as systemChat, sideChat, or other chat commands.\n\nThe output message could be overridden:\n- Return true to block incoming chat message from being added to the chat feed.\n- Return String to replace the chat message content but not the sender name.\n- Return Array [from, text] to replace both the chat message content and the the sender's name.\n\n> [!IMPORTANT]\n> Only the last added HandleChatMessage EH with override will be used to override the message.\n\n> [!WARNING]\n> 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.\n\n```sqf\naddMissionEventHandler [\"HandleChatMessage\", {\n params [\"_channel\", \"_owner\", \"_from\", \"_text\", \"_person\", \"_name\", \"_strID\", \"_forcedDisplay\", \"_isPlayerMessage\", \"_sentenceType\", \"_chatMessageType\", \"_params\"];\n}];\n```\n\n- channel: Number - see radio channel indices (16 for system chat message for example)\n- owner: Number - owner id of the sender:\n - in SP: 0\n - in MP with no sender: clientOwner\n - in MP with sender: sender's clientOwner, or if AI - creator id part of netId of the AI\n- from: String - sender's formatted name as appeared on the chat\n- text: String - the chat message\n- person: Object - sender's object\n- name: String - sender's name, could be different from `from`\n- strID: String - sender's network player ID (marker id):\n - \"-1\": means not available\n - \"0\": means isPlayer in SP\n - \"1\": means AI in SP or MP\n - >1: getPlayerID in MP\n- 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)\n- isPlayerMessage: Boolean - if the message is addressed to player\n- sentenceType: Number - 0: Normal type, 1: Protocol type\n- chatMessageType: Number - 0: Generic type, 1: SimpleMove type, 2: KillConfirmation type\n- params: Array of Strings - sentence parameters, if any\n\n##### HandleDisconnect (Arma 3 v1.32 Server Execution)\n\nTriggered 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).\nSimilar to the #PlayerDisconnected event but contains the unit occupied by the player before their disconnection.\nMust be added on the server and triggers only on the server.\n\n> [!IMPORTANT]\n> A player disconnecting while not controlling a unit (not spawned, deleted unit, etc) does **not** trigger this event.\n\n```sqf\naddMissionEventHandler [\"HandleDisconnect\", {\n params [\"_unit\", \"_id\", \"_uid\", \"_name\"];\n true;\n}];\n```\n\n- unit: Object - unit formerly occupied by player\n- id: Number - same as _id in onPlayerDisconnected\n- uid: String - same as _uid in onPlayerDisconnected\n- name: String - same as _name in onPlayerDisconnected\n**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;`.\n\n##### HCGroupSelectionChanged (Arma 3 v1.58)\n\nExecutes assigned code when user selects available HC group (`F1, F2…`). Stackable version of onHCGroupSelectionChanged.\n\n```sqf\naddMissionEventHandler [\"HCGroupSelectionChanged\", {\n params [\"_group\", \"_isSelected\"];\n}];\n```\n\n- group: Group - group selected (same as `_group` param)\n- isSelected: Boolean - true if selected (same as `_isSelected` param)\n\n##### Loaded (Arma 3 v0.50)\n\nTriggered when mission is loaded from save.\n\n> [!WARNING]\n> \"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.\n\n```sqf\naddMissionEventHandler [\"Loaded\", {\n params [\"_saveType\"];\n}];\n```\n\n- savingType: String - one of \"autosaveold\", \"autosave\", \"save\", \"save2\", \"save3\", \"save4\", \"save5\", \"save6\", \"continue\" or \"\".\n - \"save\" - custom save, achieved by pressing SAVE button in the pause menu\n - \"autosave\" - automatic checkpoint, saved using saveGame command\n - \"continue\" - saved when leaving a mission to the main menu\n\n##### Map (Arma 3 v1.62)\n\nTriggered when map is opened or closed either by user action or script command openMap.\n\n```sqf\naddMissionEventHandler [\"Map\", {\n params [\"_mapIsOpened\", \"_mapIsForced\"];\n}];\n```\n\n- mapIsOpened: Boolean - true if map is opened\n- mapIsForced: Boolean - true if map is forced\n\n##### MapSingleClick (Arma 3 v1.58)\n\nExecutes 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).\n\n```sqf\naddMissionEventHandler [\"MapSingleClick\", {\n params [\"_units\", \"_pos\", \"_alt\", \"_shift\"];\n}];\n```\n\n- units: Array - leader selected units, same as groupSelectedUnits (same as onMapSingleClick's `_units` variable)\n- pos: Array - world Position3D of the click in format `[x, y, 0]` (same as onMapSingleClick's `_pos` variable)\n- alt: Boolean - true if Alt key was pressed (same as onMapSingleClick's `_alt` variable)\n- shift: Boolean - true if Shift key was pressed (same as onMapSingleClick's `_shift` variable)\n\n##### MarkerCreated (Arma 3 v2.02)\n\nExecutes when a marker is created either by a user or via script command.\n\n```sqf\naddMissionEventHandler [\"MarkerCreated\", {\n params [\"_marker\", \"_channelNumber\", \"_owner\", \"_local\"];\n}];\n```\n\n- marker: String - the name of the created marker, can be used with the marker commands\n- channelNumber: Number - channel in which the marker was created\n- owner: Object - player that created the marker or objNull\n- Arma 3 v2.04 local: Boolean - true if the event originated locally, false if it came over the network\n\n##### MarkerDeleted (Arma 3 v2.02)\n\nExecutes immediately before a marker is deleted either by a user or via script command.\n\n```sqf\naddMissionEventHandler [\"MarkerDeleted\", {\n params [\"_marker\", \"_local\", \"_deleter\"];\n}];\n```\n\n- marker: String - the name of the deleted marker\n- Arma 3 v2.04 local: Boolean - true if the event originated locally, false if it came over the network\n- Arma 3 v2.20 deleter: Object - the player/curator unit that deleted the marker\n\n##### MarkerUpdated (Arma 3 v2.02)\n\nExecutes when a marker is changed.\n\n> [!WARNING]\n> Changing the marker in the EH code will lead to an infinite loop and the game will crash!\n\n```sqf\naddMissionEventHandler [\"MarkerUpdated\", {\n params [\"_marker\", \"_local\"];\n}];\n```\n\n- marker: String - the name of the marker\n- Arma 3 v2.04 local: Boolean - true if the event originated locally, false if it came over the network\n\n##### OnUserConnected (Arma 3 v2.06 Server Execution)\n\nExecutes assigned code on user joining server.\n\n```sqf\naddMissionEventHandler [\"OnUserConnected\", {\n params [\"_networkId\", \"_clientStateNumber\", \"_clientState\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- clientStateNumber: Number - client state number (see getClientStateNumber) - always 1\n- clientState: String - client state (see getClientState) - always \"CREATED\"\n\n##### OnUserDisconnected (Arma 3 v2.06 Server Execution)\n\nExecutes assigned code on user leaving server.\n\n```sqf\naddMissionEventHandler [\"OnUserDisconnected\", {\n params [\"_networkId\", \"_clientStateNumber\", \"_clientState\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- clientStateNumber: Number - client state number (see getClientStateNumber) - always 0\n- clientState: String - client state (see getClientState) - always \"NONE\"\n\n##### OnUserClientStateChanged (Arma 3 v2.06 Server Execution)\n\nExecutes assigned code for every stage of user client state change.\n\n```sqf\naddMissionEventHandler [\"OnUserClientStateChanged\", {\n params [\"_networkId\", \"_clientStateNumber\", \"_clientState\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- clientStateNumber: Number - client state number (see getClientStateNumber)\n- clientState: String - client state (see getClientState)\n\n##### OnUserAdminStateChanged (Arma 3 v2.06 Server Execution)\n\nExecutes assigned code after user logs in, gets voted in or logs out as admin.\n\n```sqf\naddMissionEventHandler [\"OnUserAdminStateChanged\", {\n params [\"_networkId\", \"_loggedIn\", \"_votedIn\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- loggedIn: Boolean - true if user logged in or got voted in as admin, false if logged out (see admin)\n- votedIn: Boolean - true if user got voted in as admin, false otherwise (see admin)\n\n##### OnUserSelectedPlayer (Arma 3 v2.06 Server Execution)\n\nExecutes 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.\n\n```sqf\naddMissionEventHandler [\"OnUserSelectedPlayer\", {\n params [\"_networkId\", \"_playerObject\", \"_attempts\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- playerObject: Object - player object to be controlled by the user (see player, selectPlayer)\n- Arma 3 v2.18 attempts: Number - how many times server was trying to obtain non-null playerObject. Current threshold after which the event will fire anyway is 50.\n\n> [!IMPORTANT]\n> 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:\n>\n> ```sqf\n> addMissionEventHandler [\"OnUserSelectedPlayer\", {\n> params [\"_networkId\", \"_playerObject\", \"_attempts\"];\n> _playerObject addEventHandler [\"Local\",\n> {\n> params [\"_player\"];\n> _player removeEventHandler [\"Local\", _thisEventHandler];\n> // code to handle _player\n> }];\n> }];\n> ```\n>\n> Note that the player object would change locality again if the user goes to lobby.\n\n##### OnUserKicked (Arma 3 v2.06 Server Execution)\n\nExecutes assigned code after after a user has been kicked from the server providing kick reason. The possible values for 'kickTypeNumber' and 'kickType' are:\n0 : `\"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\"`\n\n```sqf\naddMissionEventHandler [\"OnUserKicked\", {\n params [\"_networkId\", \"_kickTypeNumber\", \"_kickType\", \"_kickReason\", \"_kickMessageIncReason\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- kickTypeNumber: Number - kick type number (see above)\n- kickType: String - kick type (see above)\n- kickReason: String - reason given for the kick by the admin or by other means\n- kickMessageIncReason: String - formatted engine message including the given reason\n\n##### PlayerConnected (Arma 3 v1.58 Server Execution)\n\nExecutes assigned code when client joins the mission in MP. Stackable version of onPlayerConnected.\n\n```sqf\naddMissionEventHandler [\"PlayerConnected\", {\n params [\"_id\", \"_uid\", \"_name\", \"_jip\", \"_owner\", \"_idStr\"];\n}];\n```\n\n- id: Number - unique DirectPlay ID (very large number). It is also the same id used for user placed markers\n- uid: String - getPlayerUID of the joining client. The same as Steam ID\n- name: String - profileName of the joining client\n- jip: Boolean - didJIP of the joining client\n- owner: Number - owner id of the joining client\n- idStr: String - same as `_id` but in string format, so it can be exactly compared to user marker ids\n\n> [!NOTE]\n> **0** and **1** are special values:\n> - **0** means **everyone** (including the server)\n> - **1** means **current machine** but **is not implemented** and should **not** be used.\n\nIf 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.\nIn mission's `initServer.sqf`:\n\n```sqf\naddMissionEventHandler [\"PlayerConnected\", {\n diag_log \"Client connected\";\n diag_log _this;\n}];\n```\n\nIn RPT:\n 2016/12/16, 15:39:09 \"Client connected\"\n 2016/12/16, 15:39:09 [1.51343e+009,\"7xxxxxxxxxxxxxxx1\",\"longbow\",false,3,\"1513430065\"]\n 2016/12/16, 15:39:34 Mission id: 5071d20b183e9580d0ee4f95f413ca18681d6165\n 2016/12/16, 15:39:34 \"Client connected\"\n 2016/12/16, 15:39:34 [2,\"\",\"__SERVER__\",false,2,\"2\"]\n\nThat happens only for GUI clients, if HC client connects first, EH does not fire for server.\n\nIf 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.\n\nInteresting 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)\n\n##### PlayerDisconnected (Arma 3 v1.58 Server Execution)\n\nExecutes assigned code when client leaves the mission in MP. Stackable version of onPlayerDisconnected.\n\n```sqf\naddMissionEventHandler [\"PlayerDisconnected\", {\n params [\"_id\", \"_uid\", \"_name\", \"_jip\", \"_owner\", \"_idstr\"];\n}];\n```\n\n- id: Number - unique DirectPlay ID (very large number). It is also the same id used for user placed markers (same as `_id` param)\n- uid: String - getPlayerUID of the leaving client. The same as Steam ID (same as `_uid` param)\n- name: String - profileName of the leaving client (same as `_name` param)\n- jip: Boolean - didJIP of the leaving client (same as `_jip` param)\n- owner: Number - owner id of the leaving client (same as `_owner` param)\n- idstr: String - same as id but in string format, so could be exactly compared to user marker ids\n\n##### PlayerViewChanged (Arma 3 v1.66)\n\nFired 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.\n\n```sqf\naddMissionEventHandler [\"PlayerViewChanged\", {\n params [\n \"_oldUnit\", \"_newUnit\", \"_vehicleIn\",\n \"_oldCameraOn\", \"_newCameraOn\", \"_uav\"\n ];\n}];\n```\n\n- oldUnit: Object - player body before EH fired\n- newUnit: Object - player body after EH fired\n- vehicleIn: Object - vehicle player is in (objNull if not in vehicle)\n- oldCameraOn: Object - cameraOn before EH fired\n- newCameraOn: Object - cameraOn after EH fired\n- uav: Object - UAV reference if player is operating one (objNull if not operating UAV)\n\n##### PreloadStarted (Arma 3 v1.58)\n\nExecutes assigned code before the mission preload screen. Stackable version of onPreloadStarted.\n\n> [!IMPORTANT]\n> This event handler also fires on client after user closes the main map.\n\n```sqf\naddMissionEventHandler [\"PreloadStarted\", {\n // no params\n}];\n```\n\n##### PreloadFinished (Arma 3 v1.58)\n\nExecutes assigned code after the mission preload screen. Stackable version of onPreloadFinished.\n\n> [!IMPORTANT]\n> This event handler also fires on client after user closes the main map.\n\n```sqf\naddMissionEventHandler [\"PreloadFinished\", {\n // no params\n}];\n```\n\n##### ProjectileCreated (Arma 3 v2.10)\n\nTriggered when a projectile is created.\n\n```sqf\naddMissionEventHandler [\"ProjectileCreated\", {\n params [\"_projectile\"];\n}];\n```\n\n##### SaveGame (Arma 3 v2.18)\n\nTriggered 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.\n\n```sqf\naddMissionEventHandler [\"SaveGame\", {\n params [\"_saveType\"];\n}];\n```\n\n- saveType: String - one of \"autosaveold\", \"autosave\", \"save\", \"save2\", \"save3\", \"save4\", \"save5\", \"save6\", \"continue\" or \"\".\n\n##### ScriptError (Arma 3 v2.14)\n\nTriggered when a script error occurs. See also the `-showScriptErrors` startup parameter.\n\n> [!NOTE]\n> Event Handlers have a recursion check. Most of them have a level limit set to **1**;\n> **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.\n\n```sqf\naddMissionEventHandler [\"ScriptError\", {\n params [\"_errorText\", \"_sourceFile\", \"_lineNumber\", \"_errorPos\", \"_content\", \"_stackTraceOutput\"];\n}];\n```\n\n- errorText: String - e.g. \"Zero Divisor\"\n- sourceFile: String - empty string if spawned Code\n- lineNumber: Number - script's line number\n- errorPos: Number - script's error byte position in the script *content*\n- content: String - the whole script's Code as String\n- stackTraceOutput: Array - see diag_stacktrace output\n\n##### ScriptSpawned (Arma 3 v2.22)\n\nExecutes when any script is spawned.\n\n```sqf\naddMissionEventHandler [\"ScriptSpawned\", {\n params [\"_data\"];\n}];\n```\n\n- _data: Array with [fileName, content, hash, parentFileName, parentLine, parentScript]\n - fileName: String - file name of the spawned script, empty when not available\n - content: String - content of the spawned script\n - hash: String - hash value of the Script Handle\n - parentFileName String - file name of the parent script, empty when not available\n - parentLine: Number - line number of the parent script\n - parentScript: String - content of the parent script\n\n##### SelectedActionPerformed\n\nRTM helicopter user action event\n\n```sqf\naddMissionEventHandler [\"SelectedActionPerformed\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality\n\n##### SelectedActionChanged\n\nRTM helicopter user action event\n\n```sqf\naddMissionEventHandler [\"SelectedActionChanged\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality\n\n##### SelectedRotorLibActionPerformed\n\nRTM helicopter user action event\n\n```sqf\naddMissionEventHandler [\"SelectedRotorLibActionPerformed\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> 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:\n>\n> 0: HelicopterAutoTrimOn\n>\n> 1: HelicopterAutoTrimOff\n>\n> 2: HelicopterTrimOn\n>\n> 3: HelicopterTrimOff\n>\n> 4: WheelsBrakeOn\n>\n> 5: WheelsBrakeOff\n\n##### SelectedRotorLibActionChanged\n\nRTM helicopter user action event\n\n```sqf\naddMissionEventHandler [\"SelectedRotorLibActionChanged\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality\n\n##### Service (Arma 3 v2.12)\n\nExecutes 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.\n\n```sqf\naddMissionEventHandler [\"Service\", {\n params [\"_serviceVehicle\", \"_servicedVehicle\", \"_serviceType\", \"_needsService\", \"_autoSupply\"];\n}];\n```\n\n- serviceVehicle: Object - service vehicle\n- servicedVehicle: Object - vehicle receiving service\n- serviceType: Number - 0 - MINOR REPAIR, 1 - REPAIR, 2 - REFUEL, 3 - REARM\n- needsService: Number - how much serviced vehicle needsSevice, 0..1 where 0 - no need, 1 - need a lot\n- autoSupply: Boolean - true if supply started by proximity, false if supply started due to user action\n\n##### TeamSwitch (Arma 3 v1.58)\n\nExecutes assigned code when player teamswitches. Stackable version of onTeamSwitch.\n\n```sqf\naddMissionEventHandler [\"TeamSwitch\", {\n params [\"_previousUnit\", \"_newUnit\"];\n}];\n```\n\n- previousUnit: Object - switching from unit (same as `_from` param)\n- newUnit: Object - switching to unit (same as `_to` param)\n\n##### UAVCrewCreated (Arma 3 v2.14)\n\nFires when UAV or UGV is assembled from Backpack after the AI crew is created\n\n```sqf\naddMissionEventHandler [\"UAVCrewCreated\", {\n params [\"_uav\", \"_driver\", \"_gunner\"];\n}];\n```\n\n- uav: Object - the assembled weapon\n- driver: Object - AI driver\n- gunner: Object - AI gunner","sections":[{"heading":null,"level":1,"markdown":"Arma 3 v0.50 Local Effect\n\nMission event handlers are specific EHs that are anchored to the running mission and automatically removed when mission is over.\nThese events fire only on the machine where they have been added.\n\nFor all other available EHs see the Event Handlers main page.\n\n> [!NOTE]\n> **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:\n>\n> - #OnUserConnected\n> - #OnUserDisconnected\n> - #OnUserClientStateChanged\n> - #OnUserAdminStateChanged\n> - #OnUserSelectedPlayer\n> - #OnUserKicked"},{"heading":"Related Commands","level":3,"markdown":"- addMissionEventHandler\n- removeMissionEventHandler\n- removeAllMissionEventHandlers"},{"heading":"Events","level":3,"markdown":""},{"heading":"ActionTargetChanged (Arma 3 v2.22)","level":5,"markdown":"Executes when action target object changes under cursor. This event handler fires before user actions are processed and added to the player.\n\n```sqf\naddMissionEventHandler [\"ActionTargetChanged\", {\n params [\"_newActionTarget\", \"_oldActionTarget\"];\n}];\n```\n\n- newActionTarget: Object\n- oldActionTarget: Object"},{"heading":"ArtilleryShellFired (Arma 3 v2.18)","level":5,"markdown":"Global Mission Event Handler. Executes each time a vehicle classified as artillery (has an artillery computer) fires a shell.\n\n```sqf\naddMissionEventHandler [\"ArtilleryShellFired\", {\n params [\"_vehicle\", \"_weapon\", \"_ammo\", \"_gunner\", \"_instigator\", \"_artilleryTarget\", \"_targetPosition\", \"_shell\"];\n}];\n```\n\n- vehicle: Object - artillery vehicle firing the shell\n- weapon: String - weapon name\n- ammo: String - ammo name\n- gunner: Object - gunner\n- instigator: Object - instigator\n- artilleryTarget: Object - artillery target object\n- targetPosition: Position - ground position the shell is aimed at\n- shell: Object - the projectile"},{"heading":"BuildingChanged (Arma 3 v1.68)","level":5,"markdown":"Fired each time a building model changes, for example due to stages of destruction.\n\n```sqf\naddMissionEventHandler [\"BuildingChanged\", {\n params [\"_from\", \"_to\", \"_isRuin\"];\n}];\n```\n\n- from: Object - building it changes from\n- to: Object - building it changes to\n- isRuin: Boolean - true if changes to ruins"},{"heading":"CommandModeChanged (Arma 3 v1.58)","level":5,"markdown":"Executes assigned code when user switches to/from High Command mode (LShift +Space ). Stackable version of onCommandModeChanged.\n\n```sqf\naddMissionEventHandler [\"CommandModeChanged\", {\n params [\"_isHighCommand\", \"_isForced\"];\n}];\n```\n\n- isHighCommand: Boolean - same as `_isHighCommand` param\n- isForced: Boolean - true if command mode was forced"},{"heading":"ControlsShifted (Arma 3 v1.00)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"ControlsShifted\", {\n params [\"_newController\", \"_oldController\", \"_vehicle\", \"_copilotEnabled\", \"_controlsUnlocked\"];\n}];\n```\n\n- newController: Object - unit currently controlling the vehicle\n- oldController: Object - unit previously controlling the vehicle\n- vehicle: Object - the vehicle for which controls shifted\n- copilotEnabled: Boolean - true if copilot is enabled\n- controlsUnlocked: Boolean - true if controls are unlocked"},{"heading":"DisplayOpened (Arma 3 v2.22)","level":5,"markdown":"Executes when any display is opened.\n\n```sqf\naddMissionEventHandler [\"DisplayOpened\", {\n params [\"_display\", \"_configClass\"];\n}];\n```\n\n- display: Display\n- configClass: Config"},{"heading":"Draw2D (Arma 3 v2.18)","level":5,"markdown":"Runs after all UI has been drawn. Runs the EH code each frame in unscheduled environment. Client side EH only (presence of UI).\nWill stop executing when UI loses focus (Alt +Tab for example). Usually used with drawIcon.\n\n```sqf\naddMissionEventHandler [\"Draw2D\", {\n // no params\n}];\n```"},{"heading":"Draw3D (Arma 3 v0.50)","level":5,"markdown":"Runs the EH code each frame in unscheduled environment. Client side EH only (presence of UI).\nWill stop executing when UI loses focus (Alt +Tab for example). Usually used with drawIcon3D, drawLine3D.\n\n```sqf\naddMissionEventHandler [\"Draw3D\", {\n // no params\n}];\n```"},{"heading":"Drowned (Arma 3 v2.14)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"Drowned\", {\n params [\"_vehicle\", \"_drowned\"];\n}];\n```"},{"heading":"EachFrame (Arma 3 v1.58)","level":5,"markdown":"Executes assigned code each frame. Stackable version of onEachFrame.\n\n```sqf\naddMissionEventHandler [\"EachFrame\", {\n // no params\n}];\n```"},{"heading":"Ended (Arma 3 v0.50)","level":5,"markdown":"Triggered when mission ends, either using trigger of type \"End\", endMission command, BIS_fnc_endMission function or ENDMISSION cheat.\n\n```sqf\naddMissionEventHandler [\"Ended\", {\n params [\"_endType\"];\n}];\n```\n\n- endType: String - mission end type. Used in Debriefing among other things"},{"heading":"MPEnded (Arma 3 v1.60)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"MPEnded\", {\n // no params\n}];\n```\n\nIf client code must be executed on disconnect, this code can be used instead:\n\n```sqf\n0 spawn\n{\n waitUntil { !isNull findDisplay 46 };\n findDisplay 46 displayAddEventHandler [\"Unload\",\n {\n // code here gets executed on the client at end of mission, whether due to player abort, loss of connection, or mission ended by server\n // might not work on headless clients\n }];\n};\n```"},{"heading":"EntityCreated (Arma 3 v2.10)","level":5,"markdown":"Triggered when an entity is created.\n\n> [!NOTE]\n> 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.\n\n> [!IMPORTANT]\n> 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.\n\n```sqf\naddMissionEventHandler [\"EntityCreated\", {\n params [\"_entity\"];\n}];\n```"},{"heading":"EntityDeleted (Arma 3 v2.18)","level":5,"markdown":"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.\n\n> [!NOTE]\n> 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.\n\n```sqf\naddMissionEventHandler [\"EntityDeleted\", {\n params [\"_entity\"];\n}];\n```"},{"heading":"EntityKilled (Arma 3 v1.56)","level":5,"markdown":"Triggered when an entity is killed.\n\n```sqf\naddMissionEventHandler [\"EntityKilled\", {\n params [\"_unit\", \"_killer\", \"_instigator\", \"_useEffects\"];\n}];\n```\n\n- unit: Object - entity that was killed\n- killer: Object - the killer (vehicle or person)\n- Arma 3 v1.66 instigator: Object - person who pulled the trigger\n- Arma 3 v1.68 useEffects: Boolean - same as *useEffects* in setDamage alt syntax\n\n---\n\nIt's worth noting that *instigator* param is objNull during road kill. To work around this issue try:\n\n```sqf\naddMissionEventHandler [\"EntityKilled\", {\n params [\"_killed\", \"_killer\", \"_instigator\"];\n if (isNull _instigator) then { _instigator = UAVControl vehicle _killer select 0 }; // UAV/UGV player operated road kill\n if (isNull _instigator) then { _instigator = _killer }; // player driven vehicle road kill\n hint format [\"Killed By %1\", name _instigator];\n}];\n```"},{"heading":"EntityRespawned (Arma 3 v1.56)","level":5,"markdown":"Triggered when an entity is respawned.\n\n```sqf\naddMissionEventHandler [\"EntityRespawned\", {\n params [\"_newEntity\", \"_oldEntity\"];\n}];\n```\n\n- newEntity: Object - respawned entity\n- oldEntity: Object - corpse/wreck"},{"heading":"ExtensionCallback (Arma 3 v1.96)","level":5,"markdown":"Triggered when an extension calls provided function pointer with 3 params.\n\n```sqf\naddMissionEventHandler [\"ExtensionCallback\", {\n params [\"_name\", \"_function\", \"_data\"];\n}];\n```\n\n- name: String - user provided param\n- function: String - user provided param\n- data: String - user provided param"},{"heading":"GroupCreated (Arma 3 v2.04)","level":5,"markdown":"Triggered when a Group is created. Note that the group contains **no** units at that point!\n\n```sqf\naddMissionEventHandler [\"GroupCreated\", {\n params [\"_group\"];\n}];\n```\n\n- group: Group - the created group"},{"heading":"GroupDeleted (Arma 3 v2.04)","level":5,"markdown":"Triggered when a Group is manually or automatically deleted.\n\n```sqf\naddMissionEventHandler [\"GroupDeleted\", {\n params [\"_group\"];\n}];\n```\n\n- group: Group - the deleted group"},{"heading":"GroupIconClick (Arma 3 v1.58)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"GroupIconClick\", {\n params [\n \"_is3D\", \"_group\", \"_waypointId\",\n \"_mouseButton\", \"_posX\", \"_posY\",\n \"_shift\", \"_control\", \"_alt\"\n ];\n}];\n```\n\n- is3D: Boolean - true if HUD icon, false if main map icon\n- group: Group - group the icon belonds to\n- waypointId: Number - waypoint ID\n- mouseButton: Number - mouse button: 0 - LMB , 1 - RMB (only applicable to IconClick)\n- posX: Number - screen X of the mouse\n- posY: Number - screen Y of the mouse\n- shift: Boolean - true if Shift key was pressed\n- ctrl: Boolean - true if Ctrl key was pressed\n- alt: Boolean - true if Alt key was pressed"},{"heading":"GroupIconOverEnter (Arma 3 v1.58)","level":5,"markdown":"**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.\n\n```sqf\naddMissionEventHandler [\"GroupIconOverEnter\", {\n params [\n \"_is3D\", \"_group\", \"_waypointId\",\n \"_posX\", \"_posY\",\n \"_shift\", \"_control\", \"_alt\"\n ];\n}];\n```\n\n- is3D: Boolean - true if HUD icon, false if main map icon\n- group: Group - group the icon belonds to\n- waypointId: Number - waypoint ID\n- posX: Number - screen X of the mouse\n- posY: Number - screen Y of the mouse\n- shift: Boolean - true if Shift key was pressed\n- ctrl: Boolean - true if Ctrl key was pressed\n- alt: Boolean - true if Alt key was pressed"},{"heading":"GroupIconOverLeave (Arma 3 v1.58)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"GroupIconOverLeave\", {\n params [\n \"_is3D\", \"_group\", \"_waypointId\",\n \"_posX\", \"_posY\",\n \"_shift\", \"_control\", \"_alt\"\n ];\n}];\n```\n\n- is3D: Boolean - true if HUD icon, false if main map icon\n- group: Group - group the icon belonds to\n- waypointId: Number - waypoint ID\n- posX: Number - screen X of the mouse\n- posY: Number - screen Y of the mouse (Y is always 0 when leaving HUD icon for some reason)\n- shift: Boolean - true if Shift key was pressed\n- ctrl: Boolean - true if Ctrl key was pressed\n- alt: Boolean - true if Alt key was pressed"},{"heading":"HandleAccTime (Arma 3 v1.90)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"HandleAccTime\", {\n params [\"_currentTimeAcc\", \"_prevTimeAcc\", \"_messageSuppressed\"];\n}];\n```\n\n- currentTimeAcc: Number - current value\n- prevTimeAcc: Number - previous value\n- messageSuppressed: Boolean - true if on-screen message was suppressed"},{"heading":"HandleChatMessage (Arma 3 v2.00)","level":5,"markdown":"Fires when a message is received, before adding it to the chat feed. Fires clientside.\n\n> [!NOTE]\n> - On a dedicated server and headless client it fires only for global (channel 0) and system messages (channel 16).\n> - The HandleChatMessage EH can be used to disable/modify system messages like \"Player NAME connecting/is losing connection\".\n\n> [!IMPORTANT]\n> Does not trigger for any of the chat related script command such as systemChat, sideChat, or other chat commands.\n\nThe output message could be overridden:\n- Return true to block incoming chat message from being added to the chat feed.\n- Return String to replace the chat message content but not the sender name.\n- Return Array [from, text] to replace both the chat message content and the the sender's name.\n\n> [!IMPORTANT]\n> Only the last added HandleChatMessage EH with override will be used to override the message.\n\n> [!WARNING]\n> 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.\n\n```sqf\naddMissionEventHandler [\"HandleChatMessage\", {\n params [\"_channel\", \"_owner\", \"_from\", \"_text\", \"_person\", \"_name\", \"_strID\", \"_forcedDisplay\", \"_isPlayerMessage\", \"_sentenceType\", \"_chatMessageType\", \"_params\"];\n}];\n```\n\n- channel: Number - see radio channel indices (16 for system chat message for example)\n- owner: Number - owner id of the sender:\n - in SP: 0\n - in MP with no sender: clientOwner\n - in MP with sender: sender's clientOwner, or if AI - creator id part of netId of the AI\n- from: String - sender's formatted name as appeared on the chat\n- text: String - the chat message\n- person: Object - sender's object\n- name: String - sender's name, could be different from `from`\n- strID: String - sender's network player ID (marker id):\n - \"-1\": means not available\n - \"0\": means isPlayer in SP\n - \"1\": means AI in SP or MP\n - >1: getPlayerID in MP\n- 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)\n- isPlayerMessage: Boolean - if the message is addressed to player\n- sentenceType: Number - 0: Normal type, 1: Protocol type\n- chatMessageType: Number - 0: Generic type, 1: SimpleMove type, 2: KillConfirmation type\n- params: Array of Strings - sentence parameters, if any"},{"heading":"HandleDisconnect (Arma 3 v1.32 Server Execution)","level":5,"markdown":"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).\nSimilar to the #PlayerDisconnected event but contains the unit occupied by the player before their disconnection.\nMust be added on the server and triggers only on the server.\n\n> [!IMPORTANT]\n> A player disconnecting while not controlling a unit (not spawned, deleted unit, etc) does **not** trigger this event.\n\n```sqf\naddMissionEventHandler [\"HandleDisconnect\", {\n params [\"_unit\", \"_id\", \"_uid\", \"_name\"];\n true;\n}];\n```\n\n- unit: Object - unit formerly occupied by player\n- id: Number - same as _id in onPlayerDisconnected\n- uid: String - same as _uid in onPlayerDisconnected\n- name: String - same as _name in onPlayerDisconnected\n**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;`."},{"heading":"HCGroupSelectionChanged (Arma 3 v1.58)","level":5,"markdown":"Executes assigned code when user selects available HC group (`F1, F2…`). Stackable version of onHCGroupSelectionChanged.\n\n```sqf\naddMissionEventHandler [\"HCGroupSelectionChanged\", {\n params [\"_group\", \"_isSelected\"];\n}];\n```\n\n- group: Group - group selected (same as `_group` param)\n- isSelected: Boolean - true if selected (same as `_isSelected` param)"},{"heading":"Loaded (Arma 3 v0.50)","level":5,"markdown":"Triggered when mission is loaded from save.\n\n> [!WARNING]\n> \"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.\n\n```sqf\naddMissionEventHandler [\"Loaded\", {\n params [\"_saveType\"];\n}];\n```\n\n- savingType: String - one of \"autosaveold\", \"autosave\", \"save\", \"save2\", \"save3\", \"save4\", \"save5\", \"save6\", \"continue\" or \"\".\n - \"save\" - custom save, achieved by pressing SAVE button in the pause menu\n - \"autosave\" - automatic checkpoint, saved using saveGame command\n - \"continue\" - saved when leaving a mission to the main menu"},{"heading":"Map (Arma 3 v1.62)","level":5,"markdown":"Triggered when map is opened or closed either by user action or script command openMap.\n\n```sqf\naddMissionEventHandler [\"Map\", {\n params [\"_mapIsOpened\", \"_mapIsForced\"];\n}];\n```\n\n- mapIsOpened: Boolean - true if map is opened\n- mapIsForced: Boolean - true if map is forced"},{"heading":"MapSingleClick (Arma 3 v1.58)","level":5,"markdown":"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).\n\n```sqf\naddMissionEventHandler [\"MapSingleClick\", {\n params [\"_units\", \"_pos\", \"_alt\", \"_shift\"];\n}];\n```\n\n- units: Array - leader selected units, same as groupSelectedUnits (same as onMapSingleClick's `_units` variable)\n- pos: Array - world Position3D of the click in format `[x, y, 0]` (same as onMapSingleClick's `_pos` variable)\n- alt: Boolean - true if Alt key was pressed (same as onMapSingleClick's `_alt` variable)\n- shift: Boolean - true if Shift key was pressed (same as onMapSingleClick's `_shift` variable)"},{"heading":"MarkerCreated (Arma 3 v2.02)","level":5,"markdown":"Executes when a marker is created either by a user or via script command.\n\n```sqf\naddMissionEventHandler [\"MarkerCreated\", {\n params [\"_marker\", \"_channelNumber\", \"_owner\", \"_local\"];\n}];\n```\n\n- marker: String - the name of the created marker, can be used with the marker commands\n- channelNumber: Number - channel in which the marker was created\n- owner: Object - player that created the marker or objNull\n- Arma 3 v2.04 local: Boolean - true if the event originated locally, false if it came over the network"},{"heading":"MarkerDeleted (Arma 3 v2.02)","level":5,"markdown":"Executes immediately before a marker is deleted either by a user or via script command.\n\n```sqf\naddMissionEventHandler [\"MarkerDeleted\", {\n params [\"_marker\", \"_local\", \"_deleter\"];\n}];\n```\n\n- marker: String - the name of the deleted marker\n- Arma 3 v2.04 local: Boolean - true if the event originated locally, false if it came over the network\n- Arma 3 v2.20 deleter: Object - the player/curator unit that deleted the marker"},{"heading":"MarkerUpdated (Arma 3 v2.02)","level":5,"markdown":"Executes when a marker is changed.\n\n> [!WARNING]\n> Changing the marker in the EH code will lead to an infinite loop and the game will crash!\n\n```sqf\naddMissionEventHandler [\"MarkerUpdated\", {\n params [\"_marker\", \"_local\"];\n}];\n```\n\n- marker: String - the name of the marker\n- Arma 3 v2.04 local: Boolean - true if the event originated locally, false if it came over the network"},{"heading":"OnUserConnected (Arma 3 v2.06 Server Execution)","level":5,"markdown":"Executes assigned code on user joining server.\n\n```sqf\naddMissionEventHandler [\"OnUserConnected\", {\n params [\"_networkId\", \"_clientStateNumber\", \"_clientState\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- clientStateNumber: Number - client state number (see getClientStateNumber) - always 1\n- clientState: String - client state (see getClientState) - always \"CREATED\""},{"heading":"OnUserDisconnected (Arma 3 v2.06 Server Execution)","level":5,"markdown":"Executes assigned code on user leaving server.\n\n```sqf\naddMissionEventHandler [\"OnUserDisconnected\", {\n params [\"_networkId\", \"_clientStateNumber\", \"_clientState\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- clientStateNumber: Number - client state number (see getClientStateNumber) - always 0\n- clientState: String - client state (see getClientState) - always \"NONE\""},{"heading":"OnUserClientStateChanged (Arma 3 v2.06 Server Execution)","level":5,"markdown":"Executes assigned code for every stage of user client state change.\n\n```sqf\naddMissionEventHandler [\"OnUserClientStateChanged\", {\n params [\"_networkId\", \"_clientStateNumber\", \"_clientState\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- clientStateNumber: Number - client state number (see getClientStateNumber)\n- clientState: String - client state (see getClientState)"},{"heading":"OnUserAdminStateChanged (Arma 3 v2.06 Server Execution)","level":5,"markdown":"Executes assigned code after user logs in, gets voted in or logs out as admin.\n\n```sqf\naddMissionEventHandler [\"OnUserAdminStateChanged\", {\n params [\"_networkId\", \"_loggedIn\", \"_votedIn\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- loggedIn: Boolean - true if user logged in or got voted in as admin, false if logged out (see admin)\n- votedIn: Boolean - true if user got voted in as admin, false otherwise (see admin)"},{"heading":"OnUserSelectedPlayer (Arma 3 v2.06 Server Execution)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"OnUserSelectedPlayer\", {\n params [\"_networkId\", \"_playerObject\", \"_attempts\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- playerObject: Object - player object to be controlled by the user (see player, selectPlayer)\n- Arma 3 v2.18 attempts: Number - how many times server was trying to obtain non-null playerObject. Current threshold after which the event will fire anyway is 50.\n\n> [!IMPORTANT]\n> 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:\n>\n> ```sqf\n> addMissionEventHandler [\"OnUserSelectedPlayer\", {\n> params [\"_networkId\", \"_playerObject\", \"_attempts\"];\n> _playerObject addEventHandler [\"Local\",\n> {\n> params [\"_player\"];\n> _player removeEventHandler [\"Local\", _thisEventHandler];\n> // code to handle _player\n> }];\n> }];\n> ```\n>\n> Note that the player object would change locality again if the user goes to lobby."},{"heading":"OnUserKicked (Arma 3 v2.06 Server Execution)","level":5,"markdown":"Executes assigned code after after a user has been kicked from the server providing kick reason. The possible values for 'kickTypeNumber' and 'kickType' are:\n0 : `\"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\"`\n\n```sqf\naddMissionEventHandler [\"OnUserKicked\", {\n params [\"_networkId\", \"_kickTypeNumber\", \"_kickType\", \"_kickReason\", \"_kickMessageIncReason\"];\n}];\n```\n\n- networkId: String - user network id (see getPlayerID, allUsers)\n- kickTypeNumber: Number - kick type number (see above)\n- kickType: String - kick type (see above)\n- kickReason: String - reason given for the kick by the admin or by other means\n- kickMessageIncReason: String - formatted engine message including the given reason"},{"heading":"PlayerConnected (Arma 3 v1.58 Server Execution)","level":5,"markdown":"Executes assigned code when client joins the mission in MP. Stackable version of onPlayerConnected.\n\n```sqf\naddMissionEventHandler [\"PlayerConnected\", {\n params [\"_id\", \"_uid\", \"_name\", \"_jip\", \"_owner\", \"_idStr\"];\n}];\n```\n\n- id: Number - unique DirectPlay ID (very large number). It is also the same id used for user placed markers\n- uid: String - getPlayerUID of the joining client. The same as Steam ID\n- name: String - profileName of the joining client\n- jip: Boolean - didJIP of the joining client\n- owner: Number - owner id of the joining client\n- idStr: String - same as `_id` but in string format, so it can be exactly compared to user marker ids\n\n> [!NOTE]\n> **0** and **1** are special values:\n> - **0** means **everyone** (including the server)\n> - **1** means **current machine** but **is not implemented** and should **not** be used.\n\nIf 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.\nIn mission's `initServer.sqf`:\n\n```sqf\naddMissionEventHandler [\"PlayerConnected\", {\n diag_log \"Client connected\";\n diag_log _this;\n}];\n```\n\nIn RPT:\n 2016/12/16, 15:39:09 \"Client connected\"\n 2016/12/16, 15:39:09 [1.51343e+009,\"7xxxxxxxxxxxxxxx1\",\"longbow\",false,3,\"1513430065\"]\n 2016/12/16, 15:39:34 Mission id: 5071d20b183e9580d0ee4f95f413ca18681d6165\n 2016/12/16, 15:39:34 \"Client connected\"\n 2016/12/16, 15:39:34 [2,\"\",\"__SERVER__\",false,2,\"2\"]\n\nThat happens only for GUI clients, if HC client connects first, EH does not fire for server.\n\nIf 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.\n\nInteresting 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)"},{"heading":"PlayerDisconnected (Arma 3 v1.58 Server Execution)","level":5,"markdown":"Executes assigned code when client leaves the mission in MP. Stackable version of onPlayerDisconnected.\n\n```sqf\naddMissionEventHandler [\"PlayerDisconnected\", {\n params [\"_id\", \"_uid\", \"_name\", \"_jip\", \"_owner\", \"_idstr\"];\n}];\n```\n\n- id: Number - unique DirectPlay ID (very large number). It is also the same id used for user placed markers (same as `_id` param)\n- uid: String - getPlayerUID of the leaving client. The same as Steam ID (same as `_uid` param)\n- name: String - profileName of the leaving client (same as `_name` param)\n- jip: Boolean - didJIP of the leaving client (same as `_jip` param)\n- owner: Number - owner id of the leaving client (same as `_owner` param)\n- idstr: String - same as id but in string format, so could be exactly compared to user marker ids"},{"heading":"PlayerViewChanged (Arma 3 v1.66)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"PlayerViewChanged\", {\n params [\n \"_oldUnit\", \"_newUnit\", \"_vehicleIn\",\n \"_oldCameraOn\", \"_newCameraOn\", \"_uav\"\n ];\n}];\n```\n\n- oldUnit: Object - player body before EH fired\n- newUnit: Object - player body after EH fired\n- vehicleIn: Object - vehicle player is in (objNull if not in vehicle)\n- oldCameraOn: Object - cameraOn before EH fired\n- newCameraOn: Object - cameraOn after EH fired\n- uav: Object - UAV reference if player is operating one (objNull if not operating UAV)"},{"heading":"PreloadStarted (Arma 3 v1.58)","level":5,"markdown":"Executes assigned code before the mission preload screen. Stackable version of onPreloadStarted.\n\n> [!IMPORTANT]\n> This event handler also fires on client after user closes the main map.\n\n```sqf\naddMissionEventHandler [\"PreloadStarted\", {\n // no params\n}];\n```"},{"heading":"PreloadFinished (Arma 3 v1.58)","level":5,"markdown":"Executes assigned code after the mission preload screen. Stackable version of onPreloadFinished.\n\n> [!IMPORTANT]\n> This event handler also fires on client after user closes the main map.\n\n```sqf\naddMissionEventHandler [\"PreloadFinished\", {\n // no params\n}];\n```"},{"heading":"ProjectileCreated (Arma 3 v2.10)","level":5,"markdown":"Triggered when a projectile is created.\n\n```sqf\naddMissionEventHandler [\"ProjectileCreated\", {\n params [\"_projectile\"];\n}];\n```"},{"heading":"SaveGame (Arma 3 v2.18)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"SaveGame\", {\n params [\"_saveType\"];\n}];\n```\n\n- saveType: String - one of \"autosaveold\", \"autosave\", \"save\", \"save2\", \"save3\", \"save4\", \"save5\", \"save6\", \"continue\" or \"\"."},{"heading":"ScriptError (Arma 3 v2.14)","level":5,"markdown":"Triggered when a script error occurs. See also the `-showScriptErrors` startup parameter.\n\n> [!NOTE]\n> Event Handlers have a recursion check. Most of them have a level limit set to **1**;\n> **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.\n\n```sqf\naddMissionEventHandler [\"ScriptError\", {\n params [\"_errorText\", \"_sourceFile\", \"_lineNumber\", \"_errorPos\", \"_content\", \"_stackTraceOutput\"];\n}];\n```\n\n- errorText: String - e.g. \"Zero Divisor\"\n- sourceFile: String - empty string if spawned Code\n- lineNumber: Number - script's line number\n- errorPos: Number - script's error byte position in the script *content*\n- content: String - the whole script's Code as String\n- stackTraceOutput: Array - see diag_stacktrace output"},{"heading":"ScriptSpawned (Arma 3 v2.22)","level":5,"markdown":"Executes when any script is spawned.\n\n```sqf\naddMissionEventHandler [\"ScriptSpawned\", {\n params [\"_data\"];\n}];\n```\n\n- _data: Array with [fileName, content, hash, parentFileName, parentLine, parentScript]\n - fileName: String - file name of the spawned script, empty when not available\n - content: String - content of the spawned script\n - hash: String - hash value of the Script Handle\n - parentFileName String - file name of the parent script, empty when not available\n - parentLine: Number - line number of the parent script\n - parentScript: String - content of the parent script"},{"heading":"SelectedActionPerformed","level":5,"markdown":"RTM helicopter user action event\n\n```sqf\naddMissionEventHandler [\"SelectedActionPerformed\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality"},{"heading":"SelectedActionChanged","level":5,"markdown":"RTM helicopter user action event\n\n```sqf\naddMissionEventHandler [\"SelectedActionChanged\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality"},{"heading":"SelectedRotorLibActionPerformed","level":5,"markdown":"RTM helicopter user action event\n\n```sqf\naddMissionEventHandler [\"SelectedRotorLibActionPerformed\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> 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:\n>\n> 0: HelicopterAutoTrimOn\n>\n> 1: HelicopterAutoTrimOff\n>\n> 2: HelicopterTrimOn\n>\n> 3: HelicopterTrimOff\n>\n> 4: WheelsBrakeOn\n>\n> 5: WheelsBrakeOff"},{"heading":"SelectedRotorLibActionChanged","level":5,"markdown":"RTM helicopter user action event\n\n```sqf\naddMissionEventHandler [\"SelectedRotorLibActionChanged\", {\n params [\"_caller\", \"_target\", \"_enumNumber\", \"_actionId\"];\n}];\n```\n\n> [!IMPORTANT]\n> Limited or non-existent functionality"},{"heading":"Service (Arma 3 v2.12)","level":5,"markdown":"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.\n\n```sqf\naddMissionEventHandler [\"Service\", {\n params [\"_serviceVehicle\", \"_servicedVehicle\", \"_serviceType\", \"_needsService\", \"_autoSupply\"];\n}];\n```\n\n- serviceVehicle: Object - service vehicle\n- servicedVehicle: Object - vehicle receiving service\n- serviceType: Number - 0 - MINOR REPAIR, 1 - REPAIR, 2 - REFUEL, 3 - REARM\n- needsService: Number - how much serviced vehicle needsSevice, 0..1 where 0 - no need, 1 - need a lot\n- autoSupply: Boolean - true if supply started by proximity, false if supply started due to user action"},{"heading":"TeamSwitch (Arma 3 v1.58)","level":5,"markdown":"Executes assigned code when player teamswitches. Stackable version of onTeamSwitch.\n\n```sqf\naddMissionEventHandler [\"TeamSwitch\", {\n params [\"_previousUnit\", \"_newUnit\"];\n}];\n```\n\n- previousUnit: Object - switching from unit (same as `_from` param)\n- newUnit: Object - switching to unit (same as `_to` param)"},{"heading":"UAVCrewCreated (Arma 3 v2.14)","level":5,"markdown":"Fires when UAV or UGV is assembled from Backpack after the AI crew is created\n\n```sqf\naddMissionEventHandler [\"UAVCrewCreated\", {\n params [\"_uav\", \"_driver\", \"_gunner\"];\n}];\n```\n\n- uav: Object - the assembled weapon\n- driver: Object - AI driver\n- gunner: Object - AI gunner"}],"categories":["Event Handlers","Introduced with Arma 3 version 0.50"],"groups":["Event Handlers"]},{"name":"Arma 3: Remote Execution","title":"Arma 3: Remote Execution","type":"topic","url":"https://community.bistudio.com/wiki/Arma_3:_Remote_Execution","revid":352065,"updated":"2024-02-01T23:24:38Z","aliases":["Arma 3 Remote Execution","Remote Execution"],"markdown":"Remote Execution is one of the cornerstones of Multiplayer Scripting in Arma 3. It is primarily needed to properly use commands that have *local effect* (Local Effect) or only take *local arguments* (Local Argument) in multiplayer.\n\n### Remote Execution Framework\n\nThe Remote Execution Framework currently consists of five commands:\n- remoteExec\n- remoteExecCall\n- remoteExecutedOwner\n- isRemoteExecuted\n- isRemoteExecutedJIP\nFurthermore, the framework encompasses an optional config entry to manage security settings: CfgRemoteExec.\n\n> [!NOTE]\n> While primarily designed and used for multiplayer, remoteExec and remoteExecCall also work in singleplayer; the behaviour is the same as in multiplayer.\n\n### Use Case Example\n\nTo understand why remote execution is needed and what it is used for, consider the following use case example: Let's say we want to use hint to display an announcement to all the players in our multiplayer mission at the same time.\n\nWe already know how to use the hint command:\n\n```sqf\nhint \"You have 5 minutes left!\"; // Normal use of hint.\n```\n\nThe problem is that hint only has *local effect*. This means that only the machine where hint is executed will display our \"You have 5 minutes left!\" message.\nBut we do not want to display our message to just a single player, we want to display our message to every player.\n\nSo in order to solve this problem, we need to make use of remote execution:\n\n```sqf\n\"You have 5 minutes left!\" remoteExec [\"hint\"]; // remote execution of hint.\n\"You have 5 minutes left!\" remoteExec [\"hint\", 0]; // identical to the line above\n```\n\nNow all machines that are taking part in our multiplayer session will execute `hint \"You have 5 minutes left!\";`, which means that our message will be displayed to every player at the same time - and we have achieved our goal.\n\n> [!NOTE]\n> If it is available, information about the multiplayer behaviour of a function / command can be found at the top of the documentation page of that function / command. Look for these icons: Local Argument, Global Argument, Local Effect, Global Effect and Server Execution. Hover above the icons to view a tooltip explaining what each icon means.\n\n### Environment\n\n| | | | |\n|---|---|---|---|\n| + Execution in Scheduled Environment | | Commands | Functions |\n| remoteExec | ✗ | ✓ | |\n| remoteExecCall | ✗ | ✗ | |\n\n### History\n\nPrior to Arma 3 v1.50 there was no engine based remote execution. The only officially supported way to execute code on a non-local machine was provided in the form of BIS_fnc_MP. This scripted framework suffered from several issues, mainly poor network traffic optimization and insufficient security control. The network traffic was optimized in Arma 3 v1.46, but the security issues of the scripted framework could not be fixed properly.\n\nTo fully address these issues, remote execution was implemented directly into the game engine, with Arma 3 v1.50 introducing two new script commands - remoteExec and remoteExecCall - as well as a new CfgRemoteExec, finally allowing for proper and secure remote execution from all machines.\n\nAs of Arma 3 v1.54, BIS_fnc_MP has been rewritten to internally use remoteExec and remoteExecCall, retaining full backwards compatibility and enabling it to work with the updated CfgRemoteExec. **Despite this, BIS_fnc_MP is now deprecated and should no longer be used!**\n\n### Advanced Techniques & Functionality Insight\n\n#### JIP Queue\n\nWhen a command or function is executed through remoteExec or remoteExecCall, it can be flagged as persistent. If it is flagged, the statement is stored in the JIP queue on the server (under its unique JIP ID). When a player joins a multiplayer session that has already started (JIP stands for *Join-In-Progress*), all entries stored in the JIP queue are executed on that player's machine.\n\n##### Overwriting JIP message in the queue\n\nEvery JIP message is stored in the queue. If you need to overwrite the JIP message with another message, use the same JIP id for the new message. This way the new message will be stored in the queue under the provided id and will overwrite the previously stored message that used the same id.\n\n##### Deleting JIP message from the queue\n\nTo remove a specific JIP message from the queue call the remoteExec with function/command name set to an empty string, the JIP id of the message you want to remove and no other params.\n\n```sqf\nremoteExec [\"\", \"JIPid\"];\n```\n\n#### Validity Verification\n\nThe validity of a remote execution request is verified in two steps:\n1. When the request is initiated (issued from a client machine)\n1. Before the server broadcasts the request\n\nIf the request is initialized directly from the server, step 1 is skipped (this also applies to hosted servers).\n\nA remote execution request has to meet the following criteria to be considered valid:\n1. The input parameters must be defined properly\n1. The function / command must exist on the machine\n1. The function / command must be allowed by CfgRemoteExec: Remote execution must either be fully allowed (`mode = 2`) or the particular function / command must be whitelisted.\n1. If JIP is used, JIP must be allowed by CfgRemoteExec (`jip = 1`)\n\nIf any of these conditions is not met, the remote execution request is blocked.\n\n### See Also\n\n- Multiplayer Scripting\n- Multiplayer Scripting Commands\n\nArma 3 Remote Execution","sections":[{"heading":null,"level":1,"markdown":"Remote Execution is one of the cornerstones of Multiplayer Scripting in Arma 3. It is primarily needed to properly use commands that have *local effect* (Local Effect) or only take *local arguments* (Local Argument) in multiplayer."},{"heading":"Remote Execution Framework","level":3,"markdown":"The Remote Execution Framework currently consists of five commands:\n- remoteExec\n- remoteExecCall\n- remoteExecutedOwner\n- isRemoteExecuted\n- isRemoteExecutedJIP\nFurthermore, the framework encompasses an optional config entry to manage security settings: CfgRemoteExec.\n\n> [!NOTE]\n> While primarily designed and used for multiplayer, remoteExec and remoteExecCall also work in singleplayer; the behaviour is the same as in multiplayer."},{"heading":"Use Case Example","level":3,"markdown":"To understand why remote execution is needed and what it is used for, consider the following use case example: Let's say we want to use hint to display an announcement to all the players in our multiplayer mission at the same time.\n\nWe already know how to use the hint command:\n\n```sqf\nhint \"You have 5 minutes left!\"; // Normal use of hint.\n```\n\nThe problem is that hint only has *local effect*. This means that only the machine where hint is executed will display our \"You have 5 minutes left!\" message.\nBut we do not want to display our message to just a single player, we want to display our message to every player.\n\nSo in order to solve this problem, we need to make use of remote execution:\n\n```sqf\n\"You have 5 minutes left!\" remoteExec [\"hint\"]; // remote execution of hint.\n\"You have 5 minutes left!\" remoteExec [\"hint\", 0]; // identical to the line above\n```\n\nNow all machines that are taking part in our multiplayer session will execute `hint \"You have 5 minutes left!\";`, which means that our message will be displayed to every player at the same time - and we have achieved our goal.\n\n> [!NOTE]\n> If it is available, information about the multiplayer behaviour of a function / command can be found at the top of the documentation page of that function / command. Look for these icons: Local Argument, Global Argument, Local Effect, Global Effect and Server Execution. Hover above the icons to view a tooltip explaining what each icon means."},{"heading":"Environment","level":3,"markdown":"| | | | |\n|---|---|---|---|\n| + Execution in Scheduled Environment | | Commands | Functions |\n| remoteExec | ✗ | ✓ | |\n| remoteExecCall | ✗ | ✗ | |"},{"heading":"History","level":3,"markdown":"Prior to Arma 3 v1.50 there was no engine based remote execution. The only officially supported way to execute code on a non-local machine was provided in the form of BIS_fnc_MP. This scripted framework suffered from several issues, mainly poor network traffic optimization and insufficient security control. The network traffic was optimized in Arma 3 v1.46, but the security issues of the scripted framework could not be fixed properly.\n\nTo fully address these issues, remote execution was implemented directly into the game engine, with Arma 3 v1.50 introducing two new script commands - remoteExec and remoteExecCall - as well as a new CfgRemoteExec, finally allowing for proper and secure remote execution from all machines.\n\nAs of Arma 3 v1.54, BIS_fnc_MP has been rewritten to internally use remoteExec and remoteExecCall, retaining full backwards compatibility and enabling it to work with the updated CfgRemoteExec. **Despite this, BIS_fnc_MP is now deprecated and should no longer be used!**"},{"heading":"Advanced Techniques & Functionality Insight","level":3,"markdown":""},{"heading":"JIP Queue","level":4,"markdown":"When a command or function is executed through remoteExec or remoteExecCall, it can be flagged as persistent. If it is flagged, the statement is stored in the JIP queue on the server (under its unique JIP ID). When a player joins a multiplayer session that has already started (JIP stands for *Join-In-Progress*), all entries stored in the JIP queue are executed on that player's machine."},{"heading":"Overwriting JIP message in the queue","level":5,"markdown":"Every JIP message is stored in the queue. If you need to overwrite the JIP message with another message, use the same JIP id for the new message. This way the new message will be stored in the queue under the provided id and will overwrite the previously stored message that used the same id."},{"heading":"Deleting JIP message from the queue","level":5,"markdown":"To remove a specific JIP message from the queue call the remoteExec with function/command name set to an empty string, the JIP id of the message you want to remove and no other params.\n\n```sqf\nremoteExec [\"\", \"JIPid\"];\n```"},{"heading":"Validity Verification","level":4,"markdown":"The validity of a remote execution request is verified in two steps:\n1. When the request is initiated (issued from a client machine)\n1. Before the server broadcasts the request\n\nIf the request is initialized directly from the server, step 1 is skipped (this also applies to hosted servers).\n\nA remote execution request has to meet the following criteria to be considered valid:\n1. The input parameters must be defined properly\n1. The function / command must exist on the machine\n1. The function / command must be allowed by CfgRemoteExec: Remote execution must either be fully allowed (`mode = 2`) or the particular function / command must be whitelisted.\n1. If JIP is used, JIP must be allowed by CfgRemoteExec (`jip = 1`)\n\nIf any of these conditions is not met, the remote execution request is blocked."},{"heading":"See Also","level":3,"markdown":"- Multiplayer Scripting\n- Multiplayer Scripting Commands\n\nArma 3 Remote Execution"}],"categories":["Arma 3: Remote Execution","Introduced with Arma 3 version 1.50"],"groups":["Scripting"]},{"name":"Arma 3: Scripted Event Handlers","title":"Arma 3: Scripted Event Handlers","type":"topic","url":"https://community.bistudio.com/wiki/Arma_3:_Scripted_Event_Handlers","revid":378628,"updated":"2026-05-15T10:43:40Z","aliases":["Arma 3: Event Handlers/ScriptedEventHandlers"],"markdown":"Scripted Event Handlers are triggered by some of BI's modules and functions. When triggered any code registered for one of these events via BIS_fnc_addScriptedEventHandler will be executed.\nAll the events exists as variables within a namespace, whether this is one of the main Namespaces like missionNamespace or uiNamespace or it could be a specific namespace like a Group or Object etc.\nThe event also has a set of parameters passed to the executed code.\nYou can even implement your own scripted eventHandlers by using BIS_fnc_callScriptedEventHandler.\nFor all other available Event Handlers, see Arma 3: Event Handlers.\n\n### Functions\n\n- BIS_fnc_addScriptedEventHandler\n- BIS_fnc_removeScriptedEventHandler\n- BIS_fnc_removeAllScriptedEventHandlers\n- BIS_fnc_callScriptedEventHandler\n\n### Examples\n\n#### Subscribe\n\n```sqf\n[missionNamespace, \"localPlayerNearFourArmedRobot\", {\n hint \"Hello there\";\n}] call BIS_fnc_addScriptedEventHandler;\n```\n\n```sqf\n[missionNamespace, \"arsenalOpened\", {\n hint \"Player opened the Arsenal\"; // hint message to the player when he opens the Arsenal\n}] call BIS_fnc_addScriptedEventHandler;\n```\n\n#### Trigger\n\n```sqf\nwaitUntil { sleep 1; player distance _GG < 10 };\n[missionNamespace, \"localPlayerNearFourArmedRobot\", [player, _GG]] call BIS_fnc_callScriptedEventHandler;\n```\n\n### Events\n\nThis is a list of all available scripted events that exist through BI's functions and modules.\nEach event is listed under the system that calls them whether this be a specific function or a module. List last updated for Arma 3 v2.10\n\n| Event namespace | Event name | Event passed parameters |\n|---|---|---|\n| #### EG Spectator Display | | |\n| ```sqf Description: Parameter(s): 0: can be one of: - - 1: - (Optional, default ) Returns: Examples: */` | `/* Author: Karel Moricky Description: Ends mission with specific ending. Parameter(s): 0: can be one of: STRING - (Optional, default \"end1\") end name ARRAY in format [endName, ID] - will be assembled as \"endName_ID\" string 1: BOOLEAN - (Optional, default true) true to end mission, false to fail mission 2: (Optional, default true) can be one of: BOOLEAN - true for signature closing shot (default: true) NUMBER - duration of a simple fade out to black Returns: BOOLEAN Example: [] call BIS_fnc_endMission */` |\n\n### Taking Arguments\n\nArguments are the only way to interact with a function. Let's now see how to make sure they are loaded properly.\n\nHere is this very simple function which will let a unit watch a position:\n\n```sqf\nparams [\"_unit\", \"_target\"];\n_unit doWatch _target;\n```\n\nExpected way how to call the function is by correctly defining all arguments:\n\n| | |\n|---|---|\n| ✓ | ```sqf Description: Parameter(s): 0: can be one of: - - 1: - (Optional, default ) Returns: Examples: */` | `/* Author: Karel Moricky Description: Ends mission with specific ending. Parameter(s): 0: can be one of: STRING - (Optional, default \"end1\") end name ARRAY in format [endName, ID] - will be assembled as \"endName_ID\" string 1: BOOLEAN - (Optional, default true) true to end mission, false to fail mission 2: (Optional, default true) can be one of: BOOLEAN - true for signature closing shot (default: true) NUMBER - duration of a simple fade out to black Returns: BOOLEAN Example: [] call BIS_fnc_endMission */` |"},{"heading":"Taking Arguments","level":3,"markdown":"Arguments are the only way to interact with a function. Let's now see how to make sure they are loaded properly.\n\nHere is this very simple function which will let a unit watch a position:\n\n```sqf\nparams [\"_unit\", \"_target\"];\n_unit doWatch _target;\n```\n\nExpected way how to call the function is by correctly defining all arguments:\n\n| | |\n|---|---|\n| ✓ | ```sqfRed text \"`) |\n\nExample:\n\n```sqf\nplaySound \"wolf1\"; // class name as string\nplayer say [\"wolf1\", 100];\n```\n\n> [!NOTE]\n> See [OFP ToadLife's tutorial](http://ofp.toadlife.net/downloads/tutorials/tutorial_sound/tutorial_sound.html) for a sound advice.\n\n##### CfgUnitInsignia (Arma 3 v1.24)\n\nDefine custom unit insignia (shoulder patches). See Arma 3: Unit Insignia for more detailed information.\n\n```cpp\nclass CfgUnitInsignia\n{\n class 111thID\n {\n displayName = \"111th Infantry Division\"; // name displayed in Arsenal\n author = \"Bohemia Interactive\"; // author displayed in Arsenal\n texture = \"\\a3\\UI_F_Bootcamp\\Data\\CfgUnitInsignia\\B_111thID_texture_ca.paa\"; // image path\n textureVehicle = \"\"; // does nothing, was reserved for future use\n };\n};\n```\n\n##### CfgUnitTemplates (Arma 3 v1.50)\n\nThis class is used to create units templates. For now, this is only used with the function BIS_fnc_unitHeadgear.\n\n```cpp\nclass CfgUnitTemplates\n{\n // Classic selectRandom\n class MyFirstTemplate : Default\n {\n headgearList[] =\n {\n \"H_Cap_blk\",\n \"H_Cap_grn\",\n \"H_Cap_oli_hs\"\n };\n\n facewearList[] =\n {\n \"G_Bandanna_beast\",\n \"G_Bandanna_blk\",\n \"G_Bandanna_khk\"\n };\n };\n\n // the probabilities will be considered, weighted random\n class MySecondTemplate : Default\n {\n headgearList[] =\n {\n \"H_Cap_blk\", 0.9,\n \"H_Cap_grn\", 0.6,\n \"H_Cap_oli_hs\", 0.55\n };\n\n facewearList[] =\n {\n \"G_Bandanna_beast\", 0.5,\n \"G_Bandanna_blk\", 0.5,\n \"G_Bandanna_khk\", 0.5\n };\n };\n};\n```\n\nExample:\n\n```sqf\n[myUnit, \"MyFirstTemplate\"] call BIS_fnc_unitHeadgear;\n[myUnit, \"MySecondTemplate\"] call BIS_fnc_unitHeadgear;\n```\n\n##### CfgVehicles (Arma 3 v1.70)\n\nThis class can only be used to create sound sources.\n\nSee also #CfgSFX for more detailed information.\n\n```cpp\nclass CfgVehicles\n{\n class MyOwlSound // class name to be used with createSoundSource\n {\n sound = \"MyOwl\"; // reference to CfgSFX class\n };\n};\n```\n\n##### CfgVehicleTemplates (Arma 3 v1.42)\n\nThis class is used to create vehicle templates used by the Vehicle Customisation system.\n\n```cpp\nclass CfgVehicleTemplates\n{\n class BIS_Offroad_01_default\n {\n displayName = \"Default\";\n author = \"Bohemia Interactive\";\n textureList[] =\n {\n \"guerilla_01\", 0.5,\n \"guerilla_02\", 1\n };\n\n animationList[] =\n {\n \"HideBumper1\", 1,\n \"HideBumper2\", 1\n };\n };\n};\n```\n\n##### RscTitles\n\nThis class is used to define custom HUDs. See Arma: GUI Configuration for more information.","sections":[{"heading":null,"level":1,"markdown":"The Description.ext file is a missionConfigFile and is used to set the overall mission attributes or to define global properties that will be available for other scripts.\nIt is placed in the mission root folder and uses the same syntax as the config.cpp file, but supports only a limited number of config classes.\n\nAdditionally, many attributes can also be set via the Eden Editor, where changes are automatically refreshed upon scenario preview.\nIn the 2D Editor the mission has to be reloaded for changes to be applied.\n\n> [!NOTE]\n> This file is required in Operation Flashpoint: Elite for MP missions to work, otherwise a **-1 error** is shown.\n\n> [!NOTE]\n> This page is about the **Mission Description.ext**. For the campaign version, see Campaign Description.ext.\n\n> [!WARNING]\n> The keyword `class` for class definitions **must** be lowercase, otherwise a parsing error will occur.\n\n> [!IMPORTANT]\n> Accidentally creating this file with a wrong file extension is a frequent cause of issues.\n> If you are unfamiliar with script file creation, read Introduction to Arma Scripting#File Creation for a step-by-step tutorial.\n\n> [!NOTE]\n> **Arma 3:** Since Arma 3 v2.02, it is possible to import a class from main config and inherit from it in mission config:\n>\n> ```cpp\n> import RscText;\n> class MyText : RscText\n> {\n> // ...\n> };\n> ```\n>\n> For more information, see the import (Config) page."},{"heading":"Mission Information","level":3,"markdown":"This section helps you find out how to customise Mission overall external appearance, from Mission Overview to Loading Screens.\n\n**Loading screen parameters**\n\n```cpp\nauthor = \"Varanon\";\nonLoadName = \"Point Insertion\";\nonLoadMission = \"A group of NATO soldiers is tasked with sabotaging a coastal defense.\";\nloadScreen = \"images\\loadScreen.paa\";\n\nclass Header\n{\n gameType = \"Coop\"; // game type\n minPlayers = 1; // minimum number of players the mission supports\n maxPlayers = 10; // maximum number of players the mission supports\n};\n```\n\n> [!NOTE]\n> Header's `playerCountMultipleOf` entry is available in earlier titles (from Operation Flashpoint: Elite to Arma 3 1.30), allowing to setup the auto-assign team balancing factor: 1 for Coop, 2 for Versus."},{"heading":"author (Arma 3 v0.50)","level":5,"markdown":"Mission author's name. The default loading screen shows this string below the #onLoadName in a smaller font prefixed by \"by \"."},{"heading":"onLoadName (Arma 3 v0.50)","level":5,"markdown":"String (usually mission name) shown during mission loading. The string is shown in a slightly larger font above the loadScreen.\nThe #onLoadMission text is placed below the load screen and the header gameType determines the game type on top of the box."},{"heading":"onLoadMission","level":5,"markdown":"Displays a message while the mission is loading. Note that a mission that takes very little time to load will only display the message for a short time.\nIn **OFP** this is the name you see when selecting a mission in MP and also the name that is presented to the Multiplayer browser.\n\n```cpp\nonLoadMission = \"YourMissionName\";\n```"},{"heading":"loadScreen (Arma 2: Operation Arrowhead v1.50)","level":5,"markdown":"The picture to be shown while the mission is loaded. The path is relative to the mission folder. Must be in PAA file format.\n2:1 aspect ratio (different aspect are rendered correctly as well, but won't cover the whole area).\nIdeally 1024x512 pixels.\n\n```cpp\nloadScreen = \"pictures\\intro.paa\";\n```"},{"heading":"header (Armed Assault v1.00)","level":5,"markdown":"This class defines mission type and other settings displayed in the multiplayer browser.\n\n```cpp\nclass Header\n{\n gameType = \"CTF\"; // Game type\n minPlayers = 1; // minimum number of players the mission supports\n maxPlayers = 10; // maximum number of players the mission supports\n};\n```\n\nSee Multiplayer Game Types for more detailed information."},{"heading":"onLoadIntro","level":5,"markdown":"Displays a message while the intro is loading.\n\n```cpp\nonLoadIntro = \"YourMessage\";\n```"},{"heading":"onLoadMissionTime","level":5,"markdown":"Define whether you will see the time and date displayed while the mission loads. Effect unkown in Arma 3.\n\n```cpp\nonLoadMissionTime = 1; // 0: disabled - 1: enabled. Default: 1\n```"},{"heading":"onLoadIntroTime","level":5,"markdown":"Define whether you will see the time and date displayed while the intro loads.\n\n```cpp\nonLoadIntroTime = 1; // 0: disabled - 1: enabled. Default: 0\n```"},{"heading":"briefingName (Arma 3 v1.56)","level":5,"markdown":"Mission name displayed in the mission selection menu.\n\n```cpp\nbriefingName = \"TAG 1-5 CO My super mission\";\n```\n\n> [!IMPORTANT]\n> Please note that the same parameter can be defined in 3DEN in Attributes->General->Presentation->Title, but 'briefingName' from 'description.ext' has a priority. To use localized string either in 3DEN field or in 'description.ext', prefix stringtable ID with `@`."},{"heading":"CfgLoadingTexts (Take On Helicopters v1.00)","level":5,"markdown":"Define mission specific loading texts."},{"heading":"overviewPicture (Arma 3 v0.50)","level":5,"markdown":"Path to image which will be displayed when the mission is highlighted on the mission selection screen. Image should be .paa format and in 2:1 aspect ratio – ideally 1024×512 (Arma 3)."},{"heading":"overviewText (Arma 3 v0.50)","level":5,"markdown":"Text to be displayed below the #overviewPicture on the mission selection screen when the mission is available to play.\n\n> [!IMPORTANT]\n> Please note that the same parameter can be defined in 3DEN in Attributes->General->Overview->Text, but 'overviewText' from 'description.ext' has a priority. To use localized string either in 3DEN field or in 'description.ext', prefix stringtable ID with `@`.\n\n> [!IMPORTANT]\n> The text that appears at the top of an MP mission is defined in **mod** mission definition and **not** through Description.ext:\n>\n> ```cpp\n> class Mission\n> {\n> // ...\n> class Intel\n> {\n> overviewText = \"This text here\";\n> // ...\n> };\n> // ...\n> };\n> ```"},{"heading":"overviewTextLocked (Arma 3 v0.50)","level":5,"markdown":"Text to be displayed below the #overviewPicture on the mission selection screen when the mission is locked from play.\n\n> [!IMPORTANT]\n> Please note that to use localized string prefix stringtable ID with `@`."},{"heading":"onBriefingGear","level":5,"markdown":"Defines a sound (defined in #CfgSounds) that will play when accessing the gear part of the briefing. See Briefing.html.\n\n```cpp\nonBriefingGear = \"SoundName\";\n```\n\n> [!NOTE]\n> **Arma 3:** Has no effect in Arma 3."},{"heading":"onBriefingGroup","level":5,"markdown":"Defines a sound (defined in #CfgSounds) that will play when accessing the group part of the briefing. See Briefing.html.\n\n```cpp\nonBriefingGroup = \"SoundName\";\n```\n\n> [!NOTE]\n> **Arma 3:** Has no effect in Arma 3."},{"heading":"onBriefingPlan","level":5,"markdown":"Defines a sound (defined in #CfgSounds) that will play when accessing the plan part of the briefing. See Briefing.html.\n\n```cpp\nonBriefingPlan = \"SoundName\";\n```\n\n> [!NOTE]\n> **Arma 3:** Has no effect in Arma 3."},{"heading":"CfgWorlds (Arma 3 v2.02)","level":5,"markdown":"Could be used to override the following properties used on mission loading: author, description, pictureMap, pictureShot, loadingTexts[].\nIf a specific world name given as a subclass, override will happen only when this world is loading. If subclass with name Any is used, then aforementioned properties would be overridden for any world that is loading.\n\n```cpp\nclass CfgWorlds\n{\n class Any // or specific world name\n {\n author = \"author\";\n description = \"description\";\n pictureMap = \"picturepath\";\n pictureShot = \"picturepath\";\n loadingTexts[] = { \"text1\", \"text2\", \"text3\" };\n };\n};\n```"},{"heading":"Respawn/Revive","level":3,"markdown":"This section talks about respawn and revive actions.\n- for Arma 2, see First Aid.\n- for Arma 3, see Arma 3: Respawn and Arma 3: Revive.\n\n| | | |\n|---|---|---|\n| + Respawn types | | |\n| ID | Text version | Description |\n| **0** | **\"NONE\"** | No respawn |\n| **1** | **\"BIRD\"** | Respawn as a seagull |\n| **2** | **\"INSTANT\"** | Respawn just where you died. |\n| **3** | **\"BASE\"** | Respawn in base.Red text \"`) |\n\nExample:\n\n```sqf\nplaySound \"wolf1\"; // class name as string\nplayer say [\"wolf1\", 100];\n```\n\n> [!NOTE]\n> See [OFP ToadLife's tutorial](http://ofp.toadlife.net/downloads/tutorials/tutorial_sound/tutorial_sound.html) for a sound advice."},{"heading":"CfgUnitInsignia (Arma 3 v1.24)","level":5,"markdown":"Define custom unit insignia (shoulder patches). See Arma 3: Unit Insignia for more detailed information.\n\n```cpp\nclass CfgUnitInsignia\n{\n class 111thID\n {\n displayName = \"111th Infantry Division\"; // name displayed in Arsenal\n author = \"Bohemia Interactive\"; // author displayed in Arsenal\n texture = \"\\a3\\UI_F_Bootcamp\\Data\\CfgUnitInsignia\\B_111thID_texture_ca.paa\"; // image path\n textureVehicle = \"\"; // does nothing, was reserved for future use\n };\n};\n```"},{"heading":"CfgUnitTemplates (Arma 3 v1.50)","level":5,"markdown":"This class is used to create units templates. For now, this is only used with the function BIS_fnc_unitHeadgear.\n\n```cpp\nclass CfgUnitTemplates\n{\n // Classic selectRandom\n class MyFirstTemplate : Default\n {\n headgearList[] =\n {\n \"H_Cap_blk\",\n \"H_Cap_grn\",\n \"H_Cap_oli_hs\"\n };\n\n facewearList[] =\n {\n \"G_Bandanna_beast\",\n \"G_Bandanna_blk\",\n \"G_Bandanna_khk\"\n };\n };\n\n // the probabilities will be considered, weighted random\n class MySecondTemplate : Default\n {\n headgearList[] =\n {\n \"H_Cap_blk\", 0.9,\n \"H_Cap_grn\", 0.6,\n \"H_Cap_oli_hs\", 0.55\n };\n\n facewearList[] =\n {\n \"G_Bandanna_beast\", 0.5,\n \"G_Bandanna_blk\", 0.5,\n \"G_Bandanna_khk\", 0.5\n };\n };\n};\n```\n\nExample:\n\n```sqf\n[myUnit, \"MyFirstTemplate\"] call BIS_fnc_unitHeadgear;\n[myUnit, \"MySecondTemplate\"] call BIS_fnc_unitHeadgear;\n```"},{"heading":"CfgVehicles (Arma 3 v1.70)","level":5,"markdown":"This class can only be used to create sound sources.\n\nSee also #CfgSFX for more detailed information.\n\n```cpp\nclass CfgVehicles\n{\n class MyOwlSound // class name to be used with createSoundSource\n {\n sound = \"MyOwl\"; // reference to CfgSFX class\n };\n};\n```"},{"heading":"CfgVehicleTemplates (Arma 3 v1.42)","level":5,"markdown":"This class is used to create vehicle templates used by the Vehicle Customisation system.\n\n```cpp\nclass CfgVehicleTemplates\n{\n class BIS_Offroad_01_default\n {\n displayName = \"Default\";\n author = \"Bohemia Interactive\";\n textureList[] =\n {\n \"guerilla_01\", 0.5,\n \"guerilla_02\", 1\n };\n\n animationList[] =\n {\n \"HideBumper1\", 1,\n \"HideBumper2\", 1\n };\n };\n};\n```"},{"heading":"RscTitles","level":5,"markdown":"This class is used to define custom HUDs. See Arma: GUI Configuration for more information."}],"categories":["Mission Editing"],"groups":["Scripting"]},{"name":"Diary Record","title":"Diary Record","type":"topic","url":"https://community.bistudio.com/wiki/Diary_Record","revid":340880,"updated":"2023-05-13T21:43:01Z","aliases":[],"markdown":"**Description:**\nA Diary Record is created by createDiaryRecord - introduced in Arma 2.","sections":[{"heading":null,"level":1,"markdown":"**Description:**\nA Diary Record is created by createDiaryRecord - introduced in Arma 2."}],"categories":["Data Types"],"groups":["Data Types"]},{"name":"Display","title":"Display","type":"topic","url":"https://community.bistudio.com/wiki/Display","revid":149025,"updated":"2020-03-10T21:07:04Z","aliases":[],"markdown":"**Display** is a UI object that holds Dialogs and Controls. Similar to how controls are identified by IDCs, displays and dialogs are identified by IDDs. If the IDD is available, displays (and dialogs) can be accessed with findDisplay. The existence of a distinction between displays and dialogs becomes apparent at time of creation and closing. A display uses the functions createDisplay and closeDisplay, whereas a dialog uses createDialog and closeDialog.\n\nIntroduced with Armed Assault, does not refer to Cold War Crisis or Resistance.","sections":[{"heading":null,"level":1,"markdown":"**Display** is a UI object that holds Dialogs and Controls. Similar to how controls are identified by IDCs, displays and dialogs are identified by IDDs. If the IDD is available, displays (and dialogs) can be accessed with findDisplay. The existence of a distinction between displays and dialogs becomes apparent at time of creation and closing. A display uses the functions createDisplay and closeDisplay, whereas a dialog uses createDialog and closeDialog.\n\nIntroduced with Armed Assault, does not refer to Cold War Crisis or Resistance."}],"categories":["Data Types"],"groups":["Data Types"]},{"name":"Editor Object","title":"Editor Object","type":"topic","url":"https://community.bistudio.com/wiki/Editor_Object","revid":295451,"updated":"2021-11-15T22:55:04Z","aliases":[],"markdown":"## Editor Object Type\n\n**Description:**\n\nEditor objects are used in *Offline Mission Editor* (VBS2) and *Real Time Editor* for an abstract representation of what is on the map.\n\nAn editor object is a String build this way: `\"_type_x\"`, with type being the editor object's type, e.g. \"unit\", and x being the reference number. For example `\"_unit_1\"`, `\"_artillery_23\"`, `\"_marker_4\"`.\n\nIntroduced with Virtual Battlespace 2, does not refer to Operation Flashpoint, Operation Flashpoint: Resistance or Armed Assault.","sections":[{"heading":"Editor Object Type","level":2,"markdown":"**Description:**\n\nEditor objects are used in *Offline Mission Editor* (VBS2) and *Real Time Editor* for an abstract representation of what is on the map.\n\nAn editor object is a String build this way: `\"_type_x\"`, with type being the editor object's type, e.g. \"unit\", and x being the reference number. For example `\"_unit_1\"`, `\"_artillery_23\"`, `\"_marker_4\"`.\n\nIntroduced with Virtual Battlespace 2, does not refer to Operation Flashpoint, Operation Flashpoint: Resistance or Armed Assault."}],"categories":["Data Types"],"groups":["Data Types"]},{"name":"Event Scripts","title":"Event Scripts","type":"topic","url":"https://community.bistudio.com/wiki/Event_Scripts","revid":377939,"updated":"2026-01-11T17:03:24Z","aliases":["Event based scripts","Init.sqs","Initintro.sqs","init.sqf","init.sqs","onPlayerRespawn.sqf"],"markdown":"__NOTOC____NOEDITSECTION__\n\n| | | |\n|---|---|---|\n| + Default Scripts Location | Game | Path |\n| Operation Flashpoint v1.00 | `DTA/scripts.pbo` | |\n| Armed Assault v1.00 | `Ca.pbo/data/scripts` | |\n| Arma 2 v1.00 | | |\n| Arma 2: Operation Arrowhead v1.50 | | |\n| Arma 3 v1.00 | `functions_f.pbo/scripts` | |\n| Take On Helicopters v1.00 | `data_h.pbo/data/scripts` | |\n\nEvent Scripts are scripts that are executed upon specific events. Not all event scripts are executed directly by the engine.\n\nTo use an Event Script, create a file of the given name in the mission directory.\n\n| init* scripts | (on)Player* scripts | Other Scripts |\n|---|---|---|\n| - #init.sqf] do {..code..};\n\n**Second usage:**\n\nfor [\":initPhase:\",\":condition:\",\":updatePhase:\"] do {...code...};\n\nIntroduced with Armed Assault, does not refer to Cold War Crisis or Resistance.\n\n### See Also\n\nfor, Control Structures","sections":[{"heading":null,"level":1,"markdown":"**Description:**\nThis type handles 'For' cycles.\n\n**Usage of this type:**\n\nfor \"_var\" from :expr: to :expr: [step ] do {..code..};\n\n**Second usage:**\n\nfor [\":initPhase:\",\":condition:\",\":updatePhase:\"] do {...code...};\n\nIntroduced with Armed Assault, does not refer to Cold War Crisis or Resistance."},{"heading":"See Also","level":3,"markdown":"for, Control Structures"}],"categories":["Syntactical Helper Types"],"groups":["Data Types"]},{"name":"Group","title":"Group","type":"topic","url":"https://community.bistudio.com/wiki/Group","revid":330390,"updated":"2022-09-05T21:46:56Z","aliases":[],"markdown":"A group is its own data type in the scripting language. All units belong to a group. If units are linked together in the editor, they are all part of the same group. If a unit is not linked to anyone else, then it belongs to its own group.\n\n- The AI makes many decisions as an entire group, instead of on an individual unit level. For example, behavior, combat mode, and waypoints are decided on a group, not an individual level.\n- Note that empty objects do not belong to a group. Nor do empty vehicles.\n- To get the group that a unit belongs to, use the group command.\n- To get the unit that currently leads a group, use the leader command.\n- To get an array of units that are in a group, use the units command.\n\n| | | | | | | | | |\n|---|---|---|---|---|---|---|---|---|\n| Game | Operation Flashpoint v1.00 | Operation Flashpoint: Elite v1.00 | Armed Assault v1.00 | Arma 2 v1.00 | Arma 2: Operation Arrowhead v1.50 | Take On Helicopters v1.00 | Arma 3 v1.00 | Arma 3 v1.68 |\n| Max. No. of Groups per Side | 63 | 144 | 288 | | | | | |\n| Max. No. of Units per Group | 12 | ? | 10000+ | | | | | |","sections":[{"heading":null,"level":1,"markdown":"A group is its own data type in the scripting language. All units belong to a group. If units are linked together in the editor, they are all part of the same group. If a unit is not linked to anyone else, then it belongs to its own group.\n\n- The AI makes many decisions as an entire group, instead of on an individual unit level. For example, behavior, combat mode, and waypoints are decided on a group, not an individual level.\n- Note that empty objects do not belong to a group. Nor do empty vehicles.\n- To get the group that a unit belongs to, use the group command.\n- To get the unit that currently leads a group, use the leader command.\n- To get an array of units that are in a group, use the units command.\n\n| | | | | | | | | |\n|---|---|---|---|---|---|---|---|---|\n| Game | Operation Flashpoint v1.00 | Operation Flashpoint: Elite v1.00 | Armed Assault v1.00 | Arma 2 v1.00 | Arma 2: Operation Arrowhead v1.50 | Take On Helicopters v1.00 | Arma 3 v1.00 | Arma 3 v1.68 |\n| Max. No. of Groups per Side | 63 | 144 | 288 | | | | | |\n| Max. No. of Units per Group | 12 | ? | 10000+ | | | | | |"}],"categories":["Data Types"],"groups":["Data Types"]},{"name":"HashMap","title":"HashMap","type":"topic","url":"https://community.bistudio.com/wiki/HashMap","revid":339000,"updated":"2023-04-24T16:22:14Z","aliases":[],"markdown":"Arma 3 v2.02\n\nA **HashMap** is a specialized data structure that contains key-value pairs.\n\nHashMaps provide (near) constant-time lookup for keys, making them highly efficient at finding the value associated with a specific key - even if there is a very large amount of keys.\n\nSee [Wikipedia](https://en.wikipedia.org/wiki/Hash_table) to learn more about the underlying technology.\n\nWhile HashMaps and Arrays share many traits (and SQF command names), there are important differences and HashMaps must not be considered as some sort of new or improved replacement for the Array.\n\n### HashMap Basics\n\nThis section introduces the HashMap and its features and is intended to help create a basic understanding of what HashMaps are and what they can be used for.\n\n#### Comparison with Arrays\n\nThe HashMap and the Array are both data structures that are used to store multiple elements. Arrays are simple and only store single elements, one after the other, while HashMaps store key-value pairs, where each key uniquely identifies a single value.\n\nUnlike Arrays, HashMaps have no order, i.e. there is no such thing as a first, second, third or last element in a HashMap. As such, the # and select commands can not be used with HashMaps. This also means that the order in which the forEach-loop processes a HashMap's key-value pairs is not deterministic.\n\nIterating over all elements in a HashMap is less efficient than doing the same in an Array.\n\n#### Constant-time Key Lookup\n\nHashMaps are specifically designed for (near) constant-time lookup of keys.\n\nConsider the following example to understand what that means: Let's say we have an Array that looks like this:\n\n```sqf\nprivate _playerDataArray = [[\"Player_A_UID\", \"Data A-1\", \"Data A-2\" /*, ... */], [\"Player_B_UID\", \"Data B-1\", \"Data B-2\" /*, ... */], [\"Player_C_UID\", \"Data C-1\", \"Data C-2\" /*, ... */] /*, ... */];\n```\n\nWe want to find a specific UID so that we can retrieve the corresponding data. We can easily achieve that using the findIf command:\n\n```sqf\n_index = _playerDataArray findIf {_x # 0 isEqualTo \"Wanted_UID\"};\n_data = _playerDataArray # _index;\n```\n\nBut what findIf actually does for us is something like this:\n\n```sqf\n{\n if (_x # 0 isEqualTo \"Wanted_UID\") then\n {\n breakWith _forEachIndex;\n };\n} forEach _playerDataArray;\n```\n\nNow consider how many isEqualTo comparisons this forEach-loop has to perform: If the element identified by \"Wanted_UID\" is stored at or near the end of `_playerDataArray`, then our code has to go through (almost) the entire Array to find it - and the same is the case if the element we are looking for does not exist in our Array.\n\nEvery single one of these comparisons takes some time - not much, but it will add up eventually. This is no problem as long as our Array is relatively small, but it becomes a serious issue when the Array starts growing: If there are 10,000 elements in the Array that means up to 10,000 comparisons might be necessary just to find a single element, if there are 100,000 elements that means up to 100,000 comparisons and so on - the amount of steps and time needed to find an element grows linearly with the Array size.\n\nAnd this is where HashMaps come in. Simply put: When a key-value pair is inserted into a HashMap, a hash function is applied to the key to determine the position at which the key-value pair is going to be stored. Then, when we want to retrieve the value associated with a specific key, the same hash function (Arma 3 uses [FNV-1a 64-bit](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function)) is applied to that key and the resulting position tells the HashMap exactly where to find the key-value pair that we are looking for.\n\n```sqf\nprivate _data = _playerDataHashMap get \"Wanted_UID\";\n```\n\nSince the process to find a given key-value pair is always the same (apply hash function, look at the resulting position, return the value that is stored there), it also always takes (more or less) the same amount of time - regardless of the size of the HashMap.\n\nThat is what constant-time lookup for keys means. And it comes with very useful benefits: The procedures to search for, retrieve, modify or remove a specific element can all be completed in constant time; whether the HashMap contains 10, 10,000 or 1,000,000 elements does not matter.\n\n### Working with HashMaps\n\n#### Supported Key Types\n\nBecause of the requirement for the keys to be hashable (and constant), not all Data Types can be used as keys.\n\nSupported types are limited to:\n- Array\n- Boolean\n- Code\n- Config\n- Namespace\n- NaN\n- Number\n- Side\n- String\n\n> [!IMPORTANT]\n> - For some unsupported key types, such as Objects, a workaround can be used. See Unsupported Key Types.\n> - Array keys can only contain supported types.\n> - Array keys are deep-copied on insertion and cannot be modified when retrieved via keys or inside forEach.\n> - The virtual type HashMapKey is a combination of all the supported types.\n\n#### Creating a HashMap\n\n```sqf\n// example of an empty HashMap:\nprivate _myMap = createHashMap;\ncount _myMap; // returns 0\n\n// example of a prefilled HashMap:\nprivate _myFilledMap = createHashMapFromArray [[\"a\",1], [\"b\",2], [\"c\", 3]];\ncount _myFilledMap; // returns 3\n```\n\n#### Setting an element\n\n```sqf\nprivate _myMap = createHashMap;\n_myMap set [1, \"hello there\"]; // _myMap is [[1, \"hello there\"]]\n```\n\nInserting an element with a key that already exists inside the HashMap will overwrite the existing key.\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\nprivate _overwritten = _myMap set [\"a\", 1337]; // _myMap is now [[\"a\",1337], [\"b\",2]] and _overwritten is true\n```\n\n#### Getting an element\n\nValues are retrieved by their key:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\n_myMap get \"a\"; // returns 1\n_myMap get \"z\"; // returns Nothing\n_myMap getOrDefault [\"z\", \"NotFound\"]; // returns \"NotFound\"\n// alternatively\n_myMap getOrDefaultCall [\"z\", { systemChat \"key 'z' does not exist, creating it\"; \"26\"; }, true];\n```\n\n#### Removing an element\n\nElements can be removed (deleted) from the HashMap using deleteAt with the element's key:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\n_myMap deleteAt \"b\"; // _myMap is \"a\",1\n```\n\n#### Checking if an element exists\n\nIt is possible to check if a key is present in the HashMap using the in command:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\n\"a\" in _myMap; // returns true\n\"z\" in _myMap; // returns false\n```\n\n#### Counting elements\n\nThe count command can be used to return the number of key-value pairs stored in the HashMap:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\ncount _myMap ; // returns 2\n```\n\n#### Retrieving keys\n\nRetrieving an Array of all keys in the HashMap using the keys command:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\nkeys _myMap; // returns [\"a\", \"b\"]\n```\n\n#### HashMap variables\n\nA HashMap variable is a reference to the HashMap (see [Wikipedia](https://en.wikipedia.org/wiki/Reference_(computer_science))); this means that if the HashMap is edited, all scripts and functions using this HashMap will see the changes.\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2], [\"c\",3]];\nprivate _myNewMap = _myMap;\n_myMap set [\"z\", 4];\n_myNewMap get \"z\"; // returns 4\n```\n\nA HashMap set through setVariable does not need to be assigned again:\n\n```sqf\nplayer setVariable [\"myMap\", createHashMapFromArray [[\"a\",1], [\"b\",2], [\"c\",3]]];\nprivate _myMap = player getVariable \"myMap\";\n_myMap set [\"z\", 4];\nplayer getVariable \"myMap\"; // returns [[\"a\",1], [\"b\",2], [\"c\",3], [\"z\",4]]\n```\n\n#### Copying a HashMap\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\nprivate _myNewMap = _myMap;\n_myMap set [\"a\", 1337];\n_myNewMap get \"a\"; // returns 1337\n```\n\nIn order to avoid this behaviour, **copy** the HashMap with + (plus):\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\nprivate _myNewMap = +_myMap;\n_myMap set [\"a\", 1337];\n_myNewMap get \"a\"; // still 1\n```\n\nArrays stored as key or value in the HashMap will also be deep-copied.\n\n### Advanced Usage\n\n#### Iterating through a HashMap\n\nIn general, HashMaps have to be considered unordered. While iterating through them is possible with forEach, it is less efficient than looping through Arrays.\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\", 1], [\"b\", 2]];\n{ systemChat str [_x, _y] } forEach _myMap;\n```\n\nWhen iterating through a HashMap with forEach, `_x` contains the key of the current element and `_y` contains the corresponding value.\n\n#### Merging two HashMaps\n\nTwo HashMaps can be merged together using merge.\n\n```sqf\n_hashMap1 merge _hashMap2;\n```\n\n#### Unsupported Key Types\n\nFor some unsupported data types, such as Objects, the following workaround can be used, as long as they're supported by the hashValue command:\n\n```sqf\nTAG_fnc_set = {\n params [\"_hashmap\", \"_key\", \"_value\"];\n isNil {\n private _hash = hashValue _key;\n private _keyVals = _hashmap getOrDefault [_hash, [[],[]], true]; // uses an array to resolve any potential hash collision\n \n private _keyIndex = _keyVals#0 find _key;\n if (_keyIndex < 0) then {\n _keyVals#0 pushBack _key;\n _keyVals#1 pushBack _value;\n } else {\n _keyVals#1 set [_keyIndex, _value];\n };\n };\n};\nTAG_fnc_get = {\n params [\"_hashmap\", \"_key\", \"_defaultValue\"];\n private \"_return\";\n isNil { // force unscheduled check\n private _hash = hashValue _key;\n private _keyVals = _hashmap getOrDefault [_hash, [[],[]]];\n _return = _keyVals#1 param [_keyVals#0 find _key, _defaultValue];\n };\n _return;\n};\nTAG_fnc_remove = {\n params [\"_hashmap\", \"_key\"];\n isNil { // force unscheduled check\n private _hash = hashValue _key;\n private _keyVals = _hashmap getOrDefault [_hash, [[],[]]];\n private _keyIndex = _keyVals#0 find _key;\n if (_keyIndex >= 0) then {\n _keyVals#0 deleteAt _keyIndex;\n _keyVals#1 deleteAt _keyIndex;\n };\n };\n};\n\n// Example: Add the player object to hashmap (assuming player is not null)\nprivate _tempHashmap = createHashMap;\n[_tempHashmap, player, 1] call TAG_fnc_set; // add the player object as key, and 1 as its value\nprivate _value1 = [_tempHashmap, player, 2] call TAG_fnc_get; // will return 1\nprivate _value2 = [_tempHashmap, objNull, 2] call TAG_fnc_get; // will return 2, the default value\n```\n\nThe above example can be extended to add support for iterations, etc. as well.\n\n#### Automagic assignation\n\nKeys can be prefixed by an underscore so that the HashMap can be converted to private variables on-the-fly using params. This can be useful if a HashMap is kept alive for a long time and its values need to be accessed often, or to further simplify passing data between computers. Here's an example with a simple vehicle respawn system:\n\n```sqf\nprivate _vehicleHashMaps = nearestObjects [player, [\"LandVehicle\"], 50] apply\n{\n createHashMapFromArray\n [\n [\"_vehicle\", _x],\n [\"_class\", typeOf _x],\n [\"_startPos\", getPosATL _x],\n [\"_respawnTimeout\", 10*60],\n [\"_lastSeenAlive\", diag_tickTime]\n ]\n};\n\n_vehicleHashMaps spawn\n{\n while {true} do\n {\n {\n _settings = _x;\n (values _settings) params (keys _settings); // automagic assignation of each value to a private variable of its key name\n\n if (alive _vehicle) then\n {\n _settings set [\"_lastSeenAlive\", diag_tickTime];\n }\n else\n {\n if (diag_tickTime - _lastSeenAlive >= _respawnTimeout) then\n {\n deleteVehicle _vehicle;\n _vehicle = createVehicle [_class, _startPos, [], 0, \"NONE\"];\n _settings set [\"_vehicle\", _vehicle];\n _settings set [\"_lastSeenAlive\", diag_tickTime];\n };\n };\n\n sleep 1;\n } forEach _this;\n\n sleep 60;\n };\n};\n```\n\n### Common Errors\n\n#### Scalar Key Precision\n\nNumbers in Arma 3 are floating point numbers, and because there are gaps between floating point numbers, rounding is necessary - see also [Wikipedia](https://en.wikipedia.org/wiki/Single-precision_floating-point_format). For example, 87654316, 87654317, 87654318, 87654319, 87654320, 87654321, 87654322, 87654323 and 87654324 will all be rounded to and treated as the same value by the game engine (because the actual value of each of these numbers can not be represented as an Arma 3 floating point number). Similar problems occur with fractional numbers:\n\n```sqf\n// this will return false:\n(0.3 + 0.4 == 0.7)\n```\n\nThis means that using very large numbers or fractional numbers as HashMap keys has to be done cautiously to avoid accidentally overwriting existing keys.\n\n### See Also\n\n- All HashMap commands","sections":[{"heading":null,"level":1,"markdown":"Arma 3 v2.02\n\nA **HashMap** is a specialized data structure that contains key-value pairs.\n\nHashMaps provide (near) constant-time lookup for keys, making them highly efficient at finding the value associated with a specific key - even if there is a very large amount of keys.\n\nSee [Wikipedia](https://en.wikipedia.org/wiki/Hash_table) to learn more about the underlying technology.\n\nWhile HashMaps and Arrays share many traits (and SQF command names), there are important differences and HashMaps must not be considered as some sort of new or improved replacement for the Array."},{"heading":"HashMap Basics","level":3,"markdown":"This section introduces the HashMap and its features and is intended to help create a basic understanding of what HashMaps are and what they can be used for."},{"heading":"Comparison with Arrays","level":4,"markdown":"The HashMap and the Array are both data structures that are used to store multiple elements. Arrays are simple and only store single elements, one after the other, while HashMaps store key-value pairs, where each key uniquely identifies a single value.\n\nUnlike Arrays, HashMaps have no order, i.e. there is no such thing as a first, second, third or last element in a HashMap. As such, the # and select commands can not be used with HashMaps. This also means that the order in which the forEach-loop processes a HashMap's key-value pairs is not deterministic.\n\nIterating over all elements in a HashMap is less efficient than doing the same in an Array."},{"heading":"Constant-time Key Lookup","level":4,"markdown":"HashMaps are specifically designed for (near) constant-time lookup of keys.\n\nConsider the following example to understand what that means: Let's say we have an Array that looks like this:\n\n```sqf\nprivate _playerDataArray = [[\"Player_A_UID\", \"Data A-1\", \"Data A-2\" /*, ... */], [\"Player_B_UID\", \"Data B-1\", \"Data B-2\" /*, ... */], [\"Player_C_UID\", \"Data C-1\", \"Data C-2\" /*, ... */] /*, ... */];\n```\n\nWe want to find a specific UID so that we can retrieve the corresponding data. We can easily achieve that using the findIf command:\n\n```sqf\n_index = _playerDataArray findIf {_x # 0 isEqualTo \"Wanted_UID\"};\n_data = _playerDataArray # _index;\n```\n\nBut what findIf actually does for us is something like this:\n\n```sqf\n{\n if (_x # 0 isEqualTo \"Wanted_UID\") then\n {\n breakWith _forEachIndex;\n };\n} forEach _playerDataArray;\n```\n\nNow consider how many isEqualTo comparisons this forEach-loop has to perform: If the element identified by \"Wanted_UID\" is stored at or near the end of `_playerDataArray`, then our code has to go through (almost) the entire Array to find it - and the same is the case if the element we are looking for does not exist in our Array.\n\nEvery single one of these comparisons takes some time - not much, but it will add up eventually. This is no problem as long as our Array is relatively small, but it becomes a serious issue when the Array starts growing: If there are 10,000 elements in the Array that means up to 10,000 comparisons might be necessary just to find a single element, if there are 100,000 elements that means up to 100,000 comparisons and so on - the amount of steps and time needed to find an element grows linearly with the Array size.\n\nAnd this is where HashMaps come in. Simply put: When a key-value pair is inserted into a HashMap, a hash function is applied to the key to determine the position at which the key-value pair is going to be stored. Then, when we want to retrieve the value associated with a specific key, the same hash function (Arma 3 uses [FNV-1a 64-bit](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function)) is applied to that key and the resulting position tells the HashMap exactly where to find the key-value pair that we are looking for.\n\n```sqf\nprivate _data = _playerDataHashMap get \"Wanted_UID\";\n```\n\nSince the process to find a given key-value pair is always the same (apply hash function, look at the resulting position, return the value that is stored there), it also always takes (more or less) the same amount of time - regardless of the size of the HashMap.\n\nThat is what constant-time lookup for keys means. And it comes with very useful benefits: The procedures to search for, retrieve, modify or remove a specific element can all be completed in constant time; whether the HashMap contains 10, 10,000 or 1,000,000 elements does not matter."},{"heading":"Working with HashMaps","level":3,"markdown":""},{"heading":"Supported Key Types","level":4,"markdown":"Because of the requirement for the keys to be hashable (and constant), not all Data Types can be used as keys.\n\nSupported types are limited to:\n- Array\n- Boolean\n- Code\n- Config\n- Namespace\n- NaN\n- Number\n- Side\n- String\n\n> [!IMPORTANT]\n> - For some unsupported key types, such as Objects, a workaround can be used. See Unsupported Key Types.\n> - Array keys can only contain supported types.\n> - Array keys are deep-copied on insertion and cannot be modified when retrieved via keys or inside forEach.\n> - The virtual type HashMapKey is a combination of all the supported types."},{"heading":"Creating a HashMap","level":4,"markdown":"```sqf\n// example of an empty HashMap:\nprivate _myMap = createHashMap;\ncount _myMap; // returns 0\n\n// example of a prefilled HashMap:\nprivate _myFilledMap = createHashMapFromArray [[\"a\",1], [\"b\",2], [\"c\", 3]];\ncount _myFilledMap; // returns 3\n```"},{"heading":"Setting an element","level":4,"markdown":"```sqf\nprivate _myMap = createHashMap;\n_myMap set [1, \"hello there\"]; // _myMap is [[1, \"hello there\"]]\n```\n\nInserting an element with a key that already exists inside the HashMap will overwrite the existing key.\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\nprivate _overwritten = _myMap set [\"a\", 1337]; // _myMap is now [[\"a\",1337], [\"b\",2]] and _overwritten is true\n```"},{"heading":"Getting an element","level":4,"markdown":"Values are retrieved by their key:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\n_myMap get \"a\"; // returns 1\n_myMap get \"z\"; // returns Nothing\n_myMap getOrDefault [\"z\", \"NotFound\"]; // returns \"NotFound\"\n// alternatively\n_myMap getOrDefaultCall [\"z\", { systemChat \"key 'z' does not exist, creating it\"; \"26\"; }, true];\n```"},{"heading":"Removing an element","level":4,"markdown":"Elements can be removed (deleted) from the HashMap using deleteAt with the element's key:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\n_myMap deleteAt \"b\"; // _myMap is \"a\",1\n```"},{"heading":"Checking if an element exists","level":4,"markdown":"It is possible to check if a key is present in the HashMap using the in command:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\n\"a\" in _myMap; // returns true\n\"z\" in _myMap; // returns false\n```"},{"heading":"Counting elements","level":4,"markdown":"The count command can be used to return the number of key-value pairs stored in the HashMap:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\ncount _myMap ; // returns 2\n```"},{"heading":"Retrieving keys","level":4,"markdown":"Retrieving an Array of all keys in the HashMap using the keys command:\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\nkeys _myMap; // returns [\"a\", \"b\"]\n```"},{"heading":"HashMap variables","level":4,"markdown":"A HashMap variable is a reference to the HashMap (see [Wikipedia](https://en.wikipedia.org/wiki/Reference_(computer_science))); this means that if the HashMap is edited, all scripts and functions using this HashMap will see the changes.\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2], [\"c\",3]];\nprivate _myNewMap = _myMap;\n_myMap set [\"z\", 4];\n_myNewMap get \"z\"; // returns 4\n```\n\nA HashMap set through setVariable does not need to be assigned again:\n\n```sqf\nplayer setVariable [\"myMap\", createHashMapFromArray [[\"a\",1], [\"b\",2], [\"c\",3]]];\nprivate _myMap = player getVariable \"myMap\";\n_myMap set [\"z\", 4];\nplayer getVariable \"myMap\"; // returns [[\"a\",1], [\"b\",2], [\"c\",3], [\"z\",4]]\n```"},{"heading":"Copying a HashMap","level":4,"markdown":"```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\nprivate _myNewMap = _myMap;\n_myMap set [\"a\", 1337];\n_myNewMap get \"a\"; // returns 1337\n```\n\nIn order to avoid this behaviour, **copy** the HashMap with + (plus):\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\",1], [\"b\",2]];\nprivate _myNewMap = +_myMap;\n_myMap set [\"a\", 1337];\n_myNewMap get \"a\"; // still 1\n```\n\nArrays stored as key or value in the HashMap will also be deep-copied."},{"heading":"Advanced Usage","level":3,"markdown":""},{"heading":"Iterating through a HashMap","level":4,"markdown":"In general, HashMaps have to be considered unordered. While iterating through them is possible with forEach, it is less efficient than looping through Arrays.\n\n```sqf\nprivate _myMap = createHashMapFromArray [[\"a\", 1], [\"b\", 2]];\n{ systemChat str [_x, _y] } forEach _myMap;\n```\n\nWhen iterating through a HashMap with forEach, `_x` contains the key of the current element and `_y` contains the corresponding value."},{"heading":"Merging two HashMaps","level":4,"markdown":"Two HashMaps can be merged together using merge.\n\n```sqf\n_hashMap1 merge _hashMap2;\n```"},{"heading":"Unsupported Key Types","level":4,"markdown":"For some unsupported data types, such as Objects, the following workaround can be used, as long as they're supported by the hashValue command:\n\n```sqf\nTAG_fnc_set = {\n params [\"_hashmap\", \"_key\", \"_value\"];\n isNil {\n private _hash = hashValue _key;\n private _keyVals = _hashmap getOrDefault [_hash, [[],[]], true]; // uses an array to resolve any potential hash collision\n \n private _keyIndex = _keyVals#0 find _key;\n if (_keyIndex < 0) then {\n _keyVals#0 pushBack _key;\n _keyVals#1 pushBack _value;\n } else {\n _keyVals#1 set [_keyIndex, _value];\n };\n };\n};\nTAG_fnc_get = {\n params [\"_hashmap\", \"_key\", \"_defaultValue\"];\n private \"_return\";\n isNil { // force unscheduled check\n private _hash = hashValue _key;\n private _keyVals = _hashmap getOrDefault [_hash, [[],[]]];\n _return = _keyVals#1 param [_keyVals#0 find _key, _defaultValue];\n };\n _return;\n};\nTAG_fnc_remove = {\n params [\"_hashmap\", \"_key\"];\n isNil { // force unscheduled check\n private _hash = hashValue _key;\n private _keyVals = _hashmap getOrDefault [_hash, [[],[]]];\n private _keyIndex = _keyVals#0 find _key;\n if (_keyIndex >= 0) then {\n _keyVals#0 deleteAt _keyIndex;\n _keyVals#1 deleteAt _keyIndex;\n };\n };\n};\n\n// Example: Add the player object to hashmap (assuming player is not null)\nprivate _tempHashmap = createHashMap;\n[_tempHashmap, player, 1] call TAG_fnc_set; // add the player object as key, and 1 as its value\nprivate _value1 = [_tempHashmap, player, 2] call TAG_fnc_get; // will return 1\nprivate _value2 = [_tempHashmap, objNull, 2] call TAG_fnc_get; // will return 2, the default value\n```\n\nThe above example can be extended to add support for iterations, etc. as well."},{"heading":"Automagic assignation","level":4,"markdown":"Keys can be prefixed by an underscore so that the HashMap can be converted to private variables on-the-fly using params. This can be useful if a HashMap is kept alive for a long time and its values need to be accessed often, or to further simplify passing data between computers. Here's an example with a simple vehicle respawn system:\n\n```sqf\nprivate _vehicleHashMaps = nearestObjects [player, [\"LandVehicle\"], 50] apply\n{\n createHashMapFromArray\n [\n [\"_vehicle\", _x],\n [\"_class\", typeOf _x],\n [\"_startPos\", getPosATL _x],\n [\"_respawnTimeout\", 10*60],\n [\"_lastSeenAlive\", diag_tickTime]\n ]\n};\n\n_vehicleHashMaps spawn\n{\n while {true} do\n {\n {\n _settings = _x;\n (values _settings) params (keys _settings); // automagic assignation of each value to a private variable of its key name\n\n if (alive _vehicle) then\n {\n _settings set [\"_lastSeenAlive\", diag_tickTime];\n }\n else\n {\n if (diag_tickTime - _lastSeenAlive >= _respawnTimeout) then\n {\n deleteVehicle _vehicle;\n _vehicle = createVehicle [_class, _startPos, [], 0, \"NONE\"];\n _settings set [\"_vehicle\", _vehicle];\n _settings set [\"_lastSeenAlive\", diag_tickTime];\n };\n };\n\n sleep 1;\n } forEach _this;\n\n sleep 60;\n };\n};\n```"},{"heading":"Common Errors","level":3,"markdown":""},{"heading":"Scalar Key Precision","level":4,"markdown":"Numbers in Arma 3 are floating point numbers, and because there are gaps between floating point numbers, rounding is necessary - see also [Wikipedia](https://en.wikipedia.org/wiki/Single-precision_floating-point_format). For example, 87654316, 87654317, 87654318, 87654319, 87654320, 87654321, 87654322, 87654323 and 87654324 will all be rounded to and treated as the same value by the game engine (because the actual value of each of these numbers can not be represented as an Arma 3 floating point number). Similar problems occur with fractional numbers:\n\n```sqf\n// this will return false:\n(0.3 + 0.4 == 0.7)\n```\n\nThis means that using very large numbers or fractional numbers as HashMap keys has to be done cautiously to avoid accidentally overwriting existing keys."},{"heading":"See Also","level":3,"markdown":"- All HashMap commands"}],"categories":["Data Types","Introduced with Arma 3 version 2.02"],"groups":["Data Types"]},{"name":"HashMapKey","title":"HashMapKey","type":"topic","url":"https://community.bistudio.com/wiki/HashMapKey","revid":330441,"updated":"2022-09-15T21:04:29Z","aliases":[],"markdown":"HashMapKey is a virtual compound type containing all the possible types that can be used as keys in a HashMap.\n\nThe types are:\n- Number\n- Boolean\n- String\n- Code\n- Side\n- Config\n- Namespace\n- NaN\n- Array","sections":[{"heading":null,"level":1,"markdown":"HashMapKey is a virtual compound type containing all the possible types that can be used as keys in a HashMap.\n\nThe types are:\n- Number\n- Boolean\n- String\n- Code\n- Side\n- Config\n- Namespace\n- NaN\n- Array"}],"categories":["Magic Types"],"groups":["Data Types"]},{"name":"Identifier","title":"Identifier","type":"topic","url":"https://community.bistudio.com/wiki/Identifier","revid":377927,"updated":"2026-01-11T16:19:20Z","aliases":["identifier"],"markdown":"__NOTOC__\nAn Identifier is the name given to a variable that the scripter can choose: It is the name that *identifies* the variable.\n\n### Rules\n\n| | | |\n|---|---|---|\n| + Regex: `[a-zA-Z_][a-zA-Z0-9_]*` | Valid | Invalid |\n| - variable1 is sometimes encountered but is not recommended and should be avoided:\n>\n> ```sqf\n> _my_variable_name = 5;\n> ```\n\nIt is also recommended to prefix **global variable identifiers** with **your** tag in order to avoid any potential conflict between addons, scripts and missions:\n `// **Tag**_identifier`\n UNIQUETAG_player = player;\n\n### See also\n\n- Variables","sections":[{"heading":null,"level":1,"markdown":"__NOTOC__\nAn Identifier is the name given to a variable that the scripter can choose: It is the name that *identifies* the variable."},{"heading":"Rules","level":3,"markdown":"| | | |\n|---|---|---|\n| + Regex: `[a-zA-Z_][a-zA-Z0-9_]*` | Valid | Invalid |\n| - variable1 is sometimes encountered but is not recommended and should be avoided:\n>\n> ```sqf\n> _my_variable_name = 5;\n> ```\n\nIt is also recommended to prefix **global variable identifiers** with **your** tag in order to avoid any potential conflict between addons, scripts and missions:\n `// **Tag**_identifier`\n UNIQUETAG_player = player;"},{"heading":"See also","level":3,"markdown":"- Variables"}],"categories":["Syntax"],"groups":["Scripting"]},{"name":"If Type","title":"If Type","type":"topic","url":"https://community.bistudio.com/wiki/If_Type","revid":245280,"updated":"2021-02-10T14:24:06Z","aliases":[],"markdown":"**Description:**\nHelper type used in if...then construct.","sections":[{"heading":null,"level":1,"markdown":"**Description:**\nHelper type used in if...then construct."}],"categories":["Syntactical Helper Types"],"groups":["Data Types"]},{"name":"Initialisation Order","title":"Initialisation Order","type":"topic","url":"https://community.bistudio.com/wiki/Initialisation_Order","revid":373629,"updated":"2025-05-29T15:41:33Z","aliases":["Initialization Order"],"markdown":"Whenever a mission is launched (or joined in Multiplayer) certain tasks are performed to ensure the mission's various components are initialised correctly and that everyone is synced in multiplayer games (particularly JIP players).\nInitialisation order refers to the order in which those tasks are executed and it is important to take into account when setting up the start of a mission.\n\nEvent Scripts are a key part of a mission's initialisation order and will be utilised often when working with SQF.\n\n| | | |\n|---|---|---|\n| + Key | Item | Meaning |\n| | Single Player Only | |\n| | Multiplayer Only | |\n| | Order is not guaranteed | |\n\nTake note that the order of initialisation is different in single player and multiplayer environments. If an entry is unmarked then it applies to both.\n\n> [!NOTE]\n> In multiplayer the following is relevant to every machine including the server and headless clients.\n> If the server is non-dedicated then it should be considered both a server and client.\n\n### Arma 3\n\n| | | | | | | |\n|---|---|---|---|---|---|---|\n| + Order of Initialisation (From First to Last) | Task | Applies To | JIP | Related To | Exec Environment | Notes |\n| Functions with *recompile* attribute are recompiled | All | ✓ | Arma 3: Functions Library | | | |\n| Functions with *preInit* attribute are called | All | ✓ | Arma 3: Functions Library | Unscheduled | | |\n| Object Init Event Handlers are called | All | ✗ | | Unscheduled | | |\n| Expressions of Eden Editor entity attributes are called | Server | ✗ | Eden Editor: Configuring Attributes | Unscheduled | `isPlayer _entity` does not return true immediately. Once the entity has become a player, it is transfered to the client. | |\n| Object initialisation fields are called | All | ✓ | | Unscheduled | | |\n| init.sqs is executed | Singleplayer | N/A | Event Scripts | | | |\n| init.sqf is executed | Singleplayer | N/A | Event Scripts | Scheduled (ref: Note **in single player** that while the environment is Scheduled (canSuspend returns true), the engine seems to wait until the script is done executing, essentially behaving similarly to an Unscheduled environment - infinite loops will freeze the game, uiSleep may pause the game for up to ~20s (postInit), waitUntil can cause catastrophic issues, etc.) | | |\n| Expressions of Eden Editor scenario attributes are called | All | ✓ | Eden Editor: Configuring Attributes | Unscheduled | player is not available immediately. | |\n| Persistent functions are called | Client | ✓ | Arma 3: Remote Execution, BIS_fnc_MP | | | |\n| Modules are initialised | All | ✗ | | | Modules with `isTriggerActivated = 0` execute their functions in scheduled environment | |\n| initServer.sqf is executed | Server | N/A | Event Scripts | Scheduled | | |\n| initPlayerLocal.sqf is executed | Client | ✓ | Event Scripts | Scheduled | | |\n| initPlayerServer.sqf is executed on the server | Client | ✓ | Event Scripts | Scheduled | | |\n| Functions with *postInit* attribute are called | All | ✓ | Arma 3: Functions Library | Scheduled | | |\n| \"BIS_fnc_init\" variable is set to true | All | ✓ | Arma 2: Functions Library | | | |\n| init.sqs is executed | Multiplayer | ✓ | Event Scripts | Scheduled | | |\n| init.sqf is executed | Multiplayer | ✓ | Event Scripts | Scheduled | | |","sections":[{"heading":null,"level":1,"markdown":"Whenever a mission is launched (or joined in Multiplayer) certain tasks are performed to ensure the mission's various components are initialised correctly and that everyone is synced in multiplayer games (particularly JIP players).\nInitialisation order refers to the order in which those tasks are executed and it is important to take into account when setting up the start of a mission.\n\nEvent Scripts are a key part of a mission's initialisation order and will be utilised often when working with SQF.\n\n| | | |\n|---|---|---|\n| + Key | Item | Meaning |\n| | Single Player Only | |\n| | Multiplayer Only | |\n| | Order is not guaranteed | |\n\nTake note that the order of initialisation is different in single player and multiplayer environments. If an entry is unmarked then it applies to both.\n\n> [!NOTE]\n> In multiplayer the following is relevant to every machine including the server and headless clients.\n> If the server is non-dedicated then it should be considered both a server and client."},{"heading":"Arma 3","level":3,"markdown":"| | | | | | | |\n|---|---|---|---|---|---|---|\n| + Order of Initialisation (From First to Last) | Task | Applies To | JIP | Related To | Exec Environment | Notes |\n| Functions with *recompile* attribute are recompiled | All | ✓ | Arma 3: Functions Library | | | |\n| Functions with *preInit* attribute are called | All | ✓ | Arma 3: Functions Library | Unscheduled | | |\n| Object Init Event Handlers are called | All | ✗ | | Unscheduled | | |\n| Expressions of Eden Editor entity attributes are called | Server | ✗ | Eden Editor: Configuring Attributes | Unscheduled | `isPlayer _entity` does not return true immediately. Once the entity has become a player, it is transfered to the client. | |\n| Object initialisation fields are called | All | ✓ | | Unscheduled | | |\n| init.sqs is executed | Singleplayer | N/A | Event Scripts | | | |\n| init.sqf is executed | Singleplayer | N/A | Event Scripts | Scheduled (ref: Note **in single player** that while the environment is Scheduled (canSuspend returns true), the engine seems to wait until the script is done executing, essentially behaving similarly to an Unscheduled environment - infinite loops will freeze the game, uiSleep may pause the game for up to ~20s (postInit), waitUntil can cause catastrophic issues, etc.) | | |\n| Expressions of Eden Editor scenario attributes are called | All | ✓ | Eden Editor: Configuring Attributes | Unscheduled | player is not available immediately. | |\n| Persistent functions are called | Client | ✓ | Arma 3: Remote Execution, BIS_fnc_MP | | | |\n| Modules are initialised | All | ✗ | | | Modules with `isTriggerActivated = 0` execute their functions in scheduled environment | |\n| initServer.sqf is executed | Server | N/A | Event Scripts | Scheduled | | |\n| initPlayerLocal.sqf is executed | Client | ✓ | Event Scripts | Scheduled | | |\n| initPlayerServer.sqf is executed on the server | Client | ✓ | Event Scripts | Scheduled | | |\n| Functions with *postInit* attribute are called | All | ✓ | Arma 3: Functions Library | Scheduled | | |\n| \"BIS_fnc_init\" variable is set to true | All | ✓ | Arma 2: Functions Library | | | |\n| init.sqs is executed | Multiplayer | ✓ | Event Scripts | Scheduled | | |\n| init.sqf is executed | Multiplayer | ✓ | Event Scripts | Scheduled | | |"}],"categories":["Mission Editing","Scripting Topics"],"groups":["Scripting"]},{"name":"Location","title":"Location","type":"topic","url":"https://community.bistudio.com/wiki/Location","revid":378131,"updated":"2026-02-22T20:29:35Z","aliases":["Arma 2: CfgLocationTypes","location"],"markdown":"A location is an extended type of marker. For example city names displayed on the map are locations; their information can be accessed and modified with Location commands.\n\nLocation notion was introduced in Armed Assault v1.08.\n\n### Specifics\n\nLocations:\n- are defined in `bin\\Config.bin\\CfgLocationTypes` / `configFile >> \"CfgLocationTypes\"`\n- have a name, a side, a 3D position, a 2D area, and an orientation\n- have a non-scaling map representation (icon and/or text, depending on their class)\n- can be attached to objects, with all of the location's relevant properties inherited from the object\n- are local, their properties are not synchronised over the network\n\nTerrain built-in locations:\n- provide a way to find nearby high points, towns, etc.\n- are defined in an island's `.pew` file. When the island is exported to `.wrp` its `.hpp` file is also produced, containing the location names used in the `.pew` file. This `.hpp` file is then incorporated into the config for the island using an #include statement.\nThis section included in the island config ensures any locations set in the `.pew` file are included in the island during packing.\n\n| Modification | Terrain Location | Scripted Terrain Location // Brackets are equivalent to quotation marks and may be used in their place.\n```\n\nSource directory is:\n- For any file without starting the include path with \\ - the file's current directory\n- When starting with \\ - the internal filesystem root (see Addon Prefix) or the Game's working directory (only with -filePatching enabled)\n\nA path beginning can be defined as follow:\n- drive (only with -filePatching enabled): \n\n```cpp\n#include \"D:\\file.txt\"\n```\n\n- PBO with PBOPREFIX: \n\n```cpp\n #include \"\\myMod\\myAddon\\file.txt\"\n```\n\n- PBO (keep in mind that in this case, if the PBO's file name will be changed, all '#include' referencing it will need to be updated):\n\n```cpp\n#include\"\\myMod\\myAddon\\file.txt\" // Arma 3\\@myMod\\addons\\myAddon.pbo\\file.txt;\n```\n\nTo move to parent directory use '..' (two dots) (Supported since Arma 3 v1.50):\n\n```cpp\n#include \"..\\file.sqf\"\n```\n\nPreprocessor does not support the use of macros for pre-defined file names.\n\n```cpp\n#define path \"codestrip.txt\"\n#include path // this will cause an error\n```\n\n#### #\n\n'#' (single hash) operator wraps the text with quotation marks.\n\n```cpp\n#define STRINGIFY(s) #s\n#define FOO 123\ntest1 = STRINGIFY(123); //test1 = \"123\";\ntest2 = STRINGIFY(FOO); //test2 = \"123\";\n```\n\nThis operator does only work on keywords following the rules for macro-names (see `1. define`-section).\nIf one wants to stringify anything else (like e.g. a number), one has to use a stringify-macro that takes an argument and stringifies that (as in the example above).\n\n```cpp\n#define MACRO Test #123\nMACRO // preprocesses to Test 123 - note that there are not any quotes inserted\n```\n\n#### ##\n\n'##' (double hash) operator concatenates what's before the ## with what's after it.\n\n```cpp\n#define GLUE(g1,g2) g1##g2\n#define FOO 123\n#define BAR 456\ntest1 = GLUE(123,456); //test1 = 123456;\ntest2 = GLUE(FOO,BAR); //test2 = 123456;\n```\n\n#### __LINE__\n\nThis keyword gets replaced with the line number in the file where it is found. For example, if `__LINE__` is found on the 10th line of a file, the word `__LINE__` will be replaced with the number 10.\n\n#### __FILE__\n\nThis keyword gets replaced with the CURRENT file being processed.\ne.g\n \"userconfig\\file1.sqf\"\n\n#### __FILE_NAME__ (Arma 3 v2.18)\n\nThis keyword gets replaced with the **name** of the current file being processed.\ne.g\n \"file1.sqf\"\n\n#### __FILE_SHORT__ (Arma 3 v2.18)\n\nThis keyword gets replaced with the **name** of the current file being processed, without extension.\ne.g\n \"file1\"\n\n#### __has_include (Arma 3 v2.02)\n\n**Description:** Checks if given file exists. Returns 1 if it does, 0 if it does not exist.\n\n> [!IMPORTANT]\n> - The file path must start with the backslash `\\` otherwise it would fail silently (returns `0` so does nothing unless you put something in `1. else`)!\n> - If you wanted to make an addon that can change its config dynamically depending on mods that loaded along, **do not** binarize the *config.cpp*!\n\n> [!NOTE]\n> To validate that the file exists in your game, you can use fileExists command to check.\n>\n> ```sqf\n> fileExists \"\\a3\\data_f\\config.bin\"; // returns true\n> fileExists \"\\z\\ace\\addons\\main\\script_component.hpp\"; // returns true if ACE is loaded, false otherwise\n> ```\n\n```cpp\n#if __has_include(\"\\z\\ace\\addons\\main\\script_component.hpp\")\n// file exists! Do something with it\n#else\n// file does not exist\n#endif\n```\n\n#### __DATE_ARR__ (Arma 3 v2.02)\n\n**Description:** Is replaced for current date in format array.\n\n```cpp\n__DATE_ARR__ // 2020,10,28,15,17,42\n```\n\n#### __DATE_STR__ (Arma 3 v2.02)\n\n**Description:** Is replaced for current date in format string.\n\n```cpp\n__DATE_STR__ // \"2020/10/28, 15:17:42\"\n```\n\n#### __DATE_STR_ISO8601__ (Arma 3 v2.02)\n\n**Description:** Is replaced for current date in format string. The date is presented in ISO8601 standard.\n\n```cpp\n__DATE_STR_ISO8601__ // \"2020-10-28T14:17:42Z\"\n```\n\n#### __TIME__ (Arma 3 v2.02)\n\n**Description:** Is replaced for current time.\n\n```cpp\n__TIME__ // 15:17:42\n```\n\n#### __TIME_UTC__ (Arma 3 v2.02)\n\n**Description:** Is replaced for UTC time.\n\n```cpp\n__TIME_UTC__ // 14:17:42\n```\n\n#### __DAY__ (Arma 3 v2.16)\n\n**Description:** Is replaced for UTC day.\n\n```cpp\n__DAY__ // 20\n```\n\n#### __MONTH__ (Arma 3 v2.16)\n\n**Description:** Is replaced for UTC month.\n\n```cpp\n__MONTH__ // 11\n```\n\n#### __YEAR__ (Arma 3 v2.16)\n\n**Description:** Is replaced for UTC year.\n\n```cpp\n__YEAR__ // 2023\n```\n\n#### __COUNTER__ (Arma 3 v2.02)\n\n**Description:** Counts 1 up everytime it is defined.\n\n```cpp\n__COUNTER__ // 0\n__COUNTER__ // 1\n__COUNTER__ // 2\n__COUNTER__ // 3\n__COUNTER_RESET__\n__COUNTER__ // 0\n__COUNTER__ // 1\n__COUNTER__ // 2\n```\n\n#### __TIMESTAMP_UTC__ (Arma 3 v2.06)\n\n**Description:** Is replaced to the current timestamp in UNIX timestamp.\n\n```cpp\n__TIMESTAMP_UTC__ // 1622639059\n```\n\n#### __COUNTER_RESET__ (Arma 3 v2.02)\n\n**Description:** Resets counter. See example above.\n\n#### __RAND_INT`N`__ (Arma 3 v2.02)\n\n**Description:** Gets replaced by a random `N` bit integer. `N` can be 8, 16, 32 or 64, e.g:\n\n```cpp\n__RAND_INT8__\n__RAND_INT16__\n__RAND_INT32__\n__RAND_INT64__\n```\n\n```cpp\n__RAND_INT8__ // e.g -102\n```\n\n#### __RAND_UINT`N`__ (Arma 3 v2.02)\n\n**Description:** Gets replaced by a random *unsigned* `N` bit integer. `N` can be 8, 16, 32 or 64, e.g:\n\n```cpp\n__RAND_UINT8__\n__RAND_UINT16__\n__RAND_UINT32__\n__RAND_UINT64__\n```\n\n```cpp\n__RAND_UINT8__ // 108\n```\n\n#### __GAME_VER__ (Arma 3 v2.02)\n\n**Description:** Gets replaced by the game version.\n\n```cpp\n__GAME_VER__ // 02.00.146790\n```\n\n#### __GAME_VER_MAJ__ (Arma 3 v2.02)\n\n**Description:** Gets replaced by the *major* game version.\n\n```cpp\n__GAME_VER_MAJ__ // 02\n```\n\n#### __GAME_VER_MIN__ (Arma 3 v2.02)\n\n**Description:** Gets replaced by the *minor* game version.\n\n```cpp\n__GAME_VER_MIN__ // 00\n```\n\n#### __GAME_BUILD__ (Arma 3 v2.02)\n\n**Description:** Gets replaced by the build number.\n\n```cpp\n__GAME_BUILD__ // 146790\n```\n\n#### __A3_DIAG__ (Arma 3 v2.12)\n\n**Description:** Gets replaced by 1 on diag, undefined otherwise.\n\n```cpp\n__A3_DIAG__// 1\n```\n\n#### __ARMA__ (Arma 3 v2.02)\n\n**Description:**\n\n```cpp\n__ARMA__ // 1\n```\n\n#### __ARMA3__ (Arma 3 v2.02)\n\n**Description:**\n\n```cpp\n__ARMA3__ // 1\n```\n\n#### __A3_DEBUG__ (Arma 3 v2.02)\n\n**Description:** This macro is only set when the -debug parameter was provided. It can be used to switch mods or scripts to debug mode dynamically.\n\n```cpp\n__A3_DEBUG__ // 1 (if -debug was enabled)\n```\n\n#### __A3_EXPERIMENTAL__ (Arma 3 v2.15)\n\n**Description:** This macro is only set in experimental game builds (Development branch or Profiling branch)\n\n```cpp\n__A3_EXPERIMENTAL__ // 1 (if on dev or profiling branch)\n```\n\ncan be combined with game build to check for bugfixes added to profiling branch (in case a stable branch hotfix is released with a higher buildnumber but that doesn't include the fix)\n\n```cpp\n#if __GAME_VER_MIN__ >= 16 //#TODO remove this workaround when 2.16 is released\n#define BUG_FIXED\n#endif\n\n#if __GAME_BUILD__ > 151035 // Builds newer than this\n#if __A3_EXPERIMENTAL__ // But on experimental only\n#define BUG_FIXED\n#endif\n#endif\n\n#ifdef BUG_FIXED\nuse the thing\n#else\ndon't use the thing and have some workaround\n#endif\n```\n\n#### __A3_PROFILING__ (Arma 3 v2.15)\n\n**Description:** This macro is only set when Profiling commands are available (Development branch diag binary or in Profiling branch profiling binary)\n\n```cpp\n#if __A3_PROFILING__\ndiag_captureFrame 1;\n#endif\n```\n\n### Config Parser\n\n> [!IMPORTANT]\n> - `__EXEC` and `__EVAL` **cannot** be used in preprocessor #Macros, e.g **##if**!\n\n> [!NOTE]\n> - `__EXEC` and `__EVAL` can be used in configs (such as config.cpp, Description.ext, RVMat etc) but are not suitable for SQF or SQS scripts.\n> - As they use parsingNamespace, both global and local variables set in `__EXEC` are available in `__EVAL`.\n> - parsingNamespace can then be accessed through scripting; see the __EXEC example below.\n\n#### __EXEC\n\nThis **Config Parser** macro allows to assign values to internal variables or just execute arbitrary code.\nThe code inside `__EXEC` macros runs in parsingNamespace and variables defined in it will also be created in parsingNamespace. The variables can then be used to create more complex macros:\n\n```cpp\n__EXEC(cat = 5 + 1;)\n__EXEC(lev = cat - 2;)\n```\n\n```sqf\n_cat = parsingNamespace getVariable \"cat\"; // 6\n_lev = parsingNamespace getVariable \"lev\"; // 4\n```\n\n> [!WARNING]\n> `__EXEC` does not like round brackets `()` inside expressions. If grouping is needed, perhaps values could be calculated inside the brackets separately and assigned to local variables:\n>\n> ```cpp\n> __EXEC(a = (1+2);) // ERROR\n> ```\n>\n> ```cpp\n> __EXEC(_expr = 1+2;)\n> __EXEC(a = _expr;) // OK\n> ```\n\n#### __EVAL\n\nWith this **Config Parser** macro expressions can be evaluated, including previously assigned internal variables. Unlike `__EXEC`, `__EVAL` supports multiple parentheses:\n\n```cpp\nw = __EVAL(safeZoneW - (5 * ((1 / (getResolution select 2)) * 1.25 * 4)));\n```\n\n- `__EVAL` macros **must** be assigned to a config property and the expression **must** be terminated with `****`.\n- `__EVAL` can only return Number or String. Any other type is represented as String, even Boolean type (which would result in either `\"true\"` or `\"false\"`).\n\n> [!NOTE]\n> if code is needed in the expression, use compile String instead. Like so:\n>\n> ```cpp\n> result = __EVAL(call compile \"123\");\n> ```\n>\n> that is because `__EVAL` is incapable of dealing with curly brackets `{`}\n\n### Errors\n\n#### Error 2\n\n**Problem: Preprocessor failed error 2.**\n\n**How to fix: Add quotation marks in the title, or the file path. (*e.g.* `1. include \"soGood.sqf\"`).**\n\n#### Error 6\n\n**Problem: Preprocessor failed on file X - error 6.**\n\n**Known reasons:**\n\"The problem is using `1. ifdef #ifdef #endif #endif`, a.k.a nested `1. ifdef`. This doesn't work in Arma. It's only possible to use `1. ifdef` and `1. endif` once and not nested.\"\n`1. endif` without preceding `1. ifdef` or `1. ifndef`\n\n#### Error 7\n\n**Problem: Preprocessor failed on file X - error 7.**\n\n**Known reasons: The preprocessor encountered an unknown directive. Read, as a typo most has likely found a way into the file (something like `1. in*lc*ude` or `1. defi*en*`). Double-check all preprocessor directives in that file.**\n\n### External links\n\n- [Operation Flashpoint - Preprocessor Guide (Wayback Machine)](https://ofp-faguss.com/files/ofp_preprocessor_explained.pdf)\n- [Collection of preprocessor test-cases](https://github.com/Krzmbrzl/ArmaPreprocessorTestCases)","sections":[{"heading":null,"level":1,"markdown":"The PreProcessor and the Config Parser allow to use macros in configs.\nThe purpose of macros is to re-use the same definition in scripts and configs multiple times.\nIt also gives a centralised place to correct errors in this definition.\nKnow that edge cases may arise - see the collection of test-cases linked at the end of this page.\n\n> [!NOTE]\n> **Arma 3:** In Arma 3, preprocessor commands are **case-sensitive!**"},{"heading":"Parsing","level":3,"markdown":"See #Config Parser below:\n- **Config.cpp** - parsed when PBO is binarised.\n - localize cannot be used in macros, as it would hardcode string of current language instead of creating reference.\n- **Description.ext** - parsed when mission is loaded or previewed in missions list.\n- **SQF script** - parsed when preprocessFile, preprocessFileLineNumbers, compileScript or execVM is used."},{"heading":"Macros","level":3,"markdown":""},{"heading":"Strings","level":4,"markdown":"In both Configs and SQF scripts, there are two ways to define strings: either using single quotes (`'text'`) or double quotes (`\"text\"`).\nWhile they are both identical, they are **treated differently** by the preprocessor.\nThe **single quote** string contents are **parsed** by the preprocessor, while the **double quote** ones are **ignored**.\n\n```sqf\n#define ARG world\n\nsystemChat 'hello ARG'; // prints: hello world (i.e. ARG was replaced by the preprocessor with world)\nsystemChat \"hello ARG\"; // prints: hello ARG\n```\n\n> [!WARNING]\n> While it is possible in config to define a string without quotes (the preprocessor will act as if the value were wrapped with single quotes), this practice is heavily discouraged.\n>\n> ```cpp\n> title = \"$STR_TranslationKey\"; // good\n> title = $STR_TranslationKey; // tolerated but incorrect\n> ```"},{"heading":"Comments","level":4,"markdown":"A comment is a line within code that is not actually processed by the game engine. They are used to make code more readable or to add notes for future reference.\nThe preprocessor removes all comments from the file before it is processed. Therefore, comments are never actually \"seen\" by the game engine.\n\n> [!WARNING]\n> Sometimes a problematic string can fail to purge these comment outs during preprocessing!\n>\n> ```sqf\n> private _a = '\"';\n> // this is just a comment, but failed to remove upon the preprocess so will return an error. Caused by that string\n> ```\n\n```cpp\n// this is a single-line comment\n\n/*\n this is a\n multi-line\n comment\n*/\n\nmyValue = something; // only this part of the line is commented out\n\nmyArray = { \"apple\"/*, \"banana\"*/, \"pear\" }; // a portion in the middle of this line is commented out\n```"},{"heading":"#define","level":4,"markdown":"Using the `1. define` instruction, it is possible to define a keyword and assign a definition to it.\nThe keyword may contain any letter, digit or underscore in arbitrary order, as long as it does not start with a digit (RegEx: `[a-zA-Z_][0-9a-zA-Z_]*`).\nAs an example:\n\n```cpp\n#define true 1\n```\n\nThe above means that whenever *true* is used in a config, the parser will replace this with the value *1*.\n\nThe define-statement does swallow all spaces in between the macro-keyword and any non-space-character in the body (Note that tabs are not spaces! They don't get removed)\n\n```cpp\n#define MACRO test\nMACRO // preprocesses to test (without any spaces)\n\n#define MACRO test // There's a tab between MACRO and test\nMACRO // preprocesses to \" test\" (without quotes - they are only used to show that the tab character didn't get removed)\n```\n\nThe space between the macro-keyword and the body is also fully optional (though very useful to tell the preprocessor where the macro name ends and where the body begins):\n\n```cpp\n#define MACRO#test\nMACRO // preprocesses to \"test\"\n```"},{"heading":"Arguments","level":5,"markdown":"Arguments can be added to more complex macros, by including them between brackets after the keyword. For the name of the arguments the same rule as for the macro-keyword (see above) apply.\n\n```cpp\n#define CAR(NAME) displayName = NAME;\n```\n\nIf *CAR(\"Mini\")* is used, it will be replaced with *displayName = \"Mini\";*. Multiple arguments can also be used:\n\n```cpp\n#define BLASTOFF(UNIT,RATE) UNIT setVelocity [0,0,RATE];\n```\n\nMacro arguments may be composed of any characters, as long as they do not contain a comma (because commas are used as argument-delimiters).\nIf quotes are being used, they have to be balanced.\nThe same applies to single-quotes; this is because String detection is working in macro arguments - therefore commas can even get passed in as a macro argument as long as they are part of a String (This only works with Strings wrapped in double-quotes though).\nNote however that although the macro gets resolved properly, the comma gets removed from the String (probably a bug).\n\n```cpp\n#define MACRO(arg) arg\nMACRO(\"Some, content\") // preprocesses to \"Some content\" (note the missing comma)\n```\n\nQuote escaping is also not supported in this context (neither with double- nor with single-quotes)\n\n```cpp\n#define MACRO(arg) arg\nMACRO(\"Some \"\"content\"\"\") // preprocesses to \"Some \"\"content\"\"\"\n```\n\nPassing arrays with more than one element `[el1,el2,...]` as arguments into macros as well as any argument containing commas (e.g `\"some, sentence\"`) will need a small workaround:\n\n```cpp\n#define HINTARG(ARG) hint (\"Passed argument: \" + str ARG)\n```\n\nIncorrect usage:\n\n```cpp\nHINTARG([1,2,3,4,5,6,7,8,9,0]); // ERROR, won't even compile\n```\n\nCorrect usage:\n\n```cpp\n#define array1 [1,2,3,4,5,6,7,8,9,0]\nHINTARG(array1); // SUCCESS\n```\n\nThe argument replacement is performed before the expansion of the macro body. That means one doesn't have to worry about name-conflicts between argument-names of the current macro and already defined macros:\n\n```cpp\n#define ONE foo\n#define TWO(ONE) ONE\nTWO(bar) // will preprocess to bar\n```"},{"heading":"Replacing parts of words","level":5,"markdown":"By default, only whole words can be replaced by arguments. If only a part of the word should be replaced, use the `1.` instruction.\nThis is necessary when either the start or the end of the argument connects to another character that is not a `****` (semi-colon) or (space).\n\n```cpp\nclass NAME##_Button_Slider: RscText \\\n{ \\\n model = \\OFP2\\Structures\\Various\\##FOLDER##\\##FOLDER; \\\n```\n\nIt is also possible to use the single *#* to convert an argument to a string.\n\n```cpp\nstatement = (this animate [#SEL, 0]); \\\n```"},{"heading":"Multi-line","level":5,"markdown":"For longer definitions, one can stretch the macro across multiple lines. To create a multi-line definition, each line except the last one should end with a *\\* character:\n\n```cpp\n#define DRAWBUTTON(NAME)\\\n __EXEC(idcNav = idcNav + 4) \\\n // ...\n```\n\n> [!NOTE]\n> The backslash must be the last character in a line when defining a multi-line macro. Any character (including spaces) after the backslash will cause issues."},{"heading":"Variadic Arguments (Arma 3 v2.24)","level":5,"markdown":"Reference https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html\n\nVariadic arguments allows to provide a variable number of arguments to a macro, instead of a fixed number.\n\nAnd there are several \"functions\" to work with these variable-length argument lists.\n\nA basic variadic macro looks like this\n\n```cpp\n#define MACRO(...) __VA_ARGS__\n```\n\nThere are a few special keywords and \"functions\" that are only valid when used inside a variadic macro\n- `__VA_ARGS__`\n- `__VA_OPT__(X)`\n- `__VA_OPT_INV__(X)`\n- `__VA_APPLY__(FUNC(,SEP))`\n- `__VA_SELECT__(index)`"},{"heading":"__VA_ARGS__","level":6,"markdown":"is a special keyword that will be replaced by all the macro arguments, separated by \",\". For example:\n\n```cpp\n#define MACRO(...) __VA_ARGS__\n\nMACRO() // \"\", Zero is also a valid number of arguments\nMACRO(a,b,c) // \"a,b,c\", the arguments are \"a\", \"b\" and \"c\"\nMACRO({str [1,2,3]}) // \"{str [1,2,3]}\", the arguments are \"{str [1\", \"2\" and \"3]}\"\n```\n\nThis simple variant can replace helper macros like CBA mod's ARR_1, ARR_2, ARR_3, with just one ARR(...) macro.\n\nIt can also be used to wrap code blocks, which was difficult to do without it because they can contain commas and its not easy to tell the number of commas, like in the example above."},{"heading":"__VA_OPT__(x) and __VA_OPT_INV__(x)","level":6,"markdown":"are simple functions to handle the special case of there being zero variadic arguments.\n`__VA_OPT__(x)` is only active if arguments are present. And the INV variant is only active if no arguments are present\nFor example:\n\n```cpp\n#define HAS_ARGS __VA_OPT__(Yes I have Arguments!)__VA_OPT_INV__(Nothing!)\n\nHAS_ARGS() // \"Nothing!\"\nHAS_ARGS(a) // \"Yes I have Arguments!\"\nHAS_ARGS(a,b,c) // \"Yes I have Arguments!\", no matter how many arguments, if there is at least one, the optional data is inserted\n```\n\nThis is useful when the arguments are forwarded to something like:\n\n```cpp\n#define LOG(message, ...) diag_log __VA_OPT__([) message __VA_OPT__(,) __VA_ARGS__ __VA_OPT__(])\n\nLOG(\"My Message\") // 'diag_log \"My Message\" '\nLOG(\"My Message\",1,2,3) // 'diag_log [ \"My Message\" , 1,2,3 ] '\n```"},{"heading":"__VA_APPLY__(FUNC, SEPARATOR)","level":6,"markdown":"is similar to apply in that it applies a function(macro) on every argument. The second \"SEPARATOR\" argument is optional, it can be used to replace the usual \",\" separator with something different.\n\nThe macro passed to apply must have 0, 1 or 2 arguments.\n\nIf 0 arguments, every value will be replaced by the macro contents, for example:\n\n```cpp\n#define FUNC A\n#define TRANSFORM(...) __VA_APPLY__(FUNC)\nTRANSFORM(1,2,3) // 'A,A,A'\n```\n\nIf 1 argument, it will be the value of the argument, for example:\n\n```cpp\n#define QUOTE(x) #x\n#define TRANSFORM(...) __VA_APPLY__(QUOTE)\nTRANSFORM(1,2,3) // '\"1\",\"2\",\"3\"'\n```\n\nIf 2, the second argument MUST be named `__VA_INDEX__`, it will be filled with the index of the argument, for example:\n\n```cpp\n#define FUNC(x, __VA_INDEX__) __VA_INDEX__: #x\n#define TRANSFORM(...) __VA_APPLY__(FUNC)\nTRANSFORM(1,2,3) // '0: \"1\",1: \"2\",2: \"3\"'\n```\n\nBy default, just like `__VA_ARGS__` when the values are written to the output, they will be separated by \",\".\n\nThis can be changed by providing a separator argument, for example:\nFor example:\n\n```cpp\n#define VERBATIM(x) x\n#define SEPARATOR_NONE\n#define TRANSFORM_CONCAT(...) __VA_APPLY__(QUOTE, SEPARATOR_NONE)\nTRANSFORM_CONCAT(1,2,3) // '123'\n\n#define GET_VARIABLE(x) private _##x = player getVariable #x\n#define SEPARATOR_SEMI ;\n#define GET_VARIABLES(...) __VA_APPLY__(GET_VARIABLE, SEPARATOR_SEMI)\n\nGET_VARIABLES() // ''\nGET_VARIABLES(MyFnc) // 'private _MyFnc = player getVariable \"MyFnc\"'\nGET_VARIABLES(MyFnc,MyOtherFnc) // 'private _MyFnc = player getVariable \"MyFnc\";private _MyOtherFnc = player getVariable \"MyOtherFnc\"'\n```\n\nThe results of `__VA_APPLY__` can also be passed to another variadic macro, for example:\n\n```cpp\n#define QUOTE(x) #x\n#define WRITE_LOG(...) diag_log [__VA_ARGS__]\n#define MAKE_ARRAY(...) [__VA_ARGS__]\n\n#define DO_THINGS(...) WRITE_LOG(__VA_APPLY__(QUOTE)); _array = MAKE_ARRAY(__VA_ARGS__);\n\nDO_THINGS(a,b,c) // diag_log [\"a\",\"b\",\"c\"]; _array = [a,b,c];\n```"},{"heading":"__VA_SELECT__(index)","level":6,"markdown":"will select the specified element out of the `__VA_ARGS__` list. index must be a number.\nFor example:\n\n```cpp\n#define SELECT_ARG(index, ...) __VA_SELECT__(index)\n#define FORMAT_ARG(index) SELECT_ARG(index, \"A=%2\", \"B=%3\", \"C=%4\", \"D=%5\", \"E=%6\", \"F=%7\")\n#define FORMAT_GET_ARGSTR(arg, __VA_INDEX__) FORMAT_ARG(__VA_INDEX__)\n#define FORMAT(MESSAGE, ...) format [[__VA_OPT_INV__('%1') __VA_OPT__('%1:',) __VA_APPLY__(FORMAT_GET_ARGSTR)] joinString ' ', MESSAGE __VA_OPT__(,) __VA_ARGS__]\n\nFORMAT(\"Message\") // `format [['%1' ] joinString ' ', \"Message\" ]`\nFORMAT(\"Message\", value1, value2) // `format [[ '%1:', \"A=%2\", \"B=%3\"] joinString ' ', \"Message\" , value1, value2]` which ends up as `format [\"%1: A=%2 B=%3\", \"Message\", value1, value2]`\n```"},{"heading":"#undef","level":4,"markdown":"Undefine (delete) a macro previously set by the use of #define.\n\n```cpp\n#undef NAME\n```"},{"heading":"#if","level":4,"markdown":"**Description:** Checks condition and processes content if condition returns 1. Skips content if it returns 0\n\n```cpp\n#if __GAME_VER_MAJ__ != 2\n// Do something...\n#endif\n```"},{"heading":"Comparison Operators","level":5,"markdown":"The following operations are supported:\n- <\n- >\n- <=\n- >=\n- ==\n- !=\n**Example:**\n\n```cpp\n#if __GAME_VER_MAJ__ != 2\n// Do something...\n#endif\n```"},{"heading":"#ifdef","level":4,"markdown":"A simple if-then construction to check whether a certain set of definitions has already been made:\n\n```cpp\n#ifdef NAME\n // config that will be used if NAME is defined\n#endif\n```\n\nIFDEFs *cannot* be nested. The preprocessor will generate errors for all inner definitions if the outer definition doesn't exist."},{"heading":"#ifndef","level":4,"markdown":"Same as #ifdef, but checks for absence of definition instead.\n\n```cpp\n#ifndef NAME\n // config that will be used if NAME is -not- defined\n#endif\n```"},{"heading":"#else","level":4,"markdown":"Provides alternative code to `1. if`, `1. ifdef`, `1. ifndef` checks.\n\n```cpp\n#ifndef NAME\n // config that will be used if NAME is -not- defined\n#else\n // config that will be used if NAME -is- defined\n#endif\n```"},{"heading":"#endif","level":4,"markdown":"This ends a conditional block as shown in the descriptions of #ifdef and #ifndef above."},{"heading":"#include","level":4,"markdown":"Copies the code from a target file and pastes it where #include directive is.\n\n```cpp\n#include \"file.hpp\"\n#include // Brackets are equivalent to quotation marks and may be used in their place.\n```\n\nSource directory is:\n- For any file without starting the include path with \\ - the file's current directory\n- When starting with \\ - the internal filesystem root (see Addon Prefix) or the Game's working directory (only with -filePatching enabled)\n\nA path beginning can be defined as follow:\n- drive (only with -filePatching enabled): \n\n```cpp\n#include \"D:\\file.txt\"\n```\n\n- PBO with PBOPREFIX: \n\n```cpp\n #include \"\\myMod\\myAddon\\file.txt\"\n```\n\n- PBO (keep in mind that in this case, if the PBO's file name will be changed, all '#include' referencing it will need to be updated):\n\n```cpp\n#include\"\\myMod\\myAddon\\file.txt\" // Arma 3\\@myMod\\addons\\myAddon.pbo\\file.txt;\n```\n\nTo move to parent directory use '..' (two dots) (Supported since Arma 3 v1.50):\n\n```cpp\n#include \"..\\file.sqf\"\n```\n\nPreprocessor does not support the use of macros for pre-defined file names.\n\n```cpp\n#define path \"codestrip.txt\"\n#include path // this will cause an error\n```"},{"heading":"#","level":4,"markdown":"'#' (single hash) operator wraps the text with quotation marks.\n\n```cpp\n#define STRINGIFY(s) #s\n#define FOO 123\ntest1 = STRINGIFY(123); //test1 = \"123\";\ntest2 = STRINGIFY(FOO); //test2 = \"123\";\n```\n\nThis operator does only work on keywords following the rules for macro-names (see `1. define`-section).\nIf one wants to stringify anything else (like e.g. a number), one has to use a stringify-macro that takes an argument and stringifies that (as in the example above).\n\n```cpp\n#define MACRO Test #123\nMACRO // preprocesses to Test 123 - note that there are not any quotes inserted\n```"},{"heading":"##","level":4,"markdown":"'##' (double hash) operator concatenates what's before the ## with what's after it.\n\n```cpp\n#define GLUE(g1,g2) g1##g2\n#define FOO 123\n#define BAR 456\ntest1 = GLUE(123,456); //test1 = 123456;\ntest2 = GLUE(FOO,BAR); //test2 = 123456;\n```"},{"heading":"__LINE__","level":4,"markdown":"This keyword gets replaced with the line number in the file where it is found. For example, if `__LINE__` is found on the 10th line of a file, the word `__LINE__` will be replaced with the number 10."},{"heading":"__FILE__","level":4,"markdown":"This keyword gets replaced with the CURRENT file being processed.\ne.g\n \"userconfig\\file1.sqf\""},{"heading":"__FILE_NAME__ (Arma 3 v2.18)","level":4,"markdown":"This keyword gets replaced with the **name** of the current file being processed.\ne.g\n \"file1.sqf\""},{"heading":"__FILE_SHORT__ (Arma 3 v2.18)","level":4,"markdown":"This keyword gets replaced with the **name** of the current file being processed, without extension.\ne.g\n \"file1\""},{"heading":"__has_include (Arma 3 v2.02)","level":4,"markdown":"**Description:** Checks if given file exists. Returns 1 if it does, 0 if it does not exist.\n\n> [!IMPORTANT]\n> - The file path must start with the backslash `\\` otherwise it would fail silently (returns `0` so does nothing unless you put something in `1. else`)!\n> - If you wanted to make an addon that can change its config dynamically depending on mods that loaded along, **do not** binarize the *config.cpp*!\n\n> [!NOTE]\n> To validate that the file exists in your game, you can use fileExists command to check.\n>\n> ```sqf\n> fileExists \"\\a3\\data_f\\config.bin\"; // returns true\n> fileExists \"\\z\\ace\\addons\\main\\script_component.hpp\"; // returns true if ACE is loaded, false otherwise\n> ```\n\n```cpp\n#if __has_include(\"\\z\\ace\\addons\\main\\script_component.hpp\")\n// file exists! Do something with it\n#else\n// file does not exist\n#endif\n```"},{"heading":"__DATE_ARR__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Is replaced for current date in format array.\n\n```cpp\n__DATE_ARR__ // 2020,10,28,15,17,42\n```"},{"heading":"__DATE_STR__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Is replaced for current date in format string.\n\n```cpp\n__DATE_STR__ // \"2020/10/28, 15:17:42\"\n```"},{"heading":"__DATE_STR_ISO8601__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Is replaced for current date in format string. The date is presented in ISO8601 standard.\n\n```cpp\n__DATE_STR_ISO8601__ // \"2020-10-28T14:17:42Z\"\n```"},{"heading":"__TIME__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Is replaced for current time.\n\n```cpp\n__TIME__ // 15:17:42\n```"},{"heading":"__TIME_UTC__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Is replaced for UTC time.\n\n```cpp\n__TIME_UTC__ // 14:17:42\n```"},{"heading":"__DAY__ (Arma 3 v2.16)","level":4,"markdown":"**Description:** Is replaced for UTC day.\n\n```cpp\n__DAY__ // 20\n```"},{"heading":"__MONTH__ (Arma 3 v2.16)","level":4,"markdown":"**Description:** Is replaced for UTC month.\n\n```cpp\n__MONTH__ // 11\n```"},{"heading":"__YEAR__ (Arma 3 v2.16)","level":4,"markdown":"**Description:** Is replaced for UTC year.\n\n```cpp\n__YEAR__ // 2023\n```"},{"heading":"__COUNTER__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Counts 1 up everytime it is defined.\n\n```cpp\n__COUNTER__ // 0\n__COUNTER__ // 1\n__COUNTER__ // 2\n__COUNTER__ // 3\n__COUNTER_RESET__\n__COUNTER__ // 0\n__COUNTER__ // 1\n__COUNTER__ // 2\n```"},{"heading":"__TIMESTAMP_UTC__ (Arma 3 v2.06)","level":4,"markdown":"**Description:** Is replaced to the current timestamp in UNIX timestamp.\n\n```cpp\n__TIMESTAMP_UTC__ // 1622639059\n```"},{"heading":"__COUNTER_RESET__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Resets counter. See example above."},{"heading":"__RAND_INT`N`__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Gets replaced by a random `N` bit integer. `N` can be 8, 16, 32 or 64, e.g:\n\n```cpp\n__RAND_INT8__\n__RAND_INT16__\n__RAND_INT32__\n__RAND_INT64__\n```\n\n```cpp\n__RAND_INT8__ // e.g -102\n```"},{"heading":"__RAND_UINT`N`__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Gets replaced by a random *unsigned* `N` bit integer. `N` can be 8, 16, 32 or 64, e.g:\n\n```cpp\n__RAND_UINT8__\n__RAND_UINT16__\n__RAND_UINT32__\n__RAND_UINT64__\n```\n\n```cpp\n__RAND_UINT8__ // 108\n```"},{"heading":"__GAME_VER__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Gets replaced by the game version.\n\n```cpp\n__GAME_VER__ // 02.00.146790\n```"},{"heading":"__GAME_VER_MAJ__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Gets replaced by the *major* game version.\n\n```cpp\n__GAME_VER_MAJ__ // 02\n```"},{"heading":"__GAME_VER_MIN__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Gets replaced by the *minor* game version.\n\n```cpp\n__GAME_VER_MIN__ // 00\n```"},{"heading":"__GAME_BUILD__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** Gets replaced by the build number.\n\n```cpp\n__GAME_BUILD__ // 146790\n```"},{"heading":"__A3_DIAG__ (Arma 3 v2.12)","level":4,"markdown":"**Description:** Gets replaced by 1 on diag, undefined otherwise.\n\n```cpp\n__A3_DIAG__// 1\n```"},{"heading":"__ARMA__ (Arma 3 v2.02)","level":4,"markdown":"**Description:**\n\n```cpp\n__ARMA__ // 1\n```"},{"heading":"__ARMA3__ (Arma 3 v2.02)","level":4,"markdown":"**Description:**\n\n```cpp\n__ARMA3__ // 1\n```"},{"heading":"__A3_DEBUG__ (Arma 3 v2.02)","level":4,"markdown":"**Description:** This macro is only set when the -debug parameter was provided. It can be used to switch mods or scripts to debug mode dynamically.\n\n```cpp\n__A3_DEBUG__ // 1 (if -debug was enabled)\n```"},{"heading":"__A3_EXPERIMENTAL__ (Arma 3 v2.15)","level":4,"markdown":"**Description:** This macro is only set in experimental game builds (Development branch or Profiling branch)\n\n```cpp\n__A3_EXPERIMENTAL__ // 1 (if on dev or profiling branch)\n```\n\ncan be combined with game build to check for bugfixes added to profiling branch (in case a stable branch hotfix is released with a higher buildnumber but that doesn't include the fix)\n\n```cpp\n#if __GAME_VER_MIN__ >= 16 //#TODO remove this workaround when 2.16 is released\n#define BUG_FIXED\n#endif\n\n#if __GAME_BUILD__ > 151035 // Builds newer than this\n#if __A3_EXPERIMENTAL__ // But on experimental only\n#define BUG_FIXED\n#endif\n#endif\n\n#ifdef BUG_FIXED\nuse the thing\n#else\ndon't use the thing and have some workaround\n#endif\n```"},{"heading":"__A3_PROFILING__ (Arma 3 v2.15)","level":4,"markdown":"**Description:** This macro is only set when Profiling commands are available (Development branch diag binary or in Profiling branch profiling binary)\n\n```cpp\n#if __A3_PROFILING__\ndiag_captureFrame 1;\n#endif\n```"},{"heading":"Config Parser","level":3,"markdown":"> [!IMPORTANT]\n> - `__EXEC` and `__EVAL` **cannot** be used in preprocessor #Macros, e.g **##if**!\n\n> [!NOTE]\n> - `__EXEC` and `__EVAL` can be used in configs (such as config.cpp, Description.ext, RVMat etc) but are not suitable for SQF or SQS scripts.\n> - As they use parsingNamespace, both global and local variables set in `__EXEC` are available in `__EVAL`.\n> - parsingNamespace can then be accessed through scripting; see the __EXEC example below."},{"heading":"__EXEC","level":4,"markdown":"This **Config Parser** macro allows to assign values to internal variables or just execute arbitrary code.\nThe code inside `__EXEC` macros runs in parsingNamespace and variables defined in it will also be created in parsingNamespace. The variables can then be used to create more complex macros:\n\n```cpp\n__EXEC(cat = 5 + 1;)\n__EXEC(lev = cat - 2;)\n```\n\n```sqf\n_cat = parsingNamespace getVariable \"cat\"; // 6\n_lev = parsingNamespace getVariable \"lev\"; // 4\n```\n\n> [!WARNING]\n> `__EXEC` does not like round brackets `()` inside expressions. If grouping is needed, perhaps values could be calculated inside the brackets separately and assigned to local variables:\n>\n> ```cpp\n> __EXEC(a = (1+2);) // ERROR\n> ```\n>\n> ```cpp\n> __EXEC(_expr = 1+2;)\n> __EXEC(a = _expr;) // OK\n> ```"},{"heading":"__EVAL","level":4,"markdown":"With this **Config Parser** macro expressions can be evaluated, including previously assigned internal variables. Unlike `__EXEC`, `__EVAL` supports multiple parentheses:\n\n```cpp\nw = __EVAL(safeZoneW - (5 * ((1 / (getResolution select 2)) * 1.25 * 4)));\n```\n\n- `__EVAL` macros **must** be assigned to a config property and the expression **must** be terminated with `****`.\n- `__EVAL` can only return Number or String. Any other type is represented as String, even Boolean type (which would result in either `\"true\"` or `\"false\"`).\n\n> [!NOTE]\n> if code is needed in the expression, use compile String instead. Like so:\n>\n> ```cpp\n> result = __EVAL(call compile \"123\");\n> ```\n>\n> that is because `__EVAL` is incapable of dealing with curly brackets `{`}"},{"heading":"Errors","level":3,"markdown":""},{"heading":"Error 2","level":4,"markdown":"**Problem: Preprocessor failed error 2.**\n\n**How to fix: Add quotation marks in the title, or the file path. (*e.g.* `1. include \"soGood.sqf\"`).**"},{"heading":"Error 6","level":4,"markdown":"**Problem: Preprocessor failed on file X - error 6.**\n\n**Known reasons:**\n\"The problem is using `1. ifdef #ifdef #endif #endif`, a.k.a nested `1. ifdef`. This doesn't work in Arma. It's only possible to use `1. ifdef` and `1. endif` once and not nested.\"\n`1. endif` without preceding `1. ifdef` or `1. ifndef`"},{"heading":"Error 7","level":4,"markdown":"**Problem: Preprocessor failed on file X - error 7.**\n\n**Known reasons: The preprocessor encountered an unknown directive. Read, as a typo most has likely found a way into the file (something like `1. in*lc*ude` or `1. defi*en*`). Double-check all preprocessor directives in that file.**"},{"heading":"External links","level":3,"markdown":"- [Operation Flashpoint - Preprocessor Guide (Wayback Machine)](https://ofp-faguss.com/files/ofp_preprocessor_explained.pdf)\n- [Collection of preprocessor test-cases](https://github.com/Krzmbrzl/ArmaPreprocessorTestCases)"}],"categories":["Scripting Topics","Stubs"],"groups":["Scripting"]},{"name":"Scheduler","title":"Scheduler","type":"topic","url":"https://community.bistudio.com/wiki/Scheduler","revid":351907,"updated":"2024-01-24T14:43:29Z","aliases":[],"markdown":"The Scheduler is the part of the game engine that decides which script runs at a certain point in time. It has the ability to pause a running script, move it to the back of the running queue and start a new script.\n\n### Scripts\n\nA new script can be started by using spawn, execVM, exec and execFSM commands. The script started this way will be added into the script scheduler and will be executed in turns, giving priority to the scripts waiting longest since their last suspension. Completed scripts are removed from the scheduler while scripts not completed in allocated time are suspended.\n\n### Scheduled Environment\n\nRunning code in a scheduled environment starts a new script. The executing instance will not wait for the result of scheduled code and will continue on with its execution, so it is not possible to return any values from code executed in this manner although a Script Handle for started script is provided.\n\nAs described below there is no way to predict when scheduled code will have finished, although you can use the command scriptDone with the provided Script Handle to query if the script execution has finished and there is also the command terminate to abort the script.\n\nBecause the scheduled code can run only for a fixed duration, heavy scripts spread their load over time, and thus are having lesser impact on the game performance.\n\n**All scheduled scripts can run for a maximum of 3ms in a frame**. (Except if inside loadingscreen where it is 50ms per frame)\n\nEach Script that runs add's up to the total runtime and as soon as the total runtime of 3ms is reached the current script is paused and the game continues calculating everything else it needs to calculate that frame (For example sound and graphics rendering). On the next frame the scheduler again starts to run scripts for 3ms, starting with the script which has not been executed for the longest time.\n\nThis means any script that ran as the 3ms runtime was reached will be paused in the middle of it is execution and depending on how many scripts are spawned it might take several frames till it will run again.\nA while true loop with sleep started in scheduled environment therefore has little chance to follow with exact interval, because sleep only marks the script as done in the current frame and the next time the script is executed the engine will check if the sleep is over.\nThis means at 20 FPS the time between one frame and the next is roughly 50ms. That would make a sleep 0.01 wait for atleast 0.05 seconds.This effect get's bigger when the fps get even lower and if the scheduler is so overfilled that your script only get's checked every few frames instead of every frame.\n\nIf you spawn a scheduled script it will only start to run in the next frame when the scheduler starts fresh again.\n\n#### Where code starts scheduled\n\n- init.sqf\n- initServer.sqf\n- initPlayerLocal.sqf\n- initPlayerServer.sqf\n- functions with postInit attribute (although suspension is allowed, any long term suspension will halt the mission loading until suspension has finished)\n- code executed with spawn\n- code executed with execVM\n- code executed with exec\n- code executed with call from a scheduled environment\n\n#### Scheduler diagnostics commands\n\nThe following commands are available:\n- diag_activeSQSScripts - for all execed scripts in the scheduler\n- diag_activeSQFScripts - for all execVMed and spawned scripts in the scheduler\n- diag_activeMissionFSMs - for all execFSMed scripts in the scheduler\n- diag_activeScripts - for all scripts in the scheduler\n\n### Unscheduled Environment\n\nOften also called non-scheduled environment but means the same and you will find both terms used in this wiki.\nThe unscheduled environment runs (as described above) in the executing instance. The executing instance waits until the called function is finished. This ensures the execution order and is the fastest way for scripters to execute their code. The disadvantage is that a called function can halt or slow down the game if the function has a high performance consumption. Therefore those functions should be spawned and thereby run in a scheduled environment.\n\n#### Where code starts unscheduled\n\n- Debug Console\n- Triggers\n- Waypoints (condition *and* activation)\n- All pre-init code executions including functions with preInit attribute\n- Code executed by FSM (actions, conditions, etc.)\n- Event Handlers on units and in GUI\n- *EachFrame* code (Event Handler / Scripted EH / onEachFrame)\n- Object initialisation fields\n- Expressions of Eden Editor entity/mission attributes\n- Code execution with call from an unscheduled environment\n- Code executed with remoteExecCall\n- Code inside isNil\n- SQF code called from SQS code\n- Conversation Event Handler\n- Code inside collect3DENHistory\n\n#### while Loops\n\nA while-do loop is limited to (hard-coded) **10,000** iterations in a non-scheduled environment.\n\n### Suspension\n\nSuspension is the process to wait a period of time or to wait for something to happen. Commands for suspension are sleep, uiSleep, waitUntil.\n\nSuspension is **forbidden** in an unscheduled environment and trying to use such command will fail with an error; you must ensure that you are running your code in a scheduled environment **and** can suspend with the **canSuspend** command.","sections":[{"heading":null,"level":1,"markdown":"The Scheduler is the part of the game engine that decides which script runs at a certain point in time. It has the ability to pause a running script, move it to the back of the running queue and start a new script."},{"heading":"Scripts","level":3,"markdown":"A new script can be started by using spawn, execVM, exec and execFSM commands. The script started this way will be added into the script scheduler and will be executed in turns, giving priority to the scripts waiting longest since their last suspension. Completed scripts are removed from the scheduler while scripts not completed in allocated time are suspended."},{"heading":"Scheduled Environment","level":3,"markdown":"Running code in a scheduled environment starts a new script. The executing instance will not wait for the result of scheduled code and will continue on with its execution, so it is not possible to return any values from code executed in this manner although a Script Handle for started script is provided.\n\nAs described below there is no way to predict when scheduled code will have finished, although you can use the command scriptDone with the provided Script Handle to query if the script execution has finished and there is also the command terminate to abort the script.\n\nBecause the scheduled code can run only for a fixed duration, heavy scripts spread their load over time, and thus are having lesser impact on the game performance.\n\n**All scheduled scripts can run for a maximum of 3ms in a frame**. (Except if inside loadingscreen where it is 50ms per frame)\n\nEach Script that runs add's up to the total runtime and as soon as the total runtime of 3ms is reached the current script is paused and the game continues calculating everything else it needs to calculate that frame (For example sound and graphics rendering). On the next frame the scheduler again starts to run scripts for 3ms, starting with the script which has not been executed for the longest time.\n\nThis means any script that ran as the 3ms runtime was reached will be paused in the middle of it is execution and depending on how many scripts are spawned it might take several frames till it will run again.\nA while true loop with sleep started in scheduled environment therefore has little chance to follow with exact interval, because sleep only marks the script as done in the current frame and the next time the script is executed the engine will check if the sleep is over.\nThis means at 20 FPS the time between one frame and the next is roughly 50ms. That would make a sleep 0.01 wait for atleast 0.05 seconds.This effect get's bigger when the fps get even lower and if the scheduler is so overfilled that your script only get's checked every few frames instead of every frame.\n\nIf you spawn a scheduled script it will only start to run in the next frame when the scheduler starts fresh again."},{"heading":"Where code starts scheduled","level":4,"markdown":"- init.sqf\n- initServer.sqf\n- initPlayerLocal.sqf\n- initPlayerServer.sqf\n- functions with postInit attribute (although suspension is allowed, any long term suspension will halt the mission loading until suspension has finished)\n- code executed with spawn\n- code executed with execVM\n- code executed with exec\n- code executed with call from a scheduled environment"},{"heading":"Scheduler diagnostics commands","level":4,"markdown":"The following commands are available:\n- diag_activeSQSScripts - for all execed scripts in the scheduler\n- diag_activeSQFScripts - for all execVMed and spawned scripts in the scheduler\n- diag_activeMissionFSMs - for all execFSMed scripts in the scheduler\n- diag_activeScripts - for all scripts in the scheduler"},{"heading":"Unscheduled Environment","level":3,"markdown":"Often also called non-scheduled environment but means the same and you will find both terms used in this wiki.\nThe unscheduled environment runs (as described above) in the executing instance. The executing instance waits until the called function is finished. This ensures the execution order and is the fastest way for scripters to execute their code. The disadvantage is that a called function can halt or slow down the game if the function has a high performance consumption. Therefore those functions should be spawned and thereby run in a scheduled environment."},{"heading":"Where code starts unscheduled","level":4,"markdown":"- Debug Console\n- Triggers\n- Waypoints (condition *and* activation)\n- All pre-init code executions including functions with preInit attribute\n- Code executed by FSM (actions, conditions, etc.)\n- Event Handlers on units and in GUI\n- *EachFrame* code (Event Handler / Scripted EH / onEachFrame)\n- Object initialisation fields\n- Expressions of Eden Editor entity/mission attributes\n- Code execution with call from an unscheduled environment\n- Code executed with remoteExecCall\n- Code inside isNil\n- SQF code called from SQS code\n- Conversation Event Handler\n- Code inside collect3DENHistory"},{"heading":"while Loops","level":4,"markdown":"A while-do loop is limited to (hard-coded) **10,000** iterations in a non-scheduled environment."},{"heading":"Suspension","level":3,"markdown":"Suspension is the process to wait a period of time or to wait for something to happen. Commands for suspension are sleep, uiSleep, waitUntil.\n\nSuspension is **forbidden** in an unscheduled environment and trying to use such command will fail with an error; you must ensure that you are running your code in a scheduled environment **and** can suspend with the **canSuspend** command."}],"categories":["Scripting Topics"],"groups":["Scripting"]},{"name":"Script Handle","title":"Script Handle","type":"topic","url":"https://community.bistudio.com/wiki/Script_Handle","revid":378908,"updated":"2026-08-11T15:02:59Z","aliases":["Script (Handle)"],"markdown":"A **Script Handle**, used to identify scripts in script operations called using spawn or execVM.\nIntroduced with Armed Assault, does not refer to Operation Flashpoint or Operation Flashpoint: Resistance.\n\nThis handle's status can be checked with scriptDone, it can be terminated with terminate.\n\n> [!NOTE]\n> **Arma 3:** In Arma 3:\n> - the handle's status can also be checked with isNull (A completed script will become null)\n> - the handle can be accessed from whithin itself using `_thisScript` (since Arma 3 v1.54)\n\n> [!NOTE]\n> For more information about scripts and scripting, see Scripting Topics and Introduction to Arma Scripting.\n\n### Promise Handles (Arma 3 v2.22)\n\nScript handles can be used as [promises](https://en.wikipedia.org/wiki/Futures_and_promises).\n\nA Promise is either a Script Handle to a spawned or execVMed script, or an \"Empty Handle\" that does not hold a backing script.\nThe Handle can be used to wait for the a result to be available.\nIn case of a \"real\" handle that means the scheduled script returning a value, or in the case of a \"Empty Handle\" by using terminate to set a result value.\n\nA Promise can have continuations added onto it with continueWith, which is script code that will execute once the handle is completed.\n\nHandles can be used with waitUntil, continueWith, terminate, scriptDone, name.\n\n#### Creating a Promise\n\nEvery handle returned by spawn or execVM is a promise that gets resolved once the script exits.\n\nIt's also possible to create a \"Empty Handle\" which does not hold any scheduled script, and can also be used in unscheduled code.\n\nA \"Empty Handle\" needs to be \"completed\" by calling terminate on it.\n\n```sqf\nprivate _emptyHandle = spawn \"HandleName\"; // does not contain an actual script, it's only a holder for name and potentially a value\nprivate _normalHandle = 0 spawn { scriptName \"HandleName\"; }; // contains an actual scheduled script that will execute and return a value at the end\n```\n\n#### Using Promises\n\nPromises can be used to simplify asynchronous operations.\nFor example, when calling a function that takes some time to complete, and then wanting to execute code after it has completed.\n\nTo show it on an example, let's say we have a function that paradrops a vehicle.\nAnd we want to wait for the vehicle to touch the ground and then spawn a smoke grenade on it.\n\nPreviously, that could be solved like so:\n\n```sqf\nfnc_StartParadrop = {\n params [\"_object\"];\n\n private _parachute = createVehicle [\"B_Parachute_02_F\", [0, 0, 0], [], 0, \"CAN_COLLIDE\"];\n\n // Put the parachute into the right position (setPos doesn't work on them)\n _parachute attachTo [_object, [0, 0, 0]];\n detach _parachute;\n\n _object attachTo [_parachute, [0, 0, 0]];\n // Now the object is hanging on parachute and gliding down\n // But we want to wait for it to arrive at the bottom, the parachute will be deleted once it lands, so we can use that\n\n // The parachute won't know about us, and we cannot get a value out of the eventhandler, so we will give the parachute a place to store the result\n // Note this will not work across savegame save/load because the \"result\" reference will be lost.\n\n private _result = [];\n _parachute setVariable [\"result\", _result];\n _parachute addEventHandler [\"Deleted\", {\n params [\"_entity\"];\n (_entity getVariable \"result\") set [0, getPos _entity]; // Store the landing position of the parachute\n }];\n\n // _result will be set once the parachute landed. How we wait on the result now depends on whether this is a scheduled or unscheduled function\n // In unscheduled code we cannot wait, we would need to get some callback function in our arguments to notify our caller that it can continue.\n // For simplicity we show the scheduled variant here, the unscheduled would be more complex\n\n // Keep looping, until someone (Hopefully the Deleted eventhandler) wrote a result into our array\n waitUntil { _result isNotEqualTo []; };\n\n _result select 0; // We return the result, our user must have call'ed us to wait for us to finish and get the result\n};\n\n// The fnc_StartParadrop will wait, so we have to spawn a new script to not hold up everything else\n0 spawn {\n private _dropPos = ParadropVehicle call fnc_StartParadrop; // This will wait until the vehicle has landed\n \"SmokeshellGreen\" createVehicle _dropPos; // Spawn a smoke at the landing position\n};\n```\n\nAlso note how the waitUntil always runs.\nEven if we as the caller do not care for the paradrop to finish, we wouldn't easily have the option to tell the script that, without adding another parameter to it.\nAlso note that this function is not usable in unscheduled scripts, because it uses waitUntil to wait for the landing.\n\nWith promises, it can be solved like this:\n\n```sqf\nfnc_StartParadrop = {\n params [\"_object\"];\n\n private _parachute = createVehicle [\"B_Parachute_02_F\", [0, 0, 0], [], 0, \"CAN_COLLIDE\"];\n\n // Put the parachute into the right position (setPos doesn't work on them)\n _parachute attachTo [_object, [0, 0, 0]];\n detach _parachute;\n\n _object attachTo [_parachute, [0, 0, 0]];\n // Now the object is hanging on parachute and gliding down\n // But we want to wait for it to arrive at the bottom, the parachute will be deleted once it lands, so we can use that\n\n // The parachute won't know about us, and we cannot get a value out of the eventhandler, so we will give the parachute a place to store the result\n private _paradropHandle = spawn \"Paradrop\"; // We create new Promise, that we will use to return the result\n\n _parachute setVariable [\"handle\", _paradropHandle];\n _parachute addEventHandler [\"Deleted\", {\n params [\"_entity\"];\n (_entity getVariable \"handle\") terminate (getPos _entity); // Complete the promise and pass the landing position as result\n }];\n _paradropHandle // We return the promise, the caller can decide if they want to use it or not\n};\n\n// Note we do not need to spawn another script because we are not waiting for anything, this can fully be handled in unscheduled code now\n\n_paradropHandle = ParadropVehicle call fnc_StartParadrop; // This will start the paradrop, and return a handle that we can use to wait for it to land\n_paradropHandle continueWith { \"SmokeshellGreen\" createVehicle _this; }; // We use a continuation, it will be triggered once terminate is called on the handle (Inside the \"Deleted\" eventhandler)\n```\n\nNote that the paradrop function can now also be used in scheduled scripts like so:\n\n```sqf\nprivate _paradropHandle = ParadropVehicle call fnc_StartParadrop; // This will start the paradrop, and return a handle that we can use to wait for it to land\nprivate _dropPos = waitUntil _paradropHandle; // Wait for the promise to be completed and get its result\n\"SmokeshellGreen\" createVehicle _dropPos; // Spawn a smoke at the landing position\n```\n\nOr like so:\n\n```sqf\nprivate _paradropHandle = ParadropVehicle call fnc_StartParadrop; // This will start the paradrop, and return a handle that we can use to wait for it to land\nprivate _dropPos = waitUntil [_paradropHandle, 60]; // Wait for the promise to be completed, but at most for 60 seconds, if it still has not landed yet, we will report it to the player\n\nif (isNil \"_dropPos\") then {\n // The promise yielded no result. Either it was terminated without a result, or our timeout has elapsed\n hint \"The Paradrop has failed!\";\n} else {\n \"SmokeshellGreen\" createVehicle _dropPos; // Spawn a smoke at the landing position\n};\n```","sections":[{"heading":null,"level":1,"markdown":"A **Script Handle**, used to identify scripts in script operations called using spawn or execVM.\nIntroduced with Armed Assault, does not refer to Operation Flashpoint or Operation Flashpoint: Resistance.\n\nThis handle's status can be checked with scriptDone, it can be terminated with terminate.\n\n> [!NOTE]\n> **Arma 3:** In Arma 3:\n> - the handle's status can also be checked with isNull (A completed script will become null)\n> - the handle can be accessed from whithin itself using `_thisScript` (since Arma 3 v1.54)\n\n> [!NOTE]\n> For more information about scripts and scripting, see Scripting Topics and Introduction to Arma Scripting."},{"heading":"Promise Handles (Arma 3 v2.22)","level":3,"markdown":"Script handles can be used as [promises](https://en.wikipedia.org/wiki/Futures_and_promises).\n\nA Promise is either a Script Handle to a spawned or execVMed script, or an \"Empty Handle\" that does not hold a backing script.\nThe Handle can be used to wait for the a result to be available.\nIn case of a \"real\" handle that means the scheduled script returning a value, or in the case of a \"Empty Handle\" by using terminate to set a result value.\n\nA Promise can have continuations added onto it with continueWith, which is script code that will execute once the handle is completed.\n\nHandles can be used with waitUntil, continueWith, terminate, scriptDone, name."},{"heading":"Creating a Promise","level":4,"markdown":"Every handle returned by spawn or execVM is a promise that gets resolved once the script exits.\n\nIt's also possible to create a \"Empty Handle\" which does not hold any scheduled script, and can also be used in unscheduled code.\n\nA \"Empty Handle\" needs to be \"completed\" by calling terminate on it.\n\n```sqf\nprivate _emptyHandle = spawn \"HandleName\"; // does not contain an actual script, it's only a holder for name and potentially a value\nprivate _normalHandle = 0 spawn { scriptName \"HandleName\"; }; // contains an actual scheduled script that will execute and return a value at the end\n```"},{"heading":"Using Promises","level":4,"markdown":"Promises can be used to simplify asynchronous operations.\nFor example, when calling a function that takes some time to complete, and then wanting to execute code after it has completed.\n\nTo show it on an example, let's say we have a function that paradrops a vehicle.\nAnd we want to wait for the vehicle to touch the ground and then spawn a smoke grenade on it.\n\nPreviously, that could be solved like so:\n\n```sqf\nfnc_StartParadrop = {\n params [\"_object\"];\n\n private _parachute = createVehicle [\"B_Parachute_02_F\", [0, 0, 0], [], 0, \"CAN_COLLIDE\"];\n\n // Put the parachute into the right position (setPos doesn't work on them)\n _parachute attachTo [_object, [0, 0, 0]];\n detach _parachute;\n\n _object attachTo [_parachute, [0, 0, 0]];\n // Now the object is hanging on parachute and gliding down\n // But we want to wait for it to arrive at the bottom, the parachute will be deleted once it lands, so we can use that\n\n // The parachute won't know about us, and we cannot get a value out of the eventhandler, so we will give the parachute a place to store the result\n // Note this will not work across savegame save/load because the \"result\" reference will be lost.\n\n private _result = [];\n _parachute setVariable [\"result\", _result];\n _parachute addEventHandler [\"Deleted\", {\n params [\"_entity\"];\n (_entity getVariable \"result\") set [0, getPos _entity]; // Store the landing position of the parachute\n }];\n\n // _result will be set once the parachute landed. How we wait on the result now depends on whether this is a scheduled or unscheduled function\n // In unscheduled code we cannot wait, we would need to get some callback function in our arguments to notify our caller that it can continue.\n // For simplicity we show the scheduled variant here, the unscheduled would be more complex\n\n // Keep looping, until someone (Hopefully the Deleted eventhandler) wrote a result into our array\n waitUntil { _result isNotEqualTo []; };\n\n _result select 0; // We return the result, our user must have call'ed us to wait for us to finish and get the result\n};\n\n// The fnc_StartParadrop will wait, so we have to spawn a new script to not hold up everything else\n0 spawn {\n private _dropPos = ParadropVehicle call fnc_StartParadrop; // This will wait until the vehicle has landed\n \"SmokeshellGreen\" createVehicle _dropPos; // Spawn a smoke at the landing position\n};\n```\n\nAlso note how the waitUntil always runs.\nEven if we as the caller do not care for the paradrop to finish, we wouldn't easily have the option to tell the script that, without adding another parameter to it.\nAlso note that this function is not usable in unscheduled scripts, because it uses waitUntil to wait for the landing.\n\nWith promises, it can be solved like this:\n\n```sqf\nfnc_StartParadrop = {\n params [\"_object\"];\n\n private _parachute = createVehicle [\"B_Parachute_02_F\", [0, 0, 0], [], 0, \"CAN_COLLIDE\"];\n\n // Put the parachute into the right position (setPos doesn't work on them)\n _parachute attachTo [_object, [0, 0, 0]];\n detach _parachute;\n\n _object attachTo [_parachute, [0, 0, 0]];\n // Now the object is hanging on parachute and gliding down\n // But we want to wait for it to arrive at the bottom, the parachute will be deleted once it lands, so we can use that\n\n // The parachute won't know about us, and we cannot get a value out of the eventhandler, so we will give the parachute a place to store the result\n private _paradropHandle = spawn \"Paradrop\"; // We create new Promise, that we will use to return the result\n\n _parachute setVariable [\"handle\", _paradropHandle];\n _parachute addEventHandler [\"Deleted\", {\n params [\"_entity\"];\n (_entity getVariable \"handle\") terminate (getPos _entity); // Complete the promise and pass the landing position as result\n }];\n _paradropHandle // We return the promise, the caller can decide if they want to use it or not\n};\n\n// Note we do not need to spawn another script because we are not waiting for anything, this can fully be handled in unscheduled code now\n\n_paradropHandle = ParadropVehicle call fnc_StartParadrop; // This will start the paradrop, and return a handle that we can use to wait for it to land\n_paradropHandle continueWith { \"SmokeshellGreen\" createVehicle _this; }; // We use a continuation, it will be triggered once terminate is called on the handle (Inside the \"Deleted\" eventhandler)\n```\n\nNote that the paradrop function can now also be used in scheduled scripts like so:\n\n```sqf\nprivate _paradropHandle = ParadropVehicle call fnc_StartParadrop; // This will start the paradrop, and return a handle that we can use to wait for it to land\nprivate _dropPos = waitUntil _paradropHandle; // Wait for the promise to be completed and get its result\n\"SmokeshellGreen\" createVehicle _dropPos; // Spawn a smoke at the landing position\n```\n\nOr like so:\n\n```sqf\nprivate _paradropHandle = ParadropVehicle call fnc_StartParadrop; // This will start the paradrop, and return a handle that we can use to wait for it to land\nprivate _dropPos = waitUntil [_paradropHandle, 60]; // Wait for the promise to be completed, but at most for 60 seconds, if it still has not landed yet, we will report it to the player\n\nif (isNil \"_dropPos\") then {\n // The promise yielded no result. Either it was terminated without a result, or our timeout has elapsed\n hint \"The Paradrop has failed!\";\n} else {\n \"SmokeshellGreen\" createVehicle _dropPos; // Spawn a smoke at the landing position\n};\n```"}],"categories":["Data Types"],"groups":["Data Types"]},{"name":"Side","title":"Side","type":"topic","url":"https://community.bistudio.com/wiki/Side","revid":342100,"updated":"2023-07-09T12:26:36Z","aliases":[],"markdown":"| Id | Side | Description | Commands | Can`). They always will take the first argument that occurs.\n\nA common mistake would be the following:\n\n```sqf\n// create some Array containing three arrays\n_arr = [[1, 2, 3, 4, 5], [1, 2, 3, 4], [1, 2]];\n\n// wrongly use the select operator to get the count of the third array\ncount _arr select 2; // error\n```\n\nNow, what went wrong?\n\nLet's put some brackets in the right places to make the mistake understandable:\n\n```sqf\n(count _arr) select 2; // error\n```\n\nDue to the nature of unary operators, count instantly consumes our variable *_arr* and returns the number *3*.\nThe *3* then is passed to select which does not knows what to do with a number as left argument and thus errors out.\n\nTo do it correctly, one would have to put the `_arr select 2` in brackets.\nThe correct code thus would be:\n\n```sqf\n// create an array containing three Arrays\n_arr = [[1, 2, 3, 4, 5], [1, 2, 3, 4], [1, 2]];\n\n// use brackets to correctly get count of the third Array\ncount (_arr select 2); // good :) will evaluate to 2\n```\n\n### Binary Operators\n\nBinary operators expect two arguments (`<1st argument> binary <2nd argument>`) and are executed according to their #precedence. If their precedence is equal, they are executed left to right.\n\nAs example, we will look into the following expression:\n\n```sqf\n// create a nested Array with 5 levels\n_arr = [[[[[1]]]]];\n\n// receive the nested number with some random math expressions\n_arr select 0 select 1 - 1 select 15 / 3 - 5 select 0 select 10 * 10 + 4 * 0 - 100 // evaluates to 1\n```\n\nNow, let us analyze why this is happening for the first few expressions:\n1. _arr is loaded\n1. 0 is loaded\n1. select is executed with the result of 1. & 2.\n1. 1 is loaded\n1. 1 is loaded\n1. - is executed with the result of 4. & 5.\n1. select is executed with the result of 3. & 6.\n1. ...\n\nIf we now would put brackets at the correct spots, the expression will get clearer:\n\n```sqf\n((((_arr select 0) select (1 - 1)) select ((15 / 3) - 5)) select 0) select (((10 * 10) + (4 * 0)) - 100)\n```\n\nAs you can see the `*` and `/` are executed first which matches their precedence.\nAfterward, the `+` and `-` operators will get executed followed by our select operator, which are executed from the left to the right.","sections":[{"heading":null,"level":1,"markdown":"**SQF** stands for **S**tatus **Q**uo **F**unction - a successor of **S**tatus **Q**uo **S**cript, which is deprecated since Armed Assault but could still be used in Arma 3.\nSQF was first introduced in Operation Flashpoint: Resistance together with the call operator in update 1.85.\n\n- \"Status Quo\" was a code name for [Operation Flashpoint](https://en.wikipedia.org/wiki/Operation_Flashpoint)\n- \"Combined Arms\" was a code name for [Arma](https://en.wikipedia.org/wiki/ARMA_(series))\n- \"Futura\" was a code name for [Arma 3](https://en.wikipedia.org/wiki/ARMA_3).\n\nThe SQF Language is fairly simple in how it is built.\nIn fact: there are barely any actual language structures at all.\n\nThe functionality is provided via so called *operators* (or more commonly known scripting commands).\nThose operators are one of the following types: Nular [sic], Unary, or Binary."},{"heading":"Terminating an expression","level":3,"markdown":"An SQF expression has to be terminated via either `;` (preferred by convention!) or `,`.\n\n```sqf\n_num = 10;\n_num = _num + 20; systemChat str _num;\n```\n\nIn the above example, there are three expressions:\n1. `_num = 10`\n1. `_num = _num + 20`\n1. `systemChat str _num`\nAll are separated by `;` and not the line return - they could all be inlined and it would not impact the code."},{"heading":"Brackets","level":3,"markdown":"- `()` - Round brackets are used to override the default Order of Precedence or improve legibility.\n- `[]` - Square brackets define Arrays.\n- `{}` - Curly brackets enclose instances of the Code Data Type. They are also used in Control Structures."},{"heading":"Whitespaces","level":3,"markdown":"Whitespace consists of tabs and/or space characters.\n\n For the\n purposes of the\n engine\n The 'line' begins at the first non whitespace character.\n\nSimilarly, trailing whitespace at the end of a line or statement is also ignored."},{"heading":"Blank Lines","level":3,"markdown":"Blank lines are lines containing nothing but whitespace and are therefore ignored by the engine."},{"heading":"Comments","level":3,"markdown":"A comment is additional text that gets ignored when a script is parsed.\nThey serve as future reference and are often used to explain a specific part of the code.\n\nIn SQF, there are two kind of comments:\n\n```sqf\n// in-line comment that ends on new line\n\n/* block comment that can span above multiple lines\nand ends on the following character combination: */\n```\n\nA comment can occur anywhere but inside a string.\nFor example, the following would be valid:\n\n```sqf\n1 + /* some random comment in an expression */ 1\n```\n\nIt should be mentioned that there is a comment unary operator that should not be used as it will actually be executed (thus taking time to execute) but does nothing besides consuming a string.\nThere is no benefit in using it and the reason it exists is solely for backward compatibility.\nAnother way to make a *comment* that way, is to just place a string: `/* some code */ \"I can be considered as a comment but should not be used\"; /* some other code */`\n\n*Comments are removed during the preprocessing phase.* This is important to know as that prevents usage in e.g a string that gets compiled using the compile unary operator or when only using loadFile."},{"heading":"Nular Operators","level":3,"markdown":"A nular [sic] operator is more or less a computed variable. Each time accessed, it will return the current state of something.\nIt is tempting to think of a nular [sic] operator as nothing more but a magic global variable, but it is important to differentiate!\n\nConsider following example in a mission with e.g. 5 units:\n\n```sqf\n// put the result of allUnits into a Variable\n_unitsArray = allUnits;\n\n// display the current Array size using systemChat\nsystemChat str count _unitsArray;\n\n// create a new unit in the player group\ngroup player createUnit [\"B_RangeMaster_F\", getPosATL player, [], 0, \"NONE\"];\n\n// output the Array size again\nsystemChat str count _unitsArray;\n\n// output the size of allUnits\nsystemChat str count allUnits;\n```\n\nNow, what would the output of this look like?\n System: 5\n System: 5\n System: 6\n\nAs you can see, `_unitsArray` was not automatically updated as it would have been if it was not generated each time. If allUnits was just a global variable with a reference to some internal managed array, our private variable should have had reflected the change as value types are passed by reference.\nThe reason for this is because allUnits and other nular [sic] operators just return the current state of something and do not return a reference to eg. an array containing all units.\nIt is generated each time, which is why some of theese operators are more expensive to run then *just* using a variable."},{"heading":"Unary Operators","level":3,"markdown":"The unary operators are operators that expect an argument on their right side (`unary `). They always will take the first argument that occurs.\n\nA common mistake would be the following:\n\n```sqf\n// create some Array containing three arrays\n_arr = [[1, 2, 3, 4, 5], [1, 2, 3, 4], [1, 2]];\n\n// wrongly use the select operator to get the count of the third array\ncount _arr select 2; // error\n```\n\nNow, what went wrong?\n\nLet's put some brackets in the right places to make the mistake understandable:\n\n```sqf\n(count _arr) select 2; // error\n```\n\nDue to the nature of unary operators, count instantly consumes our variable *_arr* and returns the number *3*.\nThe *3* then is passed to select which does not knows what to do with a number as left argument and thus errors out.\n\nTo do it correctly, one would have to put the `_arr select 2` in brackets.\nThe correct code thus would be:\n\n```sqf\n// create an array containing three Arrays\n_arr = [[1, 2, 3, 4, 5], [1, 2, 3, 4], [1, 2]];\n\n// use brackets to correctly get count of the third Array\ncount (_arr select 2); // good :) will evaluate to 2\n```"},{"heading":"Binary Operators","level":3,"markdown":"Binary operators expect two arguments (`<1st argument> binary <2nd argument>`) and are executed according to their #precedence. If their precedence is equal, they are executed left to right.\n\nAs example, we will look into the following expression:\n\n```sqf\n// create a nested Array with 5 levels\n_arr = [[[[[1]]]]];\n\n// receive the nested number with some random math expressions\n_arr select 0 select 1 - 1 select 15 / 3 - 5 select 0 select 10 * 10 + 4 * 0 - 100 // evaluates to 1\n```\n\nNow, let us analyze why this is happening for the first few expressions:\n1. _arr is loaded\n1. 0 is loaded\n1. select is executed with the result of 1. & 2.\n1. 1 is loaded\n1. 1 is loaded\n1. - is executed with the result of 4. & 5.\n1. select is executed with the result of 3. & 6.\n1. ...\n\nIf we now would put brackets at the correct spots, the expression will get clearer:\n\n```sqf\n((((_arr select 0) select (1 - 1)) select ((15 / 3) - 5)) select 0) select (((10 * 10) + (4 * 0)) - 100)\n```\n\nAs you can see the `*` and `/` are executed first which matches their precedence.\nAfterward, the `+` and `-` operators will get executed followed by our select operator, which are executed from the left to the right."}],"categories":["Syntax"],"groups":["Scripting"]},{"name":"String","title":"String","type":"topic","url":"https://community.bistudio.com/wiki/String","revid":373361,"updated":"2025-04-28T08:59:37Z","aliases":["Strings"],"markdown":"A **string** is a variable type that contains text. Possible length and characters depend on the game and its version.\n\n> [!NOTE]\n> The encoding should be mostly transparent. The input files can be encoded both in UTF-16 or UTF-8, the toString and toArray functions always convert from/to UTF-16 representation.\n\n### Properties\n\n| | OFP | ArmA | Arma 2 | Arma 2:OA | Take On Helicopters | Arma 3 (before v1.56) | Arma 3 (since v1.56) |\n|---|---|---|---|---|---|---|---|\n| Max length | 2056 | No set limit | 9,999,999 to 10,000,000Large text \nLarge text \n```\n\n> [!WARNING]\n> The following will log an *.rpt* error `Unknown attribute .0` and only number 2 would be taken into account:\n>\n> ```html\n> Large text \n> ```\n\n#### Text\n\nTexts could be created with the following markup:\n\n```html\nHello World! \n```\n\nOr could also be inserted via the composeText / formatText and text commands.\n\n##### Special characters\n\nTo insert special characters, such as `<`, `>`, etc. you can use the [HTML representation](https://dev.w3.org/html5/html-author/charref) of that character, e.g.:\n\n| Character | HTML |\n|---|---|\n| < | `<` |\n| > | `>` |\n| non-breaking space | |\n| ... | ... |\n\n> [!IMPORTANT]\n> Using a special character directly will result in it being displayed as \"?\" or, in the case of writing \"\", will result in an error in the RPT: `Wrong text element 'TEXT'`\n\n#### Line break\n\nLine breaks could be created with either of the following markups:\n\n```html\nArma 3 \n```\n\nBy default the links are not underlined or have a different color to stand out. These attributes should be added separately.\n\nNote: *&* should be escaped by *&*.\n\n```html\nExample URL A \nExample URL B \n```\n\n### Attributes\n\nThe following inline attributes are supported:\n- `size`\n- `color`\n- `font`\n- `align`\n- `valign`\n- `underline`\n- `shadow`\n- `shadowColor`\n- `shadowOffset`\n- `colorLink`\n- `href`\n- `image`\n\n#### Size\n\nThe structured text `size` attribute is a multiplier for the value of control config property `size`. Default is 1, meaning that the height of letters will be equal to the value set in config. Setting this to 2 will make letters 2 times the size, 0.5 will make them half the size, etc. If the control is defined as follows:\n\n```cpp\nclass MyStructuredText : RscStructuredText \n{\n ...\n text = \"Hello!\";\n size = 0.04;\n ...\n};\n```\n\nThen the structured text:\n\n```sqf\n_control ctrlSetStructuredText parseText \"Hello! \";\n```\n\nWill result in a total text size of 0.04 * 2 = 0.08. Unfortunately, there is no script command to set or get the value of config `size` property dynamically.\n\n#### Color\n\nThe `color` attribute is similar to HTML hex color and could either have format [#RRGGBB](https://en.wikipedia.org/wiki/RGB) or [#AARRGGBB](https://en.wikipedia.org/wiki/ARGB).\n\n```html\nRed text \nSemi-transparent white text \n```\n\n#### Font\n\nThe value for the `font` attribute could be found in `CfgFontFamilies` config. Some of the Arma 3 fonts:\n- `EtelkaMonospacePro`\n- `EtelkaMonospaceProBold`\n- `EtelkaNarrowMediumPro`\n- `LCD14`\n- `LucidaConsoleB`\n- `PuristaBold`\n- `PuristaLight`\n- `PuristaMedium`\n- `PuristaSemibold`\n- `RobotoCondensed`\n- `RobotoCondensedBold`\n- `RobotoCondensedLight`\n- `TahomaB`\n\n```html\nBold Text \nWicked looking text \n```\n\n#### Horizontal Alignment\n\nThe `align` attribute controls horizontal text alignment and could be one of the following:\n- `left`\n- `center`\n- `right`\n\n```html\nText displayed to the right \n```\n\n#### Vertical Alignment\n\nThe `valign` attribute controls vertical text alignment and could be one of the following:\n- `top`\n- `middle`\n- `bottom`\n\n```html\nText displayed at the bottom \n```\n\n#### Underline\n\nThe `underline` attribute underlines each individual word in text. The normal spaces are not underlined.\n\n```html\nUnderlined Text \n```\n\n> [!NOTE]\n> If you would like to have a continuous underline between words, use non-breaking spaces. This could be achieved in several ways:\n> - Insertion from keyboard: [Alt+255](https://en.wikipedia.org/wiki/Non-breaking_space#Keyboard_entry_methods)\n> - Scripted method:\n>\n> ```sqf\n> hint parseText format [\"%1 \", \"Underlined Text\" splitString \" \" joinString toString [160]]\n> ```\n>\n> - Using HTML code:\n>\n> ```sqf\n> hint parseText \"Underlined Text \";\n> ```\n\n#### Shadow\n\nThe `shadow` attribute controls the appearance of shadow/outline around text and could be one of the following:\n- `0` - normal text\n- `1` - classic shadow (text ghosting below and to the right)\n- `2` - outline (slight, always black, outline around characters)\n\n```html\nText with no shadow \nText with default black shadow \nText with default black outline \n```\n\n#### Shadow Color\n\nThe `shadowColor` attribute controls the color of the shadow (not the outline, which is always black for some reason)\n\n```html\nText with red shadow \n```\n\n#### Shadow Offset\n\nThe `shadowOffset` attribute controls how far is the shadow offset from the text source (has no effect on the outline)\n\n```html\nText with red shadow, which is offset by half character size \n```\n\n#### Link Color\n\nWill change the color of the text if the text is a link, otherwise the text color is unaffected.\n\n```html\nBlue text Blue text too \nNormal text color \n```\n\n#### Hyperlink Reference\n\nThe `href` attribute is essential part of the `` tag and should contain URL of the destination (See Hyperlink).\n\n#### Image Reference\n\nThe `image` attribute is essential part of the `Top Right Middle Center Bottom Left `s inside another `` wrapper ensure that the hint will be 3 lines tall\n\nCreate clickable image:\n\n```sqf\n_ctrl = findDisplay 46 createDisplay \"RscDisplayEmpty\" ctrlCreate [\"RscStructuredText\", -1];\n_ctrl ctrlSetPosition [0,0,1,1];\n_ctrl ctrlCommit 0;\n_ctrl ctrlSetStructuredText parseText \"Large text \nLarge text \n```\n\n> [!WARNING]\n> The following will log an *.rpt* error `Unknown attribute .0` and only number 2 would be taken into account:\n>\n> ```html\n> Large text \n> ```"},{"heading":"Text","level":4,"markdown":"Texts could be created with the following markup:\n\n```html\nHello World! \n```\n\nOr could also be inserted via the composeText / formatText and text commands."},{"heading":"Special characters","level":5,"markdown":"To insert special characters, such as `<`, `>`, etc. you can use the [HTML representation](https://dev.w3.org/html5/html-author/charref) of that character, e.g.:\n\n| Character | HTML |\n|---|---|\n| < | `<` |\n| > | `>` |\n| non-breaking space | |\n| ... | ... |\n\n> [!IMPORTANT]\n> Using a special character directly will result in it being displayed as \"?\" or, in the case of writing \"\", will result in an error in the RPT: `Wrong text element 'TEXT'`"},{"heading":"Line break","level":4,"markdown":"Line breaks could be created with either of the following markups:\n\n```html\nArma 3 \n```\n\nBy default the links are not underlined or have a different color to stand out. These attributes should be added separately.\n\nNote: *&* should be escaped by *&*.\n\n```html\nExample URL A \nExample URL B \n```"},{"heading":"Attributes","level":3,"markdown":"The following inline attributes are supported:\n- `size`\n- `color`\n- `font`\n- `align`\n- `valign`\n- `underline`\n- `shadow`\n- `shadowColor`\n- `shadowOffset`\n- `colorLink`\n- `href`\n- `image`"},{"heading":"Size","level":4,"markdown":"The structured text `size` attribute is a multiplier for the value of control config property `size`. Default is 1, meaning that the height of letters will be equal to the value set in config. Setting this to 2 will make letters 2 times the size, 0.5 will make them half the size, etc. If the control is defined as follows:\n\n```cpp\nclass MyStructuredText : RscStructuredText \n{\n ...\n text = \"Hello!\";\n size = 0.04;\n ...\n};\n```\n\nThen the structured text:\n\n```sqf\n_control ctrlSetStructuredText parseText \"Hello! \";\n```\n\nWill result in a total text size of 0.04 * 2 = 0.08. Unfortunately, there is no script command to set or get the value of config `size` property dynamically."},{"heading":"Color","level":4,"markdown":"The `color` attribute is similar to HTML hex color and could either have format [#RRGGBB](https://en.wikipedia.org/wiki/RGB) or [#AARRGGBB](https://en.wikipedia.org/wiki/ARGB).\n\n```html\nRed text \nSemi-transparent white text \n```"},{"heading":"Font","level":4,"markdown":"The value for the `font` attribute could be found in `CfgFontFamilies` config. Some of the Arma 3 fonts:\n- `EtelkaMonospacePro`\n- `EtelkaMonospaceProBold`\n- `EtelkaNarrowMediumPro`\n- `LCD14`\n- `LucidaConsoleB`\n- `PuristaBold`\n- `PuristaLight`\n- `PuristaMedium`\n- `PuristaSemibold`\n- `RobotoCondensed`\n- `RobotoCondensedBold`\n- `RobotoCondensedLight`\n- `TahomaB`\n\n```html\nBold Text \nWicked looking text \n```"},{"heading":"Horizontal Alignment","level":4,"markdown":"The `align` attribute controls horizontal text alignment and could be one of the following:\n- `left`\n- `center`\n- `right`\n\n```html\nText displayed to the right \n```"},{"heading":"Vertical Alignment","level":4,"markdown":"The `valign` attribute controls vertical text alignment and could be one of the following:\n- `top`\n- `middle`\n- `bottom`\n\n```html\nText displayed at the bottom \n```"},{"heading":"Underline","level":4,"markdown":"The `underline` attribute underlines each individual word in text. The normal spaces are not underlined.\n\n```html\nUnderlined Text \n```\n\n> [!NOTE]\n> If you would like to have a continuous underline between words, use non-breaking spaces. This could be achieved in several ways:\n> - Insertion from keyboard: [Alt+255](https://en.wikipedia.org/wiki/Non-breaking_space#Keyboard_entry_methods)\n> - Scripted method:\n>\n> ```sqf\n> hint parseText format [\"%1 \", \"Underlined Text\" splitString \" \" joinString toString [160]]\n> ```\n>\n> - Using HTML code:\n>\n> ```sqf\n> hint parseText \"Underlined Text \";\n> ```"},{"heading":"Shadow","level":4,"markdown":"The `shadow` attribute controls the appearance of shadow/outline around text and could be one of the following:\n- `0` - normal text\n- `1` - classic shadow (text ghosting below and to the right)\n- `2` - outline (slight, always black, outline around characters)\n\n```html\nText with no shadow \nText with default black shadow \nText with default black outline \n```"},{"heading":"Shadow Color","level":4,"markdown":"The `shadowColor` attribute controls the color of the shadow (not the outline, which is always black for some reason)\n\n```html\nText with red shadow \n```"},{"heading":"Shadow Offset","level":4,"markdown":"The `shadowOffset` attribute controls how far is the shadow offset from the text source (has no effect on the outline)\n\n```html\nText with red shadow, which is offset by half character size \n```"},{"heading":"Link Color","level":4,"markdown":"Will change the color of the text if the text is a link, otherwise the text color is unaffected.\n\n```html\nBlue text Blue text too \nNormal text color \n```"},{"heading":"Hyperlink Reference","level":4,"markdown":"The `href` attribute is essential part of the `` tag and should contain URL of the destination (See Hyperlink)."},{"heading":"Image Reference","level":4,"markdown":"The `image` attribute is essential part of the `Top Right Middle Center Bottom Left `s inside another `` wrapper ensure that the hint will be 3 lines tall\n\nCreate clickable image:\n\n```sqf\n_ctrl = findDisplay 46 createDisplay \"RscDisplayEmpty\" ctrlCreate [\"RscStructuredText\", -1];\n_ctrl ctrlSetPosition [0,0,1,1];\n_ctrl ctrlCommit 0;\n_ctrl ctrlSetStructuredText parseText \"Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_displayOrControl\", \"_key\", \"_shift\", \"_ctrl\", \"_alt\"];\ntrue // Intercepts the default action, e.g. pressing Escape won't close the dialog.\n```\n\nIn Arma 3, in order to be able to intercept key events during gameplay, the Event Handler should be added to Display 46:\n\n```sqf\nfindDisplay 46 displayAddEventHandler [\"KeyDown\", {}];\n```\n\nIn general, one should never return true in the `onKeyDown` EH, especially if it's added to Display 46 - otherwise all input is overridden and there is no way to do anything in the game anymore.\n\n> [!WARNING]\n> Pressing and holding key triggers 'autorepeat' action on Windows, which in turn will make this EH fire repeatedly as well.\n\n##### onKeyUp\n\n- **Use on:** Display, Control\n- **Fired on:** Releasing any keyboard key. Fired after the onKeyDown event.\n- **Returns:** Returns the display or control, the keyboard code and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_displayOrControl\", \"_key\", \"_shift\", \"_ctrl\", \"_alt\"];\n```\n\n##### onChar\n\n- **Use on:** Display, Control\n- **Fired on:** When some readable characters is recognised.\n- **Returns:** Returns the display or control and the [char code](https://www.ascii-code.com/).\n\n```sqf\nparams [\"_displayOrControl\", \"_charCode\"];\n```\n\n##### onIMEChar\n\n- **Use on:** Control\n- **Fired on:** When IME character is recognized (used in Korean and other eastern languages).\n- **Returns:** Returns the control and the char code.\n\n```sqf\nparams [\"_control\", \"_charCode\"];\n```\n\n##### onIMEComposition\n\n- **Use on:** Control\n- **Fired on:** When partial IME character is recognized (used in Korean and other eastern languages).\n- **Returns:** Returns the control and the char code.\n\n```sqf\nparams [\"_control\", \"_charCode\"];\n```\n\n##### onMouseButtonDown\n\n- **Use on:** Display, Control\n- **Fired on:** Pressing a mouse button. Followed by the `onMouseButtonUp` event.\n- **Returns:** Returns the display or control, the pressed button, the x and y coordinates and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_displayOrControl\", \"_button\", \"_xPos\", \"_yPos\", \"_shift\", \"_ctrl\", \"_alt\"];\n```\n\n##### onMouseButtonUp\n\n- **Use on:** Display, Control\n- **Fired on:** Releasing a mouse button. Follows the `onMouseButtonDown` event.\n- **Returns:** Returns the display or control, the pressed button, the x and y coordinates and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_displayOrControl\", \"_button\", \"_xPos\", \"_yPos\", \"_shift\", \"_ctrl\", \"_alt\"];\n```\n\n##### onMouseButtonClick\n\n- **Use on:** ListBox, ComboBox, TextBox, Button, ActiveText\n- **Fired on:** Pressing and releasing a mouse button.\n- **Returns:** Returns the control, the pressed button, the x and y coordinates and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_control\", \"_button\", \"_xPos\", \"_yPos\", \"_shift\", \"_ctrl\", \"_alt\"];\n```\n\n##### onMouseButtonDblClick\n\n- **Use on:** Control\n- **Fired on:** Pressing and releasing a mouse button twice within very short time.\n- **Returns:** Returns the control, the pressed button, the x and y coordinates and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_control\", \"_button\", \"_xPos\", \"_yPos\", \"_shift\", \"_ctrl\", \"_alt\"];\n```\n\n##### onMouseMoving\n\n- **Fired on:** Fires continuously while moving the mouse with a certain interval.\n\n---\n\n- **Use on:** Control, Display\n- **Returns:** Returns the control, the x and y coordinates relative to the controls parent and mouseOver.\nIf the controls parent is its display then x and y will be the same as getMousePosition else it will be relative to its parent control (for instance if inside a CT_CONTROLS_GROUP).\n\n```sqf\nparams [\"_control\", \"_xPos\", \"_yPos\", \"_mouseOver\"];\n```\n\n---\n\n- **Use on:** Display\n- **Returns:** Returns the display, and how much the mouse was moved since the last time the event fired in UI coordinates.\n\n```sqf\nparams [\"_display\", \"_xDeltaPos\", \"_yDeltaPos\"];\n```\n\n##### onMouseHolding\n\n- **Fired on:** Fires continuously with a specific interval while mouse is stationary.\n\n---\n\n- **Use on:** Control, Display\n- **Returns:** Returns the control, the x and y coordinates relative to the controls parent and mouseOver.\nIf the controls parent is its display then x and y will be the same as getMousePosition else it will be relative to its parent control (for instance if inside a CT_CONTROLS_GROUP).\n\n```sqf\nparams [\"_control\", \"_xPos\", \"_yPos\", \"_mouseOver\"];\n```\n\n---\n\n- **Use on:** Display\n- **Returns:** Returns the display, and *some kind of* x and y delta position.\n\n```sqf\nparams [\"_display\", \"_xPos\", \"_yPos\"];\n```\n\n##### onMouseZChanged\n\n- **Use on:** Display, Control\n- **Fired on:** Fires when mouse wheel position is changed. Only fires on enabled controls.\n- **Returns:** Returns the display or control and the change of the scrollwheel.\n\n```sqf\nparams [\"_displayOrControl\", \"_scroll\"];\n```\n\n##### onCanDestroy\n\n- **Use on:** Control\n- **Fired on:** Ask this control if dialog can be closed (used for validation of contained data).\n- **Returns:** Returns the control and exit code.\n\n```sqf\nparams [\"_control\", \"_exitCode\"];\n```\n\n##### onDestroy\n\n- **Use on:** Control\n- **Fired on:** Destroying control\n- **Returns:** Returns the control and exit code.\n\n```sqf\nparams [\"_control\", \"_exitCode\"];\n```\n\n#### Button Events\n\n##### onButtonClick\n\n- **Use on:** Button\n- **Fired on:** The attached button action is performed. When returned value is true, the engine behaviour is overridden.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```\n\n##### onButtonDblClick (Arma 3 v1.00)\n\n- **Use on:** Button\n- **Fired on:** Button double clicked.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```\n\n##### onButtonDown\n\n- **Use on:** Button\n- **Fired on:** The left mouse button is pressed over the button area or a key on the keyboard is pressed.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```\n\n##### onButtonUp\n\n- **Use on:** Button\n- **Fired on:** When left mouse button is released outside the button area and the attached button action **went unexecuted**.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```\n\n#### Listbox Events\n\n##### onLBSelChanged\n\n- **Use on:** Listbox, Combobox, Table\n- **Fired on:** The selection in a listbox is changed. The left mouse button has been released and the new selection is fully made.\n\n> [!WARNING]\n> This EH will fire even if no new selection was made and the user clicked on existing selection\n\n> [!NOTE]\n> Since Arma 3 v2.11 controls with the LB_MULTI style pass an additional `_lbSelection` parameter to the EH script (see lbCurSel, lbSelection).\n\n- **Returns:** Returns the control and the selected element index.\n\n```sqf\nparams [\"_control\", \"_lbCurSel\", \"_lbSelection\"];\n```\n\n##### onLBListSelChanged\n\n- **Use on:** Combobox\n- **Fired on:** When selection in XCombo box changed (but value has yet to be stored).\n- **Returns:** Returns the control and the selected element index.\n\n```sqf\nparams [\"_control\", \"_selectedIndex\"];\n```\n\n##### onLBDblClick\n\n- **Use on:** Listbox\n- **Fired on:** Double click on some row in listbox.\n- **Returns:** Returns the control and the selected element index.\n\n```sqf\nparams [\"_control\", \"_selectedIndex\"];\n```\n\n##### onLBDrag\n\n- **Use on:** Listbox\n- **Fired on:** Drag & drop operation started.\n- **Returns:** Returns the control and an array of arrays of information on the dragged item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).\nControl must have unique IDC and `canDrag` parameter enabled in its class in order to work.\n\n```sqf\nparams [\"_control\", \"_listboxInfo\"];\n// Get info of first item being dragged:\n(_listboxInfo select 0) params [\"_lbText\", \"_lbValue\", \"_lbData\"];\n```\n\n##### onLBDragging\n\n- **Use on:** Listbox\n- **Fired on:** Drag & drop operation is in progress.\n- **Returns:** Returns the control, the x and y coordinates in screen space, listbox IDC where item(s) were dragged from and an array of arrays of information on the dragged item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).\n\n```sqf\nparams [\"_control\", \"_xPos\", \"_yPos\", \"_listboxIDC\", \"_listboxInfo\"];\n// Get info of first item being dragged:\n(_listboxInfo select 0) params [\"_lbText\", \"_lbValue\", \"_lbData\"];\n```\n\n##### onLBDrop\n\n- **Use on:** Listbox, Combobox, Textbox, ActiveText, Button, ControlsGroup\n- **Fired on:** When a Drag & drop operation is finished.\n- **Returns:** Returns the control, the x and y coordinates in screen space, listbox IDC where item(s) were dragged from and an array of arrays of information on the dropped item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).\nWhen the Listbox is inside a CT_CONTROLS_GROUP the Event Handler needs to be added to the CT_CONTROLS_GROUP.\nWill only work for a CT_CONTROLS_GROUP that is outside of any other group.\n\n```sqf\nparams [\"_control\", \"_xPos\", \"_yPos\", \"_listboxIDC\", \"_listboxInfo\"];\n//Get info of first item being dropped:\n(_listboxInfo select 0) params [\"_lbText\", \"_lbValue\", \"_lbData\"];\n```\n\n#### Tree Events\n\n##### onTreeSelChanged\n\n- **Use on:** Tree\n- **Fired on:** Changing the selection in a tree.\n- **Returns:** Returns the control and the new selection path.\n\n```sqf\nparams [\"_control\", \"_selectionPath\"];\n```\n\n##### onTreeLButtonDown\n\n- **Use on:** Tree\n- **Fired on:** Pressing and releasing left mouse button on a tree.\n- **Returns:** Returns the control.\n\n```sqf\nparams [\"_control\"];\n```\n\n##### onTreeDblClick\n\n- **Use on:** Tree\n- **Fired on:** Pressing and releasing twice on a tree entry.\n- **Returns:** Returns the control and the current selection path.\n\n```sqf\nparams [\"_control\", \"_selectionPath\"];\n```\n\n##### onTreeExpanded\n\n- **Use on:** Tree\n- **Fired on:** The tree folder structure has been expanded.\n- **Returns:** Returns the control and path.\n\n```sqf\nparams [\"_control\", \"_selectionPath\"];\n```\n\n##### onTreeCollapsed\n\n- **Use on:** Tree\n- **Fired on:** The tree folder structure has been collapsed.\n- **Returns:** Returns the control and path.\n\n```sqf\nparams [\"_control\", \"_selectionPath\"];\n```\n\n##### onTreeMouseMove\n\n- **Use on:** Tree\n- **Fired on:** Fires continuously while moving the mouse with a certain interval.\n- **Returns:** Returns the control. Also returns the path, probably since Eden Editor update.\n\n```sqf\nparams [\"_control\", \"_path\"];\n```\n\n##### onTreeMouseHold\n\n- **Use on:** Tree\n- **Fired on:** Fires continuously at a specific interval while mouse is still.\n- **Returns:** Returns the control. Also returns the path, probably since Eden Editor update.\n\n```sqf\nparams [\"_control\", \"_path\"];\n```\n\n##### onTreeMouseExit\n\n- **Use on:** Tree\n- **Fired on:** The mouse pointer exits the tree control area\n- **Returns:** Returns the control.\n\n```sqf\nparams [\"_control\"];\n```\n\n##### onTreeFilterUpdated (Arma 3 v2.12)\n\n- **Use on:** Tree\n- **Fired on:** A search/filter done on the tree\n- **Returns:** Returns the control.\n\n```sqf\nparams [\"_treeControl\", \"_searchControl\", \"_searchString\"];\n```\n\n#### Checkbox Events\n\n##### onChecked (Arma 3 v1.00)\n\n- **Use on:** Checkbox (CT_CHECKBOX).\n- **Fired on:** N/A\n- **Returns:** N/A\n\n> [!NOTE]\n> This feature has yet to be implemented.\n\n##### onCheckedChanged (Arma 3 v1.00)\n\n- **Use on:** Checkbox (CT_CHECKBOX).\n- **Fired on:** Checked state of ctrlCheckBox / RscCheckBox changed.\n- **Returns:** Returns control and the checked state ( 0 for unchecked, 1 for checked ).\n\n```sqf\nparams [\"_control\", \"_checked\"];\n```\n\n##### onCheckBoxesSelChanged\n\n- **Use on:** Checkboxes (CT_CHECKBOXES).\n- **Fired on:** Changed the selection of checkboxes.\n- **Returns:** Returns the control, the selected element index and the current state.\n\n```sqf\nparams [\"_control\", \"_selectedIndex\", \"_currentState\"];\n```\n\n#### Misc. Events\n\n##### onToolBoxSelChanged\n\n- **Use on:** Toolbox\n- **Fired on:** Changed the selection in a toolbox.\n- **Returns:** Returns the control and the selected element index.\n\n```sqf\nparams [\"_control\", \"_selectedIndex\"];\n```\n\n##### onHTMLLink\n\n- **Use on:** HTML\n- **Fired on:** Pressing and releasing a HTML link.\n- **Returns:** Returns the control and href.\n\n```sqf\nparams [\"_control\", \"_url\"];\n```\n\n##### onSliderPosChanged\n\n- **Use on:** Slider\n- **Fired on:** Changing the position of a slider.\n- **Returns:** Returns the control and the change.\n\n```sqf\nparams [\"_control\", \"_newValue\"];\n```\n\n##### onObjectMoved\n\n- **Use on:** Object\n- **Fired on:** Moving an object.\n- **Returns:** Returns the control and the offset on the x, y and z axes.\n\n```sqf\nparams [\"_control\", \"_offset\"];\n```\n\n##### onMenuSelected\n\n- **Use on:** Context menu\n- **Fired on:** Some item in context menu (used now only in new mission editor) was selected.\n- **Returns:** Returns the control and the command id.\n\n```sqf\nparams [\"_control\", \"_commandId\"];\n```\n\n##### onDraw\n\n- **Use on:** Map, Display (only on UIOnTexture Display Arma 3 v2.12)\n- **Fired on:** Fires when the map is drawn or the UI On Texture Display received a draw request (can occur more than once per second).\n- **Returns:** Returns the map control.\n\n> [!IMPORTANT]\n> This event handler gets destroyed when the mission it was executed in ends.\n\n```sqf\nparams [\"_controlOrDisplay\"];\n```\n\n##### onVideoStopped (Arma 2: Operation Arrowhead v1.56)\n\n- **Use on:** Control\n- **Fired on:** Activated every time the video ends (when looped, handler is executed after every finished loop).\n- **Returns:** Returns the control.\n\n```sqf\nparams [\"_control\"];\n```\n\n> [!WARNING]\n> When using the event names via GUI scripting commands (e.g ctrlAddEventHandler, displayAddEventHandler), the prefix \"on\" in the name **must be removed** (e.g. `ButtonDown` instead of `onButtonDown`)!\n\n### Event Parameters\n\nThe Event Handlers receive parameters through the magic variable `_this`. Each event passes a different set of parameters (listed above) in an array. The control or display that the event was assigned to is always found in `_this select 0`.\n\n### Scope\n\nArmed Assault v1.00 In Armed Assault, most control-specific events ONLY work for controls and never for displays. The two exceptions being: `onKeyDown` and `onKeyUp`.\n\nArma 2 v1.00 Since Arma 2, most control-specific events work for both displays and controls.\n\n### Defining Events\n\nUser Interface Event Handlers can be assigned in two ways: Via class property definitions or via scripting commands.\n\n#### Class-Defined Events\n\nEvents can be defined in the Dialog (display) or Control classes (in Config.cpp or Description.ext). The event property value (string) is executed as a line of code.\n\nAn example line (this would be found within a control or dialog class):\n\n```cpp\nonMouseButtonDown = \"hint str _this\";\n```\n\nFull Example:\n\n```cpp\nclass RscControlsGroup\n{\n type = 15;\n idc = -1;\n style = 0;\n x = 0;\n y = 0;\n w = 1;\n h = 1;\n\n class VScrollbar\n {\n color[] = { 1, 1, 1, 1 };\n width = 0.021;\n autoScrollSpeed = -1;\n autoScrollDelay = 5;\n autoScrollRewind = 0;\n };\n\n class HScrollbar\n {\n color[] = { 1, 1, 1, 1 };\n height = 0.028;\n };\n\n class ScrollBar // >= Arma 2\n {\n color[] = { 1, 1, 1, 0.6 };\n colorActive[] = { 1, 1, 1, 1 };\n colorDisabled[] = { 1, 1, 1, 0.3 };\n thumb = \"#(argb,8,8,3)color(1,1,1,1)\";\n arrowEmpty = \"#(argb,8,8,3)color(1,1,1,1)\";\n arrowFull = \"#(argb,8,8,3)color(1,1,1,1)\";\n border = \"#(argb,8,8,3)color(1,1,1,1)\";\n };\n\n class Controls {};\n};\n\nclass MouseHandler : RscControlsGroup\n{\n onMouseHolding = \"[0, _this] call myEventFunction\";\n onMouseButtonDown = \"[1, _this] call myEventFunction\";\n onMouseButtonUp = \"[2, _this] call myEventFunction\";\n onMouseZChanged = \"[3, _this] call myEventFunction\";\n onMouseEnter = \"[4, _this] call myEventFunction\";\n idc = 123;\n x = 0.0;\n y = 0.0;\n w = 1.0;\n h = 1.0;\n colorBackground[] = { 0.2, 0.0, 0.0, 0.0 };\n};\n```\n\n#### Script-Defined Events\n\nThese events can also be given to dialogs and controls using the displayAddEventHandler and ctrlAddEventHandler commands. The control has to be enabled for the Event Handler in order for Event Handlers to fire (see ctrlEnable).\n\n```sqf\n// Add Event Handler:\n(findDisplay 46) displayAddEventHandler [\"KeyDown\", {\n _this call functionName_keyDown;\n}];\n\n// Function definition:\nfunctionName_keyDown = {\n params [\"_ctrl\", \"_dikCode\", \"_shift\", \"_ctrlKey\", \"_alt\"];\n private _handled = false;\n\n if (!_shift && !_ctrlKey && !_alt) then {\n if (_dikCode in (actionKeys \"NetworkStats\")) then {\n systemChat format [\"EH fired for %1\", _ctrl];\n _handled = true;\n };\n };\n\n _handled;\n};\n```","sections":[{"heading":null,"level":1,"markdown":"__NOEDITSECTION__\n\nUser Interface Event Handlers are used to execute code when events related to GUI components (i.e. Displays and Controls) occur.\n\n> [!WARNING]\n> About ctrlDelete in an Event Handler's script: ctrlDelete needs to be the last executed statement or Arma will crash.\n>\n> Alternatively, the code can also be spawned to circumvent this issue.\n>\n> ```cpp\n> onButtonClick = \"ctrlDelete (_this select 0); systemChat 'You will never see this';\"; // Crashes the game\n> onButtonClick = \"systemChat 'Bye bye button!'; ctrlDelete (_this select 0);\"; // Works fine\n> onButtonClick = \"_this spawn { ctrlDelete (_this select 0); systemChat 'Bye bye button!'; };\"; // Works fine\n> ```"},{"heading":"Reference List","level":3,"markdown":""},{"heading":"Generic Events","level":4,"markdown":""},{"heading":"onLoad","level":5,"markdown":"- **Use on:** Display, Control\n- **Fired on:** Fires when UI container is created, but no action is taken. The `onLoad` event for display fires **after** the `onLoad` events for all controls it contains are fired.\n- **Returns:** Display or control, for controls it also returns the control's config (since Arma 3 v1.56).\n\n```sqf\nparams [\"_displayOrControl\", [\"_config\", configNull]];\n```\n\n> [!NOTE]\n> The order of initialisation is as follows:\n> 1. all controls, top to bottom.\n> 1. Display\n> This means that during the `onLoad` event of the upper controls the lower controls have yet to be created."},{"heading":"onUnload","level":5,"markdown":"- **Use on:** Display\n- **Fired on:** Display is closed, but no controls are destroyed yet.\n- **Returns:** Returns the display and exit code.\n\n```sqf\nparams [\"_display\", \"_exitCode\"];\n```\n\n> [!NOTE]\n> The `onUnload` event never fires for RscTitles displays created with cutRsc.\n\n> [!WARNING]\n> Code or function should be called, otherwise controls might be destroyed before spawned code is executed!"},{"heading":"onChildDestroyed","level":5,"markdown":"- **Use on:** Display\n- **Fired on:** Child display is closed.\n- **Returns:** Returns the display, which child display was closed and exit code.\n\n```sqf\nparams [\"_display\", \"_closedChildDisplay\", \"_exitCode\"];\n```"},{"heading":"onCommitted (Arma 3 v2.14)","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** ctrlSetFade, ctrlSetScale, ctrlSetAngle and ctrlSetPosition in combination with ctrlCommit.\n- **Returns:** Returns the control, type of animation (`\"alpha\"`, `\"scale\"`, `\"rotation\"` or `\"position\"`) and the committed time.\n\n```sqf\nparams [\"_control\", \"_animType\", \"_animTime\"];\n```"},{"heading":"onEditChanged (Arma 3 v2.14)","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** Any changes to the CT_EDIT text field content.\n- **Returns:** Returns the control and the changed text.\n\n```sqf\nparams [\"_control\", \"_newText\"];\n```"},{"heading":"onMouseEnter","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** The mouse pointer enters the control area.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```\n\n> [!NOTE]\n> The `onMouseEnter` event only fires on enabled buttons (see ctrlEnable).\n>\n> Arma 3 v2.18 This event handler type seems to only work on controls that can be interacted with. For example buttons, listboxes and so on."},{"heading":"onMouseExit","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** The mouse pointer exits the control area.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```\n\n> [!NOTE]\n> Arma 3 v2.18 This event handler type seems to only work on controls that can be interacted with. For example buttons, listboxes and so on."},{"heading":"onSetFocus","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** Input focus is on control. It now begins to accept keyboard input.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```"},{"heading":"onKillFocus","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** Input focus is no longer on control. It no longer accepts keyboard input.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```"},{"heading":"onTimer","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** N/A.\n- **Returns:** N/A.\n\n> [!NOTE]\n> This feature has yet to be implemented."},{"heading":"onKeyDown","level":5,"markdown":"- **Use on:** Display, Control\n- **Fired on:** Pressing any keyboard key. Fired before the `onKeyUp` event.\n- **Returns:** Returns the display or control, the keyboard code and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_displayOrControl\", \"_key\", \"_shift\", \"_ctrl\", \"_alt\"];\ntrue // Intercepts the default action, e.g. pressing Escape won't close the dialog.\n```\n\nIn Arma 3, in order to be able to intercept key events during gameplay, the Event Handler should be added to Display 46:\n\n```sqf\nfindDisplay 46 displayAddEventHandler [\"KeyDown\", {}];\n```\n\nIn general, one should never return true in the `onKeyDown` EH, especially if it's added to Display 46 - otherwise all input is overridden and there is no way to do anything in the game anymore.\n\n> [!WARNING]\n> Pressing and holding key triggers 'autorepeat' action on Windows, which in turn will make this EH fire repeatedly as well."},{"heading":"onKeyUp","level":5,"markdown":"- **Use on:** Display, Control\n- **Fired on:** Releasing any keyboard key. Fired after the onKeyDown event.\n- **Returns:** Returns the display or control, the keyboard code and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_displayOrControl\", \"_key\", \"_shift\", \"_ctrl\", \"_alt\"];\n```"},{"heading":"onChar","level":5,"markdown":"- **Use on:** Display, Control\n- **Fired on:** When some readable characters is recognised.\n- **Returns:** Returns the display or control and the [char code](https://www.ascii-code.com/).\n\n```sqf\nparams [\"_displayOrControl\", \"_charCode\"];\n```"},{"heading":"onIMEChar","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** When IME character is recognized (used in Korean and other eastern languages).\n- **Returns:** Returns the control and the char code.\n\n```sqf\nparams [\"_control\", \"_charCode\"];\n```"},{"heading":"onIMEComposition","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** When partial IME character is recognized (used in Korean and other eastern languages).\n- **Returns:** Returns the control and the char code.\n\n```sqf\nparams [\"_control\", \"_charCode\"];\n```"},{"heading":"onMouseButtonDown","level":5,"markdown":"- **Use on:** Display, Control\n- **Fired on:** Pressing a mouse button. Followed by the `onMouseButtonUp` event.\n- **Returns:** Returns the display or control, the pressed button, the x and y coordinates and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_displayOrControl\", \"_button\", \"_xPos\", \"_yPos\", \"_shift\", \"_ctrl\", \"_alt\"];\n```"},{"heading":"onMouseButtonUp","level":5,"markdown":"- **Use on:** Display, Control\n- **Fired on:** Releasing a mouse button. Follows the `onMouseButtonDown` event.\n- **Returns:** Returns the display or control, the pressed button, the x and y coordinates and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_displayOrControl\", \"_button\", \"_xPos\", \"_yPos\", \"_shift\", \"_ctrl\", \"_alt\"];\n```"},{"heading":"onMouseButtonClick","level":5,"markdown":"- **Use on:** ListBox, ComboBox, TextBox, Button, ActiveText\n- **Fired on:** Pressing and releasing a mouse button.\n- **Returns:** Returns the control, the pressed button, the x and y coordinates and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_control\", \"_button\", \"_xPos\", \"_yPos\", \"_shift\", \"_ctrl\", \"_alt\"];\n```"},{"heading":"onMouseButtonDblClick","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** Pressing and releasing a mouse button twice within very short time.\n- **Returns:** Returns the control, the pressed button, the x and y coordinates and the state of Shift , Ctrl and Alt .\n\n```sqf\nparams [\"_control\", \"_button\", \"_xPos\", \"_yPos\", \"_shift\", \"_ctrl\", \"_alt\"];\n```"},{"heading":"onMouseMoving","level":5,"markdown":"- **Fired on:** Fires continuously while moving the mouse with a certain interval.\n\n---\n\n- **Use on:** Control, Display\n- **Returns:** Returns the control, the x and y coordinates relative to the controls parent and mouseOver.\nIf the controls parent is its display then x and y will be the same as getMousePosition else it will be relative to its parent control (for instance if inside a CT_CONTROLS_GROUP).\n\n```sqf\nparams [\"_control\", \"_xPos\", \"_yPos\", \"_mouseOver\"];\n```\n\n---\n\n- **Use on:** Display\n- **Returns:** Returns the display, and how much the mouse was moved since the last time the event fired in UI coordinates.\n\n```sqf\nparams [\"_display\", \"_xDeltaPos\", \"_yDeltaPos\"];\n```"},{"heading":"onMouseHolding","level":5,"markdown":"- **Fired on:** Fires continuously with a specific interval while mouse is stationary.\n\n---\n\n- **Use on:** Control, Display\n- **Returns:** Returns the control, the x and y coordinates relative to the controls parent and mouseOver.\nIf the controls parent is its display then x and y will be the same as getMousePosition else it will be relative to its parent control (for instance if inside a CT_CONTROLS_GROUP).\n\n```sqf\nparams [\"_control\", \"_xPos\", \"_yPos\", \"_mouseOver\"];\n```\n\n---\n\n- **Use on:** Display\n- **Returns:** Returns the display, and *some kind of* x and y delta position.\n\n```sqf\nparams [\"_display\", \"_xPos\", \"_yPos\"];\n```"},{"heading":"onMouseZChanged","level":5,"markdown":"- **Use on:** Display, Control\n- **Fired on:** Fires when mouse wheel position is changed. Only fires on enabled controls.\n- **Returns:** Returns the display or control and the change of the scrollwheel.\n\n```sqf\nparams [\"_displayOrControl\", \"_scroll\"];\n```"},{"heading":"onCanDestroy","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** Ask this control if dialog can be closed (used for validation of contained data).\n- **Returns:** Returns the control and exit code.\n\n```sqf\nparams [\"_control\", \"_exitCode\"];\n```"},{"heading":"onDestroy","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** Destroying control\n- **Returns:** Returns the control and exit code.\n\n```sqf\nparams [\"_control\", \"_exitCode\"];\n```"},{"heading":"Button Events","level":4,"markdown":""},{"heading":"onButtonClick","level":5,"markdown":"- **Use on:** Button\n- **Fired on:** The attached button action is performed. When returned value is true, the engine behaviour is overridden.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```"},{"heading":"onButtonDblClick (Arma 3 v1.00)","level":5,"markdown":"- **Use on:** Button\n- **Fired on:** Button double clicked.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```"},{"heading":"onButtonDown","level":5,"markdown":"- **Use on:** Button\n- **Fired on:** The left mouse button is pressed over the button area or a key on the keyboard is pressed.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```"},{"heading":"onButtonUp","level":5,"markdown":"- **Use on:** Button\n- **Fired on:** When left mouse button is released outside the button area and the attached button action **went unexecuted**.\n- **Returns:** Returns control.\n\n```sqf\nparams [\"_control\"];\n```"},{"heading":"Listbox Events","level":4,"markdown":""},{"heading":"onLBSelChanged","level":5,"markdown":"- **Use on:** Listbox, Combobox, Table\n- **Fired on:** The selection in a listbox is changed. The left mouse button has been released and the new selection is fully made.\n\n> [!WARNING]\n> This EH will fire even if no new selection was made and the user clicked on existing selection\n\n> [!NOTE]\n> Since Arma 3 v2.11 controls with the LB_MULTI style pass an additional `_lbSelection` parameter to the EH script (see lbCurSel, lbSelection).\n\n- **Returns:** Returns the control and the selected element index.\n\n```sqf\nparams [\"_control\", \"_lbCurSel\", \"_lbSelection\"];\n```"},{"heading":"onLBListSelChanged","level":5,"markdown":"- **Use on:** Combobox\n- **Fired on:** When selection in XCombo box changed (but value has yet to be stored).\n- **Returns:** Returns the control and the selected element index.\n\n```sqf\nparams [\"_control\", \"_selectedIndex\"];\n```"},{"heading":"onLBDblClick","level":5,"markdown":"- **Use on:** Listbox\n- **Fired on:** Double click on some row in listbox.\n- **Returns:** Returns the control and the selected element index.\n\n```sqf\nparams [\"_control\", \"_selectedIndex\"];\n```"},{"heading":"onLBDrag","level":5,"markdown":"- **Use on:** Listbox\n- **Fired on:** Drag & drop operation started.\n- **Returns:** Returns the control and an array of arrays of information on the dragged item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).\nControl must have unique IDC and `canDrag` parameter enabled in its class in order to work.\n\n```sqf\nparams [\"_control\", \"_listboxInfo\"];\n// Get info of first item being dragged:\n(_listboxInfo select 0) params [\"_lbText\", \"_lbValue\", \"_lbData\"];\n```"},{"heading":"onLBDragging","level":5,"markdown":"- **Use on:** Listbox\n- **Fired on:** Drag & drop operation is in progress.\n- **Returns:** Returns the control, the x and y coordinates in screen space, listbox IDC where item(s) were dragged from and an array of arrays of information on the dragged item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).\n\n```sqf\nparams [\"_control\", \"_xPos\", \"_yPos\", \"_listboxIDC\", \"_listboxInfo\"];\n// Get info of first item being dragged:\n(_listboxInfo select 0) params [\"_lbText\", \"_lbValue\", \"_lbData\"];\n```"},{"heading":"onLBDrop","level":5,"markdown":"- **Use on:** Listbox, Combobox, Textbox, ActiveText, Button, ControlsGroup\n- **Fired on:** When a Drag & drop operation is finished.\n- **Returns:** Returns the control, the x and y coordinates in screen space, listbox IDC where item(s) were dragged from and an array of arrays of information on the dropped item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).\nWhen the Listbox is inside a CT_CONTROLS_GROUP the Event Handler needs to be added to the CT_CONTROLS_GROUP.\nWill only work for a CT_CONTROLS_GROUP that is outside of any other group.\n\n```sqf\nparams [\"_control\", \"_xPos\", \"_yPos\", \"_listboxIDC\", \"_listboxInfo\"];\n//Get info of first item being dropped:\n(_listboxInfo select 0) params [\"_lbText\", \"_lbValue\", \"_lbData\"];\n```"},{"heading":"Tree Events","level":4,"markdown":""},{"heading":"onTreeSelChanged","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** Changing the selection in a tree.\n- **Returns:** Returns the control and the new selection path.\n\n```sqf\nparams [\"_control\", \"_selectionPath\"];\n```"},{"heading":"onTreeLButtonDown","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** Pressing and releasing left mouse button on a tree.\n- **Returns:** Returns the control.\n\n```sqf\nparams [\"_control\"];\n```"},{"heading":"onTreeDblClick","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** Pressing and releasing twice on a tree entry.\n- **Returns:** Returns the control and the current selection path.\n\n```sqf\nparams [\"_control\", \"_selectionPath\"];\n```"},{"heading":"onTreeExpanded","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** The tree folder structure has been expanded.\n- **Returns:** Returns the control and path.\n\n```sqf\nparams [\"_control\", \"_selectionPath\"];\n```"},{"heading":"onTreeCollapsed","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** The tree folder structure has been collapsed.\n- **Returns:** Returns the control and path.\n\n```sqf\nparams [\"_control\", \"_selectionPath\"];\n```"},{"heading":"onTreeMouseMove","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** Fires continuously while moving the mouse with a certain interval.\n- **Returns:** Returns the control. Also returns the path, probably since Eden Editor update.\n\n```sqf\nparams [\"_control\", \"_path\"];\n```"},{"heading":"onTreeMouseHold","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** Fires continuously at a specific interval while mouse is still.\n- **Returns:** Returns the control. Also returns the path, probably since Eden Editor update.\n\n```sqf\nparams [\"_control\", \"_path\"];\n```"},{"heading":"onTreeMouseExit","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** The mouse pointer exits the tree control area\n- **Returns:** Returns the control.\n\n```sqf\nparams [\"_control\"];\n```"},{"heading":"onTreeFilterUpdated (Arma 3 v2.12)","level":5,"markdown":"- **Use on:** Tree\n- **Fired on:** A search/filter done on the tree\n- **Returns:** Returns the control.\n\n```sqf\nparams [\"_treeControl\", \"_searchControl\", \"_searchString\"];\n```"},{"heading":"Checkbox Events","level":4,"markdown":""},{"heading":"onChecked (Arma 3 v1.00)","level":5,"markdown":"- **Use on:** Checkbox (CT_CHECKBOX).\n- **Fired on:** N/A\n- **Returns:** N/A\n\n> [!NOTE]\n> This feature has yet to be implemented."},{"heading":"onCheckedChanged (Arma 3 v1.00)","level":5,"markdown":"- **Use on:** Checkbox (CT_CHECKBOX).\n- **Fired on:** Checked state of ctrlCheckBox / RscCheckBox changed.\n- **Returns:** Returns control and the checked state ( 0 for unchecked, 1 for checked ).\n\n```sqf\nparams [\"_control\", \"_checked\"];\n```"},{"heading":"onCheckBoxesSelChanged","level":5,"markdown":"- **Use on:** Checkboxes (CT_CHECKBOXES).\n- **Fired on:** Changed the selection of checkboxes.\n- **Returns:** Returns the control, the selected element index and the current state.\n\n```sqf\nparams [\"_control\", \"_selectedIndex\", \"_currentState\"];\n```"},{"heading":"Misc. Events","level":4,"markdown":""},{"heading":"onToolBoxSelChanged","level":5,"markdown":"- **Use on:** Toolbox\n- **Fired on:** Changed the selection in a toolbox.\n- **Returns:** Returns the control and the selected element index.\n\n```sqf\nparams [\"_control\", \"_selectedIndex\"];\n```"},{"heading":"onHTMLLink","level":5,"markdown":"- **Use on:** HTML\n- **Fired on:** Pressing and releasing a HTML link.\n- **Returns:** Returns the control and href.\n\n```sqf\nparams [\"_control\", \"_url\"];\n```"},{"heading":"onSliderPosChanged","level":5,"markdown":"- **Use on:** Slider\n- **Fired on:** Changing the position of a slider.\n- **Returns:** Returns the control and the change.\n\n```sqf\nparams [\"_control\", \"_newValue\"];\n```"},{"heading":"onObjectMoved","level":5,"markdown":"- **Use on:** Object\n- **Fired on:** Moving an object.\n- **Returns:** Returns the control and the offset on the x, y and z axes.\n\n```sqf\nparams [\"_control\", \"_offset\"];\n```"},{"heading":"onMenuSelected","level":5,"markdown":"- **Use on:** Context menu\n- **Fired on:** Some item in context menu (used now only in new mission editor) was selected.\n- **Returns:** Returns the control and the command id.\n\n```sqf\nparams [\"_control\", \"_commandId\"];\n```"},{"heading":"onDraw","level":5,"markdown":"- **Use on:** Map, Display (only on UIOnTexture Display Arma 3 v2.12)\n- **Fired on:** Fires when the map is drawn or the UI On Texture Display received a draw request (can occur more than once per second).\n- **Returns:** Returns the map control.\n\n> [!IMPORTANT]\n> This event handler gets destroyed when the mission it was executed in ends.\n\n```sqf\nparams [\"_controlOrDisplay\"];\n```"},{"heading":"onVideoStopped (Arma 2: Operation Arrowhead v1.56)","level":5,"markdown":"- **Use on:** Control\n- **Fired on:** Activated every time the video ends (when looped, handler is executed after every finished loop).\n- **Returns:** Returns the control.\n\n```sqf\nparams [\"_control\"];\n```\n\n> [!WARNING]\n> When using the event names via GUI scripting commands (e.g ctrlAddEventHandler, displayAddEventHandler), the prefix \"on\" in the name **must be removed** (e.g. `ButtonDown` instead of `onButtonDown`)!"},{"heading":"Event Parameters","level":3,"markdown":"The Event Handlers receive parameters through the magic variable `_this`. Each event passes a different set of parameters (listed above) in an array. The control or display that the event was assigned to is always found in `_this select 0`."},{"heading":"Scope","level":3,"markdown":"Armed Assault v1.00 In Armed Assault, most control-specific events ONLY work for controls and never for displays. The two exceptions being: `onKeyDown` and `onKeyUp`.\n\nArma 2 v1.00 Since Arma 2, most control-specific events work for both displays and controls."},{"heading":"Defining Events","level":3,"markdown":"User Interface Event Handlers can be assigned in two ways: Via class property definitions or via scripting commands."},{"heading":"Class-Defined Events","level":4,"markdown":"Events can be defined in the Dialog (display) or Control classes (in Config.cpp or Description.ext). The event property value (string) is executed as a line of code.\n\nAn example line (this would be found within a control or dialog class):\n\n```cpp\nonMouseButtonDown = \"hint str _this\";\n```\n\nFull Example:\n\n```cpp\nclass RscControlsGroup\n{\n type = 15;\n idc = -1;\n style = 0;\n x = 0;\n y = 0;\n w = 1;\n h = 1;\n\n class VScrollbar\n {\n color[] = { 1, 1, 1, 1 };\n width = 0.021;\n autoScrollSpeed = -1;\n autoScrollDelay = 5;\n autoScrollRewind = 0;\n };\n\n class HScrollbar\n {\n color[] = { 1, 1, 1, 1 };\n height = 0.028;\n };\n\n class ScrollBar // >= Arma 2\n {\n color[] = { 1, 1, 1, 0.6 };\n colorActive[] = { 1, 1, 1, 1 };\n colorDisabled[] = { 1, 1, 1, 0.3 };\n thumb = \"#(argb,8,8,3)color(1,1,1,1)\";\n arrowEmpty = \"#(argb,8,8,3)color(1,1,1,1)\";\n arrowFull = \"#(argb,8,8,3)color(1,1,1,1)\";\n border = \"#(argb,8,8,3)color(1,1,1,1)\";\n };\n\n class Controls {};\n};\n\nclass MouseHandler : RscControlsGroup\n{\n onMouseHolding = \"[0, _this] call myEventFunction\";\n onMouseButtonDown = \"[1, _this] call myEventFunction\";\n onMouseButtonUp = \"[2, _this] call myEventFunction\";\n onMouseZChanged = \"[3, _this] call myEventFunction\";\n onMouseEnter = \"[4, _this] call myEventFunction\";\n idc = 123;\n x = 0.0;\n y = 0.0;\n w = 1.0;\n h = 1.0;\n colorBackground[] = { 0.2, 0.0, 0.0, 0.0 };\n};\n```"},{"heading":"Script-Defined Events","level":4,"markdown":"These events can also be given to dialogs and controls using the displayAddEventHandler and ctrlAddEventHandler commands. The control has to be enabled for the Event Handler in order for Event Handlers to fire (see ctrlEnable).\n\n```sqf\n// Add Event Handler:\n(findDisplay 46) displayAddEventHandler [\"KeyDown\", {\n _this call functionName_keyDown;\n}];\n\n// Function definition:\nfunctionName_keyDown = {\n params [\"_ctrl\", \"_dikCode\", \"_shift\", \"_ctrlKey\", \"_alt\"];\n private _handled = false;\n\n if (!_shift && !_ctrlKey && !_alt) then {\n if (_dikCode in (actionKeys \"NetworkStats\")) then {\n systemChat format [\"EH fired for %1\", _ctrl];\n _handled = true;\n };\n };\n\n _handled;\n};\n```"}],"categories":["Event Handlers","GUI Topics"],"groups":["Event Handlers"]},{"name":"Variables","title":"Variables","type":"topic","url":"https://community.bistudio.com/wiki/Variables","revid":376701,"updated":"2025-11-07T23:34:36Z","aliases":[],"markdown":"A variable is a \"storage container\" or \"named placeholder\" for data. You can read and modify the data once this container is created.\n\nIts \"name\" is referenced as Identifier.\n\n### Requirements\n\nThe following links guide to the basics to understand this article:\n\n- Introduction to Arma Scripting\n- Identifier\n\n### Initialisation\n\nThe first thing to do to create a variable is to find its name, also called identifier; this name must be speaking to the reader - keep in mind that code is meant to be read by *human beings* (see Code Best Practices - Variable format).\n\nOnce a proper name is found, it can be used to **declare** (or **initialise**) the variable:\n\n```sqf\nmyVariable = 0;\n```\n\nBefore Arma 2, querying undefined (or uninitialised) variables returns nil (undefined value); from Arma 2 and later, it returns an \"Error Undefined variable in expression\" error.\n\n> [!NOTE]\n> An undefined (nil) variable converted to String with str will return scalar bool array string 0xe0ffffef (in Armed Assault) and scalar bool array string 0xfcffffef (in Operation Flashpoint).\n>\n> Unless trying to emulate isNil, **always** declare your variable before trying to access it.\n\n### Deletion\n\nOnce created, variables take up space in the computer's memory.\n\nThis is not drastic for small variables, but if a big number of very large variables is used, it is recommended to undefine the unneeded ones in order to free up memory.\n\nVariable deletion is done by setting its value to nil:\n\n```sqf\nHugeVariable = nil;\n```\n\n> [!NOTE]\n> Local variables are automatically freed (deleted from memory) when their scope is exited, avoiding the need to manually deallocate them.\n\n### Scopes\n\nVariables are only visible in certain scopes of the game. This prevents name conflicts between different variables in different scripts.\n\nThere are two main scopes:\n\n#### Global Scope\n\nA global variable is visible from all scripts on the computer on which it was defined.\nNames given to units in the Mission Editor are also global variables pointing to those units, which may not be redefined or modified.\n\n> [!IMPORTANT]\n> a global variable can be different from one machine to another! To ensure the global variable's proper broadcast, see publicVariable, publicVariableServer and publicVariableClient.\n> If the value changes, the broadcast must be reapplied. e.g:\n>\n> ```sqf\n> GlobalVariable = 33;\n> publicVariable \"GlobalVariable\";\n>\n> GlobalVariable = 42; // GlobalVariable is now 42 on the current machine but still 33 on the others\n> publicVariable \"GlobalVariable\"; // updates the value to 42 for everyone\n> ```\n\n#### Local Scope\n\nA local variable is only visible in the Script, Function or Control Structure in which it was defined.\n\n> [!NOTE]\n> A local variable cannot be broadcast. In order to broadcast a local variable's *value*, it must be assigned to a global variable first:\n>\n> ```sqf\n> private _myLocalVariable = 33;\n> publicVariable \"_myLocalVariable\"; // incorrect\n>\n> GlobalVariable = _myLocalVariable;\n> publicVariable \"GlobalVariable\"; // correct\n> ```\n\n#### Local Variables Scope\n\n> [!WARNING]\n> Local variables in callable code (e.g Functions) should be scoped using the private/privateAll commands,\n> otherwise you may modify local variables of the calling script that are visible in the function.\n\n```sqf\n// Since Arma 3 v1.54\nprivate _myLocalVariable = 0;\n\n// From Arma 2 until Arma 3 v1.54\nlocal _myLocalVariable = 0;\n\n// Before Arma 2\nprivate \"_myLocalVariable\";\n_myLocalVariable = 0;\n\n// Alternative method to private multiple local variables at the same time\nprivate [\"_myLocalVariable1\", \"_myLocalVariable2\"];\n_myLocalVariable1 = 1;\n_myLocalVariable2 = 2;\n```\n\nIf a private variable is initialised within a Control Structure (i.e. if, for, switch, while),\nits existence will be limited to it and its sub-structures - the variable does not exist outside of the structure and will be seen as undefined.\n\n| Variables