VR-Forces Lua Documentation

• Table of Contents

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

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:

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

Function List

Functions

computeTurnStartTimes (turnAngle, speed, offsetTable, leaderIndex)

Compute a schedule of turn maneuvers for the subordinates of a unit such that they achieve a unit turn.
Given that a unit is flying in formation with a lead aircraft moving to or along a control measure and the rest of the aircraft following, when the unit turns, the followers often switch to the other side of the leader so they can turn using the same turn rate (radius) as the leader. This requires them to either turn before the leader, crossing behind it, or turn after the leader.

Parameters:

• turnAngle: The angle in radians that the unit is turning. Positive to the right.
• speed: The speed of the unit in mps.
• offsetTable: A table of VectorOffset3D representing the positions of the following aircraft. This is the table that is returned from simObjet:getFormationPositions().
• leaderIndex:

Return values:

1. A table representing the relative times when the aircraft should begin their turns. Each entry in the table is a start time for the corresponding offset in the offsetTable. The smallest offset time is always zero, i.e. one aircraft will turn immediately and the values in the table indicate when the other aircraft in the unit turn afterward.
2. leaderDelayDistance The distance that the leader flies before turning (i.e., its relative turn time in the returned table, times speed). This can be used to determine when the formation should start turning so that the leader turns at a given point.

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: (table) An emptytable created with createObjectMap(). Has SimObjects as keys.

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: (table) An emptytable created with createObjectMap(). Has SimObjects as keys.
• options: (table) See SimObject:getFormationPositions(), e.g. quantity, reference, spacing

Return value:

table keyed by subordinate with VectorOffset3Ds as values.

flipFormation (offsetTable, offsets, leaderIndex)

Flips a formation left-right, i.e. the Right values of the offset vectors.

Parameters:

• offsetTable:
• offsets: A table of VectorOffset3D defining offsets of subordinates from the leader.
• leaderIndex: An integer into the offsets table defining which entity is the leader.

Return value:

No return value, but the offsets table is modified.

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)

Gets the Location3Ds 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.

getModifiedFormationOffsets (numPositions, debug)

Function to get modified formation offsets for the current formation. TENTATIVE: supports example/prototype air unit scripts. This function looks up the current formation, the spacing state property, and the isFlipped state property to generate formation offsets.

Parameters:

• numPositions: (integer) The number of formation positions to get from the parameter database.
• debug: A boolean indicating whether debugging information should be printed to the object console (verbose).

Return values:

1. A table of OffsetVector3D defining the offsets from the leader, in unit order.
2. the index of the leader.
3. the current spacing. If the formation is using the default, SOE-defined spacing, then this value will be 0.
4. the current isFlipped status.

getPlatformOffsetsFromLeader (unit, formation)

Like getPlatformOffsetsFromUnit, but translates offsets to lead entity.

Parameters:

• unit:
• formation:

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.

printFormationOffsetObjectMap (subs, aMap)

Prints the contents of a table that has simObjects as keys and offsetVectors as values. Prints to printWarn.

Parameters:

• subs:
• aMap:

printFormationOffsets (formationOffsets)

Given a table of formation offsets from SimObject::getFormationPositions(...) print the offsets.

Parameters:

• formationOffsets:

printFormationOffsetsForSubordinates (unit, formationName)

Looks up formation offsets for the unit for the given formation name, and prints what subordinate is in what position. Prints to printWarn.

Parameters:

• unit:
• formationName:

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.