Difference between revisions of "DCS func addGroup"

From DCS World Wiki - Hoggitworld.com
 
(5 intermediate revisions by the same user not shown)
Line 13: Line 13:
 
|par4=
 
|par4=
  
|desc= Dynamically spawns a group of the specified category for the specified country. Group data table is in the same format as created by the mission editor. See [[DCS_Class_Group|here]] for the list of possible group categories.
+
|desc= Dynamically spawns a group of the specified category for the specified country. Group data table is in the same format as created by the mission editor.  
 +
 
 +
See [[DCS_enum_country|country page]] and [[DCS_Class_Group|group class page]] for the list of countries by id and group categories.
  
 
The coalition of the group is defined by the coalition its country belongs to.
 
The coalition of the group is defined by the coalition its country belongs to.
Line 45: Line 47:
 
|optType2=
 
|optType2=
  
|examples= Basic table for a ground unit
+
|examples= Detailed Examples Linked Below:
 +
    [[DCS_exam_group_ground|Ground Group]]
 +
    [[DCS_exam_group_ship|Ship Group]] 
 +
    [[DCS_exam_group_heli|Helicopter Group]]
 +
    [[DCS_exam_group_plane|Plane Group]]
 +
 
 +
 
 +
A basic table for a ground unit
 
<pre>
 
<pre>
 
   local groupData = {
 
   local groupData = {
Line 95: Line 104:
 
   lateActivation  boolean value that can override start_time to force the group to spawn in via trigger
 
   lateActivation  boolean value that can override start_time to force the group to spawn in via trigger
 
   hidden          boolean whether or not the group is visible on the F10 map view
 
   hidden          boolean whether or not the group is visible on the F10 map view
 +
  hiddenOnPlanner boolean if true the group will be hidden on the mission planner available in single player.
 +
  hiddenOnMFD    boolean if true this group will not be auto populated on relevant aircraft map screens and avionics. For instance SAM rings in F-16/F-18 and AH-64 threats pages
 
   route          table complex table defining the route and tasks assigned to the group
 
   route          table complex table defining the route and tasks assigned to the group
  
Line 105: Line 116:
 
Optional Group Values (Ground and Ships)
 
Optional Group Values (Ground and Ships)
 
   visible        boolean For whether or not the group is visible before its start time
 
   visible        boolean For whether or not the group is visible before its start time
 +
  uncontrollable  boolean corresponds to "Game Master Only" setting in editor. Dictates whether or not ground commanders can give orders to the group.
 +
 +
Optional Group Values (Ground only)
 +
 +
  manualHeading  boolean When spawned with a route assigned each unit in the group will automatically be pointing toward the next waypoint in the route. When set to true each unit will respect their own heading value.
 
    
 
    
 
Required Unit values
 
Required Unit values
Line 123: Line 139:
 
  heading      number heading of the object in radians
 
  heading      number heading of the object in radians
 
  skill        string of the units skill level. Can be "Excellent", "High", "Good", "Average", "Random", "Player"
 
  skill        string of the units skill level. Can be "Excellent", "High", "Good", "Average", "Random", "Player"
 +
 +
Optional Unit Values for Ground
 +
 +
coldAtStart    boolean if true the vehicle will start with its engine off and should take some time to appear on FLIR
 +
playerCanDrive  boolean if true Combined Arms players can take direct control of the unit.
  
  
 
Aircraft and Helicopter values
 
Aircraft and Helicopter values
   livery_id   string name of the livery for the aircraft
+
  AddPropAircraft      table additional aircraft properties for some contains the datalink ID information for that unit.
   psi         number
+
   livery_id             string name of the livery for the aircraft
   onboard_num string of the tail number on the aircraft
+
   psi                   number
 
+
   onboard_num           string of the tail number on the aircraft
 +
  parking_landing      number the "Term_Index" associated with the landing parking spot see Airbase.getParking
 +
  parking_landing_id    string displayd value in the mission editor of the parking spot the unit will taxi to on landing
 +
  parking              string of a number of the "Term_Index" associated with the starting parking spot see Airbase.getParking
 +
  parking_id            string displayed value in the mission editor where the unit starts parked at
 +
  datalinks            table defines the link16, SADL, or Longbow Net data used for that specific unit         
 
Helicopter Values
 
Helicopter Values
 
   ropeLength  number length of a rope used for sling loading, default is 15
 
   ropeLength  number length of a rope used for sling loading, default is 15
Line 146: Line 172:
 
}}
 
}}
 
[[Category:Singleton Functions|addGroup]]
 
[[Category:Singleton Functions|addGroup]]
 +
[[Category:Game Patch 1.2.4|addGroup]]

Latest revision as of 07:52, 20 March 2024

Scripting Root

Envrioment: Mission Scripting
Function: addGroup Added with: 1.2.4
Member Of: coalition
Syntax: Group coalition.addGroup(enum countryId , enum groupCategory , table groupData )
Description: Dynamically spawns a group of the specified category for the specified country. Group data table is in the same format as created by the mission editor.

See country page and group class page for the list of countries by id and group categories.

The coalition of the group is defined by the coalition its country belongs to.

If the group or any unit within shares a name of an existing group or unit, the existing group or unit will be destroyed when the new group is created.

Function can NOT spawn new aircraft with a skill level of "client". However in single player a group can be spawned with the skill level of "Player". When this occurs the existing player aircraft will be destroyed.

If no groupId or unitId is specified or the Ids are shared with existing groups or units, a new Id will be created for the new group.


Return Value: Group
Return Example: none
Examples: Detailed Examples Linked Below:
   Ground Group
   Ship Group  
   Helicopter Group
   Plane Group


A basic table for a ground unit

  local groupData = {
	["visible"] = false,
	["taskSelected"] = true,
	["route"] = 
	{
	}, -- end of ["route"]
	["groupId"] = 2,
	["tasks"] = 
	{
	}, -- end of ["tasks"]
	["hidden"] = false,
	["units"] = 
	{
		[1] = 
		{
			["type"] = "LAV-25",
			["transportable"] = 
			{
				["randomTransportable"] = false,
			}, -- end of ["transportable"]
			["unitId"] = 2,
			["skill"] = "Average",
			["y"] = 616314.28571429,
			["x"] = -288585.71428572,
			["name"] = "Ground Unit1",
			["playerCanDrive"] = true,
			["heading"] = 0.28605144170571,
		}, -- end of [1]
	}, -- end of ["units"]
	["y"] = 616314.28571429,
	["x"] = -288585.71428572,
	["name"] = "Ground Group",
	["start_time"] = 0,
	["task"] = "Ground Nothing",
  } -- end of [1]

  coalition.addGroup(country.id.USA, Group.Category.GROUND, groupData)

Required Group values

 name         string for the group name
 task         string for the master task that will dictate core AI behavior

Optional Group Values

 groupId         number groupId
 start_time      number time in seconds after mission start time that the group will spawn in. If 0 the group will spawn immediately.
 lateActivation  boolean value that can override start_time to force the group to spawn in via trigger
 hidden          boolean whether or not the group is visible on the F10 map view
 hiddenOnPlanner boolean if true the group will be hidden on the mission planner available in single player. 
 hiddenOnMFD     boolean if true this group will not be auto populated on relevant aircraft map screens and avionics. For instance SAM rings in F-16/F-18 and AH-64 threats pages
 route           table complex table defining the route and tasks assigned to the group

Optional Group Values (Aircraft and Helicopters)

 uncontrolled    boolean for ground starts, whether or not the aircraft will be visible but not active
 modulation      number (0 or 1) for AM or FM radio
 frequency       number of the radio frequency the unit will broadcast to
 communication   boolean for whether or not the group will communicate over the radio

Optional Group Values (Ground and Ships)

 visible         boolean For whether or not the group is visible before its start time
 uncontrollable  boolean corresponds to "Game Master Only" setting in editor. Dictates whether or not ground commanders can give orders to the group.

Optional Group Values (Ground only)

 manualHeading   boolean When spawned with a route assigned each unit in the group will automatically be pointing toward the next waypoint in the route. When set to true each unit will respect their own heading value. 
 

Required Unit values

name         name for the type of object
type         string for the type of object
x            number for x coordinate
y            number for y coordinate

Required Unit Values for Aircraft and Helicopters

 alt         number altitude in meters
 alt_type    string "BARO" or "RADIO" for Above sea level or above ground level
 speed       number velocity the aircraft will spawn at measured in meters per second
 payload     table of the aircrafts payload including fuel, weapons, and countermeasures
 callsign    table/number of the callsign for the unit. NATO countries use a table to define callsigns while the Russian style uses a number 

Optional Unit Values

unitId       number unitId
heading      number heading of the object in radians
skill        string of the units skill level. Can be "Excellent", "High", "Good", "Average", "Random", "Player"

Optional Unit Values for Ground

coldAtStart     boolean if true the vehicle will start with its engine off and should take some time to appear on FLIR
playerCanDrive  boolean if true Combined Arms players can take direct control of the unit. 


Aircraft and Helicopter values

 AddPropAircraft       table additional aircraft properties for some contains the datalink ID information for that unit. 
 livery_id             string name of the livery for the aircraft
 psi                   number
 onboard_num           string of the tail number on the aircraft
 parking_landing       number the "Term_Index" associated with the landing parking spot see Airbase.getParking
 parking_landing_id    string displayd value in the mission editor of the parking spot the unit will taxi to on landing
 parking               string of a number of the "Term_Index" associated with the starting parking spot see Airbase.getParking
 parking_id            string displayed value in the mission editor where the unit starts parked at
 datalinks             table defines the link16, SADL, or Longbow Net data used for that specific unit          

Helicopter Values

 ropeLength  number length of a rope used for sling loading, default is 15
Related Functions: Coalition Functions: addGroup, addStaticObject, getGroups, getStaticObjects, getAirbases. getPlayers, getServiceProviders, addRefPoint, getRefPoints, getMainRefPoint, getCountryCoalition
Notes: You MUST have a built in delay before accessing the group or units controllers and issuing tasks, commands or options of the group spawned. Otherwise the you are likely to cause a game crash.

Route table can be empty or assigned to the group after spawning using getController and pushTask functions. See page on mission task for more information regarding the route table.

FARPs are spawned using the addGroup function, with groupCategory set to -1

Payload table