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
• dataFileUtils
• execTool
• fsm
• fsm2
• munitionLauncherUtils
• parseUtil
• pathUtil
• rtdIntegrationUtil
• spatialUtil
• this
• vrf
• vrfutil

SimObject

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

The SimObject class refers to a single object in the simulation. It may be an entity, waypoint, route, or any other simulation object. These objects may be VRF simulated objects, or remote objects received over DIS or HLA by VR-Forces.

SimObject Validity
There are a number of cases where a SimObject can be removed from the simulation or deleted by a user in the middle of a simulation. Because of this, it is possible for a SimObject to become invalid from one tick to the next. The SimObject instance will continue to exist, but the isValid() function will return false if this occurs. Once the object is invalid, most functions are disallowed, and will cause a runtime error if called. See the isValid() function for further details.

Function List

Functions

animationDuration (animationName)

The time the animation will run (in seconds).

Parameters:

• animationName:

Return value:

Seconds of the animation duration. If the entity is not a DI-Guy character, does not have this animation, then 0 is returned.

animationSpeed (animationName)

The speed of the animation

Parameters:

• animationName:

Return value:

Animation speed

deleteObject ()

Deletes the given entity object from the simulation. After object is deleted, if there is a scripted object
tied to that simulation object is isDeleted member will return true

getAirTurbulence ()

Returns the value of the air turbulence the object is experiencing. Will return an empty string if vrfObject is not valid.

getAllSubordinates (bool)

Retrieve all the leaf node (lowest level) SimObjects that are subordinate to this entity. Will recursively traverse all subordinate aggregates and add their children to this list. Note that this list *will not* contain the subordinate pseudo-aggregates -- only the list of lowest level objects. If the optional boolean flag is true, only return VR-Forces simulated objects. Default value is false.

Parameters:

• bool:

Return value:

Table of subordinate entities (SimObjects).

getAnimationTransitionInfo (fromAnimation, toAnimation)

Gets the information about the transition motion from one animation to the next.

Parameters:

• fromAnimation: The name of the starting animation.
• toAnimation: The name of the ending animation.

Return values:

1. The duration of the transition animation.
2. A VectorOffset3D indicating the change in position that occurs due to this transition.
3. A value indicating the change in heading, in radians, that occurs due to this transition.

getAppearance ()

Returns the appearance bits of the entity.

Return value:

The appearance bits of the entity as an unsigned integer.

getBoundingVolume ()

Get bounding volume as a vectorOffset3D

Return values:

1. Bounding volume-- a vectorOffset3D representing the bounding volume: full length (forward-back dimension), width (left-right) and height.
2. Offset-- an vectorOffset3D representing the offset of the bounding volume center from the location point of the entity. The three numbers represent forward, right, and up.

getCapableSubordinates (bool)

Retrieve the SimObjects subordinate to this entity that are not destroyed, and that have firepower and mobility capability. If the optional boolean flag is true, only return VR-Forces simulated objects. Default value is false.

Parameters:

• bool:

Return value:

Table of subordinate entities (SimObjects).

getClosestPointToLocation2D (location)

Finds the closest point in 2D space on the object's geometry to the given location. For lines and areas it will check each segment. For points the point itself is returned.

Parameters:

• location: A Location3D to from which we are finding the closest point

Return values:

1. Location3D The location of the closest point in the object's geometry to the specified location.
2. double The distance in meters between the specified and returned locations.

getDamageState ()

Returns the damage state of the entity as: none slight moderate destroyed

Return value:

The damage state of this entity, as a string. Possible values are "none", "slight", "moderate", and "destroyed".

getDiGuyHandItem ()

Returns a string identifying the hand item, if any, of any lifeform object represented by DI-Guy

getDirection3D ()

Get directionf othe object as a vector3D

Return value:

vector3D of direction of object

getDraft ()

Gets the distance of the bottom of the bounding volume below the entity origin. Since ships are defined with their origin at the waterline, this is the draft of the ship.

Return value:

The number of meters the bounding volume bottom (keel) is below the entity origin (waterline). Positive and increasing as the keel gets farther below the origin.

getEchelonLevel ()

Provides a string indicating the echelon level of this SimObject. Possible values are:

• individual
• element
• team
• squad
• section
• platoon
• battery
• company
• battalion
• regiment
• brigade
• division
• corps
• force
• other

Return value:

String naming the echelon level of this SimObject.

getEmbarkedObjects ()

Retrieve the current objects embarked on this entity.

Return value:

Table of entities as script objects that are embarked on this entity

getEmbarkedOn ()

Retrieve the entity on which this entity is embarked, if any.

Return value:

If embarked, the SimObject the entity is embarked on. Otherwise, an invalid SimObject.

getEntityType ()

Retrieve the entity type as the DIS septuplet.

Return value:

Entity type, as a colon-delimited string. E.g. "1:1:222:3:1:0:0"

getExtendedData (key)

VR-Forces SimObjects may contain extended data, encoded as key/value pairs of strings, that is published to the network. Returns the value associated with the given key. Will return an empty string if no data matching that key is found.

Parameters:

• key: A string key for the extended data.

Return value:

String value associated with the key.

getExtendedLabel (index)

Retrieve the object extended label of this entity at the given index. Will throw an exception if the entity is in an invalid state

Parameters:

• index: Integer index of the extended label.

Return value:

The extended label of the entity (string)

getForceEnumeration ()

The force this entity belongs to.

Return value:

The force tyoe as an integer.

getForceType ()

The force this entity belongs to.

Return value:

The force name as a string.

getFormationNames ()

Gets a list of names of the formations available to this entity. These will only be valid if the entity is an aggregate (ie: squad, fire team, etc.) with formations defined in the Simulation Object Editor.

Return value:

A list (table) for formation names.

getFormationPositions (formationName)

Gets the position offsets for the formation. The position offsets are returned as a list of VectorOffset3Ds, with the first position being 0,0,0, or the centre of the formation. Note that in squads, position offsets will be of the fire team as a whole, not all individual positions. Each fire team will need to be queried for formation positions.

Parameters:

• formationName: The name of the formation to get positions for

Return value:

A list (table) of formation position offsets in VectorOffset3D

getGlobalId ()

Retrieve the object's global identifier. Will throw an exception if the entity is in an invalid state

Return value:

The global identifier of the entity (string)

getHeading ()

Retrieve the heading of the entity.

Return value:

The heading, clockwise from north, in radians

getHeightAboveTerrain ()

The height of the entity above the terrain. Note that if terrain is not paged in for this location, 0 is returned and the second return value will be false.

Return values:

1. Meters above terrain.
2. A boolean indicating if the height value is valid.

getIntersectionPointWithLine2D (point1, point2)

Calculates the point where the line defined by the two points intersects with the object in 2 dimensional space. In cases of multiple intersections, only the first one is returned. This function only works with areal and linear objects. If the point is within the area, the closest point on the perimeter of the area is returned.

Parameters:

• point1: A Location3D defining the start point of the line.
• point2: A Location3D defining the end point of the line.

Return values:

1. Location3D The location of the intersection between the line and the geometry of this object.
2. boolean Whether or not an intersection was found.

getLabel ()

Retrieve the object label of this entity. Will throw an exception if the entity is in an invalid state

Return value:

The label of the entity (string)

getLifeformPosture ()

Returns the DIS enumerated value for the current lifeform posture.

getLocation3D ()

Retrieve the location of this entity.

Return value:

A Location3D giving the location of this entity.

getLocations3D ()

Retrieve the vertices that make up this VRF object. Entities will have a table of a single vertex

Return value:

Table of vertices.

getName ()

Retrieve the object name of this entity. Note that this value can be retrieved, even if the SimObject is currently in an invalid state.

Return value:

The name of the entity (string)

getNavigationEnabled ()

Retrieves whether or not navigation by Gameware (in a navigation area) is enabled for this entity.

Return value:

True if Gameware navigation is enabled, false if not

getNbcAgent ()

Returns a string identifying the type of NBC agent in an NBC contamination area.

getNbcDamage ()

Get information about the Nuclear, Biological, or Chemical (NBC) damage caused by this object, which must be a Contamination Area. Returns string identifying the type of contamination, the rate of damage the area causes (health per second) and necessary MOPP Level to protect against it.

Return values:

1. string NBC type -- String identifying the NBC type: "Nuclear", "Biological", or "Chemical".
2. int Damage per second -- NBC damage per second caused by this object.
3. int MOPP level -- MOPP level required to protect against the NBC damage caused by this object.

getObjectId ()

Retrieve the object's object identifier. Will throw an exception if the entity is in an invalid state

Return value:

The global identifier of the entity (string)

getOffsetFromParent ()

Returns the offset from the entity on which this object is embarked to this object's position. If not embarked, this will be a 0 offset vector.

Return value:

A VectorOffset3D

getOffsetOfLocation (location)

Computes the offset from the object to the given location, relative to the object's orientation. Note that this is a full 3D orientation, including pitch and roll; if roll is not zero, then the resulting offset vector will not correctly translate to a Vector3D using makeVectorRefToDirection(), and it will not produce the correct result when added to a Vector3D with addOffset().

Parameters:

• location: A Location3D to which we are finding the offset.

Return value:

A VectorOffset3D representing the offset, relative to the orientation of the object.

getParameter (paramName)

Looks up and returns a static parameter for a simulation object. Return type will vary based on type of parameter. This only applies to "top level" parameters in the OPE file, and only to parameters of basic types.

Parameters:

• paramName: The string name of the parameter, as specified in the .ope file for the entity platform.

Usage:

getParameter("max-speed")

Return value:

The parameter value, if found. May be a number, boolean or string.

getParameterProperty (propertyName)

Gets the field values for the given named parameter (static) property.

Parameters:

• propertyName: The name of the property to be retrieved.

Usage:

propertyFieldValues = this:getParameterProperty(propertyName)

Return value:

Returns a table containing the names of the fields and their values.

getParameterPropertyListItem (propertyName, keyValues)

Gets value for a single item in a parameter property which is a list of items. Rather than return the entire list, as getParameterProperty() would, the first entry found which matches the values specified in keyValues is returned.

Parameters:

• propertyName: The name of the list property to be searched.
• keyValues: Indicates what value(s) to look for when finding the item. If the property is a list of structures (values with multiple, named fields), this parameter should be table containing a list of key field names and values. The list will be searched for items which have those values in those fields. If the property is a list of simple values (a list of numbers or strings, for instance), this parameter should be a single value. The first entry that matches this value will be returned. If the parameter does not match the underlying fields or structure of the items in the list, the call will fail and the return value will be nil.

Usage:

• listItem, index = this:getParameterPropertyListItem(propertyName, { KeyField1Name = KeyField1Value, KeyField2Name = KeyField2Value })

• listItem, index = this:getParameterPropertyListItem(propertyName, valueOfItemToFind)

Return values:

1. The value of the item that was found, or nil. For a list of structures, this will be a table containing the names of each field and their set values.
2. The index of the item in the list.

getParameterPropertyListItemByIndex (propertyName, index)

Gets value for a single item in a parameter property which is a list of items. Rather than return the entire list, as getParameterProperty() would, returns the entry at the specified index (starting at index 1).

Parameters:

• propertyName: The name of the list property to be searched.
• index: The index (starting at 1) of the item to look up.

Usage:

listItem = this:getParameterPropertyListItemByIndex(propertyName, index)

Return value:

Returns the value of the item at the index. For a list of structures, this will be a table containing the names of each field and their set values.

getParameterPropertyMapItem (propertyName, keyValue)

Gets the value for a single item in a parameter property which is a map. Rather than return the entire map, as getParameterProperty() would, the entry matching the value specified in keyValue is returned.

Parameters:

• propertyName: The name of the map property to be searched.
• keyValue: The key value of the map item to be updated.

Usage:

mapItem = this:getParameterProperty(propertyName, keyValue)

Return value:

Returns the value of the item with the given key. May be a single item for maps of simple data types, or table for maps containing structures or other complex data types.

getParameterSubordinateFunctions ()

Get a table of subordinate types and role tags from parameters.

Return value:

Returns a table in the form of {{OBJECT_TYPE, FUNCTION_HANDLE}}

getPartHeading (part, includeParent)

Computes the heading of the given articulated part relative to the body coordinate system of the entity.

Parameters:

• part: The articulated part number to return the heading for.
• includeParent: Optional, default is false. If true, include the parent heading, i.e. the returned heading will be relative to true north.

Return value:

Returns the heading if the part exists or 0 if it does not.

getPartParentPosition (part)

Returns vectorOffset3D of the part from the parent

Parameters:

• part: The articulated part number to return the parent offset position for

Return value:

Returns a DtOffsetVector3D which is the offset parent position of the part, or an empty vector if the part does not exist

getPartPitch (part, includingParent, inludingParent)

Returns pitch in radians

Parameters:

• part: The articulated part number to return the topographic pitch for
• includingParent:
• inludingParent: Optional, default is false. If true, include the parent pitch

Return value:

Returns the pitch if the part exists or 0 if it does not

getPartTranslationForward (part)

Parameters:

• part: The articulated part number to return the translation for.

Return value:

Returns the forward translation value for the specified part.

getPartTranslationRight (part)

Parameters:

• part: The articulated part number to return the translation for.

Return value:

Returns the right translation value for the specified part.

getPartTranslationUp (part)

Parameters:

• part: The articulated part number to return the translation for.

Return value:

Returns the up translation value for the specified part.

getPartWorldPosition (part)

Returns as a Location3D of the part position

Parameters:

• part: The articulated part number to return the world position for

Return value:

Returns a DtLocation3D which is the world position of the part, or an empty DtLocation3D if the part does not exist

getPitch ()

Retrieve the pitch of the entity.

Return value:

The pitch in radians

getRoll ()

Retrieve the roll of the entity.

Return value:

The roll in radians

getSpeed ()

Retrieve the speed of the entity.

Return value:

Speed in meters/second for this entity

getStateProperty (propertyName)

Gets the field values for the given named state property.

Parameters:

• propertyName: The name of the property to be retrieved.

Usage:

propertyFieldValues = this:getStateProperty(propertyName)

Return value:

Returns a table containing the names of the fields and their values.

getStatePropertyListItem (propertyName, keyValues)

Gets value for a single item in a state property which is a list of items. Rather than return the entire list, as getParameterProperty() would, the first entry found which matches the values specified in keyValues is returned.

Parameters:

• propertyName: The name of the list property to be searched.
• keyValues: Indicates what value(s) to look for when finding the item. If the property is a list of structures (values with multiple, named fields), this parameter should be table containing a list of key field names and values. The list will be searched for items which have those values in those fields. If the property is a list of simple values (a list of numbers or strings, for instance), this parameter should be a single value. The first entry that matches this value will be returned. If the parameter does not match the underlying fields or structure of the items in the list, the call will fail and the return value will be nil.

Usage:

• listItem, index = this:getStatePropertyListItem(propertyName, { KeyField1Name = KeyField1Value, KeyField2Name = KeyField2Value })

• listItem, index = this:getStatePropertyListItem(propertyName, valueOfItemToFind)

Return values:

1. The value of the item that was found, or nil. For a list of structures, this will be a table containing the names of each field and their set values.
2. The index of the item in the list.

getStatePropertyListItemByIndex (propertyName, index)

Gets value for a single item in a state property which is a list of items. Rather than return the entire list, as getStateProperty() would, returns the entry at the specified index (starting at index 1).

Parameters:

• propertyName: The name of the list property to be searched.
• index: The index (starting at 1) of the item to look up.

Usage:

listItem = this:getStatePropertyListItemByIndex(propertyName, index)

Return value:

Returns the value of the item at the index. For a list of structures, this will be a table containing the names of each field and their set values.

getStatePropertyMapItem (propertyName, keyValue)

Gets the value for a single item in a state property which is a map. Rather than return the entire map, as getStateProperty() would, the entry matching the value specified in keyValue is returned.

Parameters:

• propertyName: The name of the map property to be searched.
• keyValue: The key value of the map item to be updated.

Usage:

mapItem = this:getStateProperty(propertyName, keyValue)

Return value:

Returns the value of the item with the given key. May be a single item for maps of simple data types, or table for maps containing structures or other complex data types.

getSubordinateFunctions ()

Get a table of subordinates and function tags for the unit.

Return value:

{{"subordinate" = DtScriptVrfObject, "function" = string}, {"subordinate" = DtScriptVrfObject, "function" = string}, ...}

getSubordinates (bool)

Retrieve the SimObjects immediately subordinate to this entity' If the optional boolean flag is true, only return VR-Forces simulated objects. Default value is false.

Parameters:

• bool:

Return value:

Table of subordinate entities (SimObjects).

getSuperior (bool)

Retrieve the SimObject superior of this object

Parameters:

• bool:

Return value:

DtScriptVrfObject of superior

getUUID ()

Retrieve the UUID of this object. Note that this value can be retrieved, even if the SimObject is currently in an invalid state.

Return value:

A string, the UUID of the entity.

getVelocity3D ()

Retrieve the velocity of the entity. The return value is a Vector3D, i.e. the velocity components are north-east-down.

Return value:

A Vector3D representing this entity's velocity.

hasLosToLocation (targetLocation)

Checks to see if the line of sight to the given location is clear. Checks LOS from the entity bounding volume center, which may not be the sensor location.

This function returns two boolean values. The second value indicates whether the first result is valid, or whether it is invalid because the terrain data to make the check was not available.

Parameters:

• targetLocation: The Location3D to which LOS is checked.

Usage:

hasLos, isValid = entity1:hasLosToLocation(targetLoc) 

Return values:

1. A boolean, true if LOS is clear.
2. A boolean, true if the terrain data was valid

hasLosToObject (targetEntity)

Checks to see if the line of sight to the given target object is clear. Checks LOS from the entity bounding volume center, which may not be the sensor location. Checks LOS to the center of the target's bounding volume.

This function returns two boolean values. The second value indicates whether the first result is valid, or whether it is invalid because the terrain data to make the check was not available.

Parameters:

• targetEntity: The SimObject to which LOS is checked.

Usage:

hasLos, isValid = entity1:hasLosToObject(targetEntity) 

Return values:

1. A boolean, true if LOS is clear.
2. A boolean, true if the terrain data was valid

hasParameterProperty (propertyName)

Checks to see if the parameter property exists. It is OK to call the get... Lua API functions when the property doesn't exist; a warning is printed and a nil object is returned. Using this test is appropriate thought when it is known ahead of time that the property might not exist for some entity.

Parameters:

• propertyName: The name (string) of the property to be retrieved.

Return value:

Returns true if the property exists; false otherwise.

hasStateProperty (propertyName)

Checks to see if the parameter property exists. It is OK to call the get... Lua API functions when the property doesn't exist; a warning is printed and a nil object is returned. Using this test is appropriate thought when it is known ahead of time that the property might not exist for some entity.

Parameters:

• propertyName: The name (string) of the property to be retrieved.

Return value:

Returns true if the property exists; false otherwise.

isActive ()

Returns a boolean indicating if this is an environmental object which is active.

isAggregate ()

Determine if this object is an aggregate (unit).

Return value:

True if this is an aggregate SimObject.

isAnimationAvailable (animationName)

Checks to see if the object is capable of playing a specified DI-Guy animation.

Parameters:

• animationName: The name of a DI-Guy animation.

Return value:

Returns true if the specified animation name is available for this object.

isAppearanceAvailable (appearanceName)

Checks to see if the object is capable of displaying a specified DI-Guy appearance.

Parameters:

• appearanceName: The name of a DI-Guy appearance.

Return value:

Returns true if the specified appearance name is available for this object.

isBreached ()

Returns a boolean indicating if this is an engineering object which has been breached.

isDeleted ()

Determine if this SimObject has been deleted from the simulation. If it has been deleted, the SimObject will be in an invalid state, and most functions called on this object will result in an error.

Return value:

True if the object has been deleted.

isDestroyed ()

Determine if the entity is in the destroyed state. This is a DIS entity state value, and is independent of mobility/firepower kill state.

Return value:

True if this object is destroyed, else false

isEmbarked ()

Determine if this entity is currently embarked on another entity.

Return value:

True if this object is embarked, false if not

isFirePowerKilled ()

Determine if the entity's fire power has been killed.

Return value:

True if this object is fire power killed, else false

isGestureAvailable (gestureName)

Checks to see if the object is capable of playing a specified DI-Guy gesture.

Parameters:

• gestureName: The name of a DI-Guy gesture.

Return value:

Returns true if the specified gesture name is available for this object.

isHandItemAvailable (handItemName)

Checks to see if the object is capable of holding a specified DI-Guy hand item.

Parameters:

• handItemName: The name of a DI-Guy hand item.

Return value:

Returns true if the specified hand item name is available for this object.

isHeadAvailable (headName)

Checks to see if the object is capable of displaying a specified DI-Guy head appearance.

Parameters:

• headName: The name of a DI-Guy head appearance.

Return value:

Returns true if the specified head name is available for this object.

isIndependentlyTasked ()

Returns true if object is indenpendently tasked

Return value:

True if object is currently independently tasked

isInvisible ()

Determine if the entity is invisible.

Return value:

True if this object is invisible, else false

isLocal ()

Determine if the SimObject represents an entity that is being simulated on the same VRF SimEngine on which this script is being run. Some data is only available for entities that are local. If that is the case, it will be noted in the function description.

Return value:

True if object is local.

isMobilityKilled ()

Determine if the entity's mobility has been killed.

Return value:

True if this object is fire power killed, else false

isPointInside (point)

Determines if the given point is inside the vertices associated with this object (the 2D footprint). It is intended to be used with area objects, but will work on any object if it has 3 or more vertices.

Parameters:

• point: A Location3D to test

Return value:

A boolean that is true if this point is inside the object vertices.

isPseudoAggregate ()

isDisaggregatedUnit() Determine if this object is a pseudo aggregate; that is, a collection of other entities, vs. a single entity that represents a unit. A pseudo aggregate is a unit that is aggregated and in the DtDisaggregated state.

Return value:

True if this is a pseudo aggregate SimObject.

isSensorKilled ()

Determine if the entity's sensors have been killed.

Return value:

True if this object is sensor killed, else false

isValid ()

Determine if this SimObject is current in a valid state. A SimObject must be valid in order to call any functions on it other than isValid(), isDeleted(), and getName().
A SimObject may become invalid for a number of reasons, including:

• Object deleted by user or other simulation activity. In this case isDeleted() will return true.
• Initial load of a scenario on a multi-sim engine configuration, and this object has not yet been discovered locally. In this case, once the object is discovered locally, the object will no longer be invalid.
• This SimObject references a network object (perhaps non-VRF) that was removed or has not yet joined the simulation.

After a SimObject becomes invalid, it may become valid again if an entity with the same name (marking text) is later added to the simulation. The SimObject will then refer to that new object.
If any disallowed functions are called on an invalid SimObject, a runtime error will occur, stopping the script execution.

isVrfSimulated ()

Determine if this entity is simulated by VR-Forces

Return value:

True if this object is simulated by VR-Forces, false if not

setSubordinateFunctions ()

Given a table {{"subordinate" = DtScriptVrfObject, "function" = string}, {"subordinate" = DtScriptVrfObject, "function" = string}, ...} Set the "SubordinateFunctions" state property.

Return value:

true if setStateProperties message was sent.