VR-Forces 4.10 Lua Function Documentation

vrfutil

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

Vrfutil is a collection of tables and functions that provide useful capabilities and definitions to Lua scripts in VR-Forces. To use them, the script must start with 

	 require "vrfutil"

This line is included in new scripts by default.

The following general capabilities are provided:
  • Printing to the Entity Console
  • Entity type definitions. These all return strings of the form "n:n:n:n:n:n:n", where n is a number.
  • Appearance testing and setting.
  • Reactive task management
  • Identifying systems and resources on the entity.
  • Miscellaneous useful utilities

Function List

Appearance.BrakeLightsOn (appearance) Return boolean indicating whether the brake lights are on.
Appearance.DamageLevel (appearance) Return the damage number from appearance
Appearance.FirePowerKillOn (appearance) Return whether the object is fire power-killed.
Appearance.FlamingOn (appearance) Return a boolean indicating if the object is flaming.
Appearance.HeadLightsOn (appearance) Return boolean indicating whether the head lights are on.
Appearance.InteriorLightsOn (appearance) Return a boolean indicating whether interior lights are on.
Appearance.IsConcealed (appearance) Return boolean indicating whether the object is concealed.
Appearance.IsLandingGearExtended (appearance) Return boolean indicating whether the landing gear are extended.
Appearance.IsSmokeEmanating (appearance) Return a boolean indicating whether the object is smoking.
Appearance.LandingLightsOn (appearance) Return a boolean indicating whether landing lights are on.
Appearance.MobilityKillOn (appearance) Return whether the object is mobility-killed.
Appearance.PowerPlantStatusOn (appearance) Return boolean indicating whether the power plant is on.
Appearance.SetBrakeLightsOn (appearance, enable) Set appearance to indicate whether the brake lights are on.
Appearance.SetConcealed (appearance, enable) Set appearance to indicate whether the object is concealed.
Appearance.SetDamageLevel (appearance, damage) Set the appearance bits for damage based on the damage number
Appearance.SetFirePowerKill (appearance, enable) Set appearance to indicate that the object is fire power-killed.
Appearance.SetFlaming (appearance, enable) Set appearance to indicate whether or not the object is flaming.
Appearance.SetHeadLightsOn (appearance, enable) Set appearance to indicate whether the head lights are on.
Appearance.SetInteriorLights (appearance, enable) Set appearance to indicate that interior lights are on.
Appearance.SetLandingGearExtended (appearance, enable) Set appearance to indicate whether the landing gear are extended.
Appearance.SetLandingLights (appearance, enable) Set appearance to indicate whether landing lights are on.
Appearance.SetMobilityKill (appearance, enable) Set appearance to indicate that the object is mobility-killed.
Appearance.SetPowerPlantStatus (appearance, enable) Set appearance to indicate whether the power plant is on.
Appearance.SetSmokeEmanating (appearance, enable) Set appearance to indicate whether the object is smoking.
Appearance.SetSpotLights (appearance, enable) Set the spot lights on or off in the appearance.
Appearance.SetTailLightsOn (appearance, enable) Set appearance to indicate whether the tail lights are on.
Appearance.SpotLightsOn (appearance) Return a boolean indicating whether the spot lights are on.
Appearance.TailLightsOn (appearance) Return boolean indicating whether the tail lights are on.
DamageState.EnumToString (enum) Converts a damage state enumerated value into a string.
DamageState.StringToEnum (str) Converts a damage state string into an enumerated value.
EntityType.Aggregate () Returns an entity type string for a generic aggregate.
EntityType.AggregateAir () Returns an entity type string for the given type of aggregate.
EntityType.AggregateGround () Returns an entity type string for the given type of aggregate.
EntityType.AggregateSpace () Returns an entity type string for the given type of aggregate.
EntityType.AggregateSubsurface () Returns an entity type string for the given type of aggregate.
EntityType.AggregateSurface () Returns an entity type string for the given type of aggregate.
EntityType.Area () Returns an entity type string for an area control measure.
EntityType.ArealObject () Returns an entity type string for a generic area object.
EntityType.CulturalFeature () Returns an entity type string for a generic cultural feature.
EntityType.EngineeringArealObject () Returns an entity type string for a generic engineering area object.
EntityType.EngineeringFixedSizeArealObject () Returns an entity type string for a generic fixed size engineering area object.
EntityType.EngineeringLinearObject () Returns an entity type string for a generic engineering linear object.
EntityType.EngineeringPointObject () Returns an entity type string for a generic engineering point object.
EntityType.GetCategory (entityType) Returns the category field from the given entity type
EntityType.GetCountry (entityType) Returns the country field from the given entity type
EntityType.GetDomain (entityType) Returns the domain field from the given entity type
EntityType.GetExtra (entityType) Returns the extra field from the given entity type
EntityType.GetKind (entityType) Returns the kind field from the given entity type
EntityType.GetNthField (entityType, n) Returns the nth field in the entity type.
EntityType.GetSpecific (entityType) Returns the specific field from the given entity type
EntityType.GetSubcategory (entityType) Returns the subcategory field from the given entity type
EntityType.Lifeform () Returns an entity type string for a generic lifeform.
EntityType.LinearObject () Returns an entity type string for a generic linear object.
EntityType.Munition () Returns an entity type string for a generic munition.
EntityType.NbcArealObject () Returns an entity type string for a generic hazard area object.
EntityType.Obstacle () Returns an entity type string for an obstacle control measure.
EntityType.PhaseLine () Returns an entity type string for a phase line.
EntityType.Platform () Returns an entity type string for a generic platform.
EntityType.PlatformAir () Returns an entity type string for a generic air platform.
EntityType.PlatformLand () Returns an entity type string for a generic land platform.
EntityType.PlatformSpace () Returns an entity type string for a generic space platform.
EntityType.PlatformSubsurface () Returns an entity type string for a generic subsurface platform.
EntityType.PlatformSurface () Returns an entity type string for a generic surface platform.
EntityType.PointObject () Returns an entity type string for a generic point object.
EntityType.Route () Returns an entity type string for a route.
EntityType.SetCategory (entityType, val) Sets the category field in the entytType string with val.
EntityType.SetNthField (entityType, n, val) Returns a string which is the input entityType string with the nth field replaced by val.
EntityType.Waypoint () Returns an entity type string for a waypoint.
EntityType.Weather () Returns an entity type string for a local weather object.
LifeformPosture.EnumToString (enum) Converts a lifeform posture enumerated value into a string.
LifeformPosture.StringToEnum (str) Converts a lifeform posture string into an enumerated value.
Util.findResource (namePart) Finds a resource on this entity whose name contains the given string.
Util.findSystem (namePart) Finds a system on this entity whose name contains the given string.
Util.getSensorSystems () Gets a list of the sensor systems on this entity.
Util.getWeaponSystems () Gets a list of the weapon systems on this entity.
disableReaction (reactionName) Disables a reactive task on this entity.
enableReaction (reactionName, params) Enables a reactive task on this entity.
getFixedTaskParameter (attributeName, defaultValue) Looks up the given parameter name for this script as specified in a script-enable-controller-descriptor in a parameter file (e.g.
getReactionActive (reactionName) Gets whether or not a reaction is active on the current entity.
getReactionPriority (reactionName) Gets the priority of a particular reaction on the entity.
printDebug (...) Prints to the entity's Debug console.
printError (...) Prints to the entity's Error console.
printInfo (...) Prints to the entity's Info console.
printVerbose (...) Prints to the entity's Verbose console.
printWarn (...) Prints to the entity's Warn console.
roundToInt (num) Rounds a number to the nearest integer using normal rounding rules.
setReactionPriority (reactionName, newPriority) Changes the priority of a reactive task on this entity.
table.copy (t) A utility to copy tables.
table.find (t, value) Determines if the given value is in the table.
taskDone (taskId, quitIfError) Determine if a task or subtask is done, and handle errors.
vrfprint (printFcn, ...) New print function that prints to the VRF Object console instead of the sim engine console.

Table List

Appearance A table of functions to check and set the bits of an appearance value.
DamageState A table of functions to convert between damage state strings and the corresponding enumeration values.
EntityType A table of functions returning strings corresponding to entity types.
LifeformPosture A table of functions to convert between life form posture strings and the corresponding enumeration values.
Util A table of functions for getting systems (ComponentSystem) on the entity.


Functions

Appearance.BrakeLightsOn (appearance)
Return boolean indicating whether the brake lights are on.

Parameters:

  • appearance:
Appearance.DamageLevel (appearance)
Return the damage number from appearance

Parameters:

  • appearance:
Appearance.FirePowerKillOn (appearance)
Return whether the object is fire power-killed.

Parameters:

  • appearance:
Appearance.FlamingOn (appearance)
Return a boolean indicating if the object is flaming.

Parameters:

  • appearance:
Appearance.HeadLightsOn (appearance)
Return boolean indicating whether the head lights are on.

Parameters:

  • appearance:
Appearance.InteriorLightsOn (appearance)
Return a boolean indicating whether interior lights are on.

Parameters:

  • appearance:
Appearance.IsConcealed (appearance)
Return boolean indicating whether the object is concealed.

Parameters:

  • appearance:
Appearance.IsLandingGearExtended (appearance)
Return boolean indicating whether the landing gear are extended.

Parameters:

  • appearance:
Appearance.IsSmokeEmanating (appearance)
Return a boolean indicating whether the object is smoking.

Parameters:

  • appearance:
Appearance.LandingLightsOn (appearance)
Return a boolean indicating whether landing lights are on.

Parameters:

  • appearance:
Appearance.MobilityKillOn (appearance)
Return whether the object is mobility-killed.

Parameters:

  • appearance:
Appearance.PowerPlantStatusOn (appearance)
Return boolean indicating whether the power plant is on.

Parameters:

  • appearance:
Appearance.SetBrakeLightsOn (appearance, enable)
Set appearance to indicate whether the brake lights are on.

Parameters:

  • appearance:
  • enable:
Appearance.SetConcealed (appearance, enable)
Set appearance to indicate whether the object is concealed.

Parameters:

  • appearance:
  • enable:
Appearance.SetDamageLevel (appearance, damage)
Set the appearance bits for damage based on the damage number

Parameters:

  • appearance:
  • damage:
Appearance.SetFirePowerKill (appearance, enable)
Set appearance to indicate that the object is fire power-killed.

Parameters:

  • appearance:
  • enable:
Appearance.SetFlaming (appearance, enable)
Set appearance to indicate whether or not the object is flaming.

Parameters:

  • appearance:
  • enable:
Appearance.SetHeadLightsOn (appearance, enable)
Set appearance to indicate whether the head lights are on.

Parameters:

  • appearance:
  • enable:
Appearance.SetInteriorLights (appearance, enable)
Set appearance to indicate that interior lights are on.

Parameters:

  • appearance:
  • enable:
Appearance.SetLandingGearExtended (appearance, enable)
Set appearance to indicate whether the landing gear are extended.

Parameters:

  • appearance:
  • enable:
Appearance.SetLandingLights (appearance, enable)
Set appearance to indicate whether landing lights are on.

Parameters:

  • appearance:
  • enable:
Appearance.SetMobilityKill (appearance, enable)
Set appearance to indicate that the object is mobility-killed.

Parameters:

  • appearance:
  • enable:
Appearance.SetPowerPlantStatus (appearance, enable)
Set appearance to indicate whether the power plant is on.

Parameters:

  • appearance:
  • enable:
Appearance.SetSmokeEmanating (appearance, enable)
Set appearance to indicate whether the object is smoking.

Parameters:

  • appearance:
  • enable:
Appearance.SetSpotLights (appearance, enable)
Set the spot lights on or off in the appearance.

Parameters:

  • appearance:
  • enable:
Appearance.SetTailLightsOn (appearance, enable)
Set appearance to indicate whether the tail lights are on.

Parameters:

  • appearance:
  • enable:
Appearance.SpotLightsOn (appearance)
Return a boolean indicating whether the spot lights are on.

Parameters:

  • appearance:
Appearance.TailLightsOn (appearance)
Return boolean indicating whether the tail lights are on.

Parameters:

  • appearance:
DamageState.EnumToString (enum)
Converts a damage state enumerated value into a string.

Parameters:

  • enum: The SISO enumerated value representing a damage state.

Return value:

    A string representation of the damage state enum. Possible return values are "none", "slight", "moderate", "destroyed", and "unknown".
DamageState.StringToEnum (str)
Converts a damage state string into an enumerated value.

Parameters:

  • str: A recognized string specifying a damage state. Valid strings are "none", "slight", "moderate", and "destroyed".

Return value:

    A SISO enumerated value representing the damage state.
EntityType.Aggregate ()
Returns an entity type string for a generic aggregate.
EntityType.AggregateAir ()
Returns an entity type string for the given type of aggregate.
EntityType.AggregateGround ()
Returns an entity type string for the given type of aggregate.
EntityType.AggregateSpace ()
Returns an entity type string for the given type of aggregate.
EntityType.AggregateSubsurface ()
Returns an entity type string for the given type of aggregate.
EntityType.AggregateSurface ()
Returns an entity type string for the given type of aggregate.
EntityType.Area ()
Returns an entity type string for an area control measure.
EntityType.ArealObject ()
Returns an entity type string for a generic area object.
EntityType.CulturalFeature ()
Returns an entity type string for a generic cultural feature.
EntityType.EngineeringArealObject ()
Returns an entity type string for a generic engineering area object.
EntityType.EngineeringFixedSizeArealObject ()
Returns an entity type string for a generic fixed size engineering area object.
EntityType.EngineeringLinearObject ()
Returns an entity type string for a generic engineering linear object.
EntityType.EngineeringPointObject ()
Returns an entity type string for a generic engineering point object.
EntityType.GetCategory (entityType)
Returns the category field from the given entity type

Parameters:

  • entityType:
EntityType.GetCountry (entityType)
Returns the country field from the given entity type

Parameters:

  • entityType:
EntityType.GetDomain (entityType)
Returns the domain field from the given entity type

Parameters:

  • entityType:
EntityType.GetExtra (entityType)
Returns the extra field from the given entity type

Parameters:

  • entityType:
EntityType.GetKind (entityType)
Returns the kind field from the given entity type

Parameters:

  • entityType:
EntityType.GetNthField (entityType, n)
Returns the nth field in the entity type. Generally not used directly, but by other utility functions defined below.

Parameters:

  • entityType:
  • n:
EntityType.GetSpecific (entityType)
Returns the specific field from the given entity type

Parameters:

  • entityType:
EntityType.GetSubcategory (entityType)
Returns the subcategory field from the given entity type

Parameters:

  • entityType:
EntityType.Lifeform ()
Returns an entity type string for a generic lifeform.
EntityType.LinearObject ()
Returns an entity type string for a generic linear object.
EntityType.Munition ()
Returns an entity type string for a generic munition.
EntityType.NbcArealObject ()
Returns an entity type string for a generic hazard area object.
EntityType.Obstacle ()
Returns an entity type string for an obstacle control measure.
EntityType.PhaseLine ()
Returns an entity type string for a phase line.
EntityType.Platform ()
Returns an entity type string for a generic platform.
EntityType.PlatformAir ()
Returns an entity type string for a generic air platform.
EntityType.PlatformLand ()
Returns an entity type string for a generic land platform.
EntityType.PlatformSpace ()
Returns an entity type string for a generic space platform.
EntityType.PlatformSubsurface ()
Returns an entity type string for a generic subsurface platform.
EntityType.PlatformSurface ()
Returns an entity type string for a generic surface platform.
EntityType.PointObject ()
Returns an entity type string for a generic point object.
EntityType.Route ()
Returns an entity type string for a route.
EntityType.SetCategory (entityType, val)
Sets the category field in the entytType string with val.

Parameters:

  • entityType:
  • val:
EntityType.SetNthField (entityType, n, val)
Returns a string which is the input entityType string with the nth field replaced by val.

Parameters:

  • entityType:
  • n:
  • val:
EntityType.Waypoint ()
Returns an entity type string for a waypoint.
EntityType.Weather ()
Returns an entity type string for a local weather object.
LifeformPosture.EnumToString (enum)
Converts a lifeform posture enumerated value into a string.

Parameters:

  • enum: The SISO enumerated value representing a lifeform posture.

Return value:

    A string representation of the lifeform posture enum. Possible return values are "NA", "standing", "walking", "kneeling", "prone", "crawling", "swimming", "parachuting", "jumping", "sitting", "squatting", "crouching", "wading", "surrender", "detained", and "unknown".
LifeformPosture.StringToEnum (str)
Converts a lifeform posture string into an enumerated value.

Parameters:

  • str: A recognized string specifying a lifeform posture. Valid strings are "NA", "standing", "walking", "kneeling", "prone", "crawling", "swimming", "parachuting", "jumping", "sitting", "squatting", "crouching", "wading", "surrender", and "detained".

Return value:

    A SISO enumerated value representing the lifeform posture.
Util.findResource (namePart)
Finds a resource on this entity whose name contains the given string. The return value can be used in functions such as this:getResourceAmounts(). The resource names are made up of the internal system name plus the resource name as displayed in the Object Parameter Database Editor, for example "weapon-2|M829A1-AP-120mm". If more than one resource on this entity contain the string, it is not specified which one this function will return.

Parameters:

  • namePart: A string to search for in the resource names. For example, "fuel" or "120mm".

Return value:

    A string that is the full resource name.
Util.findSystem (namePart)
Finds a system on this entity whose name contains the given string. The string must be in the print name, i.e. the name shown in the Entity Editor. If more than one system on this entity contain the string, it is not specified which one this function will return.

Parameters:

  • namePart: A string. For example, "Missile" or "Radar".

Return value:

    A ComponentSystem on this entity whose name contains the given string.
Util.getSensorSystems ()
Gets a list of the sensor systems on this entity. Sensor systems are defined as those that have "sensor" in the the top level subsystem name.

Return value:

    A table containing a list of component systems, which are the sensors on this entity.
Util.getWeaponSystems ()
Gets a list of the weapon systems on this entity. Weapon systems are defined as those that have "weapon" in the the top level subsystem name.

Return value:

    A table containing a list of component systems, which are the weapons on this entity.
disableReaction (reactionName)
Disables a reactive task on this entity.

Parameters:

  • reactionName: The script ID (string) of the reactive task.
enableReaction (reactionName, params)
Enables a reactive task on this entity.

Parameters:

  • reactionName: The script ID (string) of the reactive task.
  • params: A table of the parameters to pass to the reaction as it is enabled. (optional)
getFixedTaskParameter (attributeName, defaultValue)
Looks up the given parameter name for this script as specified in a script-enable-controller-descriptor in a parameter file (e.g. .ope, .sysdef, etc.) The part in descriptor might look like this example: 
 (script-variables 
 (my-script-variables 
 (script-id "my_Script") 
 (variables 
 (DtRwReal size 20.0) 
 (DtRwReal speed $userspeed) 
 ) 
 )
This example defines parameters "size" and "speed" for script my_Script.

Parameters:

  • attributeName: The name of the parameter. As listed in the "variables" section of the "script-variables" section of the script-enable-controller-descriptor.
  • defaultValue: The value to return if the function cannot find the named parameter.

Return value:

    The parameter value in the descriptor, or the default value if the named parameter cannot be found.
getReactionActive (reactionName)
Gets whether or not a reaction is active on the current entity.

Parameters:

  • reactionName: The script ID of the reaction.

Return value:

    false if the reaction is not enabled, or doesn't exist.
getReactionPriority (reactionName)
Gets the priority of a particular reaction on the entity.

Parameters:

  • reactionName: The script ID (string) of the reaction.

Return value:

    The reaction priority (number), or nil if the reaction is not enabled, or doesn't exist.
printDebug (...)
Prints to the entity's Debug console. The "..." can be a comma separated list of arguments, as with a normal print statement, or a single TranslatableStream object. A TranslatableStream is created with the vrf:trUtf8() function. See the HowToPrint module documentation.

Parameters:

  • ...:
printError (...)
Prints to the entity's Error console. The "..." can be a comma separated list of arguments, as with a normal print statement, or a single TranslatableStream object. A TranslatableStream is created with the vrf:trUtf8() function. See the HowToPrint module documentation.

Parameters:

  • ...:
printInfo (...)
Prints to the entity's Info console. This function is assigned to the Lua print function by default. The "..." can be a comma separated list of arguments, as with a normal print statement, or a single TranslatableStream object. A TranslatableStream is created with the vrf:trUtf8() function. See the HowToPrint module documentation.

Parameters:

  • ...:
printVerbose (...)
Prints to the entity's Verbose console. The "..." can be a comma separated list of arguments, as with a normal print statement, or a single TranslatableStream object. A TranslatableStream is created with the vrf:trUtf8() function. See the HowToPrint module documentation.

Parameters:

  • ...:
printWarn (...)
Prints to the entity's Warn console. The "..." can be a comma separated list of arguments, as with a normal print statement, or a single TranslatableStream object. A TranslatableStream is created with the vrf:trUtf8() function. See the HowToPrint module documentation.

Parameters:

  • ...:
roundToInt (num)
Rounds a number to the nearest integer using normal rounding rules.

Parameters:

  • num:
setReactionPriority (reactionName, newPriority)
Changes the priority of a reactive task on this entity.

Parameters:

  • reactionName: The script ID (string) of the reactive task.
  • newPriority: The new priority value for this reaction. Lower numbers are higher priority.
table.copy (t)
A utility to copy tables. Normally, able assignment just copies the "reference" to the table, so changes to either variable changes the same table and affects both. From stackoverflow.com, question 640642

Parameters:

  • t: The table to copy.

Return value:

    A table that is a copy of the input table.
table.find (t, value)
Determines if the given value is in the table. i.e., if a table item has this value. If so, returns the key of the item. Otherwise, returns nil.

Parameters:

  • t: Table to search.
  • value: The value to find in the table.

Usage:

    table.find({x = 24, y = 25, z = 26}, 25) returns "y".

Return value:

    The key of the first table entry whose value is the given value. If the value is not found, the function returns nil.
taskDone (taskId, quitIfError)
Determine if a task or subtask is done, and handle errors.

Parameters:

  • taskId: The handle (number) of the task or subtask.
  • quitIfError: Boolean indicating that the function should end this script immediately if the given task has ended unsuccessfully. Defaults to false.

Usage:

     
     init()
     ... 
     taskHandle = vrf:startSubtask("move-to", {control_point = myGoalPt})
     ... 
     tick()
     if taskDone(taskHandle, true) then
     myFSM:fire("nextEvent")
     ...

Return values:

  1. True if the task result is done, either successfully or otherwise.
  2. True if the task is no longer running, and has completed successfully. False if the task is still running, or has stopped unsuccessfully--because it ended with status "false" or was cancelled.
vrfprint (printFcn, ...)
New print function that prints to the VRF Object console instead of the sim engine console.

Parameters:

  • printFcn:
  • ...:

Tables

Appearance
A table of functions to check and set the bits of an appearance value.
In each of the query functions, argument a is a number that represents appearance. The appearance of an entity is obtained from the SimObject function getAppearance. The Appearance- functions here return a boolean.
Example:
myAppearance = this:getAppearance()
myCanShoot = not Appearance.FirePowerKillOn(myAppearance)

The set functions generate a new appearance from the given appearance, but with the relevant feature changed. These functions do NOT change the published appearance of the entity; they merely computes an appearance value that is the input appearance but with the the relevant feature set on or off according to the enable parameter.
Example:
myAppearance = this:getAppearance()
lightsOnAppearance = Appearance.SetSpotLights(myAppearance, true)
vrf:executeSetData("set-appearance", {appearance = lightsOnAppearance})


DamageState
A table of functions to convert between damage state strings and the corresponding enumeration values.

EntityType
A table of functions returning strings corresponding to entity types. These strings can be used when checking the type of an entity. The returned types have wildcards that match all entities of a class. The strings are seven numbers separated by colons, e.g. "1:2:-1:-1:-1:-1:-1". The numbers represent the DIS enumeration values for kind, domain, etc. The "-1" values are wild cards intended to match any value; thus in the example above, the type would match any entity type that had "1" and "2" as its first values, and then any other values. The function vrf:entityTypeMatches can be used to determine if two entity types match.
Example:
-- Check to see if an object is a munition
myType = myObj:getEntityType()
isMunition = vrf:entityTypeMatches(myType, EntityType.Munition())


-- Get the Domain field of an entity type string
entType = "1:2:225:9:3:3:0"
domain = EntityType.GetDomain(entType) -- domain gets the number 2


LifeformPosture
A table of functions to convert between life form posture strings and the corresponding enumeration values.

Util
A table of functions for getting systems (ComponentSystem) on the entity.

Copyright© 2021 MAK Technologies, Inc. All rights reserved.