`this`

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

The 'this' object instance refers to the SimObject on which the script is running.
All SimObject functions are available on the this object. There are additional functions available only for the this object, listed in this module.

Function List

addResource (resourceName, currentAmount, fullAmount, bin)	Adds the new resource into the system given name, current, full amounts and bin.
addResource (resourceName, currentAmount, fullAmount, bin)	Adds the new resource into the system given name, current, full amounts and bin.
attachToParent (parent)	If parent is valid, immediately attach to that parent at the current position (embark)
canFireAt (location)	Determine if object can fire at specified location given current rules of engagement (checks whether the entity is under fire if necessary, and if the location is in the assigned engagement zone, if necessary).
changeAttachment (parentUUID)	Sets the parent of this object.
clearAssignedTransport (parent)	Sets state property "AssignedTransport" to DtUUID::nullUUID();
clearLastDetonation ()	If interest in detonations has previously been registered clears the last detonation received
depleteResource (resourceName, bin amount, bin, amount)	Removes from the current amount the specified resource amount from the named resource.
depleteResource (resourceName, bin amount, bin, amount)	Removes from the current amount the specified resource amount from the named resource.
getAllContacts ()	This function gets a table of all entities from this entity's contact list.
getAllHostileContacts ()	This function gets a table of non-destroyed, detected, hostile entities from this entity's contact list.
getAllHostileContacts ()	This function gets a table of non-destroyed, detected, hostile entities from this entity's contact list.
getContactInfo (otherEntity)	Returns the contact information that this entity has for the specified entity.
getContacts (typeFilters, flags)	This function gets a table of all objects from this entity's contact list that match the given entity type filters.
getContactsWithFilter (typeFilters, observedOnly, aliveOnly)	This function gets a table of all objects from this entity's contact list that match the given entity type filters.
getCurrentFormationName ()
getEmbeddedEntitiesCapableOf (taskSetName)	Returns a list of Embedded Entity names available to this object that are capable of the given task/set,
getEmbeddedEntitiesOfType (typeString)	Returns a list of Embedded Entity names available to this object matching the given typeString,
getEmbeddedEntityNames ()	Returns the complete list of Embedded Entity names available to this object.
getEmbeddedEntityStatus (eeName)	Returns the deployment status of the Embedded Entity with the given name.
getFormationExtent ()	Gets the size of the current formation, given the current subordinates.
getHostileContactsWithFilter ()	calls getContactsWithFilterObservedAliveHostile() passing in param aliveOnly and defaulting hostileOnly to true
getInternalStateProperty (context, propertyName)	Gets the value or list of field values for the given named internal state property.
getInternalStatePropertyListItem (context, propertyName, keyValues)	Gets value for a single item in an internal state property which is a list of items.
getInternalStatePropertyListItemByIndex (context, propertyName, index)	Gets value for a single item in an internal state property which is a list of items.
getInternalStatePropertyMapItem (context, propertyName, keyValue)	Gets the value for a single item in an internal state property which is a map.
getLastDetonation ()	If interest in detonations has previously been registered via the this:registerDetonationInterest() function, this function will return the munition type and location of the detonation.
getLastDetonationInformation ()	If interest in detonations has previously been registered via the this:registerDetonationInterest() function, this function will return the the Detonation object that represents that detonation.
getLastFire ()	If interest in fires has previously been registered via the registerFireInterest() function, this function will return the munition type and location of the fire.
getMunitionType (resourceName)	If resource is a munition, returns the entity type of that munition else returns an empty string.
getNavigationEnabled ()	Retrieves whether or not navigation by Gameware (in a navigation area) is enabled for this entity.
getNonLethalDamageEffect ()	Provides the non lethal damage type of the entity.
getNotifyLevel ()	Returns the current rules of notify level.
getOrderedSpeed ()	Returns the current ordered speed of the entity in m/s.
getResourceAmounts (resource, bin)	Retrieve the current and full amount of the named resource from bin 0.
getResourceAmounts (resource, bin)	Retrieve the current and full amount of the named resource from bin 0.
getResourceNames (bin)	Retrieve the current resources on the supplied entity in the specified bin
getResourceNames (bin)	Retrieve the current resources on the supplied entity in the specified bin
getResourceTypeFromName (resource)	Return the resoure type from the given name.
getRulesOfEngagement ()	Returns the current rules of engagement.
getSimObjectByEmbeddedEntityName (eeName)	Returns the DtScriptVrfObject corresponding to the given Embedded Entity name.
getSubordinateFormation ()	Get the formation positions that all of the current subordinates should be in.
getSuppressionLevel ()	Provides the suppression level of the entity.
getSystem (systemName)	Gets the component system indicated by systemName.
getSystemCategory (systemName)	Gets the "category" of the system, e.g.
getSystemNames ()	Gets a list of names of the systems available on this entity.
getTargetPriorityList ()	Returns the target priority list that this entity has.
getWeaponInfo (weaponId)
getWeaponInfoList ()
isCapableOfTask (taskName)	Returns true if the simulated object is capable of performing the task.
isInSectorOfResponsibility (target)
isOnTopOf (parent, distance)	If parent is valid, returns true if this entity is within the outline of and within distance above that entity.
isTargetAllowedByRulesOfEngagement (target)
isUnderFire ()	Returns true if entity is under fire.
missileTarget ()	Returns this entity's target entity.
registerDetonationInterest (range, munitionType)	This function registers interest in detonations that occur within the specified range of this object with the specified munition type.
registerFireInterest (range, munitionType)	This function registers interest in fires that occur within the specified range of this object with the specified munition type.
removeResource (resourceName, bin)	Removes the named resource from the system specified.
removeResource (resourceName, bin)	Removes the named resource from the system specified.
replenishResource (resourceName, amount, bin)	Add from the current amount the specified resource amount from the named resource.
replenishResource (resourceName, amount, bin)	Add from the current amount the specified resource amount from the named resource.
setAssignedTransport (parent)	Sets state property "AssignedTransport"
setDestroyed (destroyed)	Sets the damage state of this entity to destroyed or undamaged.
setExtendedData (key, data)	VR-Forces SimObjects may contain extended data, encoded as key/value pairs of strings, that is published to the network.
setExtendedLabel (index, label)	Sets the entities extended label to the supplied label at the given index.
setHeading (heading)	Sets the heading of this entity.
setInternalStateProperty (context, propertyName, propertyValue, addIfNotFound)	Sets the field values for the given named internal property.
setInternalStatePropertyListItem (context, propertyName, keyValues, itemValue)	Sets the value for a single item in an internal state property which is a list.
setInternalStatePropertyListItemByIndex (context, propertyName, index, itemValue)	Sets the field values for a single item in an internal state property which is a list of structures.
setInternalStatePropertyMapItem (context, propertyName, keyValue, itemValue)	Sets the value for a single item in a state property which is a map.
setLabel (label)	Sets the entities label to the supplied label.
setLocation3D (location)	Sets the location of this entity.
setNavigationEnabled (enabled)	For human entities only: Sets whether or not to allow Gameware navigation in navigation areas.
setOperationInProgress (operation, flag)	This function is used to set special "in progress" flags in the simulation engine.
setPitch (pitch)	Sets the pitch of this entity.
setRulesOfEngagement (rule)	Set how the object is to engage hostile objects
setStateProperty (propertyName, propertyValue, addIfNotFound)	Sets the field values for the given named property.
setStatePropertyListItem (propertyName, keyValues, itemValue)	Sets the value for a single item in a state property which is a list.
setStatePropertyListItemByIndex (propertyName, index, itemValue)	Sets the field values for a single item in a state property which is a list of structures.
setStatePropertyMapItem (propertyName, keyValue, itemValue)	Sets the value for a single item in a state property which is a map.
targetPriority ()	Returns the target priority that this entity has for the specified entity.
targetSignature (target, domain)	This function computes the normalized sensor signature of the target entity in the given domain, as seen by this entity.
updateStateAndParameterProperties ()	If this is a pseudo aggregate will update state and parameter properties in the state repository given the composition of the leaf nodes and their current values
userTarget ()	Returns the user target set using Set Target as a ScriptVrfObject

Functions

addResource (resourceName, currentAmount, fullAmount, bin)

Adds the new resource into the system given name, current, full amounts and bin. The resource is specified by its DIS Enumeration

Parameters:

resourceName: The DIS Enumeration of the resource
currentAmount: The current amount (number). Will be bounded by full amount
fullAmount: The full amount (number).
bin: Bin to add resourcee to

Return value:

Returns true if resource successfully added

addResource (resourceName, currentAmount, fullAmount, bin)

Adds the new resource into the system given name, current, full amounts and bin. The resource is specified by its DIS Enumeration

Parameters:

resourceName: The DIS Enumeration of the resource
currentAmount: The current amount (number). Will be bounded by full amount
fullAmount: The full amount (number).
bin: Bin to add resourcee to

Return value:

Returns true if resource successfully added

attachToParent (parent)

If parent is valid, immediately attach to that parent at the current position (embark)

Parameters:

parent: parent to attach to

canFireAt (location)

Determine if object can fire at specified location given current rules of engagement (checks whether the entity is under fire if necessary, and if the location is in the assigned engagement zone, if necessary).

Parameters:

location: the location to check.

Return value:

whether this entity can fire at a location given the rules of engagement.

changeAttachment (parentUUID)

Sets the parent of this object. If parentUUID is empty and the object is currently attached, will detach the object If attaching, object is placed at center of parent.

Parameters:

parentUUID: New parent's UUID

clearAssignedTransport (parent)

Sets state property "AssignedTransport" to DtUUID::nullUUID();

Parameters:

parent: parent to attach to

clearLastDetonation ()

If interest in detonations has previously been registered clears the last detonation received

depleteResource (resourceName, bin amount, bin, amount)

Removes from the current amount the specified resource amount from the named resource. The resource is specified as resource type. The resource will be removed from the specified bin

Parameters:

resourceName: Resource tyoe of the resource to get the amount for (string).
bin amount:
bin: Bin to use
amount: The amount of resource to deplete (number).

depleteResource (resourceName, bin amount, bin, amount)

Removes from the current amount the specified resource amount from the named resource. The resource is specified as resource type. The resource will be removed from the specified bin

Parameters:

resourceName: Resource tyoe of the resource to get the amount for (string).
bin amount:
bin: Bin to use
amount: The amount of resource to deplete (number).

getAllContacts ()

This function gets a table of all entities from this entity's contact list. These are entities that have been detected by sensors or added through spot reports. They may be of any force, including unknown, and may be at any detection level (but always greater than 0, which is not-detected).

Return value:

A table (list) of SimObjects.

getAllHostileContacts ()

This function gets a table of non-destroyed, detected, hostile entities from this entity's contact list. These are entities that have been detected by sensors or added through spot reports.

Return value:

A table (list) of SimObjects.

getAllHostileContacts ()

This function gets a table of non-destroyed, detected, hostile entities from this entity's contact list. These are entities that have been detected by sensors or added through spot reports.

Return value:

A table (list) of SimObjects.

getContactInfo (otherEntity)

Returns the contact information that this entity has for the specified entity. In many cases, an entity may not have full information about another entity it has detected. The contact information represents what this entity knows about the specified entity.

Parameters:

otherEntity: SimObject representing the entity we are viewing.

Usage:

contactInfoStruct = this:getContactInfo(otherEntity)

Return value:

getContacts (typeFilters, flags)

This function gets a table of all objects from this entity's contact list that match the given entity type filters. These are objects that have been detected by sensors or added through spot reports. If only objects that have been directly observed from sensors are desired, set observedOnly to true. The returned objects may be of any force, including unknown, and may be at any detection level.
Important: observedOnly, aliveOnly, and hostileOnly are required

Parameters:

typeFilters: A table of strings, defining a list of entity types to include.
flags: A lua table of boolean flags, each indexed by a name, such as: {observedOnly=true, aliveOnly=true, hostileOnly=true, currentlyDetectedOnly=true}

Return value:

A table (list) of SimObjects.

getContactsWithFilter (typeFilters, observedOnly, aliveOnly)

This function gets a table of all objects from this entity's contact list that match the given entity type filters. These are objects that have been detected by sensors or added through spot reports. If only objects that have been directly observed from sensors are desired, set observedOnly to true. The returned objects may be of any force, including unknown, and may be at any detection level.
Important: the observedOnly and aliveOnly parameters must either both be included, or both omitted.

Parameters:

typeFilters: A table of strings, defining a list of entity types to include.
observedOnly: (optional, with aliveOnly) A boolean indicating the function should only return objects that have been directly observed by this entity.
aliveOnly: (optional, with observedOnly) A boolean indicating that only non-destroyed objects should be returned.

Return value:

A table (list) of SimObjects.

getCurrentFormationName ()

Return value:

A string that is the name of the active formation.

getEmbeddedEntitiesCapableOf (taskSetName)

Returns a list of Embedded Entity names available to this object that are capable of the given task/set,

Parameters:

taskSetName: The string identifier of any task or set. (e.g. "turn-to-heading" or "set-destroy")

Usage:

ees = this:getEmbeddedEntitiesCapableOf("vertical-landing-task")

Return value:

A lua array(table) containing Embedded Entity names

getEmbeddedEntitiesOfType (typeString)

Returns a list of Embedded Entity names available to this object matching the given typeString,

Parameters:

typeString: A string representation of the seven digit DIS entity type enumeration. (e.g. "1:2:-1:-1:-1:-1:-1")

Usage:

ees = this:getEmbeddedEntitiesOfType("1:2:-1:-1:-1:-1:-1")

Return value:

A lua array(table) containing Embedded Entity names

getEmbeddedEntityNames ()

Returns the complete list of Embedded Entity names available to this object.

Usage:

all_ees = this:getEmbeddedEntityNames()

Return value:

A lua array(table) containing Embedded Entity names

getEmbeddedEntityStatus (eeName)

Returns the deployment status of the Embedded Entity with the given name. Return values are one of "recovered", "deleted", "destroyed", "deployed", and "unknown". "unknown" is returned if the given Embedded Entity is not available (configured) on this object, or if the given entity has not been deployed.

Parameters:

eeName: The name of an Embedded Entity available to this object.

Usage:

status = this:getEmbeddedEntityStatus("Seahawk Alpha")

Return value:

String representing the Embedded Entity's current deployment status.

getFormationExtent ()

Gets the size of the current formation, given the current subordinates.

Return value:

VectorOffset3D whose values indicate the size of the formation.

getHostileContactsWithFilter ()

calls getContactsWithFilterObservedAliveHostile() passing in param aliveOnly and defaulting hostileOnly to true

getInternalStateProperty (context, propertyName)

Gets the value or list of field values for the given named internal state property. Very similar to getStateProperty(), however this is the recommended function for internal state properties as it supports contexts.

Parameters:

context: The name of the context for this property. Helps prevent property name collisions.
propertyName: The name of the property to be retrieved.

Usage:

propertyFieldValues = this:getInternalStateProperty(context, propertyName)

Return value:

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

getInternalStatePropertyListItem (context, propertyName, keyValues)

Gets value for a single item in an internal state property which is a list of items. Rather than return the entire list, as getInternalStateProperty() would, the first entry found which matches the values specified in keyValues is returned. Very similar to getStatePropertyListItem(), however this is the recommended function for internal state properties as it supports contexts.

Parameters:

context: The name of the context for this property. Helps prevent property name collisions.
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 a 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:getInternalStatePropertyListItem(context, propertyName, { KeyField1Name = KeyField1Value, KeyField2Name = KeyField2Value })

listItem, index = this:getInternalStatePropertyListItem(context, propertyName, valueOfItemToFind)

Return values:

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.
The index of the item in the list.

getInternalStatePropertyListItemByIndex (context, propertyName, index)

Gets value for a single item in an internal state property which is a list of items. Rather than return the entire list, as getInternalStateProperty() would, returns the entry at the specified index (starting at index 1). Very similar to getStatePropertyListItemByIndex(), however this is the recommended function for internal state properties as it supports contexts.

Parameters:

context: The name of the context for this property. Helps prevent property name collisions.
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:getInternalStatePropertyListItemByIndex(context, 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.

getInternalStatePropertyMapItem (context, propertyName, keyValue)

Gets the value for a single item in an internal state property which is a map. Rather than return the entire map, as getInternalStateProperty() would, the entry matching the value specified in keyValue is returned. Very similar to getStatePropertyMapItem(), however this is the recommended function for internal state properties as it supports contexts.

Parameters:

context: The name of the context for this property. Helps prevent property name collisions.
propertyName: The name of the map property to be searched.
keyValue: The key value of the map item to be updated.

Usage:

mapItem = this:getInternalStatePropertyMapItem(context, 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.

getLastDetonation ()

If interest in detonations has previously been registered via the this:registerDetonationInterest() function, this function will return the munition type and location of the detonation.

Usage:

wasDetonationReceived, munitionType, location = this:getLastDetonation()

Return values:

(boolean) True if a detonation has been received since the last call to this function.
(string) Munition entity type, as a colon delimited type string (e.g. "2:1:...").
(Location3D) Location of the detonation.

getLastDetonationInformation ()

If interest in detonations has previously been registered via the this:registerDetonationInterest() function, this function will return the the Detonation object that represents that detonation.

Usage:

wasDetonationReceived, detonationInfo = this:getLastDetonationInformation()

Return values:

(boolean) True if a detonation has been received since the last call to this function.
(Detonation) An object with methods that provide information about the detonation such as detonation result. See Detonation luadoc module.

getLastFire ()

If interest in fires has previously been registered via the registerFireInterest() function, this function will return the munition type and location of the fire.

Usage:

fireReceived, munitionType, location = this:getLastFire()

Return values:

Whether or not a fire has been received since the last call to this function.
Munition entity type, as a colon delimited string.
Location of the fire, as a Location3D.

getMunitionType (resourceName)

If resource is a munition, returns the entity type of that munition else returns an empty string. The resource is specified as the link of systems the resource is in (each system separated by a |) and then the resource name, for example Movement|fuel.

Parameters:

resourceName: Resource name of the resource to get the amount for (string).

getNavigationEnabled ()

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

Return value:

True if Gameware navigation is enabled, false if not

getNonLethalDamageEffect ()

Provides the non lethal damage type of the entity. Default is an empty value

getNotifyLevel ()

Returns the current rules of notify level.

Return value:

An integer giving the current notify level: ! DtNlFatal = 0, ! DtNlWarn = 1, ! DtNlInfo = 2, ! DtNlVerbose = 3, ! DtNlDebug = 4

getOrderedSpeed ()

Returns the current ordered speed of the entity in m/s.

getResourceAmounts (resource, bin)

Retrieve the current and full amount of the named resource from bin 0. The resource is specified as the link of systems the resource is in (each system separated by a |) and then the resource name, for example Movement|fuel.

Parameters:

resource: Resource name of the resource to get the amount for (string).
bin: Bin to get the resource from

Usage:

current, full = this:getResourceAmounts(, bin)

Return values:

The current amount of the resource (number).
The full amount of the resource (number).

getResourceAmounts (resource, bin)

Parameters:

resource: Resource name of the resource to get the amount for (string).
bin: Bin to get the resource from

Usage:

current, full = this:getResourceAmounts(, bin)

Return values:

The current amount of the resource (number).
The full amount of the resource (number).

getResourceNames (bin)

Retrieve the current resources on the supplied entity in the specified bin

Parameters:

bin: is the bin number to look in

Return value:

Returns the table of resources (as strings) on this entity.

getResourceNames (bin)

Retrieve the current resources on the supplied entity in the specified bin

Parameters:

bin: is the bin number to look in

Return value:

Returns the table of resources (as strings) on this entity.

getResourceTypeFromName (resource)

Return the resoure type from the given name. If the name is already a well formed resource type, will return that

Parameters:

resource: (string)

Return value:

The resoure type from the given name. If the name is already a well formed resource type, will return that.

getRulesOfEngagement ()

Returns the current rules of engagement. The engagement rules available in VR-Forces are \93fire-at-will\94, \93fire-when-fired-upon\94, "fire-when-in-engagement-zone", \93hold-fire\94, and \93fire-if-on-target-priority-list\94.

Return value:

A string indicating the current rules of engagement.

getSimObjectByEmbeddedEntityName (eeName)

Returns the DtScriptVrfObject corresponding to the given Embedded Entity name. isValid() will return false on the returned object if there is no corresponding DtScriptVrfObject, either because it is recovered or the Embedded Entity is not available(configured) on this object.

Parameters:

eeName: The name of an Embedded Entity available to this object.

Usage:

object = this:getSimObjectByEmbeddedEntityName("RHIB Alpha")

Return value:

SimObject instance corresponding to the given Embedded Entity name.

getSubordinateFormation ()

Get the formation positions that all of the current subordinates should be in.

Return values:

Table indexed by subordinate (SimObjects). Each table entry is a table: {"leaderOffset" = VectorOffset3D, "unitOffset" = VectorOffset3D, "promotionID" = integer, "subFormation" = string}.
LeaderOffset is the offset from the formation lead position to this position, oriented to the formation direction.
UnitOffset is the offset from the center of mass of the formation (with the subordinates in this table), with each subordinate given equal weight in calculating the center of mass.
PromotionID is an index indicating the order of the position in the formation, with 0 being the "lead position" in the formation as defined in entity parameters. Other formation positions have unique indices > 0. (The Offset for the lead position is (0,0,0).)
SubFormation is the name of the formation the subordinate should be in, if the subordinate is itself a unit.
Note that it is possible, if the unit is under-strength, for none of the subordinates returned to have an Order of 0; in this case the Offsets returned will be relative to the position with the lowest order. Note that the returned table is indexed by a USER_DATA type, and this
Formation leader (SimObject). This is the leader subordinate, i.e. the one assigned to the lowest Order position.

getSuppressionLevel ()

Provides the suppression level of the entity. This is an integer in the range 0-3. 0 indicates that the entity is not suppressed, and 1-3 are considered suppressed.

Return value:

Level, a number from 0-3.

getSystem (systemName)

Gets the component system indicated by systemName.
Note that the top level system is always called "base". This system has most other capabilities attached as subsystems underneath it (movement, damage, etc.). However some components may be directly part of "base", and so that system may have attributes as well. Note: This function only works on sim objects that are local to this sim engine. There is no way of knowing what systems are available to remote sim objects. When using more than one sim engine, it is recommended that this function is not used except for the sim object on which the script is being run.

Parameters:

systemName: A string naming the system. This is the name used in the Entity Editor to identify the system. The "reader-writer" names in the SMS data files may also be used, in particular names like "movement" or "damage".

Return value:

A component system. If the lookup was unsuccessful, the return value will be nil.

getSystemCategory (systemName)

Gets the "category" of the system, e.g. weapon, sensor, movement, damage, or other.

Parameters:

systemName: String, the name of the system. The display name, i.e. the same name that is returned by getSystemName or getSystemNames.

Return value:

String, the category of the system. Note that any "-1" extensions are removed.

getSystemNames ()

Gets a list of names of the systems available on this entity. These names can be used in lookupSystem to get the system object. Note: This function only works on sim objects that are local to this sim engine. There is no way of knowing what systems are available to remote sim objects. When using more than one sim engine, it is recommended that this function is not used except for the sim object on which the script is being run.

Return value:

A list (table) of system names.

getTargetPriorityList ()

Returns the target priority list that this entity has. In many cases an entity may not have anything on this list.

Usage:

targetPriorityList = this:getTargetPriorityList()

Return value:

getWeaponInfo (weaponId)

Parameters:

weaponId: [String] The weapon ID for the weapon to get info on.

Return value:

A WeaponInfo class for a specific weapon ID on this entity. Returns nil if weapon is not found.

getWeaponInfoList ()

Return value:

A table of weapon information for this entity. The index of the table is weapon ID strings, and the contents are WeaponInfo classes.

isCapableOfTask (taskName)

Returns true if the simulated object is capable of performing the task.

Parameters:

taskName: String, the name of the task to perform.

Return value:

boolean, true if task-capable

isInSectorOfResponsibility (target)

Parameters:

target: [SimObject] The target object to test.

Return value:

True if the specified target object is within the currently defined sector of responsibility for this entity.

isOnTopOf (parent, distance)

If parent is valid, returns true if this entity is within the outline of and within distance above that entity.

Parameters:

parent: object to check
distance: Optional distance to check (Default distance is the entities bounding volume half height Z + .5 meters)

Return value:

True if the entity is on top of the target entity within distance

isTargetAllowedByRulesOfEngagement (target)

Parameters:

target: [SimObject] The target object to test.

Return value:

True if the specified target object is allowed to be fired on by the current rules of engagement.

isUnderFire ()

Returns true if entity is under fire. An entity is under fire if it was the target of a fire interaction, or if there was a detonation within a certain distance within a certain time. The distance and time parameters are configuration parameters in the entity's under-fire sensor.

Return value:

True if the entity is under fire.

missileTarget ()

Returns this entity's target entity. Only applicable when this is a missile entity.

Usage:

missileTarget = this:getMissileTarget()
 if missileTarget:isValid() then...

Return value:

:isValid() is false.

registerDetonationInterest (range, munitionType)

This function registers interest in detonations that occur within the specified range of this object with the specified munition type. This function may be called multiple times to register interest in different munition types.
The script maintains a variable internally that records the last relevant detonation object received by the script. This object can be accessed through the getLastDetonation and getLastDetonationInformation functions. These functions do not change the variable, i.e successive calls to them will return the same information if a new detonation is not received between calls or clearLastDetonation is not called. If more than one detonation is received by the script between calls to getLastDetonation, the earlier detonations will not be available. Only the latest detonation received is available.

Parameters:

range: The range, in meters, of the area of interest.
munitionType: Munition entity type, as a colon delimited string.

Return value:

Returns true if the registration was successful.

registerFireInterest (range, munitionType)

This function registers interest in fires that occur within the specified range of this object with the specified munition type. This function may be called multiple times to register interest in different munition types.

Parameters:

range: The range, in meters, of the area of interest.
munitionType: Munition entity type, as a colon delimited string.

Return value:

Returns true if the registration was successful.

removeResource (resourceName, bin)

Removes the named resource from the system specified. The resource is specified a DIS Enumeration. The resource wil be removed from the specified bin

Parameters:

resourceName: The name of the resource to remove (string)
bin: The bin to remove the resource rom

removeResource (resourceName, bin)

Removes the named resource from the system specified. The resource is specified a DIS Enumeration. The resource wil be removed from the specified bin

Parameters:

resourceName: The name of the resource to remove (string)
bin: The bin to remove the resource rom

replenishResource (resourceName, amount, bin)

Add from the current amount the specified resource amount from the named resource. The resource is specified as resource type. The resource will be removed from the specified bin. The resource amount will not go above the full amount

Parameters:

resourceName: resource DIS Enumeration of the resource to get the amount for (string).
amount: the amount of resource to replenish (number).
bin: The bin to remove the resource from

replenishResource (resourceName, amount, bin)

Parameters:

resourceName: resource DIS Enumeration of the resource to get the amount for (string).
amount: the amount of resource to replenish (number).
bin: The bin to remove the resource from

setAssignedTransport (parent)

Sets state property "AssignedTransport"

Parameters:

parent: parent to attach to

setDestroyed (destroyed)

Sets the damage state of this entity to destroyed or undamaged.

Parameters:

destroyed: If true, damage state will be set to destroyed. Otherwise it will be undamaged.

setExtendedData (key, data)

VR-Forces SimObjects may contain extended data, encoded as key/value pairs of strings, that is published to the network. Updates the extended data with the given key.

Parameters:

key: The unique key for the data to be updated.
data: The new value for the extended data.

setExtendedLabel (index, label)

Sets the entities extended label to the supplied label at the given index. if the index is not valid an exception will be thrown. If entity is not valid an exception will be thrown for an invalid state

Parameters:

index: Label index to set
label: The label to set

setHeading (heading)

Sets the heading of this entity. Changes ground truth (doesn't just request a controller turn the entity). Usually an entity has an actuator running that sets the heading as it does kinematic state updates, so use this function with care.

Parameters:

heading: New heading of entity, in radians. Clockwise from north.

setInternalStateProperty (context, propertyName, propertyValue, addIfNotFound)

Sets the field values for the given named internal property. Very similar to setStateProperty, however this is the recommended function for internal state properties as it supports contexts.

Parameters:

context: The name of the context for this property. Helps prevent property name collisions.
propertyName: The name of the property to be set.
propertyValue: The value to be set. May be a simple data type or a table containing a list of values, or a table containing the names of the fields to be set and their values. Type must match the existing property definition.
addIfNotFound: Optional, assumed false if not specified. If true and the state property cannot be found, adds it. When adding a new, previously undefined state property, some assumptions must be made and the full range state property types are not supported. The following Lua types are supported and will be mapped to state property types as indicated.
- string -> DtRwString
- number -> DtRwReal
- boolean -> DtRwBoolean
- SimObject -> DtRwString (object's UUID)
- table -> DtRwStructure (if items have different types)
DtRwList (if items have numeric, increasing keys)
DtRwMap

Usage:

wasSet = this:setInternalStateProperty(context, propertyName, propertyValue)

wasSet = this:setInternalStateProperty(context, propertyName, propertyValue, addIfNotFound)

Return value:

Returns true if the property was able to be set.

setInternalStatePropertyListItem (context, propertyName, keyValues, itemValue)

Sets the value for a single item in an internal state property which is a list. Very similar to setStatePropertyListItem, however this is the recommended function for internal state properties as it supports contexts. Rather than set the entire list, as setInternalStateProperty() would, the first entry found which matches the value(s) specified in keyValues is updated with the new values specified in itemValues. If no matching entry is found, a new one is added.

Parameters:

context: The name of the context for this property. Helps prevent property name collisions.
propertyName: The name of the list property to be searched.
keyValues: Indicates what value(s) to look for when finding the item to set. 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 replaced with the new value. If no match is found, a new item will be added. 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 false.
itemValue: A table specifying the new value to be used for the item which matches the keyValues. If the items in the list are structures, itemValue will contain a table of the field names and values for each field to be updated. If a field is not listed, its current value will be maintained. If the items in the list are simple values, the itemValue should be a value of the same type.

Usage:

wasSet = this:setInternalStatePropertyListItem(context, propertyName, { KeyField1Name = KeyField1Value, KeyField2Name = KeyField2Value }, newFieldValues)

wasSet = this:setInternalStatePropertyListItem(context, propertyName, valueOfItemToReplace, newValue)

Return value:

True if the list item was able to be set.

setInternalStatePropertyListItemByIndex (context, propertyName, index, itemValue)

Sets the field values for a single item in an internal state property which is a list of structures. Very similar to setStatePropertyListItemByIndex, however this is the recommended function for internal state properties as it supports contexts. Rather than set the entire list, as setInternalStateProperty() would, the item at the specified index (starting at index 1) is updated. If the specified index is greater than the number of items in the list, the list will be extended to include enough entries to set the new item. Any items added in this way will be given the same value as the new entry.

Parameters:

context: The name of the context for this property. Helps prevent property name collisions.
propertyName: The name of the list property to be searched.
index: The index of the item in the list that should be updated.
itemValue: A table specifying the new value to be used for the item at the specified index. If the items in the list are structures, itemValue will contain a table of the field names and values for each field to be updated. If a field is not listed, its current value will be maintained. If the items in the list are simple values, the itemValue should be a value of the same type.

Usage:

wasSet = this:setInternalStatePropertyListItemByIndex(context, propertyName, index, newItemValue)

Return value:

True if the list item was able to be set.

setInternalStatePropertyMapItem (context, propertyName, keyValue, itemValue)

Sets the value for a single item in a state property which is a map. Very similar to setInternalStatePropertyMapItem, however this is the recommended function for internal state properties as it supports contexts. Rather than set the entire list, as setInternalStateProperty() would, the entry matching the key value specified is updated with the new value. If no matching entry is found, a new one is added.

Parameters:

context: The name of the context for this property. Helps prevent property name collisions.
propertyName: The name of the map property to be searched.
keyValue: The key value of the map item to be updated.
itemValue: The new value for the map item. Can be a single item for maps of simple data types, or table for maps containing structures or other complex data types. For structures, if a field in the structure is not listed, its current value will be maintained.

Usage:

wasSet = this:setInternalStatePropertyMapItem(context, propertyName, keyValue, newItemValue)

Return value:

True if the map item was able to be set.

setLabel (label)

Sets the entities label to the supplied label. If entity is not valid an exception will be thrown for an invalid state

Parameters:

label: The label to set

setLocation3D (location)

Sets the location of this entity. Changes ground truth (doesn't just request a controller drive the entity toward the location). Usually an entity has an actuator running that sets the location as it does kinematic state updates, so use this function with care.

Parameters:

location: New Location3D of entity.

setNavigationEnabled (enabled)

For human entities only: Sets whether or not to allow Gameware navigation in navigation areas. If this value is set to false the object will still be seen as an obstacle (if configured) in navigation areas.

Parameters:

enabled: Whether or not navigation is enabled

setOperationInProgress (operation, flag)

This function is used to set special "in progress" flags in the simulation engine. When the simulation has one or more operations in progress, it sends a message to the GUI so that an animated indicator can be displayed for the user. Test this object with isValid() first to make sure the object is valid. Also, for every operation turned on it must also be turned off when complete else the GUI will continue to show the operation in progress.

Parameters:

operation: A bit map (integer) corresponding to the operation. These are defined in the Operations table in the vrfutil module.
flag: Boolean True to set the operation in progress, and false to clear the operation flag.

setPitch (pitch)

Sets the pitch of this entity. Does not do any special placement -- simply changes the pitch. Clockwise from west.

Parameters:

pitch:

setRulesOfEngagement (rule)

Set how the object is to engage hostile objects

Parameters:

rule: A string encoding the ROE: "fire-at-will", "fire-when-fired-upon", "fire-when-in-engagement-zone", "fire-only-if-on-target-priority-list", or "hold-fire".

setStateProperty (propertyName, propertyValue, addIfNotFound)

Sets the field values for the given named property. Will work for both internal and external state properties.

Parameters:

propertyName: The name of the property to be set.
propertyValue: The value to be set. May be a simple data type or a table containing a list of values, or a table containing the names of the fields to be set and their values. Type must match the existing property definition.
addIfNotFound: Optional, assumed false if not specified. If true and the state property cannot be found, adds it. When adding a new, previously undefined state property, some assumptions must be made and the full range state property types are not supported. The following Lua types are supported and will be mapped to state property types as indicated.
- string -> DtRwString
- number -> DtRwReal
- boolean -> DtRwBoolean
- SimObject -> DtRwString (object's UUID)
- table -> DtRwStructure (if items have different types)
DtRwList (if items have numeric, increasing keys)
DtRwMap

Usage:

wasSet = this:setStateProperty(propertyName, propertyValue)

wasSet = this:setStateProperty(propertyName, propertyValue, addIfNotFound)

Return value:

Returns true if the property was able to be set.

setStatePropertyListItem (propertyName, keyValues, itemValue)

Sets the value for a single item in a state property which is a list. Works for both internal and external state properties. Rather than set the entire list, as setStateProperty() would, the first entry found which matches the value(s) specified in keyValues is updated with the new values specified in itemValues. If no matching entry is found, a new one is added.

Parameters:

propertyName: The name of the list property to be searched.
keyValues: Indicates what value(s) to look for when finding the item to set. 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 replaced with the new value. If no match is found, a new item will be added. 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 false.
itemValue: A table specifying the new value to be used for the item which matches the keyValues. If the items in the list are structures, itemValue will contain a table of the field names and values for each field to be updated. If a field is not listed, its current value will be maintained. If the items in the list are simple values, the itemValue should be a value of the same type.

Usage:

wasSet = this:setStatePropertyListItem(propertyName, { KeyField1Name = KeyField1Value, KeyField2Name = KeyField2Value }, newFieldValues)

wasSet = this:setStatePropertyListItem(propertyName, valueOfItemToReplace, newValue)

Return value:

True if the list item was able to be set.

setStatePropertyListItemByIndex (propertyName, index, itemValue)

Sets the field values for a single item in a state property which is a list of structures. Works for both internal and external properties. Rather than set the entire list, as setStateProperty() would, the item at the specified index (starting at index 1) is updated. If the specified index is greater than the number of items in the list, the list will be extended to include enough entries to set the new item. Any items added in this way will be given the same value as the new entry.

Parameters:

propertyName: The name of the list property to be searched.
index: The index of the item in the list that should be updated.
itemValue: A table specifying the new value to be used for the item at the specified index. If the items in the list are structures, itemValue will contain a table of the field names and values for each field to be updated. If a field is not listed, its current value will be maintained. If the items in the list are simple values, the itemValue should be a value of the same type.

Usage:

wasSet = this:setStatePropertyListItem(propertyName, index, newItemValue)

Return value:

True if the list item was able to be set.

setStatePropertyMapItem (propertyName, keyValue, itemValue)

Sets the value for a single item in a state property which is a map. Works for both internal and external properties. Rather than set the entire list, as setStateProperty() would, the entry matching the key value specified is updated with the new value. If no matching entry is found, a new one is added.

Parameters:

propertyName: The name of the map property to be searched.
keyValue: The key value of the map item to be updated.
itemValue: The new value for the map item. Can be a single item for maps of simple data types, or table for maps containing structures or other complex data types. For structures, if a field in the structure is not listed, its current value will be maintained.

Usage:

wasSet = this:setStatePropertyMapItem(propertyName, keyValue, newItemValue)

Return value:

True if the map item was able to be set.

targetPriority ()

Returns the target priority that this entity has for the specified entity. In many cases this entity may not have the other entity on its target priority list.

Usage:

targetPriority = this:getTargetPriorityList(otherEntity)

Return value:

targetSignature (target, domain)

This function computes the normalized sensor signature of the target entity in the given domain, as seen by this entity. The "normalized" signature is the raw sensor signature of the entity modified by the appropriate propagation functions, including a scaling for range. Thus if there are no attenuating factors in the environment, a target with a raw signature of S will have a normalized signature of 1.0 at a range of S km. Given that the default detection tables in VR-Forces only allow detection for normalized signatures >= 1.0, a signature of 1.0 generally indicates that the target is detectable.

If line of sight is relevant in this domain, then a blocked line of sight will result in a signature of 0. Weather and other factors may reduce the signature.

This function is valid to use even if this entity doesn't have a sensor in the given domain configured on it. In fact, the intent of this function is to allow scripts to pretend that a sensor is configured, even if that is not the case, for example for performance reasons.

Parameters:

target: The SimObject whose detectability is to be checked.
domain: A string defining the domain of the sensor. May be, for example, visual, radar, sonar, infrared, passive-sonar, active-sonar, emissions, or magnetic-anomaly-detection.

Return value:

number signifying the normalized signature.

updateStateAndParameterProperties ()

If this is a pseudo aggregate will update state and parameter properties in the state repository given the composition of the leaf nodes and their current values

userTarget ()

Returns the user target set using Set Target as a ScriptVrfObject

Usage:

userTarget = this:getUserTarget()

Return value:

:isValid() is false, that indicates no user target.

VR-Forces Lua Documentation

this

Function List

Functions

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Parameters:

Return value:

Parameters:

Parameters:

Parameters:

Parameters:

Return value:

Return value:

Return value:

Parameters:

Usage:

Return value:

Parameters:

Return value:

Parameters:

Return value:

Return value:

Parameters:

Usage:

Return value:

Parameters:

Usage:

Return value:

Usage:

Return value:

Parameters:

Usage:

Return value:

Return value:

Parameters:

Usage:

Return value:

Parameters:

Usage:

Return values:

Parameters:

Usage:

Return value:

Parameters:

Usage:

Return value:

Usage:

Return values:

Usage:

Return values:

Usage:

Return values:

Parameters:

Return value:

Return value:

Parameters:

Usage:

Return values:

Parameters:

Usage:

Return values:

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Return value:

Return value:

Parameters:

Usage:

Return value:

Return values:

Return value:

Parameters:

Return value:

Parameters:

`this`