unitUtil
(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)
Summary
These utilities help computation about units.
Dependencies
Please make sure that this is preceded by these inclusions:
require "vrfutil"
require "formationUtils"
Function List
| areUnitSubsOnlyOfType (unit, entityType) | Determines if the given unit is homogenous, based on the given entity type. |
| averagePositionOfDismountedSubordinates (unit, clamp) | Computes the average position of dismounted subordinates. |
| calculateSubordinatePosition (subordinate, battlePosition, targetPoint, formationOffsetMap) | Given a subordinate, a battlefield position, a location toward which to orient, and a map of subordinates to formation offset locations, use the map offset to compute a location relative to the battlefield position according to formationOffset. |
| calculateSubordinatePositionFromHeading (subordinate, battlePosition, heading, formationOffsetMap) | Given a SimObject subordinate, a Location3D representing a battlefield position,a heading, and a map of subordinates to formation offset locations, use the formationOffsetMap offset to return a Location3D representing a location relative to battlePosition according to formationOffset. |
| getAllTaskableSubordinates (unit) | Gets all bottom-level entities in a unit hierarchy, much like vrf:getAllCapableSubordinates. |
| orderSubordinatesAlongDirection (subordinates, heading, table) | returns a list of subordinates ordered along the direction from least to most |
| setPostureUrgency (simObjects, urgencyLevel) | Sets the posture urgency for the SimObjects in the given array (table). |
Functions
- areUnitSubsOnlyOfType (unit, entityType)
-
Determines if the given unit is homogenous, based on the given entity type. Goes through the list of subordinates and checks if the first septuplet of the entity type (entity kind) matches with the entity kind of the entity type given by the user.
Parameters:
-
unit: The unit (simObject) of which to get subordinates. -
entityType: the entity kind (first DIS septuplet) such as platform/vehicle (1), life form (3), etc.
Return value:
- boolean that is true if the unit is a homogenous aggregate of the given entity kind, or false if it is not.
-
- averagePositionOfDismountedSubordinates (unit, clamp)
-
Computes the average position of dismounted subordinates.
Parameters:
-
unit: SimObject that is a unit -
clamp: (boolean) terrain clamp the result (default or nil is true)
Return value:
- Location3D of that unit based on average of not destroyed, dismounted subordinates
-
- calculateSubordinatePosition (subordinate, battlePosition, targetPoint, formationOffsetMap)
-
Given a subordinate, a battlefield position, a location toward which to orient, and a map of subordinates to formation offset locations, use the map offset to compute a location relative to the battlefield position according to formationOffset. The return location is clamped 0.5m above terrain.
Parameters:
-
subordinate: SimObject. Subordinate for whom to calculate a position. -
battlePosition: Location3D. The location about which to position the subordinate. -
targetPoint: Location3D. A location toward which to orient from the battlePosition. -
formationOffsetMap: ObjectMap. A table indexed by SimObject with value VectorOffset3D representing subordinate formation offsets. See formationUtils.fillFormationOffsetObjectMap()
Return value:
- Location3D. Represents a location relative to battlePosition according to formationOffset, clamped 0.5m above terrain.
-
- calculateSubordinatePositionFromHeading (subordinate, battlePosition, heading, formationOffsetMap)
-
Given a SimObject subordinate, a Location3D representing a battlefield position,a heading, and a map of subordinates to formation offset locations, use the formationOffsetMap offset to return a Location3D representing a location relative to battlePosition according to formationOffset. the return location is clamped 0.5m above terrain.
Parameters:
-
subordinate: SimObject. Subordinate for whom to calculate a position. -
battlePosition: Location3D. The location about which to position the subordinate. -
heading: Number. A heading toward the enemy -
formationOffsetMap: ObjectMap. A table indexed by SimObject with value VectorOffset3D representing subordinate formation offsets. See formationUtils.fillFormationOffsetObjectMap()
Return value:
- Location3D. Represents a location relative to battlePosition according to formationOffset, clamped 0.5m above terrain.
-
- getAllTaskableSubordinates (unit)
-
Gets all bottom-level entities in a unit hierarchy, much like vrf:getAllCapableSubordinates. However, it also filter out subordinates that are externally tasked. It does this by descending the hierarchy recursively, pruning any subordinate unit that is independently tasked. Note that lowest level entities might be tasked by their superior, but pruned anyway because their superior is independendtly tasked. This function also returns only vrf-simulated entities.
Parameters:
-
unit: The unit (simObject) of which to get subordinates.
Return value:
- A list (table) of simObjects that are the lowest level in the hierarchy under unit. Destroyed, mobility killed, firepower killed, and entities whose parent is independently tasked are not included.
-
- orderSubordinatesAlongDirection (subordinates, heading, table)
-
returns a list of subordinates ordered along the direction from least to most
Parameters:
-
subordinates: -
heading: Number. Heading in radians of direction to order subordinates. -
table: Array of subordinates
Return value:
- table. Array of subordinates. First element is the first along the heading.
-
- setPostureUrgency (simObjects, urgencyLevel)
-
Sets the posture urgency for the SimObjects in the given array (table).
Parameters:
-
simObjects: Table. List of SimObjects. -
urgencyLevel: Number. 0 for least, 7 for immediate.
-