VR-Forces Lua Documentation

• Table of Contents

• !HowToPrint
• !Set Catalog
• !Task Catalog
• AirRefuelSupplier
• AsyncJob
• ComponentSystem
• ExtendableArtPart
• FeatureGeometry
• FeatureSet
• Location3D
• ScriptAnimationModel
• SensorGimbal
• SimObject
• SwingingArtPart
• SystemAttribute
• TranslatableArtPart
• TranslatableStream
• Vector3D
• VectorGeoc3D
• VectorOffset3D
• aggregateUtils
• airportDataUtils
• behaviorEngine
• componentSystemUtil
• contactsUtils
• dataFileUtils
• displayGraphUtil
• embarkationUtil
• engagementUtil
• formationUtils
• fsm
• fsm2
• msgUtil
• munitionLauncherUtils
• parseUtil
• pathUtil
• spatialUtil
• terrainReasoningUtil
• this
• unitUtil
• vrf
• vrfutil

formationUtils

(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)

Functions that help with access to and manipulation of formation definition data, including formation names and position offsets.
Usage:

 require "formationUtils"  
 formName = formationUtils.getValidFormationNameFor(this, "Line") 

Function List

Functions

fillFormationOffsetObjectMap (unit, formationName, bCenterFormation, objectMap)

Given an object map (see behavior engine module), fills the map with subordinate-offset pairs, where subordinate is a subordinate of the unit and offset is the offset to the formation leader for that subordinate. if formation name is not found, map is not changed. Optionally, center the formation before creating the map, i.e. the offsets will all be relative to the center of the bounding volume containing the formation positions.

Parameters:

• unit: (SimObject) The unit whose formation data to get.
• formationName: (string) Name of the desired formation.
• bCenterFormation: (bool) If true, center the offsets on the formation bounding volume.
• objectMap:

Return value:

table keyed by subordinate with VectorOffset3Ds as values.

fillFormationOffsetObjectMapWithOptions (unit, formationName, bCenterFormation, objectMap, options)

Given an object map (see behavior engine module), fills the map with subordinate-offset pairs, where subordinate is a subordinate of the unit and offset is the offset to the formation leader for that subordinate. if formation name is not found, map is not changed. Optionally, center the formation before creating the map, i.e. the offsets will all be relative to the center of the bounding volume containing the formation positions.

Parameters:

• unit: (SimObject) The unit whose formation data to get.
• formationName: (string) Name of the desired formation.
• bCenterFormation: (bool) If true, center the offsets on the formation bounding volume.
• objectMap:
• options:

Return value:

table keyed by subordinate with VectorOffset3Ds as values.

getFormationExtent (unit, formation, numSubordinates)

Determines the size of a formation. This is very similar to the Lua API function this:getFormationExtent(), except that it supports a query for any unit, and any formation of that unit. It provides information based on the first numSubordinates positions defined in the formation, not the positions currently assigned to the subordinates of this.

Parameters:

• unit: (SimObject) The unit to get formation data for.
• formation: (string) The name of the formation.
• numSubordinates: (number) The number of positions in this formation to use in the calculation. May be greater or less than the number of positions defined in this formation.

Return value:

(VectorOffset3D) An offset vector representing the bounding volume of the formation.

getGroundFormationPositionsAtLocation (unit, location, targetLocation, formationName, spacingMeters)

Location3D of formation positions around a location.

Parameters:

• unit: SimObject of the unit to compute formation positions for.
• location: Location3D of the place where the formation will be positioned.
• targetLocation: Location3D of a place that the formation should face (for orientation).
• formationName: string containing the desired formation name.
• spacingMeters:

Return value:

If the unit has a formation with the given name, a list (table) of ground-clamped Location3D positions. These will be in formation-definition order. If the formation name is not recognized, the table will be empty.

getPlatformOffsetsFromUnit (unit, formation)

Computes the offsets of all of the platform-level positions in the given unit, which may be a higher-echelon unit. The offsets are computed from the unit center. The unit center is the center of mass of the subordinates of the top level unit, with each subordinate given equal weight.

Parameters:

• unit: A SimObject, the unit to get positions for.
• formation: string The name of the unit formation. Note that lower-level subordinate units will have their formations taken from the subordinateFormation information in the unit formation, or if there is none, from the parent's formation name. If any formation name is not valid, the first formation entry for that unit will be used.

Return values:

1. A table of offsets for the subordinates. For subordinates that are platforms, the table entry will be a VectorOffset3D. For subordinates that are units, the table entry will be a table of subordinate offset data, recursively. For example, a tank company with 3 PLTs and a single CO vehicle might produce this:
   { {offset, offset, offset, offset}, offset, {offset, offset, offset, offset}, {offset, offset, offset, offset}}
   The offsets are returned in structured tables this way so that the calling script can identify groups of positions that belong to the same subordinate, and potentially shift them as a group to fill in a gap for a missing entity.
2. A list (table) of leader indices (integers). Each index is the index of the subordinates of a unit that has the lowest promotion ID. (These are formation promotion IDs, an not necessarily the unit promotion order.) Succeeding indices are for lower echelons. For example, if the the formations for the above tank company defined the first platoon and the first vehicle in the platoon to have promotion ID 0, then the returned table would be:
   {1, 1}
   This list is returned so that the calling script can find the individual position, match an entity to it, and make it the leader of follow tasks for other entities.

getValidFormationNameFor (unit, desiredFormationName)

Return a formation name for the unit from among the formation names available to the given unit. The desiredFormationName is processed with regularizeFormationName before comparing it to available names. If there is an exact match with an available name, that name is returned. Otherwise, if there is a match that doesn't consider "left", "right", or "center", that (full) formation name is returned. If no matches are found, the first formation name available is returned.

Parameters:

• unit: SimObject for which to find formation. If it is not a unit with formations, return will be nil.
• desiredFormationName: string representing the desired formation name such as "Line-Left".

Return value:

either a string that is guaranteed to be a formation for the unit, or nil if the subject is not a unit or has no formation names.

offsetPositionOrder (offsets, heading)

Takes a list of VectorOffset3D offsets and a direction (heading) and computes the order of the offset positions along the direction. The offsets are effectively treated as locations in a cartesian coordinate system relative to 0,0,0.

Parameters:

• offsets: (table of VectorOffset3D) A list of offsets.
• heading: (number) A heading in radians.

Return value:

A list of indices (table of integers) into the offsets list. The first index in the list points to the offset that is first along the given direction; the last index points to the offset that is farthest along the given direction.

regularizeFormationName (inputName)

Returns a string with all alpha characters converted to lower case, and non-alphanumeric characters converted to '-'. This is the algorithm for "regularizing" formation names in VR-Forces.

Parameters:

• inputName: (string) A formation name

Return value:

(string) The formation name with characters converted as described. If the input is nil, an empty string is returned.