createUnit - Revision history

BrettMayson at 06:50, 2 January 2026

2026-01-02T06:50:26Z

← Older revision		Revision as of 08:50, 2 January 2026
Line 66:		Line 66:
	\|p2= type: [[String]] - classname of unit to be created as per [[CfgVehicles]]		\|p2= type: [[String]] - classname of unit to be created as per [[CfgVehicles]]

	\|p3= position: [[Object]], [[Group]] or ~~[[Array]] format~~ [[Position]] or [[Position#Introduction\|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.		\|p3= position: [[Object]], [[Group]] or [[Position]] or [[Position#Introduction\|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.

	\|p4= markers: [[Array]] - placement markers		\|p4= markers: [[Array]] - placement markers
Line 93:		Line 93:
	\|p21= type: [[String]] - classname of unit to be created as per [[CfgVehicles]]		\|p21= type: [[String]] - classname of unit to be created as per [[CfgVehicles]]

	\|p22= position: [[Object]], [[Group]] or ~~[[Array]] format~~ [[Position]] or [[Position#Introduction\|Position2D]] - location at which the unit is created. In case of [[Group]] position of the [[group]] [[leader]] is used		\|p22= position: [[Object]], [[Group]] or [[Position]] or [[Position#Introduction\|Position2D]] - location at which the unit is created. In case of [[Group]] position of the [[group]] [[leader]] is used

	\|p23= group: [[Group]] - existing group the new unit will join		\|p23= group: [[Group]] - existing group the new unit will join

Leopard20 at 14:59, 25 January 2025

2025-01-25T14:59:05Z

← Older revision		Revision as of 16:59, 25 January 2025
Line 66:		Line 66:
	\|p2= type: [[String]] - classname of unit to be created as per [[CfgVehicles]]		\|p2= type: [[String]] - classname of unit to be created as per [[CfgVehicles]]

	\|p3= position: [[Object]], [[Group]] or [[Array]] format [[Position]] or [[Position#Introduction\|Position2D]] - location where to create the unit. In case of [[Group]], the [[group]] [[leader]]'s position is used		\|p3= position: [[Object]], [[Group]] or [[Array]] format [[Position]] or [[Position#Introduction\|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.

	\|p4= markers: [[Array]] - placement markers		\|p4= markers: [[Array]] - placement markers

R3vo: Warning

2024-10-22T08:27:39Z

Warning

← Older revision		Revision as of 10:27, 22 October 2024
Line 98:		Line 98:

	\|p24= 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.		\|p24= 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.
	The code itself receives the reference to the created unit via local variable [[Magic Variables#this_2\|this]]. 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]]).		The code itself receives the reference to the created unit via local variable [[Magic Variables#this_2\|this]].
			{{Feature\|warning\|
			* 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]]).
			* Do not use local variables inside the init code as they are not available in multiplayer.}}


	\|p25= skill: [[Number]] - (Optional, default 0.5) unit [[skill]]		\|p25= skill: [[Number]] - (Optional, default 0.5) unit [[skill]]

Lou Montana: Some wiki formatting

2024-10-09T14:38:17Z

Some wiki formatting

← Older revision		Revision as of 16:38, 9 October 2024
Line 54:		Line 54:

	{{Feature\|arma1\|		{{Feature\|arma1\|
	{{GVI\|ofp\|1.34}} {{GVI\|arma1\|1.00}} This command ~~could be~~ bugged in {{ofp}} or {{arma1}}; an additional [[join]] may solve the problem.<br>		{{GVI\|ofp\|1.34}} {{GVI\|arma1\|1.00}} This command was sometimes bugged in {{ofp}} or {{arma1}}; an additional [[join]] may solve the problem.<br>
	However, some commands such as [[setUnitPos]] only work if run before the [[join]].		However, some commands such as [[setUnitPos]] only work if run before the [[join]].
	}}		}}
Line 97:		Line 97:
	\|p23= group: [[Group]] - existing group the new unit will join		\|p23= group: [[Group]] - existing group the new unit will join

	\|p24= 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. The code itself receives the reference to the created unit via local variable [[Magic Variables#this_2\|this]]. Do not use global commands in a unit's ''init'' as it runs on every client.		\|p24= 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.
			The code itself receives the reference to the created unit via local variable [[Magic Variables#this_2\|this]]. 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]]).

	\|p25= skill: [[Number]] - (Optional, default 0.5) unit [[skill]]		\|p25= skill: [[Number]] - (Optional, default 0.5) unit [[skill]]
Line 143:		Line 144:
	Reference the created unit through a global variable:		Reference the created unit through a global variable:
	<sqf>		<sqf>
	_myUnit = "B_RangeMaster_F" createUnit [position player, group player]; // wrong - this syntax does not return a reference		_myUnit = "B_RangeMaster_F" createUnit [position player, group player]; // wrong - this syntax does not return a reference

	"B_RangeMaster_F" createUnit [position player, group player, "myUnit = this"]; // correct - the unit is myUnit		"B_RangeMaster_F" createUnit [position player, group player, "myUnit = this"]; // correct - the unit is myUnit (NOT _myUnit!)
	</sqf>		</sqf>

Line 168:		Line 169:
	\|user= Killzone_Kid		\|user= Killzone_Kid
	\|timestamp= 20190318193100		\|timestamp= 20190318193100
	\|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. This is because the unit created with Alt Syntax is created strictly where passed [[group]] is [[Multiplayer Scripting#Locality\|local]]. This 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. In 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: {{hl\|Warning: Adding units to a remote group is not safe. Please use [[setGroupOwner]] to change the group owner first.}}<br><br>		\|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.
	Another 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. For example, if the group is WEST and the unit faction is OPFOR of type, say {{hl\|"O_Soldier_GL_F"}}, the unit created will be on the WEST side as well. In 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.		This is because the unit created with Alt Syntax is created strictly where passed [[group]] is [[Multiplayer Scripting#Locality\|local]].
	{{Feature\|warning\|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:		This 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.
			In 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: {{hl\|Warning: Adding units to a remote group is not safe. Please use [[setGroupOwner]] to change the group owner first.}}<br><br>
			Another 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.
			For example, if the group is WEST and the unit faction is OPFOR of type, say {{hl\|"O_Soldier_GL_F"}}, the unit created will be on the WEST side as well.
			In 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.
			{{Feature\|warning\|
			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:
	<sqf>		<sqf>
	// real example of the bad code		// real example of the bad code
Line 184:		Line 191:
	\|user= fusselwurm		\|user= fusselwurm
	\|timestamp= 20200619101300		\|timestamp= 20200619101300
	\|text= {{GVI\|arma3\|1.98}} note that even when setting the ''placement special'' parameter to "NONE", 3DEN-placed objects are being ignored when looking for a free position. In other words: units will spawn within editor-placed rocks or under houses.		\|text= {{GVI\|arma3\|1.98}} note that even when setting the ''placement special'' parameter to "NONE", 3DEN-placed objects are being ignored when looking for a free position.
			In other words: units will spawn within editor-placed rocks or under houses.
	}}		}}

Lou Montana: Fix "FORM" → "NONE"

2024-04-24T15:52:03Z

Fix "FORM" → "NONE"

← Older revision		Revision as of 17:52, 24 April 2024
Line 105:		Line 105:
	\|r2= {{Feature\|warning\|'''[[Nothing]]''' - this syntax does '''not''' return a unit reference! See {{Link\|#Example 7}} for a workaround.}}		\|r2= {{Feature\|warning\|'''[[Nothing]]''' - this syntax does '''not''' return a unit reference! See {{Link\|#Example 7}} for a workaround.}}

	\|x1= <sqf>_unit = group player createUnit ["B_RangeMaster_F", position player, [], 0, "~~FORM~~"];</sqf>		\|x1= <sqf>_unit = group player createUnit ["B_RangeMaster_F", position player, [], 0, "NONE"];</sqf>

	\|x2= <sqf>"B_RangeMaster_F" createUnit [position player, group player];</sqf>		\|x2= <sqf>"B_RangeMaster_F" createUnit [position player, group player];</sqf>
Line 132:		Line 132:
	_grp = createGroup east;		_grp = createGroup east;
	hint str side _grp; // EAST		hint str side _grp; // EAST
	_ap = _grp createUnit ["C_man_p_beggar_F", position player, [], 0, "~~FORM~~"];		_ap = _grp createUnit ["C_man_p_beggar_F", position player, [], 0, "NONE"];
	hint str side _ap; // CIV, not EAST		hint str side _ap; // CIV, not EAST

Lou Montana: re-add "FORM", for doc and potential fix purpose

2024-04-21T17:52:20Z

re-add "FORM", for doc and potential fix purpose

← Older revision		Revision as of 19:52, 21 April 2024
Line 30:		Line 30:
	\|descr= Create a unit of the provided [[:Category:CfgVehicles\|CfgVehicles]] class.		\|descr= Create a unit of the provided [[:Category:CfgVehicles\|CfgVehicles]] class.

	{{Feature\|warning\|The unit will not be created if the passed group does not exist (a.k.a [[grpNull]]); this can happen if [[createGroup]] fails because the '''group limit has been reached''' (see [[createGroup]] for respective game limits).}}		{{Feature\|warning\|
			The unit will not be created if the passed group does not exist (a.k.a [[grpNull]]);
			this can happen if [[createGroup]] fails because the '''group limit has been reached''' (see [[createGroup]] for respective game limits).
			}}

	{{{!}} class="wikitable" style="width: 100%"		{{{!}} class="wikitable" style="width: 100%"
Line 50:		Line 53:
	{{!}}}		{{!}}}

	{{Feature \| arma1 \| {{GVI\|ofp\|1.34}} {{GVI\|arma1\|1.00}} This command could be bugged in {{ofp}} or {{arma1}}; an additional [[join]] may solve the problem.<br>		{{Feature\|arma1\|
	However, some commands such as [[setUnitPos]] only work if run before the [[join]].}}		{{GVI\|ofp\|1.34}} {{GVI\|arma1\|1.00}} This command could be bugged in {{ofp}} or {{arma1}}; an additional [[join]] may solve the problem.<br>
			However, some commands such as [[setUnitPos]] only work if run before the [[join]].
			}}

	\|mp= It is recommended to create the unit where the group is '''[[Multiplayer Scripting#Locality\|local]]''' - use [[remoteExec]] if needed.		\|mp= It is recommended to create the unit where the group is '''[[Multiplayer Scripting#Locality\|local]]''' - use [[remoteExec]] if needed.
Line 69:		Line 74:
	\|p6= special: [[String]] - unit placement special, one of:		\|p6= special: [[String]] - unit placement special, one of:
	* {{hl\|"NONE"}} - The unit will be created at the first available free position nearest to given position		* {{hl\|"NONE"}} - The unit will be created at the first available free position nearest to given position
	~~<!--~~ * {{hl\|"FORM"}} - Not implemented, currently functions the same as "NONE" ~~-->~~		* {{hl\|"FORM"}} - Not implemented, currently functions the same as "NONE"
	* {{hl\|"CAN_COLLIDE"}} - The unit will be created exactly at ~~passed~~ position		* {{hl\|"CAN_COLLIDE"}} - The unit will be created exactly at the provided position
	* {{hl\|"CARGO"}} - The unit will be created in cargo of the group's vehicle, regardless of the passed position (see {{Link\|#Example 5}}). If group has no vehicle or there is no cargo space available, the unit will be placed according to {{hl\|"NONE"}}. {{hl\|"CARGO"}} placement excludes cargo positions with personal FFV turrets. To check available cargo space use:		* {{hl\|"CARGO"}} - The unit will be created in cargo of the group's vehicle, regardless of the passed position (see {{Link\|#Example 5}}).<!--
			--> If group has no vehicle or there is no cargo space available, the unit will be placed according to {{hl\|"NONE"}}.<!--
			--> {{hl\|"CARGO"}} placement excludes cargo positions with personal FFV turrets. To check available cargo space use:
	{{{!}} style="width: 100%"		{{{!}} style="width: 100%"
	~~{{!}} rowspan="2" style="width: 2em" {{!}}~~
	! {{GVI\|arma3\|1.34}} FFV		! {{GVI\|arma3\|1.34}} FFV
	{{!}} <sqf>private _hasCargo = { isNull (_x select 0) } count (fullCrew [_veh, "cargo", true]) > 0;</sqf>		{{!}} <sqf>private _hasCargo = { isNull (_x select 0) } count (fullCrew [_veh, "cargo", true]) > 0;</sqf>

Lou Montana: Text replacement - "{{Feature|Warning|" to "{{Feature|warning|"

2024-02-01T23:25:22Z

Text replacement - "{{Feature|Warning|" to "{{Feature|warning|"

← Older revision		Revision as of 01:25, 2 February 2024
Line 97:		Line 97:
	\|p26= rank: [[String]] - (Optional, default "PRIVATE") unit [[rank]]		\|p26= rank: [[String]] - (Optional, default "PRIVATE") unit [[rank]]

	\|r2= {{Feature\|~~Warning~~\|'''[[Nothing]]''' - this syntax does '''not''' return a unit reference! See {{Link\|#Example 7}} for a workaround.}}		\|r2= {{Feature\|warning\|'''[[Nothing]]''' - this syntax does '''not''' return a unit reference! See {{Link\|#Example 7}} for a workaround.}}

	\|x1= <sqf>_unit = group player createUnit ["B_RangeMaster_F", position player, [], 0, "FORM"];</sqf>		\|x1= <sqf>_unit = group player createUnit ["B_RangeMaster_F", position player, [], 0, "FORM"];</sqf>

Lou Montana: Text replacement - " +\[ +" to " ["

2023-11-08T16:48:35Z

Text replacement - " +\[ +" to " ["

← Older revision		Revision as of 18:48, 8 November 2023
Line 126:		Line 126:
	_grp = createGroup east;		_grp = createGroup east;
	hint str side _grp; // EAST		hint str side _grp; // EAST
	_ap = _grp createUnit [ "C_man_p_beggar_F", position player, [], 0, "FORM"];		_ap = _grp createUnit ["C_man_p_beggar_F", position player, [], 0, "FORM"];
	hint str side _ap; // CIV, not EAST		hint str side _ap; // CIV, not EAST

Lou Montana: Text replacement - "(\|[pr][0-9]+ = [^-\r\n]+) - T([a-z])" to "$1 - t$2"

2023-11-08T13:45:16Z

Text replacement - "(\|[pr][0-9]+ *= *[^-\r\n]+) *- *T([a-z])" to "$1 - t$2"

← Older revision		Revision as of 15:45, 8 November 2023
Line 81:		Line 81:
	{{!}}}		{{!}}}

	\|r1= [[Object]] - ~~The~~ created unit		\|r1= [[Object]] - the created unit

	\|s2= type [[createUnit]] [position, group, init, skill, rank]		\|s2= type [[createUnit]] [position, group, init, skill, rank]
Line 97:		Line 97:
	\|p26= rank: [[String]] - (Optional, default "PRIVATE") unit [[rank]]		\|p26= rank: [[String]] - (Optional, default "PRIVATE") unit [[rank]]

	\|r2= {{Feature\|Warning\|'''[[Nothing]]''' - ~~This~~ syntax does '''not''' return a unit reference! See {{Link\|#Example 7}} for a workaround.}}		\|r2= {{Feature\|Warning\|'''[[Nothing]]''' - this syntax does '''not''' return a unit reference! See {{Link\|#Example 7}} for a workaround.}}

	\|x1= <sqf>_unit = group player createUnit ["B_RangeMaster_F", position player, [], 0, "FORM"];</sqf>		\|x1= <sqf>_unit = group player createUnit ["B_RangeMaster_F", position player, [], 0, "FORM"];</sqf>

Lou Montana: Text replacement - "(\|p[0-9]+ = [^(]+$Optional(, default[^)]*)$ )U([a-z])" to "$1u$3"

2023-11-08T11:32:49Z

Text replacement - "(\|p[0-9]+ *= *[^(]+$Optional(, default[^)]*)$ )U([a-z])" to "$1u$3"

← Older revision		Revision as of 13:32, 8 November 2023
Line 93:		Line 93:
	\|p24= 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. The code itself receives the reference to the created unit via local variable [[Magic Variables#this_2\|this]]. Do not use global commands in a unit's ''init'' as it runs on every client.		\|p24= 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. The code itself receives the reference to the created unit via local variable [[Magic Variables#this_2\|this]]. Do not use global commands in a unit's ''init'' as it runs on every client.

	\|p25= skill: [[Number]] - (Optional, default 0.5) ~~Unit~~ [[skill]]		\|p25= skill: [[Number]] - (Optional, default 0.5) unit [[skill]]

	\|p26= rank: [[String]] - (Optional, default "PRIVATE") ~~Unit~~ [[rank]]		\|p26= rank: [[String]] - (Optional, default "PRIVATE") unit [[rank]]

	\|r2= {{Feature\|Warning\|'''[[Nothing]]''' - This syntax does '''not''' return a unit reference! See {{Link\|#Example 7}} for a workaround.}}		\|r2= {{Feature\|Warning\|'''[[Nothing]]''' - This syntax does '''not''' return a unit reference! See {{Link\|#Example 7}} for a workaround.}}