createUnit: Difference between revisions
Jump to navigation
Jump to search
Lou Montana (talk | contribs) m (Text replacement - " *\| *Syntax[0-9]* *= * " to " ") |
Lou Montana (talk | contribs) m (revert + fix) Tag: Undo |
||
Line 1: | Line 1: | ||
{{RV|type=command | {{RV|type=command | ||
| ofp | |game1= ofp | ||
|1.34 | |version1= 1.34 | ||
|eff= global | |eff= global | ||
Line 9: | Line 9: | ||
|gr1= Object Manipulation | |gr1= Object Manipulation | ||
| Create a unit of class that is defined in [[:Category:CfgVehicles|CfgVehicles]]. | |descr= Create a unit of class that is defined in [[:Category:CfgVehicles|CfgVehicles]]. | ||
{{Important | <div style{{=}}"float: left; margin-right: 0.5em;">{{GVI|ofp|1.34}} {{GVI|arma1|1.00}}</div> | {{Important | <div style{{=}}"float: left; margin-right: 0.5em;">{{GVI|ofp|1.34}} {{GVI|arma1|1.00}}</div> | ||
This command could be bugged in {{ofp}} or {{arma1}} ; an additional [[join]] may solve the problem.<br> | This command could be bugged in {{ofp}} or {{arma1}} ; an additional [[join]] may solve the problem.<br> | ||
Line 15: | Line 15: | ||
{{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).}} | {{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).}} | ||
|group [[createUnit]] [type, position, markers, placement, special] | |s1= group [[createUnit]] [type, position, markers, placement, special] | ||
|p1= group: [[Group]] - Existing group new unit will join | |p1= group: [[Group]] - Existing group new unit will join | ||
|p2= [type, position, markers, placement, special]: [[Array]] | |p2= [type, position, markers, placement, special]: [[Array]] | ||
|p3= type: [[String]] - Class name of unit to be created as per [[CfgVehicles]] | |p3= type: [[String]] - Class name of unit to be created as per [[CfgVehicles]] | ||
|p4= position: [[Position]], [[Position2D]], [[Object]] or [[Group]] - Location unit is created at. In case of [[Group]] position of the [[group]] [[leader]] is used | |p4= position: [[Position]], [[Position2D]], [[Object]] or [[Group]] - Location unit is created at. In case of [[Group]] position of the [[group]] [[leader]] is used | ||
|p5= markers: [[Array]] - Placement markers | |p5= markers: [[Array]] - Placement markers | ||
|p6= placement: [[Number]] - Placement radius | |p6= placement: [[Number]] - Placement radius | ||
|p7= special: [[String]] - Unit placement special, one of: | |p7= special: [[String]] - Unit placement special, one of: | ||
* <tt>"NONE"</tt> - The unit will be created at the first available free position nearest to given position | * <tt>"NONE"</tt> - The unit will be created at the first available free position nearest to given position | ||
* <tt>"FORM"</tt> - Not implemented, currently functions the same as "NONE". | * <tt>"FORM"</tt> - Not implemented, currently functions the same as "NONE". | ||
* <tt>"CAN_COLLIDE"</tt> - The unit will be created exactly at passed position | * <tt>"CAN_COLLIDE"</tt> - The unit will be created exactly at passed position | ||
* <tt>"CARGO"</tt> - 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 <tt>"NONE"</tt>. To check available cargo space use: | * <tt>"CARGO"</tt> - 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 <tt>"NONE"</tt>. To check available cargo space use: {{Inline code|_hasCargo {{=}} _veh [[emptyPositions]] "CARGO" > 0;}} | ||
| [[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] | ||
|p21= type: [[String]] - Class name of unit to be created as per [[CfgVehicles]] | |p21= type: [[String]] - Class name of unit to be created as per [[CfgVehicles]] | ||
|p22= [position, group, init, skill, rank]: [[Array]] | |p22= [position, group, init, skill, rank]: [[Array]] | ||
|p23= position: [[Position]], [[Position2D]], [[Object]] or [[Group]] - Location unit is created at. In case of [[Group]] position of the [[group]] [[leader]] is used | |p23= position: [[Position]], [[Position2D]], [[Object]] or [[Group]] - Location unit is created at. In case of [[Group]] position of the [[group]] [[leader]] is used | ||
|p24= group: [[Group]] - Existing group new unit will join | |p24= group: [[Group]] - Existing group new unit will join | ||
|p25= 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 [[this]]. Avoid using global commands in unit init statement as it already runs on every client. | |p25= 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 [[this]]. Avoid using global commands in unit init statement as it already runs on every client. | ||
|p26= skill: [[Number]] - (Optional, default 0.5) Unit [[skill]] | |p26= skill: [[Number]] - (Optional, default 0.5) Unit [[skill]] | ||
|p27= rank: [[String]] - (Optional, default "PRIVATE") Unit [[rank]] | |p27= rank: [[String]] - (Optional, default "PRIVATE") Unit [[rank]] | ||
Line 45: | Line 57: | ||
|x1= <code>_unit = [[group]] [[player]] [[createUnit]] ["B_RangeMaster_F", [[position]] [[player]], [], 0, "FORM"];</code> | |x1= <code>_unit = [[group]] [[player]] [[createUnit]] ["B_RangeMaster_F", [[position]] [[player]], [], 0, "FORM"];</code> | ||
|x2= <code>"B_RangeMaster_F" [[createUnit]] [<nowiki/>[[position]] [[player]], [[group]] [[player]]];</code> | |x2= <code>"B_RangeMaster_F" [[createUnit]] [<nowiki/>[[position]] [[player]], [[group]] [[player]]];</code> | ||
|x3= <code>"B_RangeMaster_F" [[createUnit]] [<nowiki/>[[getMarkerPos]] "barracks", _groupAlpha];</code> | |x3= <code>"B_RangeMaster_F" [[createUnit]] [<nowiki/>[[getMarkerPos]] "barracks", _groupAlpha];</code> | ||
|x4= <code>"B_RangeMaster_F" [[createUnit]] [ | |x4= <code>"B_RangeMaster_F" [[createUnit]] [ | ||
[[getMarkerPos]] "marker_1", | [[getMarkerPos]] "marker_1", | ||
Line 59: | Line 74: | ||
_unit = _grp [[createUnit]] [<nowiki/>[[typeOf]] [[driver]] _veh, _grp, [], 0, "CARGO"];</code> | _unit = _grp [[createUnit]] [<nowiki/>[[typeOf]] [[driver]] _veh, _grp, [], 0, "CARGO"];</code> | ||
| [[createCenter]], [[createGroup]], [[createVehicle]], [[setVehiclePosition]], [[create3DENEntity]] | |seealso= [[createCenter]], [[createGroup]], [[createVehicle]], [[setVehiclePosition]], [[create3DENEntity]] | ||
}} | }} | ||
[[Category:Scripting Commands OFP 1.46|{{uc:{{PAGENAME}}}}]] | [[Category:Scripting Commands OFP 1.46|{{uc:{{PAGENAME}}}}]] | ||
[[Category:Scripting Commands OFP 1.96|{{uc:{{PAGENAME}}}}]] | [[Category:Scripting Commands OFP 1.96|{{uc:{{PAGENAME}}}}]] | ||
Line 73: | Line 87: | ||
<dl class="command_description"> | <dl class="command_description"> | ||
<!-- Note Section BEGIN --> | <!-- Note Section BEGIN --> | ||
<dd class="notedate">Posted on 27th Nov 2016 | <dd class="notedate">Posted on 27th Nov 2016</dd> | ||
<dt class="note">[[User:Ffur2007slx2_5|Ffur2007slx2_5]] | <dt class="note">[[User:Ffur2007slx2_5|Ffur2007slx2_5]]</dt> | ||
<dd class="note"> | <dd class="note"> | ||
{{GVI|arma3|1.64}} The side of the created unit by this command uses its config's side and not the side of a passed empty group created by [[createGroup]]: | {{GVI|arma3|1.64}} The side of the created unit by this command uses its config's side and not the side of a passed empty group created by [[createGroup]]: | ||
<code>_grp = [[createGroup]] [[east]]; | <code>_grp = [[createGroup]] [[east]]; | ||
[[hint]] [[str]] [[side]] _grp; {{cc| EAST}}_ap = _grp [[createUnit]] [ "C_man_p_beggar_F", [[position]] [[player]], [], 0, "FORM"]; | [[hint]] [[str]] [[side]] _grp; {{cc|EAST}} | ||
[[hint]] [[str]] [[side]] _ap; {{ | _ap = _grp [[createUnit]] [ "C_man_p_beggar_F", [[position]] [[player]], [], 0, "FORM"]; | ||
[[hint]] [[str]] [[side]] _ap; {{cc|CIV, not EAST}}</code> | |||
We can use [[join]] command or fill the _grp with entities in advance to set _ap to the desired side. | We can use [[join]] command or fill the _grp with entities in advance to set _ap to the desired side. | ||
</dd> | |||
<dd class="notedate">Posted on 8th Dec 2018 | <dd class="notedate">Posted on 8th Dec 2018 | ||
Line 93: | Line 109: | ||
];</code> | ];</code> | ||
<dd class="notedate">Posted on 18th Mar 2019 | <dd class="notedate">Posted on 18th Mar 2019</dd> | ||
<dt class="note">[[User:Killzone_Kid|Killzone_Kid]] | <dt class="note">[[User:Killzone_Kid|Killzone_Kid]]</dt> | ||
<dd class="note"> | <dd class="note"> | ||
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 [[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: <tt>Warning: Adding units to a remote group is not safe. Please use [[setGroupOwner]] to change the group owner first.</tt><br><br> | 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 [[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: <tt>Warning: Adding units to a remote group is not safe. Please use [[setGroupOwner]] to change the group owner first.</tt><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 <tt>"O_Soldier_GL_F"</tt>, 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.<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 <tt>"O_Soldier_GL_F"</tt>, 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.<br><br> | ||
{{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: | {{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: | ||
{{cc| Real example of the bad code}} "O_Soldier_AR_F" [[createUnit]] [<nowiki/>[[position]] [[player]], someRemoteGroup, "thisUnit {{=}} this"]; | {{cc|Real example of the bad code}} | ||
"O_Soldier_AR_F" [[createUnit]] [<nowiki/>[[position]] [[player]], someRemoteGroup, "thisUnit {{=}} this"]; | |||
[[publicVariable]] "thisUnit"; | [[publicVariable]] "thisUnit"; | ||
[[hint]] [[str]] [[isNil]] "thisUnit"; {{ | [[hint]] [[str]] [[isNil]] "thisUnit"; {{cc|[[true]]! | ||
// The unit reference is [[nil]] because init statement has not been executed on this client yet.}} | // The unit reference is [[nil]] because init statement has not been executed on this client yet.}} | ||
}} | }} | ||
</dd> | |||
</ | |||
<dd class="notedate">Posted on June 19, 2020 - 10:13 (UTC)</dd> | <dd class="notedate">Posted on June 19, 2020 - 10:13 (UTC)</dd> | ||
<dt class="note">[[User:fusselwurm|fusselwurm]]</dt> | <dt class="note">[[User:fusselwurm|fusselwurm]]</dt> |
Revision as of 22:11, 29 January 2021
Description
- Description:
- Create a unit of class that is defined in CfgVehicles.
- Groups:
- Object Manipulation
Syntax
- Syntax:
- group createUnit [type, position, markers, placement, special]
- Parameters:
- group: Group - Existing group new unit will join
- [type, position, markers, placement, special]: Array
- type: String - Class name of unit to be created as per CfgVehicles
- position: Position, Position2D, Object or Group - Location unit is created at. In case of Group position of the group leader is used
- markers: Array - Placement markers
- placement: Number - Placement radius
- special: String - Unit placement special, one of:
- "NONE" - The unit will be created at the first available free position nearest to given position
- "FORM" - Not implemented, currently functions the same as "NONE".
- "CAN_COLLIDE" - The unit will be created exactly at passed position
- "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". To check available cargo space use:
_hasCargo = _veh emptyPositions "CARGO" > 0;
- Return Value:
- Object - The created unit
Alternative Syntax
- Syntax:
- type createUnit [position, group, init, skill, rank]
- Parameters:
- type: String - Class name of unit to be created as per CfgVehicles
- [position, group, init, skill, rank]: Array
- position: Position, Position2D, Object or Group - Location unit is created at. In case of Group position of the group leader is used
- group: Group - Existing group new unit will join
- 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 this. Avoid using global commands in unit init statement as it already runs on every client.
- skill: Number - (Optional, default 0.5) Unit skill
- rank: String - (Optional, default "PRIVATE") Unit rank
- Return Value:
Examples
- Example 1:
_unit = group player createUnit ["B_RangeMaster_F", position player, [], 0, "FORM"];
- Example 2:
"B_RangeMaster_F" createUnit [position player, group player];
- Example 3:
"B_RangeMaster_F" createUnit [getMarkerPos "barracks", _groupAlpha];
- Example 4:
"B_RangeMaster_F" createUnit [ getMarkerPos "marker_1", _groupAlpha, "loon1 = this; this addWeapon 'BAF_L85A2_RIS_SUSAT'", 0.6, "corporal" ];
- Example 5:
_veh = "O_Quadbike_01_F" createVehicle (player getRelPos [10, 0]); _grp = createVehicleCrew _veh; _unit = _grp createUnit [typeOf driver _veh, _grp, [], 0, "CARGO"];
Additional Information
Notes
-
Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note
- Posted on 27th Nov 2016
- Ffur2007slx2_5
-
1.64 The side of the created unit by this command uses its config's side and not the side of a passed empty group created by createGroup:
_grp = createGroup east; hint str side _grp; // EAST _ap = _grp createUnit [ "C_man_p_beggar_F", position player, [], 0, "FORM"]; hint str side _ap; // CIV, not EAST
We can use join command or fill the _grp with entities in advance to set _ap to the desired side. - Posted on 8th Dec 2018
- oOKexOo
-
Since 1.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:
private _grp = createGroup sideLogic; "ModuleSmokeWhite_F" createUnit [ getPos player, _grp, "this setVariable ['BIS_fnc_initModules_disableAutoActivation', false, true];" ];
- Posted on 18th Mar 2019
- Killzone_Kid
-
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 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: Warning: Adding units to a remote group is not safe. Please use setGroupOwner to change the group owner first.
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 "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.
- Posted on June 19, 2020 - 10:13 (UTC)
- fusselwurm
- 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.
Categories:
- Scripting Commands
- Introduced with Operation Flashpoint version 1.34
- Operation Flashpoint: New Scripting Commands
- Operation Flashpoint: Scripting Commands
- Command Group: Object Manipulation
- Scripting Commands: Global Effect
- Scripting Commands OFP 1.46
- Scripting Commands OFP 1.96
- Scripting Commands OFP 1.99
- ArmA: Armed Assault: Scripting Commands
- Arma 2: Scripting Commands
- Take On Helicopters: Scripting Commands
- Arma 3: Scripting Commands