{"name":"createUnit","operator":null,"title":"createUnit","type":"command","url":"https://community.bistudio.com/wiki/createUnit","revid":377516,"updated":"2026-01-02T06:50:26Z","groups":["Object Manipulation"],"status":"ok","replaced_by":[],"games":[{"game":"ofp","name":"Operation Flashpoint","version":"1.34"},{"game":"ofpe","name":"Operation Flashpoint: Elite","version":"1.00"},{"game":"arma1","name":"Armed Assault","version":"1.00"},{"game":"arma2","name":"Arma 2","version":"1.00"},{"game":"arma2oa","name":"Arma 2: Operation Arrowhead","version":"1.50"},{"game":"tkoh","name":"Take On Helicopters","version":"1.00"},{"game":"arma3","name":"Arma 3","version":"0.50"}],"since":{"game":"ofp","name":"Operation Flashpoint","version":"1.34"},"arma3_since":"0.50","branch":null,"locality":{"argument":"local","effect":"global","server_exec":false},"exec":null,"description":"Create a unit of the provided CfgVehicles class.\n\n> [!WARNING]\n> The unit will not be created if the passed group does not exist (a.k.a grpNull);\n> this can happen if createGroup fails because the **group limit has been reached** (see createGroup for respective game limits).\n\n|  | #Syntax 1 | #Syntax 2 |\n|---|---|---|\n| Group's locality | the provided group *can* be non-local, but a warning will be logged | the provided group **must** be local |\n| Unit's side | using a classname from a different side than the provided group will result in the unit itself being of a (config-defined) side inside a group of another side - see #Example 6 for more information | using a classname from a different side than the provided group will result in the unit being of the same side as the provided group |\n| Other | the unit's init code will execute after a slight delay if the provided group is not local | this syntax does **not** return a reference to the created unit (see #Example 7) |\n\n> [!NOTE]\n> **Armed Assault:** Operation Flashpoint v1.34 Armed Assault v1.00 This command was sometimes bugged in Operation Flashpoint or Armed Assault; an additional join may solve the problem.\n>\n> However, some commands such as setUnitPos only work if run before the join.","syntaxes":[{"syntax":"group createUnit [type, position, markers, placement, special]","since":null,"effect":null,"exec":null,"params":[{"name":"group","type":"Group","optional":false,"default":null,"description":"existing group new unit will join; if the group is not local, a warning will be logged","types":["Group"],"since":null,"text":"group: Group - existing group new unit will join; if the group is not local, a warning will be logged"},{"name":"type","type":"String","optional":false,"default":null,"description":"classname of unit to be created as per CfgVehicles","types":["String"],"since":null,"text":"type: String - classname of unit to be created as per CfgVehicles"},{"name":"position","type":"Object, Group or Position or Position2D","optional":false,"default":null,"description":"location where to create the unit. In case of Group, the group leader's position is used. The Z component of the position is ignored and the unit is always placed on the surface.","types":["Object","Group","Position","Position2D"],"since":null,"text":"position: Object, Group or Position or Position2D - location where to create the unit. In case of Group, the group leader's position is used. The Z component of the position is ignored and the unit is always placed on the surface."},{"name":"markers","type":"Array","optional":false,"default":null,"description":"placement markers","types":["Array"],"since":null,"text":"markers: Array - placement markers"},{"name":"placement","type":"Number","optional":false,"default":null,"description":"placement radius","types":["Number"],"since":null,"text":"placement: Number - placement radius"},{"name":"special","type":"String","optional":false,"default":null,"description":"unit placement special, one of:\n- `\"NONE\"` - The unit will be created at the first available free position nearest to given position\n- `\"FORM\"` - Not implemented, currently functions the same as \"NONE\"\n- `\"CAN_COLLIDE\"` - The unit will be created exactly at the provided position\n- `\"CARGO\"` - The unit will be created in cargo of the group's vehicle, regardless of the passed position (see #Example 5). If group has no vehicle or there is no cargo space available, the unit will be placed according to `\"NONE\"`. `\"CARGO\"` placement excludes cargo positions with personal FFV turrets. To check available cargo space use:\n\n|  |  |\n|---|---|\n| Arma 3 v1.34 FFV | ```sqf<br>private _hasCargo = { isNull (_x select 0) } count (fullCrew [_veh, \"cargo\", true]) > 0;<br>``` |\n| before | ```sqf<br>_hasCargo = _veh emptyPositions \"CARGO\" > 0;<br>``` |","types":["String"],"since":null,"text":"special: String - unit placement special, one of:\n- `\"NONE\"` - The unit will be created at the first available free position nearest to given position\n- `\"FORM\"` - Not implemented, currently functions the same as \"NONE\"\n- `\"CAN_COLLIDE\"` - The unit will be created exactly at the provided position\n- `\"CARGO\"` - The unit will be created in cargo of the group's vehicle, regardless of the passed position (see #Example 5). If group has no vehicle or there is no cargo space available, the unit will be placed according to `\"NONE\"`. `\"CARGO\"` placement excludes cargo positions with personal FFV turrets. To check available cargo space use:\n\n|  |  |\n|---|---|\n| Arma 3 v1.34 FFV | ```sqf<br>private _hasCargo = { isNull (_x select 0) } count (fullCrew [_veh, \"cargo\", true]) > 0;<br>``` |\n| before | ```sqf<br>_hasCargo = _veh emptyPositions \"CARGO\" > 0;<br>``` |"}],"returns":{"type":"Object","types":["Object"],"description":"the created unit","text":"Object - the created unit"},"form":"binary","operator":null,"left":{"text":"group","types":["Group"]},"right":{"text":"[type, position, markers, placement, special]","types":["Array"]}},{"syntax":"type createUnit [position, group, init, skill, rank]","since":null,"effect":null,"exec":null,"params":[{"name":"type","type":"String","optional":false,"default":null,"description":"classname of unit to be created as per CfgVehicles","types":["String"],"since":null,"text":"type: String - classname of unit to be created as per CfgVehicles"},{"name":"position","type":"Object, Group or Position or Position2D","optional":false,"default":null,"description":"location at which the unit is created. In case of Group position of the group leader is used","types":["Object","Group","Position","Position2D"],"since":null,"text":"position: Object, Group or Position or Position2D - location at which the unit is created. In case of Group position of the group leader is used"},{"name":"group","type":"Group","optional":false,"default":null,"description":"existing group the new unit will join","types":["Group"],"since":null,"text":"group: Group - existing group the new unit will join"},{"name":"init","type":"String","optional":true,"default":"\"\"","description":"unit init statement, similar to unit init field in the editor. The code placed in unit init will run upon unit creation for every client on network, present and future.\nThe code itself receives the reference to the created unit via local variable this.\n\n> [!WARNING]\n> - Do not use global effect commands in a unit's *init* as it runs on every client (local effect ones are OK, e.g setIdentity).\n> - Do not use local variables inside the init code as they are not available in multiplayer.","types":["String"],"since":null,"text":"init: String - (Optional, default \"\") unit init statement, similar to unit init field in the editor. The code placed in unit init will run upon unit creation for every client on network, present and future.\nThe code itself receives the reference to the created unit via local variable this.\n\n> [!WARNING]\n> - Do not use global effect commands in a unit's *init* as it runs on every client (local effect ones are OK, e.g setIdentity).\n> - Do not use local variables inside the init code as they are not available in multiplayer."},{"name":"skill","type":"Number","optional":true,"default":"0.5","description":"unit skill","types":["Number"],"since":null,"text":"skill: Number - (Optional, default 0.5) unit skill"},{"name":"rank","type":"String","optional":true,"default":"\"PRIVATE\"","description":"unit rank","types":["String"],"since":null,"text":"rank: String - (Optional, default \"PRIVATE\") unit rank"}],"returns":{"type":"> [!WARNING] > Nothing","types":["Nothing"],"description":"this syntax does not return a unit reference! See #Example 7 for a workaround.","text":"> [!WARNING]\n> **Nothing** - this syntax does **not** return a unit reference! See #Example 7 for a workaround."},"form":"binary","operator":null,"left":{"text":"type","types":["String"]},"right":{"text":"[position, group, init, skill, rank]","types":["Array"]}}],"examples":[{"text":"```sqf\n_unit = group player createUnit [\"B_RangeMaster_F\", position player, [], 0, \"NONE\"];\n```","code":["_unit = group player createUnit [\"B_RangeMaster_F\", position player, [], 0, \"NONE\"];"]},{"text":"```sqf\n\"B_RangeMaster_F\" createUnit [position player, group player];\n```","code":["\"B_RangeMaster_F\" createUnit [position player, group player];"]},{"text":"```sqf\n\"B_RangeMaster_F\" createUnit [getMarkerPos \"barracks\", _groupAlpha];\n```","code":["\"B_RangeMaster_F\" createUnit [getMarkerPos \"barracks\", _groupAlpha];"]},{"text":"```sqf\n\"B_RangeMaster_F\" createUnit [\n    getMarkerPos \"marker_1\",\n    _groupAlpha,\n    \"loon1 = this; this addWeapon 'BAF_L85A2_RIS_SUSAT'\",\n    0.6,\n    \"corporal\"\n];\n```","code":["\"B_RangeMaster_F\" createUnit [\n\tgetMarkerPos \"marker_1\",\n\t_groupAlpha,\n\t\"loon1 = this; this addWeapon 'BAF_L85A2_RIS_SUSAT'\",\n\t0.6,\n\t\"corporal\"\n];"]},{"text":"```sqf\n_veh = \"O_Quadbike_01_F\" createVehicle (player getRelPos [10, 0]);\n_grp = createVehicleCrew _veh;\n_unit = _grp createUnit [typeOf driver _veh, _grp, [], 0, \"CARGO\"];\n```","code":["_veh = \"O_Quadbike_01_F\" createVehicle (player getRelPos [10, 0]);\n_grp = createVehicleCrew _veh;\n_unit = _grp createUnit [typeOf driver _veh, _grp, [], 0, \"CARGO\"];"]},{"text":"Creating a unit from a different side may lead to issues:\n\n```sqf\n_grp = createGroup east;\nhint str side _grp; // EAST\n_ap = _grp createUnit [\"C_man_p_beggar_F\", position player, [], 0, \"NONE\"];\nhint str side _ap; // CIV, not EAST\n\n// workaround\n[_ap] joinSilent _grp;\nhint str side _ap; // EAST\n```","code":["_grp = createGroup east;\nhint str side _grp; // EAST\n_ap = _grp createUnit [\"C_man_p_beggar_F\", position player, [], 0, \"NONE\"];\nhint str side _ap; // CIV, not EAST\n\n// workaround\n[_ap] joinSilent _grp;\nhint str side _ap; // EAST"]},{"text":"Reference the created unit through a global variable:\n\n```sqf\n_myUnit = \"B_RangeMaster_F\" createUnit [position player, group player];            // wrong - this syntax does not return a reference\n\n\"B_RangeMaster_F\" createUnit [position player, group player, \"myUnit = this\"];    // correct - the unit is myUnit (NOT _myUnit!)\n```","code":["_myUnit = \"B_RangeMaster_F\" createUnit [position player, group player];\t\t\t// wrong - this syntax does not return a reference\n\n\"B_RangeMaster_F\" createUnit [position player, group player, \"myUnit = this\"];\t// correct - the unit is myUnit (NOT _myUnit!)"]}],"multiplayer":"It is recommended to create the unit where the group is **local** - use remoteExec if needed.","problems":null,"aliases":[],"see_also":["createCenter","createGroup","createVehicle","setVehiclePosition","create3DENEntity"],"notes":[{"user":"oOKexOo","date":"2018-12-08T21:57:00Z","text":"Since Arma 3 v1.86: If you want to place a module with createUnit, you have to ensure that the module gets activated automatically by setting **BIS_fnc_initModules_disableAutoActivation** to false, *e.g*:\n\n```sqf\nprivate _grp = createGroup sideLogic;\n\"ModuleSmokeWhite_F\" createUnit [\n    getPos player,\n    _grp,\n    \"this setVariable ['BIS_fnc_initModules_disableAutoActivation', false, true];\"\n];\n```"},{"user":"Killzone_Kid","date":"2019-03-18T19:31:00Z","text":"Alt Syntax is the older syntax and differs in functionality from the main, newer syntax. The main difference is that the older syntax **does not** return unit reference.\nThis is because the unit created with Alt Syntax is created strictly where passed group is local.\nThis means that if the group is remote the unit will be created on the different client than the one the command was executed on and therefore it is not possible to return created unit reference immediately.\nIn contrast, the newer syntax allows creating units in remote groups while returning unit reference immediately, which could be unsafe and the appropriate warning is logged into *.rpt* file: `Warning: Adding units to a remote group is not safe. Please use setGroupOwner to change the group owner first.`\n\nAnother very important difference is that the older syntax (Alt Syntax) will create unit of the same side as the side of the group passed as argument.\nFor example, if the group is WEST and the unit faction is OPFOR of type, say `\"O_Soldier_GL_F\"`, the unit created will be on the WEST side as well.\nIn contrast, newer syntax will create the same unit on the EAST side in the WEST group, which will be treated as hostile by other group members and eliminated.\n\n> [!WARNING]\n> Beware that in MP if unit is created in remote group with older syntax, the unit init will execute on calling client sometime in the future, after the unit is created on remote client, therefore the following code will fail:\n>\n> ```sqf\n> // real example of the bad code\n> \"O_Soldier_AR_F\" createUnit [position player, someRemoteGroup, \"thisUnit = this\"];\n> publicVariable \"thisUnit\";\n> hint str isNil \"thisUnit\"; // true!\n> // the unit reference is nil because init statement has not been executed on this client yet\n> ```"},{"user":"fusselwurm","date":"2020-06-19T10:13:00Z","text":"Arma 3 v1.98 note that even when setting the *placement special* parameter to \"NONE\", 3DEN-placed objects are being ignored when looking for a free position.\nIn other words: units will spawn within editor-placed rocks or under houses."}],"categories":["ArmA: Armed Assault: Scripting Commands","Arma 2: Operation Arrowhead: Scripting Commands","Arma 2: Scripting Commands","Arma 3: Scripting Commands","Command Group: Object Manipulation","Introduced with Operation Flashpoint version 1.34","Operation Flashpoint: Elite: Scripting Commands","Operation Flashpoint: New Scripting Commands","Operation Flashpoint: Scripting Commands","Scripting Commands","Scripting Commands: Global Effect","Take On Helicopters: Scripting Commands"]}