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

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.

getAllCapableSubordinates (vrfSimulatedOnly)

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.
This function only returns subordinates that are not destroyed and have firepower and mobility capability. See also getCapableSubordinates, getSubordinates and getAllSubordinates.

Parameters:

• vrfSimulatedOnly: (boolean) Optional. If this flag is true, only return VR-Forces simulated objects. Default value is false.

Return value:

Table of subordinate entities (SimObjects).

getAllSubordinates (vrfSimulatedOnly)

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.
See also getCapableSubordinates, getSubordinates, and getAllCapableSubordinates.

Parameters:

• vrfSimulatedOnly: (boolean) Optional. If this flag is true, only return VR-Forces simulated objects. Default value is false.

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.

getAssignedTransport (SimObject)

Using state property "AssignedTransport", retrieve the assigned SimObject, otherwise null object.

Parameters:

• SimObject: for the assigned transport if assigned and valid, otherwise null object

getBoundingVolume (includingDestroyedSubordinates)

Get bounding volume as a vectorOffset3D

Parameters:

• includingDestroyedSubordinates: Optional, default is false. If true, include the destroyed subordinates in calculation of volume for units. If called on a platform, it returns the platform's volume and offset. defaults to false

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 (vrfSimulatedOnly)

Retrieve the SimObjects subordinate to this entity that are not destroyed, and have firepower and mobility capability. See also getSubordinates, getAllSubordinates, and getAllCapableSubordinates.

Parameters:

• vrfSimulatedOnly: (boolean) Optional. If this flag is true, only return VR-Forces simulated objects. Default value is false.

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 direction of the object as a vector3D.

Return value:

vector3D of direction of object. This vector has unit length.

getDistanceBehind (targetEntity)

Will return (in meters) the distance behind the supplied object

Parameters:

• targetEntity: The SimObject to which distance behind is checked.

Usage:

local distanceBehdind entity1:getDistanceBehind(targetEntity) 

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 ()

Returns the SimObject on which this object is embarked.

Return value:

SimObject embarkation host, or SimObject with null UUID.

getEmbarkedOn ()

Returns the SimObject on which this object is embarked.

Return value:

SimObject embarkation host, or SimObject with null UUID.

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, options)

Gets the position offsets for the formation. The position offsets are returned as a list of returned as a list of VectorOffset3Ds. The vector is the offset from the formation leader. If the subordinate is itself a unit, then the vector specifies the offset between unit centers.

Parameters:

• formationName: (string) The name of the formation to get positions for.
• options: (table) An optional list of options to apply. If this parameter is not provided, all of the default values will be used.
  
  • quantity -- (number) The number of positions to return. Can be more than than the number of positions originally defined; if it is, additional positions will be computed. The default is to provide all of the defined positions in the formation.
  • reference -- (string) The location that the offsets are referenced to. A value of "unit" will make all the vectors offsets from the unit center, where the unit center is the center of mass of the positions returned. The default is "leader," making the vectors offsets from the returned positions with the lowest promotion ID.
  • spacing -- (number) The desired spacing of the positions. This is the space between the position with promotion ID 0 and its closest follower. The default is to use the spacing that is in the formation definition.

Return values:

1. A list (table) of formation position offsets in VectorOffset3D. The offsets are in subordinate order, i.e. unit promotion order (vs. formation promotion order). If the formation name is not found in the formation definitions, this table will have no entries.
2. A index (number) into the returned table that indicates which position is the leader, i.e. has the lowest formation promotion ID. Normally the first offset in the list, which is the first subordinate, will have the lowest formation promotion ID and that ID will be 0, but this does not have to be the case.

getFormationPromotionOrder (formationName)

Returns a list of integers, which are the promotion IDs in the formation entry, ordered by subordinate.

Parameters:

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

Return value:

A list (table) of integers representing promotion IDs, in subordinate order.

getFormationSubFormations (formationName)

Gets the names of the formations of the subordinates when this unit is in the given formation.

Parameters:

• formationName: (string) Name of this unit's formation.

Return value:

(table) List of formation names (strings) of the subordinates, in the unit subordinate order.

getGlobalId ()

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

Return value:

The global identifier of the entity (string)

getGroundAltitude (latitude, longitude)

Gets the ground altitude at the objects location.

If this point on the terrain is ground, then the value will be the same as that returned by getTerrainAltitude. However, if the terrain is water, then this function will return the altitude of the sea floor instead of the altitude of the water surface.
The function returns a second value, a boolean, that is true if this point has water over the ground.
It is possible that for an arbitrary location, the terrain data for that location is not available in the simulation, and has to be paged in. In this situation, the altitude data is not valid. Therefore, this function returns a third value that is a boolean indicating if the altitude result is valid.

Parameters:

• latitude:
• longitude:

Return values:

1. Number indicating the altitude of the terrain in meters.
2. Boolean indicating whether there is water on top of the ground.
3. Boolean that is true if the altitude (and surface) data is valid.

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, using physical world. 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 (includingDestroyedSubordinates)

Retrieve the location of this entity.

Parameters:

• includingDestroyedSubordinates: Optional, default is false. If true, and this is a unit, include the destroyed subordinates in calculation of central location. (default false)

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 if the SimObject is currently in an invalid state, the object's last known UUID will be returned instead.

Return value:

The name of the entity (string)

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}}

getPartExtension (part)

Parameters:

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

Return value:

Returns the up extension value for the specified part.

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)

Returns pitch in radians

Parameters:

• part: The articulated part number to return the topographic pitch for.
• includingParent: 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.

getSubordinateFunction (subordinate)

Get the function for the given subordinate of this unit.

Parameters:

• subordinate: A SimObject; one of the subordinates of this unit.

Return value:

A string, the function name.

getSubordinateFunctions ()

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

Return value:

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

getSubordinates (vrfSimulatedOnly)

Retrieve the SimObjects immediately subordinate to this entity.
See also getCapableSubordinates, getAllSubordinates and getAllCapableSubordinates.
Note that this function should not be called in the global section of a script (code run when the script is loaded), as the unit may not have its subordinates defined yet if the script is being loaded as part of a scenario load.

Parameters:

• vrfSimulatedOnly: (boolean) Optional. If this flag is true, only return VR-Forces simulated objects. Default value is false.

Return value:

Table of subordinate entities (SimObjects).

getSuperior ()

Retrieve the SimObject superior of this object. If the entity only has the Force as a superior, an invalid SimObject is returned.

Return value:

SimObject 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 (location)

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:

• location: A Location3D to test

Return value:

A boolean that is true if the location is inside this object's 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

setSubordinateFunction (subordinate, function)

Set the function for the given subordinate of this unit.

Parameters:

• subordinate: A SimObject; one of the subordinates of this unit.
• function: A string; the function of the subordinate.

Return value:

Nothing

setSubordinateFunctions (functionTable)

Set the "SubordinateFunctions" state property.

Parameters:

• functionTable: A table {{"subordinate" = DtScriptVrfObject, "function" = string}, {"subordinate" = DtScriptVrfObject, "function" = string}, ...}

Return value:

true if setStateProperties message was sent.