{"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
lifespan | Code | | | | | | | | |\n|---|---|---|---|---|---|---|---|---|---|\n| | | | | | | | | | **BEGINNING OF FILE** - e.g `execVM \"script.sqf\";` |\n| | | | | | | | | | **TAG_GlobalVariable** = \"Global variable\"; `// Global variable is accessible from any scope` |\n| | | | | | | | | | |\n| | | | private **_myVariable** = 0; | | | | | | |\n| | | if (**_condition**) then | | | | | | | |\n| | | { | | | | | | | |\n| | | **_myVariable** = 1; | | | | | | | |\n| | | | private **_myVariable** = 2; | | | | | | |\n| | | **_myVariable** = 3; | | | | | | | |\n| | | | } else { | | | | | | |\n| | | **_myVariable** = 4; | | | | | | | |\n| | | private **_anotherVariable** = 10; | | | | | | | |\n| | | }; | | | | | | | |\n| | | | | | | | | | |\n| | | hint str **_myVariable**;\t\t\t`// if **_condition** is true, **_myVariable**'s value is **1**;` | | | | | | | |\n| | | `// if **_condition** is false, **_myVariable**'s value is **4**.` | | | | | | | |\n| | | | | | | | | | |\n| | | 0 call { | | | | | | | |\n| | | hint str **_myVariable**;\t\t`// works, as called code runs in the same scope` | | | | | | | |\n| | | }; | | | | | | | |\n| | | | | | | | | | |\n| | | [**_myVariable**] spawn { | | | | | | | |\n| | | | hint **TAG_GlobalVariable**;\t`// works` | | | | | | |\n| | | | hint str _myVariable;\t\t`// throws an \"undefined variable\" error,` | | | | | | |\n| | | | `// as **_myVariable** does **not** exist in this new script` | | | | | | |\n| | | | }; | | | | | | |\n| | | | | | | | | | |\n| | | `// trying to use **_anotherVariable** here would result in an \"undefined variable\" error,` | | | | | | | |\n| | | `// **_anotherVariable** being only scoped in the else block.` | | | | | | | |\n| | | | | | | | | **END OF FILE** - **TAG_GlobalVariable** keeps on living in missionNamespace | |\n\n| Correct | Incorrect |\n|---|---|\n| ```sqf
private _living = false;
if (alive player) then
{
_living = true;
};
hint format [\"%1\", _living]; // returns true
``` | ```sqf
// -
if (alive player) then
{
private _living = true;
};
// throws an error since the private variable was
// not initialised outside of the if control structure.
hint format [\"%1\", _living];
``` |\n\n### Data Types\n\nVariables may store values of a certain Data Types (String, Number, etc). The kind of the value specifies the *type* of the variable.\nDifferent operators and commands require variables to be of different types.\n\nA variable is not strongly typed and changes its type according to the new data:\n\n```sqf\nprivate \"_myVariable\"; // nil\n_myVariable = 1; // 1 (Number)\n_myVariable = \"test\"; // \"test\" (String)\n```\n\n### Multiplayer Considerations\n\nStoring functions (or any callable code) into global variables without securing them with compileFinal (since Arma 3) is a **very** bad practice in multiplayer.\nThe biggest security risk would be to see it being overridden by a malicious usage of publicVariable, setting potentially dangerous code in it.\n\nThe best option is to declare your function in CfgFunctions so the engine secures it for you.\n\nIf you want to manually create a global function anyway, the best practice is the following:\n\n```sqf\nTAG_MyGlobalVariableFunction = compileFinal preprocessFileLineNumbers \"functionFile.sqf\";\n```\n\n> [!NOTE]\n> You should ideally run this code locally on every machine.\n> Using publicVariable on a \"final\" global function (created with compileFinal) will indeed broadcast the variable **and** make it final on other clients as well, but the network can quickly become saturated from sending big pieces of code.\n\n### See also\n\n- Introduction to Arma Scripting\n- Identifier\n- Data Types\n- Control Structures\n- Magic Variables\n- private/privateAll (Arma 3)\n- local (Arma 2)","sections":[{"heading":null,"level":1,"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."},{"heading":"Requirements","level":3,"markdown":"The following links guide to the basics to understand this article:\n\n- Introduction to Arma Scripting\n- Identifier"},{"heading":"Initialisation","level":3,"markdown":"The 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."},{"heading":"Deletion","level":3,"markdown":"Once 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."},{"heading":"Scopes","level":3,"markdown":"Variables 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:"},{"heading":"Global Scope","level":4,"markdown":"A 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> ```"},{"heading":"Local Scope","level":4,"markdown":"A 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> ```"},{"heading":"Local Variables Scope","level":4,"markdown":"> [!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
lifespan | Code | | | | | | | | |\n|---|---|---|---|---|---|---|---|---|---|\n| | | | | | | | | | **BEGINNING OF FILE** - e.g `execVM \"script.sqf\";` |\n| | | | | | | | | | **TAG_GlobalVariable** = \"Global variable\"; `// Global variable is accessible from any scope` |\n| | | | | | | | | | |\n| | | | private **_myVariable** = 0; | | | | | | |\n| | | if (**_condition**) then | | | | | | | |\n| | | { | | | | | | | |\n| | | **_myVariable** = 1; | | | | | | | |\n| | | | private **_myVariable** = 2; | | | | | | |\n| | | **_myVariable** = 3; | | | | | | | |\n| | | | } else { | | | | | | |\n| | | **_myVariable** = 4; | | | | | | | |\n| | | private **_anotherVariable** = 10; | | | | | | | |\n| | | }; | | | | | | | |\n| | | | | | | | | | |\n| | | hint str **_myVariable**;\t\t\t`// if **_condition** is true, **_myVariable**'s value is **1**;` | | | | | | | |\n| | | `// if **_condition** is false, **_myVariable**'s value is **4**.` | | | | | | | |\n| | | | | | | | | | |\n| | | 0 call { | | | | | | | |\n| | | hint str **_myVariable**;\t\t`// works, as called code runs in the same scope` | | | | | | | |\n| | | }; | | | | | | | |\n| | | | | | | | | | |\n| | | [**_myVariable**] spawn { | | | | | | | |\n| | | | hint **TAG_GlobalVariable**;\t`// works` | | | | | | |\n| | | | hint str _myVariable;\t\t`// throws an \"undefined variable\" error,` | | | | | | |\n| | | | `// as **_myVariable** does **not** exist in this new script` | | | | | | |\n| | | | }; | | | | | | |\n| | | | | | | | | | |\n| | | `// trying to use **_anotherVariable** here would result in an \"undefined variable\" error,` | | | | | | | |\n| | | `// **_anotherVariable** being only scoped in the else block.` | | | | | | | |\n| | | | | | | | | **END OF FILE** - **TAG_GlobalVariable** keeps on living in missionNamespace | |\n\n| Correct | Incorrect |\n|---|---|\n| ```sqf
private _living = false;
if (alive player) then
{
_living = true;
};
hint format [\"%1\", _living]; // returns true
``` | ```sqf
// -
if (alive player) then
{
private _living = true;
};
// throws an error since the private variable was
// not initialised outside of the if control structure.
hint format [\"%1\", _living];
``` |"},{"heading":"Data Types","level":3,"markdown":"Variables may store values of a certain Data Types (String, Number, etc). The kind of the value specifies the *type* of the variable.\nDifferent operators and commands require variables to be of different types.\n\nA variable is not strongly typed and changes its type according to the new data:\n\n```sqf\nprivate \"_myVariable\"; // nil\n_myVariable = 1; // 1 (Number)\n_myVariable = \"test\"; // \"test\" (String)\n```"},{"heading":"Multiplayer Considerations","level":3,"markdown":"Storing functions (or any callable code) into global variables without securing them with compileFinal (since Arma 3) is a **very** bad practice in multiplayer.\nThe biggest security risk would be to see it being overridden by a malicious usage of publicVariable, setting potentially dangerous code in it.\n\nThe best option is to declare your function in CfgFunctions so the engine secures it for you.\n\nIf you want to manually create a global function anyway, the best practice is the following:\n\n```sqf\nTAG_MyGlobalVariableFunction = compileFinal preprocessFileLineNumbers \"functionFile.sqf\";\n```\n\n> [!NOTE]\n> You should ideally run this code locally on every machine.\n> Using publicVariable on a \"final\" global function (created with compileFinal) will indeed broadcast the variable **and** make it final on other clients as well, but the network can quickly become saturated from sending big pieces of code."},{"heading":"See also","level":3,"markdown":"- Introduction to Arma Scripting\n- Identifier\n- Data Types\n- Control Structures\n- Magic Variables\n- private/privateAll (Arma 3)\n- local (Arma 2)"}],"categories":["Scripting Topics"],"groups":["Scripting"]}