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

vrf

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

This module defines API functions that pass information to and from the simulation without reference to a particular simulation object or other class instance. Functions are called using vrf: to preface them. For example: vrf:stopTask(taskId).

Organization:

• Communication
• registerForObjectMessage
• sendInfluence
• sendMessage
• sendObjectMessage
• sendRadioObjectMessage
• sendReport
• unregisterForObjectMessage


• Entity Attributes
• entityTypeMatches
• forcesHostile
• getEmbarkationEgressPoints
• getEmbarkationSlots
• getEntityTypesForEquipment
• getParameterPropertyFromType
• getParameterSubordinateFunctionsFromType
• getSubordinateFunctionNames
• reserveEmbarkationSlot


• Environment
• getAirPressure
• getAirTemperature
• getChoppiness
• getCloudLayerDescriptionsAt
• getEpochTime
• getExpectedIllumination
• getFogHeight
• getFogColor
• getIllumination
• getMagneticDeclination
• getPrecipitation
• getPrecipitationIntensity
• getPrecipitationType
• getPriority
• getRainAccumulation
• getSeaState
• getSeaStateDirection
• getSnowAccumulation
• getSnowMinimumAltitude
• getSnowRoadAccumulation
• getSurfaceTransparency
• getSurgeDepth
• getSwellState
• getSwellStateDirection
• getTimeOfDay
• getUnderwaterVisibility
• getVisibilityDistance
• getVisibilityObscurant
• getWindDirection
• getWindDrivenSeaStateEnabled
• getWindSpeed


• Geometry
• makeAreaGeometry
• makeOffsetRoute
• makePathGeometry
• makePointGeometry


• Math
• bitwiseAnd
• bitwiseLeftShift
• bitwiseNot
• bitwiseOr
• bitwiseRightShift
• bitwiseXor
• gaussian


• Script Data
• getScriptAttribute
• getScriptId
• getSystemName


• Scenario Event Management
• playScenarioEvent
• stopScenarioEvent
• setScenarioEventEnabled
• isScenarioEventPlaying
• isScenarioEventEnabled


• Sim Object Management
• createArea
• createEntity
• createFromOrbat
• createObstacle
• createPhaseLine
• createRoute
• createSelectionGroup
• createTacticalGraphic
• createWaypoint
• deleteObject
• getDesignatorsWithinRange
• getEmbarkationSlots
• getEmbarkationEgressPoints
• getSimObjectByName
• getSimObjectByUUID
• getSimObjectsNear
• getSimObjectsNearWithFilter
• getVrfObjects
• reserveEmbarkationSlot


• Simulation Management
• getExerciseTime
• getSimulationTime
• getTimeMultiplier
• runDurationTime
• runForDuration
• setRespondToNewSensorContacts
• setTickPeriod
• setTickWhilePaused
• setCheckpointMode
• stopSimulationDurationTimer
• getApplicationId
• finishTest


• Task and Set Management
• addPostSetDataCallback
• cleanupInactiveSubtaskStatus
• endSet
• endTask
• executeSetData
• getReactionStatus
• isSubtaskCanceled
• isSubtaskComplete
• isSubtaskRunning
• isTaskCanceled
• isTaskComplete
• isTaskRunning
• removePostSetDataCallback
• sendEmbeddedEntitySet
• sendEmbeddedEntityTask
• sendSetData
• sendTask
• startSubtask
• stopAllSubtasks
• stopAllTasks
• stopSubtask
• stopTask
• subtaskResult
• taskResult


• Terrain Information
• chordIntersectsTerrain
• doesChordHitTerrain
• findClosestPointToRoad
• getFeaturesWithinArea
• getFeaturesWithinRange
• getGroundAltitude
• getTerrainAltitude
• getTerrainAltitudeBelow
• makeOffsetRoutes
• navigateThroughFeatures
• Queries on Navigation Mesh:
  • findClosestPointInNavigationArea
  • findCoverPoint
  • findClosestPointToRoad
  • findFarthestPositionAlongHeading
  • findLadders
  • findNearbyPointOfInterest
  • findPathToLocation
  • generateRandomPoints
• Dynamic Terrain:
  • getDynamicTerrainFeatureChangeTypes
  • getDynamicTerrainFeatureLocationsForChangeType
  • getDynamicTerrainFeatureValuesForChangeType
  • changeDynamicTerrain
• Terrain Reasoning (without Navigation Mesh):
  • findHighPoints
  • findSinglePosition
  • findVehicleFightingPositions
  • findPositionGroupsInArea
  • findPositionGroupsInAreaRidge


• Aerodromes
• getAerodrome
• getAerodromesWithinRange
• User Interaction
• askUserQuestion
• cancelUserQuestion
• statusOfUserQuestion
• updateTaskVisualization
• deleteTaskVisualization
• processGraphCommands
• setGraphCapable
• shouldGenerateGraphOutput
• trUtf8

Function List

Functions

addPostSetDataCallback (setDataType, functionName)

Adds a post-set data request callback - a function to be called after the specified type of set data request is executed. This will not make new set data requests available to the entity - this callback will only be called for set data requests the entity is already capable of executing. of the script rather than init(). (init() will not be called when the script is loaded if it is a task that was running during a scenario save, and that scenario is being reloaded. See VR-Forces Scenario Management Guide section 14.) executing on loaded entities. The callback function should return nothing. The callback function will be called with one parameter, a table with the contents of the set data message. This will match the format of tables used for vrf:executeSetData or vrf:sendSetData.

Parameters:

• setDataType: (string) The type of set data request to register interest in, for example "set-restore"
• functionName: (string) the name of the lua function to call in response to the specified type of set data request being executed. For example, "setRestoreCallback". Note that this name is a string, and must be in quotes.

askUserQuestion (title, message, options, displayFlags)

Sends a message to all front-ends to ask the user the question supplied in the message. A script can ask only one question at a time. If there is an outstanding question, that question is cancelled and the new one asked. The options table contains a list of options the user can select from. Only one option can be selected.

Parameters:

• title: A string or a translatable stream. Title of the question. This will also be displayed in the object console.
• message: A string or a translatable stream. Message to show in the body of the question dialog.
• options: A table whose items are strings or translatable streams. Each string is a label for a selection option presented to the user.
• displayFlags: How to display the options to the user: 0 - As a series of buttons 1 - As radio buttons 2 - As a combo box.

Return value:

The ID of the question that can be used as supply to other question related methods.

bitwiseAnd (unsigned val1, unsigned val2, val1, val2)

Returns the bitwise and of the two unsigned integers.

Parameters:

• unsigned val1:
• unsigned val2:
• val1: Argument 1, a number. This number will be converted to an unsigned int before the operation.
• val2: Argument 2, a number. This number will be converted to an unsigned int before the operation.

Return value:

The unsigned integer result of the bitwise and.

bitwiseLeftShift (val, shift)

Returns the bitwise left shift of an unsigned integer by the given amount.

Parameters:

• val: The number to be shifted. This number will be converted to an unsigned int before the operation.
• shift: The amount to shift by.

Return value:

The unsigned integer result of the bit shift.

bitwiseNot (val)

Returns the bit inversion of an unsigned integer.

Parameters:

• val: The number to be inverted. This number will be converted to an unsigned int before the operation.

Return value:

The unsigned integer result of the bitwise inversion.

bitwiseOr (unsigned val1, unsigned val2, val1, val2)

Returns the bitwise or of the two unsigned integers.

Parameters:

• unsigned val1:
• unsigned val2:
• val1: Argument 1. This number will be converted to an unsigne int before the operation.
• val2: Argument 2. This number will be converted to an unsigne int before the operation.

Return value:

The unsigned integer result of the bitwise or.

bitwiseRightShift (val, shift)

Returns the bitwise right shift of an unsigned integer by the given amount.

Parameters:

• val: The number to be shifted.
• shift: The amount to shift by.

Return value:

The unsigned integer result of the bit shift.

bitwiseXor (unsigned val1, unsigned val2, val1, val2)

Returns the bitwise xor of the two unsigned integers.

Parameters:

• unsigned val1:
• unsigned val2:
• val1: Argument 1, a number. This number will be converted to an unsigned int before the operation.
• val2: Argument 2, a number. This number will be converted to an unsigned int before the operation.

Return value:

The unsigned integer result of the bitwise xor.

cancelUserQuestion (questionId)

Cancels the asked question

Parameters:

• questionId: Question to cancel

changeDynamicTerrain (changeType, changeValue, location, radius)

Causes a change to the dynamic terrain in the spherical area represented by the given location and radius.

Parameters:

• changeType: String representing the value of the dynamic terrain change
• changeValue:
• location: The center point of the area to be affected
• radius: The radius of the area to be affected

chordIntersectsTerrain (point1, point2)

Determines if the chord formed by (point1, point2) intersects the terrain. The ground surface and features are considered. Features that would block line of fire like buildings, infrastructure, and most of the vegetation are considered. Vegetation which are not features - are not considered
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 intersection data is not valid. Therefore, this function returns a second value which is a boolean indicating if the intersection result is valid.

Parameters:

• point1: Location3D.
• point2: Location3D.

Usage:

isBlocked, valid, location = vrf:chordIntersectsTerrain(pt1, pt2)

Return values:

1. Boolean that is true if the LOS is blocked.
2. Boolean that is true if the intersection data is valid.
3. DtLocation3D with location where the chord is blocked, if dataAvailable is true

cleanupInactiveSubtaskStatus ()

Clears out any task status that is stored for completed or canceled subtasks that were started by this script. After calling this, subtaskResult(), isSubtaskComplete() isSubtaskCanceled() will no longer return information on tasks that were complete or canceled at the time this was called. It is generally not necessary to call this, except for scripts that are starting an unbounded number of subtasks without the task itself ending.

createArea (parameters)

Creates an area and returns the area created. The area will be automatically closed from the last to first point

Parameters:

• parameters: See description of "createEntity" commands for parameters. This command will fill in entity_type of 18 0 0 1 0 0 0

Usage:

createArea({locations=arrayOfLocations})

Return value:

SimObject for newly created object

createEntity (parameters)

Creates an entity with the following supplied information:

Parameters:

• parameters:
  entity_type [required] - Entity Type septuplet or entity creation name found in mst file of loaded simulation model set
  location [required] - DtLocation3D of entity to be created
  object_name - Name of the object to create. If unspecified or blank will create name automatically
  object_name_prefix - Prefix to be used in creating a unique object name. Ignored if object_name is set. If unspecified or blank will create name automatically
  force - Force name or type of entity being created. If no force specified will use force of creating entity
  heading - Heading (in radians) of entity
  publish - Whether or not to publish object on the network. Default is true
  overlay - Name of overlay layer for object to be placed on.
  superior - SimObject for the superior unit of this entity.
  extended_data - Extended data to supply to object. Format is {reader/writer type = data},
  ex: {DtRwString="test"} or {name= string}, {name= number}, {name = {reader/writer type = data}}
  Extended data is added to the state repository of the newly created item by RW type name and can be accessed via the reader/writer type if no name is specified or by the name if it is, in C++. color - If a tactical graphic, the color of the tactical grapic. The color can be set by using the Color.ARGB(red, green, blue, alpha) lua function color=Color.ARGB(0, 255, 0, 200) attach_to - If a tactical graphic, the object to attach the newly created tactical graphic to.

Usage:

createEntity({entity_type="1:3:0:0:0:0:0",location=entityLocation})

Return value:

SimObject for newly created object

createFromOrbat (orbatobjectname, location)

Creates an object from the ORBAT with the given name if the ORBAT object has not already been created at the specified location

Parameters:

• orbatobjectname: - Name of the object to create as it appears in the ORBAT
• location: - The Location3D to create the object at

Usage:

createFromORBAT("M1A2 1", entitylocation)

Return value:

SimObject for the newly created object

createObstacle (parameters)

Creates an obstacle and returns the obstacle created. The obstacle will be automatically closed from the last to first point

Parameters:

• parameters: See description of "createEntity" commands for parameters. This command will fill in entity_type of 18 0 0 2 0 0 0

Usage:

createObstacle({locations=arrayOfLocations})

Return value:

SimObject for newly created object

createPhaseLine (parameters)

Creates a phase line and returns the phase line created. This method will not enforce the two points per phase line. That restriction will need to be imposed by the user of this method

Parameters:

• parameters: See description of "createEntity" commands for parameters. This command will fill in entity_type of 17 0 0 1 0 0 0

Usage:

createPhaseLine({locations=arrayOfLocations})

Return value:

SimObject for newly created object

createRoute (parameters)

Creates a route and returns the route created.

Parameters:

• parameters: See description of "createEntity" commands for parameters. This command will fill in entity_type of 17 0 0 2 0 0 0

Usage:

createRoute({locations=arrayOfLocations})

Return value:

SimObject for newly created object

createSelectionGroup (name, objects)

Creates a new selection group with the given name containing the specified SimObjects.

Parameters:

• name: string, The name of the selection group.
• objects: Table containing the list of SimObjects to be included in the selection group.

createTacticalGraphic (parameters)

Creates a tactical graphic of the supplied entity_type as specified with a create name or DIS entity enumeration

Parameters:

• parameters: See description of "createEntity" commands for parameters.

Usage:

• createTacticalGraphic({entity_type="16:1:0:0:0:0:0", location=pointLocation})

• createTacticalGraphic({entity_type="17:1:0:0:0:0:0", locations=arrayOfLocation})

Return value:

SimObject for newly created object

createWaypoint (parameters)

Creates a waypoint and returns the waypoint created.

Parameters:

• parameters: See description of "createEntity" commands for parameters. This command will fill in entity_type of 16 0 0 1 0 0 0

Usage:

createWaypoint({location=waypointLocation})

Return value:

SimObject for newly created object

deleteObject (entity)

Deletes the given entity object from the simulation. After the object is deleted, the isDeleted() function for the corresponding SimObject in Lua will return true.

Parameters:

• entity: This parameter can either be the name (string) of the entity or the SimObject for the entity.

Usage:

• vrf:deleteObject("APC 1")

• vrf:deleteObject(firstAPC)

deleteTaskVisualization (name)

Deletes the task visualization with the given name.

Parameters:

• name: The name of the visualization. If no visualization by this name exists, one will be created.
  

Usage:

deleteTaskVisualization("name")

doesChordHitTerrain (point1, point2)

Determines if the chord formed by (point1, point2) intersects the terrain. The ground surface and features are considered. Features that would block line of fire (buildings and infrastructure, but not vegetation) are considered.
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 intersection data is not valid. Therefore, this function returns a second value which is a boolean indicating if the intersection result is valid.

Parameters:

• point1: Location3D.
• point2: Location3D.

Usage:

isBlocked, valid = vrf:doesChordHitTerrain(pt1, pt2)

Return values:

1. Boolean that is true if the LOS is blocked.
2. Boolean that is true if the intersection data is valid.

endSet ()

Causes the current set to end once the current tick is complete. The tick function for this set instance will not be run again.

Usage:

vrf:endSet()

endTask (status)

Causes the current task to end once the current tick is complete. The tick function for this task instance will not be run again.

Parameters:

• status: A boolean indicating either success (true) or failure (false) of the task. This is the status that is returned to the parent task though taskResult().

Usage:

vrf:endTask(true)

entityTypeMatches (entityType1, entityType2)

Check to see if the patterns of the entity types match.

Parameters:

• entityType1: An entity type (string) to check
• entityType2: An entity type (string) to check

Return value:

A boolean, true if the entity types match.

executeSetData (setName, parameters)

Executes a set data request to the ownship. The parameters vary depending on the name of the set. If a set data request does not have parameters, you must include empty braces in the command, for example: vrf:executeSetData("set-destroy", {}) Not all entities are capable of accepting all set data requests.
This function will throw an error if an invalid set name or invalid parameter is specified.

Parameters:

• setName: String from the list of available sets. See the "Sets" reference section for the list of valid set names.
• parameters: A table of parameters for the set being sent. The parameter names must be valid for the specified setName. See the "Sets" reference section for the valid parameters. Any parameters not included will assume their default value.

Usage:

vrf:executeSetData("set-lifeform-posture", {lifeform_posture = "standing"})

findClosestPointInNavigationArea (point, radius, verticalLimit)

Finds the closest point on the traversable part of a navigation area. The input point must be within the extent of a navigation area. This function is used to take a location that is generally in a nav area but may be within an obstacle, and finds the nearest point in the traversable portion of the nav area. The location will be placed on the surface (if in a building, the nearest surface to the input altitude). If the point is already in the traversable area, then the input location is returned.
This search uses a nav area with the navigation profile determined by the entity (see appData\settings\vrfSim\navigationProfiles.mtl). If that profile is null, then the state property "Navigation-profile-for-query" is retrieved. If that is null, or equal a null string, then the first profile in the above file is used.

Parameters:

• point: A Location3D of the point from which to search for the traversable area.
• radius: The horizontal distance within which to search. Optional (but required if the verticalLimit parameter is used). Default 10.0 m.
• verticalLimit: The vertical distance within which to search. Optional. Default 2.0 m.

Return values:

1. A Location3D of the closest location on the traversable part of the nav area. The point will be on the ground.
2. A boolean that is true if the input point is not in the extent of a navigation area, or a traversable surface could not be found within the horizontal radius or vertical limit of the input point.

findClosestPointToRoad (point, searchRadius)

Searches the radius distance specified from the given point to find a road feature near it. If it finds a road, this function has multiple return values. This function depends on loading of feature data and may not necessarily return valid data on first call and will need to be tested for such via some of the return values. If it does not return a valid point, increasing the search radius would help.

Parameters:

• point: The starting point to search from
• searchRadius: The distance from the point to perform the search

Return values:

1. Location3D of the closest point on the road (assuming one was found)
2. Boolean indicating if the data is yet available for this call to succeed
3. Boolean indicating whether or not (assuming data is available) this call found a road within the radius.
4. Location3D of one end of the closest road edge (assuming one was found)
5. Location3D of the other end of the closest road edge (assuming one was found)
6. Number indicating the offset distance from the road center (the point returned is on the road center) to the center of the outside lane. Normally a vehicle will start driving on the outside lane. If the simulation is configured to have vehicles drive on the left side of the road, the offset value will be negative.

findCoverPoint (startLocation, threatLocation, threatRadius, distanceFromThreat, range, numberOfPoints)

If the entity is within a nav area, this searches for the specified number of cover points from the specified threat location in the specified radius of the entity. This search uses a nav area with the navigation profile determined by the entity (see appData\settings\vrfSim\navigationProfiles.mtl). If that profile is null, then the state property "Navigation-profile-for-query" is retrieved. If that is null, or equal a null string, then the first profile in the above file is used.

Parameters:

• startLocation: The starting location from which to search for cover.
• threatLocation: Location from which to find cover.
• threatRadius: Radius around threat which to find cover from, i.e. cover points should be hidden from all locations within this radius of the threat.
• distanceFromThreat: Minimum distance to keep from threat.
• range: Range from the entity in which to search for cover.
• numberOfPoints: Number of cover points desired.

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a table of cover points where each entry in the table is another table with the following fields:


 point  - A Location3D for the cover point.
 isHigh - A boolean indicating whether the cover is high enough for the entity to stand.

findFarthestPositionAlongHeading (point, heading, distance)

Finds the farthest point along a given heading that can be traveled without hitting the edge of the nav mesh, within the given distance. This indicates how far an entity can move on the nav mesh in that direction.
This search uses a nav area with the navigation profile determined by the entity (see appData\settings\vrfSim\navigationProfiles.mtl). If that profile is null (for example if the entity using this script is a unit), then the state property "Navigation-profile-for-query" is retrieved. If that state property is null, then the function assumes the point is not on a nav mesh.
If the point is not on a nav mesh--maybe there is no nav mesh in this part of the terrain--the function returns false and the information returned results from a call to checkLineOfSightWithoutObjects for a chord 1m above the starting point. This may not be an accurate indication of how far an entity can move.

Parameters:

• point: Location3D The start point on the nav mesh.
• heading: number The heading direction in radians.
• distance: number The maximum distance to test, in meters.

Return values:

1. bool True if the start point was on a nav mesh.
2. Location3D The location of the farthest point reached.
3. float The distance reached along the heading.

findHighPoints (corners, nPoints, bDebug)

Given a table of Location3D points defining an area in which to search, try to find a nPoints points that are hilltops. Hilltops are points that are higher than surrounding points within some radius. The getObject call for this job will return a list (table) of Location3D indicating the hilltops found.

Parameters:

• corners: A table of Location3D points defining an area in which to search.
• nPoints: The number of points to return, if any prominent points are found.
• bDebug: Boolean value, optional. If true, additional debug output is provided in the console.

Return value:

An async job.

findLadders (startLocation, range, tagID, tagId)

If the entity is within a nav area, this searches for ladders from the specified location in the specified radius of the entity.

Parameters:

• startLocation: The starting location from which to search for cover.
• range: Range from the entity in which to search for cover.
• tagID:
• tagId: Integer (optional), a nav tag value.The ladders returned must have a tag that matches the ID. If the ID is not provided, all ladders in range will be returned.

Return value:

A list (table) of ladders. Each ladder is a table with the following fields:
• mainLocations - a list (table) of location items, the main locations describing the ladder. Each location item is a table containing:
  • location - a Location3D of the location
  • index - an integers, the index of the location in the nav data(not useful?).
• entryExitLocations - a list (table) of location items (as above), the entry and exit locations of the ladder when using it to move.

findNearbyPointOfInterest (type)

If the entity is within a nav area, this searches for a defined point of interest with the shortest path to reach, within a defined radius. This search uses a nav area with the navigation profile determined by the entity (see appData\settings\vrfSim\navigationProfiles.mtl). If that profile is null, then the state property "Navigation-profile-for-query" is retrieved. If that is null, or equal a null string, then the first profile in the above file is used.

Parameters:

• type: Points tagged with this type will be considered. -1 matches all points.

Return value:

An AsyncJob object that will produce a nearby point of interest, if one can be found. When the job successfully completes, a call to job:getObject() will return a nearby point of interest, if one can be found.

findPathToLocation (startLocation, destinationLocation, useAbstractGraphs, avoidLocation, avoidanceRadius)

Finds a path from the start location to the destination location. Points must be in nav areas. This search uses a nav area with the navigation profile determined by the entity (see appData\settings\vrfSim\navigationProfiles.mtl). If that profile is null, then the state property "Navigation-profile-for-query" is retrieved. If that is null, or equal a null string, then the first profile in the above file is used.

Parameters:

• startLocation: Location to start from.
• destinationLocation: Location to find a path to.
• useAbstractGraphs: Uses abstract graphs during path finding. This can speed up path finding queries at the expense of finer detail in the pathing. It may also result in an inability to properly avoid the specified avoidLocation.
• avoidLocation: Specifies a location to avoid when planning a path.
• avoidanceRadius: Specifies the minimum distance around avoidLocation to avoid.

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a table of points that make up the path, if one can be found.

findPositionGroupsInArea (nPositionPairsPerGroup, searchAreaVertices, targetsAreaVertices, viewHeightMeters, coverHeightMeters, forwardBackRangeMeters, sideSideRangeMeters, sideSideIntervalMeters, maxSlopeDegrees, positionsLateralSpacingMeters)

Starts an async job to find multiple "position" groups in a search area. This function is suitable for looking for possible Attack By Fire lines for the platoons of a company, for example. The search starts by finding hilltop points, then looking for positions near each one. The getObject function for this job returns a list of tables where each table describes one group of positions. In each table, there are 5 elements: 1) the center ("pivot") point for each group of positions, 2) the average view score for the group, 3) the average cover score for the group, 4) the overall score for the group, 5) the positions in the group. The positions element is itself a list of positions, where each position is a table of 2 values (view and hide locations).

Parameters:

• nPositionPairsPerGroup: The number of position pairs to find in each group.
• searchAreaVertices: Table of Location3D vertices defining the area in which to find position groups.
• targetsAreaVertices: Table of Location3D vertices defining the engagement area.
• viewHeightMeters: In meters, a height above the ground to use for line of sight checks, notionally some portion of a vehicle gun height, used for detection, e.g. 2/3 vehicle height.
• coverHeightMeters: In meters, a height above the ground taller than a vehicle, so it can hide, e.g 4m.
• forwardBackRangeMeters: In meters, for any group, what should be the search distance from the forward edge of the group area to the rear? E.g. 50m forward + 50m back = 100m
• sideSideRangeMeters: In meters, for any group, what should be the search distance from the left edge of the group area to the right? E.g. 50m left + 50m right = 100m
• sideSideIntervalMeters: In meters, when searching for shoot/hide positions in a group, sample side to side at what rate? E.g. 1.5x vehicle width or 5m.
• maxSlopeDegrees: In degrees, the absolute value of the maximum slope along the line between view point and cover point. Must be from 0.0 to 90.0.
• positionsLateralSpacingMeters: In meters, within a group, how far apart should one position pair be from another, side to side? E.g. 5x vehicle width or 25m.

Return value:

An async job.

findPositionGroupsInAreaRidge (nPositionPairsPerGroup, searchAreaVertices, targetsAreaVertices, viewHeightMeters, coverHeightMeters, forwardBackRangeMeters, sideSideRangeMeters, sideSideIntervalMeters, maxSlopeDegrees, positionsLateralSpacingMeters, targetsAreaSampleRate, tableOfDoubles)

This function is the same as findPositionGroupsInArea except that it uses a different algorithm to test groups. This algorithm essentially finds ridges oriented perpendicular to the view of the target instead of finding hilltops. The getObject function returns the same information.

Parameters:

• nPositionPairsPerGroup: The number of position pairs to find in each group.
• searchAreaVertices: Table of Location3D vertices defining the area in which to find position groups.
• targetsAreaVertices: Table of Location3D vertices defining the engagement area.
• viewHeightMeters:
• coverHeightMeters:
• forwardBackRangeMeters:
• sideSideRangeMeters:
• sideSideIntervalMeters:
• maxSlopeDegrees:
• positionsLateralSpacingMeters:
• targetsAreaSampleRate: Integer, the number of points within the target area against which the reasoner will try to find line of sight from the search area.
• tableOfDoubles: A Lua table consisting of doubles: {targetsHeightMeters=#.#, viewHeightMeters=#.#, coverHeightMeters=#.#, coverRangeMeters=#.#, lateralRangeMeters=#.#, lateralIntervalMeters=#.#, verticalRangeMeters=#.#, verticalIntervalMeters=#.#, maxSlopeDegrees=#.#, positionsLateralSpacingMeters=#.#}

Return value:

An async job. targetsHeightMeters is the height above the terrain, in meters, to be used when sampling the area defined by targetsAreaVertices viewHeightMeters is the height above the terrain, in meters, to be used when searching for a vantage point from searchAreaVertices to targetsAreaVertices coverHeightMeters is the height needed to consider something hidden by terrain, e.g. the height of a vehicle. coverRangeMeters is a limit on the distance that we want between a shoot position and a hide position. lateralRangeMeters is the width in meters that a cluster of position-pairs can span. lateralIntervalMeters is the distance left or right that is used to sample for positions (i.e. comb density) verticalRangeMeters is the desired depth forward/back of a cluster of position pairs. verticalIntervalMeters is a rate at which to sample elevation forward/back when searching along a line for shoot/hide positions. maxSlopeDegrees the maximium slope in degrees between a hide position and a shoot position. positionsLateralSpacingMeters this is the desired space between returned position pairs. It must be larger than lateralIntervalMeters

findSinglePosition (targetAreaCorners, pivotPoint, targetHeightMeters, viewHeightMeters, hideHeightMeters, forwardBackSearchLimitMeters, forwardBackSearchIntervalMeters, maxSlopeDegrees, bDebug, forwardBackSearchLimit)

Start a terrain reasoning query job to find a "position" which is really two Location3D points: a shoot position where an observer at viewHeight can see the target area, and a hide position where an object of hideHeight is not visible from the target area. The getObject call for this job will provide a table of Location3D points: {, }.

Parameters:

• targetAreaCorners: Table of Location3D vertices defining the area to target for engagement.
• pivotPoint: A point representing the battle position from which to engage the enemy, i.e. the pivot point for the search.
• targetHeightMeters: In meters, a notional value that represents some portion of the height of a target vehicle, e.g. 2/3 vehicle height. Used to make an endpoint for a line-of-sight check.
• viewHeightMeters: In meters, a notional value that represents the height of the gun of the shooter, e.g. 2/3 vehicle height. Used to make an origin point for a line-of-sight check.
• hideHeightMeters: In meters, a notional value that represents the height necessary to hide a vehicle, e.g. 1.10x vehicle height.
• forwardBackSearchLimitMeters:
• forwardBackSearchIntervalMeters: In meters, the rate at which the line toward and away from the target should be sampled to search for suitable points. E.g. 1/2 vehicle length.
• maxSlopeDegrees: In degrees, the absolute value of the maximum slope along the line between view point and cover point. Must be from 0.0 to 90.0.
• bDebug: Boolean value, optional. If true, additional debug output is provided in the console.
• forwardBackSearchLimit: In meters, total distance forward and back of the originPoint, in which to find shoot/hide positions. E.g. 50m forward + 50m back = 100m.

Return value:

An async job. When the job successfully completes, a call to job:getObject() will return a table of generated points, which may be empty. Prior to completion, getObject() returns nil.

findVehicleFightingPositions (nPositionPairs, targetAreaCorners, originPoint, hideVolume, shootHeight, targetHeight, forwardBackSearchLimit, sideSideSearchLimit, maxSlopeDegrees, positionSpacing)

Given an origin point, which is assumed to be near a hilltop or ridge, find "positions" (described in findSinglePosition) where the shoot and hide locations in each position are lined up with the target area. The positions are returned in left to right order as viewed from the originPoint looking toward the targetArea. This function is intended to compute the shoot and hide positions more accurately than the findPositionGroups functions. This function starts an async job to find the positions. The getObject function for this job returns a list of lists. Each list (table) has two Location3Ds in it; the first is the shoot position and the second is the hide position. Ideally there will be nPositionPairs pairs of locations, but there may not be.

Parameters:

• nPositionPairs: The number of pairs to find. A pair is a shoot position and a hide position. Typically one pair per subordinate.
• targetAreaCorners: Table of Location3D vertices defining the area to target for engagement.
• originPoint: A point representing the battle position from which to engage the enemy, i.e. the pivot point for the search.
• hideVolume: Notional bounding volume (full dimensions) of a vehicle, perhaps the largest vehicle in a unit. Used to space out the pairs along searchWidthSide.
• shootHeight: In meters, a height above the ground where presumably a shooter's gun is located. Used as an endpoint for line of sight checks.
• targetHeight: In meters, a height above the ground to use for line of sight checks, notionally some portion of an enemy's vehicle height, used for detection, e.g. 2/3 vehicle height.
• forwardBackSearchLimit: In meters, total distance forward and back of the originPoint, in which to find shoot/hide positions. E.g. 50m forward + 50m back = 100m.
• sideSideSearchLimit: In meters, the total width left to right about origin point in which the position pairs should fit. E.g. 50m left + 50m right = 100m.
• maxSlopeDegrees: In degrees, the absolute value of the maximum slope along the line between view point and cover point. Must be from 0.0 to 90.0.
• positionSpacing: In meters, how far apart should the position pairs be laterally across the width of a formation?

Return value:

An asynchronous job.

finishTest (status, message)

Causes VR-Forces to execute a finish-test action. This is used for automated testing. A "finish action" causes a message to be printed to the Warn console and, if simulation options have been set to exit on test finish, the simulation exits. If the option hasn't been set this way, the simulation pauses.

Parameters:

• status: Number. Result of the test: 0 - pass, 1 - fail, 2 - no status. This status is reported, but does not affect the action.
• message: The message printed to the Warn console.

forcesHostile (force1, force2)

Determine the hostility between two forces.

Parameters:

• force1: Force type (string)
• force2: Force type (string)

Return value:

True if force1 is hostile to (is allowed to shoot at) force2. Note that this relationship is not necessarily reciprocal, so testing forcesHostile(force2, force1) may return a different result.

gaussian ()

Provides a random number drawn from a Gaussian distribution. Uses the Marsaglia polar method to generate numbers.

Return value:

A real number

generateRandomPoints (parameters, number_of_points, parent_object, start_point, access_point, boundary, min_distance_from_access_point, max_distance_from_access_point, min_distance_between_points, placement_restriction, tightly_pack, need_line_of_sight, ground_clamp, left_of_line_start)

If the entity is within a nav area, this searches for a random point in the nav area. This search uses a nav area with the navigation profile determined by the entity (see appData\settings\vrfSim\navigationProfiles.mtl). If that profile is null, then the state property "Navigation-profile-for-query" is retrieved. If that is null, or equal a null string, then the first profile in the above file is used.

Parameters:

• parameters:
• number_of_points: - Specify to generate more than one point. Default is 1.
  
• parent_object: - If specified, use navData attached to this object. Otherwise, find navData using start_point.
  
• start_point: - If specified, and parent_object is not, this point is used to determine which navArea to use. If unspecified, the location of the entity is used to find the .
  
• access_point: - If specified, the random points generated will be tested for connectivity to the access_point.
  
• boundary: - If specified, the random point generated will be confined to within the points of the boundary object.
  
• min_distance_from_access_point: - If specified, and if boundary is empty, the minimum distance wander points will be generated from access_point.
  
• max_distance_from_access_point: - If specified, and if boundary is empty, the maximum distance wander points will be generated from access_point.
  
• min_distance_between_points: - Minimum distance between generated points. Default is 0.0.
  
• placement_restriction: - Restriction on point placement. Valid strings are "free", "prefer-roads", "avoid-roads", & "prefer-pedestrian-paths". Default is "free".
  is_strict - Whether only points matching the placement_restriction should be returned, or if other points are allowed if not enough can be generated. Default is true.
  
• tightly_pack: - Whether points closer to the access point should be favored. Default is false.
  
• need_line_of_sight: - Whether points with line of sight to the access point should be favored. Default is false.
  
• ground_clamp: - Will attempt to ground clamp points to the closest surface below generated point plus the entity height specified during nav data generation.
  
• left_of_line_start: & left_of_line_end - Define a line and only points to the left of the line will be generated.
  

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a table of generated points.

getAerodrome (airportCode)

Returns aerodrome object provided the aerodrome object exists

Parameters:

• airportCode: (string) The airport code of the aerodrome.

Return value:

The AerodromeObject with the given aerodrome code. If the named AerodromeObject does not exist, then a AerodromeObject will still be returned, but isValid() will return false on that object.

getAerodromesWithinRange (location, range)

Given a location and radius, return a list of all AerodromeObject within that sphere

Parameters:

• location: (Location3D) location of the center of the range.
• range: (number) range in meters.

Return value:

(table) A list of the AerodromeObjects within that radius, else an empty list.

getAirPressure (where)

Returns the air pressure at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

The value of the air pressure (in kiloPascals)

getAirTemperature (where)

Returns the air temperature at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

The value of the air temperature (in Celsius)

getAllEmbarkationSlots (simObject)

Queries the simObject for all its embarkation slot information.

Parameters:

• simObject: The object whose embarkation slot information you wish to query.

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a list of slot information for all slots on the entity. The information for each slot in the list is a table that includes the following fields:
slot_number - The slot number reserved. Should match the input slotNumber unless it was -1, in which case it will be the assigned slot.
slot_name - The name assigned to this slot.
slot_type - String identifying the type of slot.
slot_position - VectorOffset3D specifying the offset location of the slot on the entity being embarked upon.
occupied - Boolean indicating whether the slot is currently occupied.
available - Boolean indicating whether the slot is currently available to this entity.

getApplicationId ()

Returns the SimEngine's id

Return value:

The simulation application ID (ex "3001").

getCloudLayerDescriptionsAt (where)

Parameters:

• where: Location3D at which to get the environment information

Return value:

Returns a table with several fields with the cloud layer descriptions It contains the following fields:
• cloudType - the cloud layer type:
  • Cirrocumulus = 0 High planar cloud puffs
  • CirrusFibratus = 1 High, thicker and fibrous clouds that signal changing weather
  • Nimbostratus = 2 Low rain clouds that cover the sky
  • CumulusMediocris = 3 Low, puffy clouds on fair days
  • CumulusCongestus = 4 Large cumulus clouds that could turn into a thunderhead
  • CumulonimbusCapillatus = 5 Big storm clouds.
  • StratoCumulus = 6 Dense, puffy clouds rendered with GPU ray-casting
  • Sandstorm = 7
  • Fog = 8
• layerBottomAltitude - the cloud layer bottom altitude
• layerTopAltitude - the cloud layer top altitude
• visibility - visibility, in meters, through the layer
• coverFraction - the cloud cover fraction

getDesignatorsWithinRange (location, distance, filter)

Return a list of laser designators within range of a point.

Parameters:

• location: Location at which to search for designators.
• distance: Distance from location at which to search for designators.
• filter: (optional) The filter to apply to the search. This should be a table with the elements (all optional):
  • code - A specific designator code to search for.
  • designatedObject - A specific object to search for (i.e. the designator with that object as the designated object)

Return value:

list of tables in the following form, each table having the elements
• code
• codeName
• designatedObject (0:0:0 if designatorObject was not specified in the input filter)
• wavelength
• power
• location (of the spot)
• acceleration (of the spot)

getDynamicTerrainFeatureChangeTypes (location, radius, searchRadius)

Searches for any dynamic terrain features within the given radius of the given point and returns a list of strings indicating the type of changes they support.

Parameters:

• location: The starting point to search from
• radius:
• searchRadius: The distance from the point to perform the search

Return values:

1. Returns a list of strings representing the dynamic terrain changes supported in this area
2. Boolean indicating if the data is yet available for this call to succeed

getDynamicTerrainFeatureLocationsForChangeType (changeType, location, radius, searchRadius)

Searches for any dynamic terrain features within the given radius of the given point that support the indicated type of change and returns a list of their locations.

Parameters:

• changeType: String representing the type of dynamic terrain change to search for
• location: The starting point to search from
• radius:
• searchRadius: The distance from the point to perform the search

Return values:

1. Returns a list of Location3Ds representing the location of the found dynamic terrain features
2. Boolean indicating if the data is yet available for this call to succeed

getDynamicTerrainFeatureValuesForChangeType (changeType, location, radius, searchRadius)

Searches for any dynamic terrain features within the given radius of the given point that support the indicated type of change and returns a list of all possible values supported for this type of change.

Parameters:

• changeType: String representing the type of dynamic terrain change to search for
• location: The starting point to search from
• radius:
• searchRadius: The distance from the point to perform the search

Return values:

1. Returns a list of strings representing the valid values for this type of terrain change
2. Boolean indicating if the data is yet available for this call to succeed

getEmbarkationEgressPoints (simObject)

Queries the simObject for its embarkation egress points.

Parameters:

• simObject: The object whose embarkation slot information you wish to query.

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a list of slot information for all egress points on the entity. The information for each egress point in the list is a table that includes the following fields: {egress_positions = {DtVectorOffset3D, DtVectorOffset3D, ...}

getEmbarkationSlots (simObject, bool, bAllSlots)

Queries the simObject for its embarkation slot information. If the boolean flag is true, all slots are returned. If false, only those that can be used by the caller are returned.

Parameters:

• simObject: The object whose embarkation slot information you wish to query.
• bool:
• bAllSlots: A boolean that indicates to return all the slots.

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a list of slot information for all slots on the entity that can be used by the calling entity. The information for each slot in the list is a table that includes the following fields:
slot_number - The slot number reserved. Should match the input slotNumber unless it was -1, in which case it will be the assigned slot.
slot_name - The name assigned to this slot.
slot_type - String identifying the type of slot.
slot_position - VectorOffset3D specifying the offset location of the slot on the entity being embarked upon.
occupied - Boolean indicating whether the slot is currently occupied.
available - Boolean indicating whether the slot is currently available to this entity.

getEmbarkationSlots (simObject, bool, bAllSlots)

Queries the simObject for its embarkation slot information. If the boolean flag is true, all slots are returned. If false, only those that can be used by the caller are returned.

Parameters:

• simObject: The object whose embarkation slot information you wish to query.
• bool:
• bAllSlots: A boolean that indicates to return all the slots.

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a list of slot information for all slots on the entity that can be used by the calling entity. The information for each slot in the list is a table that includes the following fields:
slot_number - The slot number reserved. Should match the input slotNumber unless it was -1, in which case it will be the assigned slot.
slot_name - The name assigned to this slot.
slot_type - String identifying the type of slot.
slot_position - VectorOffset3D specifying the offset location of the slot on the entity being embarked upon.
occupied - Boolean indicating whether the slot is currently occupied.
available - Boolean indicating whether the slot is currently available to this entity.

getEntityTypesForEquipment (equipmentType)

Finds the Entity Types in the current VRF parameter database that have a table in their parameter properties called "Base-Primary-Equipment", and a Type field in this table with a value that matches equipmentType. This property is expected in many entities in the AggregateLevel SMS.

Parameters:

• equipmentType: A string giving the name of the equipment type to find.

Return value:

A table of strings listing the types that have this equipment. If the table is empty, no types match.

getEpochTime ()

Provides the exercise date and time in UTC.
The exercise time at the start of the scenario is taken from the saved state of the global environmental object. This time can be set from the GUI. See the User's Guide for more details.

Return value:

Real number representing the current time as the number of seconds since 1/1/1970.

getExerciseTime ()

Provides the exercise date-time, where the exercise date-time is always 10:00AM UTC on the date of scenario creation at the start of the simulation run. Or, this start time can be viewed as 1000 "local time," where "local" is usually where the first entity in the scenario was placed. However, there isn't a function that converts "local" to UTC, so this time can't be compared to a value in a date-time parameter. Exercise time is really only useful in a comparison to another exercise time to determine an elapsed time.

Return value:

Returns the number of seconds since midnight 1/1/1970 of the current exercise date-time.

getExpectedIllumination (where, when)

Returns the expected illumination value at the location and time indicated. Only considers illumination from the sun, not from any other light source.

Parameters:

• where: Either
  • a Location3D at which to get the environment information, or
  • a SimObject. The SimObject may be either a weather object, a SimObject that has an associated weather object, or any other SimObject. In the last case, the location of the SimObject is used to define the location at which to get the environment information.
• when: The date and time of day at which to get the environment information.

Return value:

the value of the illumination intensity, which is a number between 0 and 1.

getFeatures (type)

Return a FeatureSet class can be used to access all the features which match a given query. The returned feature set will cause entire feature layers to be paged in so should not be used unless this is the desired behavior. For generate usage see getFeaturesWithinRange or getFeaturesInArea.

Parameters:

• type: Feature query name defined in featureconfig.txt. If type is not present then the returned FeatureSet will represent all features.

Usage:

getFeatures("MAK_OBSTACLE")

Return value:

A FeatureSet object that can be used to check for queries results.

getFeaturesWithinArea (points, attributes)

Return a FeatureSet class which can be used to return information about features within a certain geometric area. The geometric area supplied will be considered a closed area. Check the isLoaded member of the returned object to make sure all data is available. This should be done before any request is made. If a request is made on an unloaded feature set an exception will be thrown. The attributes supplied will be considered to be ANDed together, except for the ispoint, isareal and inlinear which will be ORed

Parameters:

• points: The list (table) of points that define the area in which to search.
• attributes: The attributes to apply to the search, or no attributes. The attributes are the values specified for each feature (as in a shape attribute) or the following defined attributes:
  query= - Use a previously stored named query. See the feature documentation for how to create named queries
  ispoint=true - Return all point objects within the area
  isareal=true - Return all areal objects within the area
  islinear=true - Return all linear objects within the area
  

Usage:

getFeaturesWithinArea(locations, {isarea=true})

Return value:

A FeatureSet object that can be used to check for queries results

getFeaturesWithinRange (center, range, attributes)

Return a FeatureSet class which can be used to return information about features within a certain range around a center point. The geometry searched will be a bounding area of square range around the center point Check the isLoaded member of the returned object to make sure all data is available. This should be done before any request is made. If a request is made on an unloaded feature set an exception will be thrown. The attributes supplied will be considered to be ANDed together, except for the ispoint, isareal and inlinear which will be ORed

Parameters:

• center: The point to use as the center of the search area
• range: Range, in meters, of the search box
• attributes: The attributes to apply to the search, or no attributes. The attributes are the values specified for each feature (as in a shape attribute) or the following defined attributes:
  query= - Use a previously stored named query. See the feature documentation for how to create named queries
  ispoint=true - Return all point objects within the area
  isareal=true - Return all areal objects within the area
  islinear=true - Return all linear objects within the area
  

Usage:

getFeaturesWithinRange(this:getLocation3D(), 50, {ispoint=true})

Return values:

1. A FeatureSet object that can be used to check for queries results
2. A FeatureSet object that can be used to check for queries results

getGroundAltitude (latitude, longitude)

Gets the ground altitude at the given 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: Location latitude in radians.
• longitude: Location longitude in radians.

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.

getIllumination (where)

Returns the illumination value at the location indicated.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the value of the illumination intensity, which is a number between 0 and 1.

getMagneticDeclination (location)

Gets the magnetic declination at the given location. Add declination to heading to convert from Magnetic to True. Subtract declination from heading to convert from True to Magnetic.

Parameters:

• location: as a DtLocation3D, at which to get the magnetic declination

Return value:

Number indicating the magnetic declination in radians.

getOrbatList ()

Provides the ORBAT (order of battle) currently loaded. The ORBAT is returned as a list of tables, where each table contains the following key-value pairs:

• markingText - The marking text of the ORBAT item
• entityType - Entity type of the ORBAT type
• uuid - uuid of the ORBAT item
• parentUUID - parentUUUID of the ORBAT item (or blank)
• force - force of the ORBAT item
• created - true if created

Return value:

Returns a list of all entities in the ORBAT (order of battle) that is loaded.

getParameterPropertyFromType (entityType, propertyName)

Gets the field values for the given named parameter (static) property in the given type of entity (not a particular entity).

Parameters:

• entityType: A type string (e.g. "11:1:225:4:1:0:0")
• propertyName: A string; the name of the property to be retrieved.

Usage:

property = this:getParameterPropertyFromType(entityType, propertyName)

Return value:

Returns a value or a table containing field names and values. If the type has no parameter database entry, or the property is not found, nil is returned.

getParameterSubordinateFunctionsFromType ()

given a DtObjectTypeString, e.g. "3:11:1:225:3:2:0:127" Returns a table in the form {{,}}

Return value:

a table of string pairs in the form {{,}}

getPrecipitationInformation (where)

Returns the precipitation type and precipitation intensity at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Usage:

local precipitationType, precipitationIntensity = this:getPrecipitationInformation(object)

Return values:

1. the precipitation type. See setPrecipitationType for types.
2. the precipitation intensity, a number between 0 and 1.

getPrecipitationIntensity (where)

Returns the precipitation intensity at the indicated location.

Parameters:

• where: Location3D at which to get the environment information.

Return value:

The value of the precipitation intensity; a small number with 1.0 corresponding to maximum intensity on the GUI (currently 20mm/hr).

getPrecipitationType (where)

Returns the precipitation type at the indicated location.

Parameters:

• where: Location3D at which to get the environment information.

Return value:

the precipitation type. See setPrecipitationType for types

getRainAccumulation (where)

Returns the rain accumulation at the specified location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the snow accumulation in meters.

getReactionStatus ()

Returns a list of all enabled reactions on the entity, with the status of the reactive tasks.

Return value:

Returns a list of all enabled reactions on the entity, with the status of the reactive tasks. Data is returned as a list of tables in the following form:
{ { script_id = , priority = , active = }, ... }

getScriptAttribute (attributeName)

Gets the value of the given attribute for this script as defined in the script-enable-controller.

Parameters:

• attributeName: The name of the desired attribute.

Usage:

rainModifierByIntensity, error = vrf:getScriptAttribute("Rain-Modifier-By-Intensity")

Return values:

1. An object containing the attribute value. May be a boolean, a number, a string, or some other object. This is an object with a nil value if the attribute was not found in the system.
2. A boolean indicating whether there was an error because the an attribute of the given name was not found.

getScriptId ()

Script ID of current task being executed

Return value:

The script ID of the task being executed.

getSeaState (where)

Returns the value of the sea state at the indicated location. Only valid if wind driven sea state is enabled.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the value of the sea state, an integer. See setSeaState for values.

getSeaStateDirection (where)

Returns the direction of the sea state at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the heading of the sea state; the value is in radians.

getSimObjectByName (name)

Returns simObject of provided name if exists

Parameters:

• name: The name of the object (string)

Return value:

The SimObject with the given name or UUID. If the named SimObject does not exist, e.g. was deleted, then a SimObject will still be returned, but isValid() will return false on that object.

getSimObjectByUUID (uuid)

Returns simObject of provided UUID if exists

Parameters:

• uuid: The UUID of the object (string)

Return value:

The SimObject with the given UUID. If the SimObject does not exist, e.g. was deleted, then a SimObject will still be returned, but isValid() will return false on that object.

getSimObjectsNear (location, radius)

Gets a list (table) of all SimObjects that are within the given radius of the given location.
Some returned objects may be at a greater distance than the given radius, but no objects within the distance will be left out.
Exception: does not include the entity running the script (note-- this is new in 4.2).

Parameters:

• location: The center of the region in which to search.
• radius: The radius of the region.

Return value:

A table of SimObjects

getSimObjectsNearWithFilter (location, radius, filter)

Gets a list (table) of all SimObjects that are within the given radius of the given location. See notes for getSimObjectsNear().

Parameters:

• location: The center of the region in which to search.
• radius: The radius of the region.
• filter: Table entry of items that can be used to filter the selection. Valid values are:
  types={"<enttype>", ...} - Table list of entity types to match
  ignore={"<ent name>", ...} - Table list of entity names to ignore

Return value:

A table of SimObjects

getSimulationTime ()

The current simulation time in seconds

Return value:

A number indicating seconds elapsed in simulation time since the beginning of the simulation.

getSnowAccumulation (where)

Returns the snow accumulation at the specified location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the snow accumulation in meters.

getSnowRoadAccumulation (where)

Returns the snow road accumulation at the specified location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the snow road accumulation in meters.

getSubordinateFunctionNames ()

Returns a table of subordinate function handles and display text, e.g. { HANDLE1 = "First Function" }

Return value:

Returns a table of subordinateFunction handles and display text, e.g. { HANDLE1 = "First Function" }

getSurgeDepth (where)

Returns the surge depth of the water at the specified location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the surge depth of the water in meters.

getSwellState (where)

Returns the water swell state at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the water swell state; an integer. See luaSetSwellState for values

getSwellStateDirection (where)

Returns the direction of the swell state at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the heading of the swell state in radians.

getSystemName ()

Provides the name of the system that enabled this script (task). For example, a torpedo weapon system might enable a launch-torpedo scripted task. Note that more than one system on an entity may enable the same script, in which case this function arbitrarily returns one of them.

Return value:

The name of the system that enabled this script.

getTerrainAltitude (latitude, longitude)

Gets the terrain altitude from the physical world at the given location.

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 second value which is a boolean indicating if the altitude result is valid.

The function returns a third value that is the type of the terrain surface at the location. The value can be "Unspecified", or a value that implies ground, water, or a cultural feature. Possible values for the surface type are:
NoSurface (when no surface at all was found),
Unspecified,
GROUND--
Grass, CultivatedFields, Orchards, USRailRoad, EuroRailRoad,
(unimproved:) SoftSoil, Swamp, Mud, Forest, Rock, Boulder, Sand, DirtRoad, MuddyRoad, DryGround, WetGround, IcyGround, SnowGround, UnspecifiedEnvStateGround,
(improved: ) DirtRoad, GravelRoad, PavedRoad, AsphaltOrOtherHardSurface,
Icy, Flimsy, UndefinedSoilType.
WATER--
Ocean, DeepLake, ShallowLake, DeepRiver, ShallowRiver, DeepPond, ShallowPond, DeepStream, ShallowStream, DeepBrook, ShallowBrook, UnspecifiedBodyOfWater.
CULTURAL--
Building, Tree, UnspecifiedCulturalFeature.

Parameters:

• latitude: Location latitude in radians.
• longitude: Location longitude in radians.

Usage:

terrainElev, valid, surfaceType = vrf:getTerrainAltitude(lat, lon)

Return values:

1. Number indicating the altitude of the terrain in meters.
2. Boolean that is true if the altitude (and surface) data is valid.
3. String describing the type of surface.

getTerrainAltitudeBelow (point)

Gets the terrain altitude and surface info below the given point. The return information is the same as getTerrainAltitude, but that function returns the highest surface at a lat, lon while this function looks only below the point.

Parameters:

• point: Location3D

Return values:

1. Number indicating the altitude of the terrain in meters.
2. Boolean that is true if the altitude (and surface) data is valid.
3. String describing the type of surface. See getTerrainAltitude for description.

getTimeMultiplier ()

Provides the rate at which the simulation clock is running.

Return value:

The current time multiplier; how much faster than real time the simulation is running.

getTimeOfDay ()

Returns the time of day, in seconds since midnight.

Return value:

Number representing the time of day in seconds since midnight.

getUnderwaterVisibility (where)

Returns the visibility underwater in at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the visibility underwater in meters.

getVisibilityDistance (where)

Returns the visibility at the indicated location.

Parameters:

• where: a Location3D at which to get the environment information

Return value:

the visibility distance in meters.

getVisibilityObscurant (where)

Returns the visibility obscurant at the indicated location.

Parameters:

• where: a Location3D at which to get the environment information

Return value:

See VisibilityObscurant in makArchives::DtEnvironmentRecord for obscurant types

getVrfObjects ()

Returns list of all simobjects

Return value:

Returns a list of all objects in the simulation as SimObjects

getWallClockTime ()

The wall clock time in seconds from 1/1/1970

Return value:

A number indicating seconds of wall clock time.

getWeaponSystemsInfoFor (simObject)

Queries the simObject for its weapon system information.

Parameters:

• simObject: The object whose information you wish to query.

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return the results (see AsyncJob). The results table will be in the form: {{"<weaponName>","<weaponType>",{"<resourceName>","<resourceName>"...},{"<weaponName>","<weaponType>",{"<resourceName>","<resourceName>"...}, ...} @usage checkpointState.job = vrf:getWeaponSystemsInfo(subject) ... local results, index, msg = checkpointState.job:getObject()

getWindDirection (where)

Returns the direction of the wind at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the heading of the wind in radians.

getWindSpeed (where)

Returns the speed of the wind at the indicated location.

Parameters:

• where: Location3D at which to get the environment information

Return value:

the speed of the wind in meters/second.

isScenarioEventEnabled (event)

Returns true if the scenario event is enabled

Parameters:

• event: A simObject. The scenario event. If the object given is not valid a warning will be give

Usage:

vrf:isScenarioEventEnabled(EventObject)

isScenarioEventPlaying (event)

Returns true if the scenario event is playing

Parameters:

• event: A simObject. The scenario event. If the object given is not valid a warning will be give

Usage:

vrf:isScenarioEventPlaying(EventObject)

isSetAvailable (setName)

Checks whether the specified set name is a valid set for this entity.

Parameters:

• setName: String name of a set. See the "Sets" section of the doc for possible names.

Return value:

True if the set is valid for this entity.

isSubtaskCanceled (taskId)

Checks the if a subtask started by this script was canceled.

Parameters:

• taskId: The ID of the task to check.

Return value:

True if the subtask has been canceled. A task is canceled when it is overridden by another task, or has been explicitly stopped.

isSubtaskComplete (taskId)

Checks the completed state of a subtask started by this script.

Parameters:

• taskId: The ID of the task to check.

Return value:

True if the subtask has completed. Completion does not mean the task was successful. The completion result may be checked by subtaskResult() if this returns true.

isSubtaskRunning (taskId)

Checks if a subtask for this entity is running based on the task ID. A subtask will not be running if it failed to start, completed, or was canceled.

Parameters:

• taskId: The ID of the task to check.

Return value:

True if the subtask is still running, false otherwise.

isTaskAvailable (taskName)

Checks whether the specified task name is a valid task for this entity.

Parameters:

• taskName: String name of a task. See the "Tasks" section of the doc for possible names.

Return value:

True if the task is valid for this entity.

isTaskCanceled (taskId)

Checks the if a task started by this script was canceled.

Parameters:

• taskId: The ID of the task to check.

Return value:

True if the task has been canceled. A task is canceled when it is overridden by another task, or has been explicitly stopped.

isTaskComplete (taskId)

Checks the completed state of a task started by this script.

Parameters:

• taskId: The ID of the task to check.

Return value:

True if the task has completed. Completion does not mean the task was successful. The completion result may be checked by taskResult() if this returns true.

isTaskRunning (taskId)

Checks if a task for this entity is running based on the task ID. A task will not be running if it failed to start, completed, or was canceled.

Parameters:

• taskId: The ID of the task to check.

Return value:

True if the task is still running, false otherwise.

makeAreaGeometry (table)

Return a FeatureGeometry object representing an area.

Parameters:

• table: A luabind table representing the boundary of the object.

Return value:

FeatureGeometry object representing the area.

makeOffsetRoute (points, vectorOffset, minimumTurnRadius)

Create a table of points that are offset from another table of points, given offset forward, right, up

Parameters:

• points: A table of Location3D points.
  
• vectorOffset: A VectorOffset3D
  
• minimumTurnRadius: (optional) A number that indicates the minimum turn radius to assume for the turns (arcs) that connect the segments of the output path. The default value is 0.0.

Usage:

makeOffsetPoints({Location3D table}, VectorOffset3D, this:getParameter("turning-radius"))

Return value:

A table of Location3D points offset from the original.

makePathGeometry (table)

Return a FeatureGeometry object representing a path (a linear geometry).

Parameters:

• table: A luabind table defining the path.

Return value:

FeatureGeometry object representing the path.

makePointGeometry (point)

Return a FeatureGeometry object representing a point.

Parameters:

• point: Location3D of the desired point.

Usage:

makePointGeometry(this:getLocation3D())

Return value:

FeatureGeometry object representing the point.

navigateThroughFeatures (table_of_parameters)

The output path object will be the input altered as to move around the features.

Parameters:

• table_of_parameters: A table containing parameters in a key=value form. The allowed keys are below:
  • buffer Number of meters to apply to geometry buffer operation. Buffer "grows" the geometries so it can be used to account for width.
  • obstacleQuery If supplied it will be treated as the text of a feature query and applied on top of the named query. This can be used to further refine the search within one feature set.
  • pathQuery If supplied it will be used to select features for road graph path planning.
  • start Location3D; starting location of path.
  • destination Location3D; ending location of path.

Usage:

vrf:navigateThroughFeatures({start=this:getLocation3D(), destination=myEnd, buffer=myWidth})

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a table of points describing a path between the input points.

playScenarioEvent (event)

Will start to play the given scenario event.

Parameters:

• event: A simObject. The event to play. If the object given is not valid a warning will be give

Usage:

vrf:playScenarioEvent(EventObject)

printLLL (message)

A set of 5 print functions, one for each notification level LLL. Generally the Vrfutil print functions should be used instead; see documentation in the Printing module.

Parameters:

• message: A string to print. Must end with a newline character (\n) to flush the output and separate output lines.

processGraphCommands (dotCommandString)

Causes the VRF script interface to process the dot-language graph description in the given string and send it to the GUI for display in the entity information panel.

Parameters:

• dotCommandString: string Contains the dot commands.

Return value:

Nothing.

registerForObjectMessage (messageType)

Registers interest in a specific type of object message. Once called, this script will have its receiveObjectMessage(messageType, message, sender) function called any time the object running this script receives a message of this type. This only works for message types that have been registered with the lua system. The following Object Message Types are available:

• request-air-refuel-initial-point
• air-refuel-initial-point-response
• refuel-request
• refuel-response
• initiate-refuel-rendezvous
• initiate-refuel
• refuel-position-request
• refuel-position
• release-refuel-position
• refuel-complete
• cancel-refuel

Parameters:

• messageType: Registered name of the object message type (string).

removePostSetDataCallback (setDataType, functionName)

Removes a post-set data request callback. If this is called while there is still a pending callback on an executed

Parameters:

• setDataType: (string) The type of set data request to register interest in, for example "set-restore"
• functionName: (string) the name of the lua function to call in response to the specified type of set data request being executed. For example, "setRestoreCallback".

require (moduleName)

Loads and runs Lua libraries. Similar to the Lua require command, but caches loaded modules as bytecode for faster subsequent loading, reducing load time. The search path for modules is always the SMS scripts directory (e.g. data/simulationModelSets/EntityLevel/scripts) followed by makLua and userData/scripts. If additional script directories are needed, the Lua require command is the preferred method.
Note that this function does not return the result of the Lua require call, so it is not possible to use the return value, as in for example

 FSM = require("fsm2")
 newFsm = FSM.new()

Instead, write

 vrf:require("fsm2")
 newFsm = fsm2.new() 

Parameters:

• moduleName: The name of module to be loaded and run. If the module is in a subdirectory, the path should be written with "/" instead of ".".

Usage:

vrf:require("vrfutil") 

 For a module in a subdirectory, write 
 
 vrf:require("myModules/myUtil") 
 instead of 
 
 require "myModules.myUtil" 

reserveEmbarkationSlot (simObject, slotNumber)

Attempts to reserve an embarkation slot for this entity.

Parameters:

• simObject: The object this entity is trying to embark on.
• slotNumber: The slot number the entity is trying to embark in. -1 indicates any available slot.

Return value:

An AsyncJob object. When the job successfully completes, a call to job:getObject() will return a table with information on the result of the reservation request. The table includes the following fields:
available - Boolean indicating whether the slot is currently available to this entity, i.e. the reservation was successful. slot_number - The slot number reserved. Should match the input slotNumber unless it was -1, in which case it will be the assigned slot. slot_position - Vector3D specifying the offset location of the slot on the entity being embarked upon. slot_orientation - Vector3D specifying the offset orientation of the slot from the orientation of the entity being embarked upon.

runDurationTime ()

Returns amoun of time in seconds the simulation is scheduled to run for. See runForDuration

Return value:

Amount of time simulation is scheduled to run for. If 0 then it is scheduled to run infinitely.

runForDuration (duration)

Sets a timer to run the simulation for the given amount of time, starting at the current time. Once the amount of time has passed the simulation will pause.

Parameters:

• duration: Time (in seconds) to run the simulation for.

sendEmbeddedEntitySet (eeName, setName, parms)

Performs an implicit deployment of the Embedded Entity if necessary then sends the given set request to the corresponding SimObject.
See sendSetData() for further details.

Important note:

sendEmbeddedEntityTask() and sendEmbeddedEntitySet() implicitly begin a task to ensure the Embedded Entity being referenced is deployed, which takes a minimum of one sim tick to complete. As such, tasks and sets sent using these methods will cancel each other when referring to the same Embedded Entity even when the task or set being sent would not usually cause cancellation. For this reason, it is often more appropriate to use the standard sendTask() and sendSetData() for intricate tasks, after it has been verified that the Embedded Entity has been deployed.

Parameters:

• eeName: Name of the Embedded Entity to perform the task.
• setName: Name of the set request to be sent.
• parms: Parameter table for the indicated set request.

Usage:

setTaskId = vrf:sendEmbeddedEntitySet(taskParameters.ee1, "set-notify-level", {notify_level = 2})

Return value:

The task ID of the implicit task started that ensures the Embedded Entity is deployed.

sendEmbeddedEntityTask (eeName, taskName, parms, actAsSubtask)

Performs an implicit deployment of the Embedded Entity if necessary then sends the given task to the corresponding SimObject.
See sendTask() for further details.

Important note:

sendEmbeddedEntityTask() and sendEmbeddedEntitySet() implicitly begin a task to ensure the Embedded Entity being referenced is deployed, which takes a minimum of one sim tick to complete. As such, tasks and sets sent using these methods will cancel each other when referring to the same Embedded Entity even when the task or set being sent would not usually cause cancellation. For this reason, it is often more appropriate to use the standard sendTask() and sendSetData() for intricate tasks, after it has been verified that the Embedded Entity has been deployed.

Parameters:

• eeName: Name of the Embedded Entity to perform the task.
• taskName: Name of the task to be performed.
• parms: Parameter table for the indicated task.
• actAsSubtask: True to treat the sent task as a subtask and thus wait for it to complete before considering this task complete. Otherwise, isTaskComplete() etc. will return true once the Embedded Entity has been deployed and the task sent.

Usage:

taskId = vrf:sendEmbeddedEntityTask(taskParameters.ee1, "turn-to-heading", {heading = 0.0})

Return value:

The task ID of the started task, or -1 if the task failed.

sendInfluence (target, influenceName, influenceParams)

Sends an Influence interaction to the target.
APPLICABLE ONLY WHEN USING AGGREGATE SIMULATION AND HLA.

Parameters:

• target: SimObject the Influence targeted at.
• influenceName: String specifying the name of Influence (see table below).
• influenceParams: All other Influence parameters are specified in table. The index for each item in the table should be the parameter name in the FOM. The following parameters should be specified for the indicated influences:

  Influence Name	Parameters
  Engagement	InfluenceType ("Anti-Tank", etc.) Strength Duration Location (i.e. target location) HitFactor ProbabilityKilled ProbabilityCaptured ProbabilityWounded WeaponType GuidanceSystem TargetPart IsPointAttack StopInfluence
  Engagement.IndirectFire	Same as above.
  Jamming	InfluenceType ("Comms" or "Radar") Strength StopInfluence
  ImproveEngineeringObject	Strength StopInfluence
  ProvidingSupplies	InfluenceType (, only for one-time transfer) Strength (amount, only for one-time transfer) StopInfluence (for continuous resupply)

Return value:

Nothing

sendMessage (recipient, message)

Sends a text message to the recipient. This message is sent using the "sim internal" communications, not the radio system.

Parameters:

• recipient: SimObject the message is being sent to.
• message: String containing the text message.

sendObjectMessage (recipient, messageType, message)

Sends a message to a specified object using the "sim internal" communication mechanism. The message must be defined in the C++ layer and be enabled for sending from Lua.

Parameters:

• recipient: SimObject the message is being sent to.
• messageType: String identifying the message type to be used. This will match the C++ AdminContent type for the message
• message: Table with the contents of the message. The table is formatted as key/value pairs, which are specific to the messageType being sent. The following Object Message Types are available:

  Message Type	Message Parameters
  request-air-refuel-initial-point	Empty Table. i.e. {}
  air-refuel-initial-point-response	initial-point (Location3D) Location of the Air Refuel Initial Point (ARIP)
  refuel-request	fuel-system-type (string) 7-digit EntityType
  refuel-response	refuel-response (bool; where accepted is true; rejected is false)
  initiate-refuel-rendezvous	coordinate-point (Location3D) coordinate-time (time in seconds) heading (radians)
  initiate-refuel	num-positions (int)
  refuel-position-request	refuel-method (int; 0 = Boom, 1 = Drogue)
  refuel-position	position-id (int) position-offset (x,y,z offset as VectorOffset3D)
  release-refuel-position	position-id (int)
  refuel-complete	Empty Table. i.e. {}
  cancel-refuel	Empty Table. i.e. {}

  
  

Usage:

• vrf:sendObjectMessage(taskParameter.recipient, "air-refuel-initial-point-response", {initial-point = taskParameter.point:getLocation3D()})

• vrf:sendObjectMessage(taskParameter.recipient, "cancel-refuel", {}) 

sendRadioMessage (recipient, message)

Sends a text message to the recipient via the radio network.

Parameters:

• recipient: SimObject the message is being sent to. Alternatively, this can be the string "DtBroadcast", in which case the message will go to all recipients that the comms model connects this entity to (see commModelParams.mtl).
• message: String containing the text message.

sendRadioObjectMessage (recipient, messageType, message)

Sends a message to a specified object via the radio network. The message must be defined in the C++ layer and be enabled for sending from Lua.

Parameters:

• recipient: SimObject the message is being sent to.
• messageType: String identifying the message type to be used. This will match the C++ AdminContent type for the message
• message: Table with the contents of the message. The table is formatted as key/value pairs, which are specific to the messageType being sent.

sendRadioSetData (entity, setName, parameters)

See doc for sendSetData. This function is equivalent except will send set on radio network Not all entities are capable of accepting all set data requests.
This function will throw an error if an invalid set name or invalid parameter is specified.

Parameters:

• entity: SimObject to receive the set data request.
• setName: String from the list of available sets. See the "Sets" reference section for the list of valid set names.
• parameters: A table of parameters for the set being sent. The parameter names must be valid for the specified setName. See the "Sets" reference section for the valid parameters. Any parameters not included will assume their default value.

Usage:

vrf:sendSetData(subordinate, "set-lifeform-posture", {lifeform_posture = "standing"})

sendRadioTask (entity, taskName, parameters, actAsSubtask)

See documentation for sendTask. This lua function acts exactly as that except it will use the radio network to send the task

Parameters:

• entity:
• taskName:
• parameters:
• actAsSubtask:

sendReport (reportName, recipients, parameters)

Sends a single report of the given report reader/writer name (i.e. "spot-report") as a report object. This report is sent to the entire network if recipients are blank, or to the list of recipient names is not-blank. The report is sent using the radio interface rather than the VR-Forces internal communication interface.
This function will throw an error if an invalid set name or invalid parameter is specified.
The following report types are available:

Report Name	Parameters
spot-report	contact-info (see usage info below) spotter or spotter-name spotter-mt (marking text, string) spotter-ft (force type, integer) engagement-result (string) use-ground-truth (boolean) reason (NewContact = 0, PeriodicRefresh = 1, StateUpdate = 2, Resend = 3) < / li> expiration-time Note that parameters date-and-report-time and simulation-report-time are set automatically; the script should not set them.
text-report	text (string)
engagement-report	reporter-name report-time date-and-time (number) engagements (Table of: target-name, target-location, engagement-complete, number-killed, number-captured, original-date-and-time-of-contact)

Parameters:

• reportName: Registered name of the report type (string).
• recipients: [optional] Names of entities to receive reports. If omitted, report is broadcast.
• parameters: A table of parameters for the report being sent. The parameters are the reader/writer names with a value after the name. For details on the reader/writers supported by a report, please see that report's header file (e.g. spotReport.h). If the reader/writer name has a - character, then substitute with underscores.
  

Usage:

• vrf:sendReport("spot-report",
   {contact_info= 
   {contact=contactEntity:getUUID(), contact_name=contactEntity:getName(),
   contact_type=contactEntity:getEntityType(), combat_identification_level=3,
   last_detection_time=vrf:getSimulationTime()}, 
   spotter_name=this, 
   simulation_report_time=vrf:getSimulationTime(),
   expiration_time=60,
   use_ground_truth=true})

• vrf:sendReport("spot-report", {"M1A2 1"}, 
   {contact_info= 
   {contact=contactEntity:getUUID(), contact_name=contactEntity:getName(),
   contact_type=contactEntity:getEntityType(), combat_identification_level=3,
   last_detection_time=vrf:getSimulationTime()},
   spotter_name=this, 
   simulation_report_time=vrf:getSimulationTime(),
   expiration_time=60,
   use_ground_truth=true}) 

sendSetData (entity, setName, parameters)

Send a set data request to an entity other than the ownship. The parameters vary depending on the name of the set. If a set data request does not have parameters, you must include empty braces in the command, for example: vrf:sendSetData("set-destroy", {}) Not all entities are capable of accepting all set data requests.
This function will throw an error if an invalid set name or invalid parameter is specified.

Parameters:

• entity: SimObject to receive the set data request.
• setName: String from the list of available sets. See the "Sets" reference section for the list of valid set names.
• parameters: A table of parameters for the set being sent. The parameter names must be valid for the specified setName. See the "Sets" reference section for the valid parameters. Any parameters not included will assume their default value.

Usage:

vrf:sendSetData(subordinate, "set-lifeform-posture", {lifeform_posture = "standing"})

sendTask (entity, taskName, parameters, actAsSubtask)

Starts a task on another entity. The task name and parameters vary from task to task. Do not use this function to start a task on the ownship entity. Note that not all entities can perform all tasks. If a task is send to an entity which is incapable of performing it, the task will complete with a failure result.
Once a task is started, the task ID returned by this function can be used to check it's status. A task will be in one of three states: Running, Complete, or Canceled. A task that entered the Complete state will have a result of either success (true) or failure (false). See the list below for various reasons a task will enter the various states:

• Complete (success): The task has completed, and called endTask(true) to end itself.
• Complete (failure): One of:
  • The task has ended itself by calling endTask(false)
  • The task failed to start because the entity was incapable of executing this task
• Canceled: One of:
  • The task was explicitly canceled using stopTask()
  • The task was replaced by another conflicting task was started.
  • An explicit "Skip Task" from the user.
• Running: The task was started, but has not completed or been canceled.

Parameters:

• entity: SimObject; the entity to which the task will be sent.
• taskName: The name (string) of the task. This may be either the name of a built-in task from the "Tasks" list in this documentation, or the ScriptID string of another scripted task.
• parameters: A table of parameters used to start the task. The parameters available depend on the taskName. A reference of parameters for each built-in task is available in the "Tasks" list in this documentation. For scripted tasks, the parameter names match the parameter names configured in that scripted task. Any parameters that are not specified in the table will assume the default value.
• actAsSubtask: Assign task as a subtask. If true (the default), then if the sending task completes, the subtask will also end. If false, the sent task is considered independent of the sending task, and will not end when the sending task completes. The task ID returned is -1 when actAsSubatask if false. This parameter is not available to background processes, where actAsSubtask is always false.

Usage:

taskId = vrf:sendTask(entity1, "move-to", {destination = "Waypoint 1"}, false) 
 This function will throw an error if the taskName is not known, or any invalid parameters are specified.

Return value:

The task ID of the started task, or -1 if the task is independent or sending the task failed.

setCheckpointMode (flag)

Sets whether or not the checkpoint mode saves just the checkpointState table (true) or all globals (false).

Parameters:

• flag: A boolean indicating whether to save only the checkpointState table. Note that constants CheckpointStateOnly (= true) and AllGlobals (= false) have been defined in module vrfutil to make the use of this function clearer.

Usage:

vrf:setCheckpointMode(AllGlobals)

setGraphCapable ()

Tells VR-Forces that this script can generate graphical status output (by calling vrf:processGraphCommands). The script interface will not return shouldGenerateGraphOutput true if this function is not called.

setInterest (center, radius)

If this application is using interest management in the network simulation protocol, this function will set the area of interest of the application.

Parameters:

• center: (Location3D) The center of the (circular) interest area.
• radius: (number) The radius of the interest area.

setRespondToNewSensorContacts (enable)

Sets whether this script should respond to new sensor contacts. If true, when there is a new sensor contact - or an existing sensor contact has new information - the script's next tick time is set to current sim time, so the script will tick again as soon as possible. For reactive tasks, the check function will also be run as soon as possible, if applicable.

Parameters:

• enable: A Boolean; true to enable new contact response, and false to disable it.

setScenarioEventEnabled (event, enabled)

Enable or disable a scenario event. If the event is playing and then it is disabled it will stop playing

Parameters:

• event: A simObject. The event to play. If the object given is not valid a warning will be given.
• enabled: The flag to enable or disable

Usage:

vrf:playScenarioEvent(EventObject, true)

setTickPeriod (seconds)

Sets the amount of simulation time in between each script tick. Default is 1/2 second. Will also add a random amount of time between 0 and the time period or 1 second (whichever is lower)

Parameters:

• seconds: The period time (in seconds) to tick the script

setTickWhilePaused (enable)

Sets whether the script should be ticked while the simulation is paused. By default this is disabled.

Parameters:

• enable: A Boolean; true to enable ticking while paused, and false to disable.

shouldGenerateGraphOutput ()

Returns a boolean that lets the script know if the GUI wants to display debug graph output from this script. The script should call this before generating graph output. If false, the GUI will not display anything, so the script should not bother generating a graph. If true, the script should begin generating graph commands whenever its state changes, writing them to a file, and calling vrf:processGraphCommands().

Return value:

bool Indicator that the script should generate a graph.

startSubtask (taskName, parameters)

Starts a subtask on the ownship entity. The task name and parameters vary from task to task.
Once a task is started, the task ID returned by this function can be used to check it's status. A task will be in one of three states: Running, Complete, or Canceled. A task that entered the Complete state will have a result of either success (true) or failure (false). See the list below for various reasons a task will enter the various states:

• Complete (success): The task has completed, and called endTask(true) to end itself.
• Complete (failure): One of:
  • The task has ended itself by calling endTask(false)
  • The task failed to start because the entity was incapable of executing this task
• Canceled: One of:
  • The task was explicitly canceled using stopTask()
  • The task was replaced by another conflicting task was started.
  • An explicit "Skip Task" from the user.
• Running: The task was started, but has not completed or been canceled.

Parameters:

• taskName: The name (string) of the task. This may be either the name of a built-in task from the "Tasks" list in this documentation, or the ScriptID string of another scripted task.
• parameters: A table of parameters used to start the task. The parameters available depend on the taskName. A reference of parameters for each built-in task is available in the "Tasks" list in this documentation. For scripted tasks, the parameter names match the parameter names configured in that scripted task. Any parameters that are not specified in the table will assume the default value.

Usage:

taskId = vrf:startSubtask("move-to", {destination = "Waypoint 1"})

Return value:

The task ID (number) of the started task, or -1 if the task failed.

statusOfUserQuestion (questionId)

Retrieves the status of the question asked by the question id.

Parameters:

• questionId: Question to return information about

Return value:

-1 if the question has not yet been answered or 0 - n which will be the option the user selected

stopAllSubtasks ()

Stops all subtasks that have been started by this task and are still running. This applies only to subtasks started with startSubtask(), and not to tasks.

stopAllTasks ()

Stops all tasks that have been started by this task and are still running. This only applies to tasks started with sendTask(), not subtasks.

stopScenarioEvent (event, reset)

Will start to play the given scenario event.

Parameters:

• event: A simObject. The event to stop. If the object given is not valid a warning will be give
• reset: (Optional) Boolean. If true will reset the scenario event to be played again via a start time or the gui. A subsequent call to playScenarioEvent will still start the event even if the event is not reset. Default true.

Usage:

vrf:stopScenarioEvent(EventObject, false)

stopSimulationDurationTimer ()

Cancels the timer set by vrf:runForDuration(); the simulation will continue without automatically pausing. If there is no timer active this call will have no effect

stopSubtask (taskId)

Stops a subtask that is currently running on the ownship entity.

Parameters:

• taskId: Task ID of the subtask you wish to stop on this entity, as provided by startSubtask when the task was started.

stopTask (taskId)

Stops task that was started by this script. This will result in a "canceled" status for this task.

Parameters:

• taskId: Task ID of the task you wish to stop.

subtaskResult (taskId)

Checks the completion result of a subtask started by this script. This call is only valid if the task in question has completed. If it has not, then False will be returned.

Parameters:

• taskId: The ID of the task to check.

Return value:

True if the task completion result was successful, and false otherwise. This is the value of the parameter passed to vrf:endTask() to end a task.

taskResult (taskId)

Checks the completion result of a task started by this script. This call is only valid if the task in question has completed. If it has not, then False will be returned.

Parameters:

• taskId: The ID of the task to check.

Return value:

True if the task completion result was successful, and false otherwise. This is the value of the parameter passed to vrf:endTask() to end a task.

trUtf8 (message)

Converts the message from a string to a TranslatableStream for possible translation to the current display language, and then output to the entity console.

Parameters:

• message: The message string. This string may have substitution parameters in it ("%1", "%2", etc.) that can be filled in with variable values. See the documentation for TranslatableStream and the Printing module.

Usage:

• printWarn(vrf:trUtf8("Out of %1"):arg(resourceName))

• printWarn(vrf:trUtf8("Out of Fuel."))

Return value:

a TranslatableStream object

unregisterForObjectMessage (messageType)

Unregisters interest in a message that was previously registered for using registerForObjectMessage().

Parameters:

• messageType: Registered name of the object message type.

updateTaskVisualization (name, visualizationType, parameters)

Updates the task visualization with the given name to use the specified parameters, creating the visualization if necessary.

Parameters:

• name: The name of the visualization. If no visualization by this name exists, one will be created.
  
• visualizationType: A string representing the type of visualization. Valid types are "line", "point", "text", or "area".
  
• parameters: A table containing key-value pairs describing the graphic. The keys can be the following:
  color - Table containing 4 integers for red. green, blue, and opaqueness. Each takes a value from 0 to 255. If not specified, black is assumed.
  size - integer - Size of the visualization. Width of the point or thickness of line.
  location - The location reference of a single point object (points, text). Can be either a Location3D or a SimObject.
  locations - Table specifying location references of each point in a multi-point object (lines, areas). Each entry can be either a Location3D or a SimObject.
  offset - A Vector3D specifying the offset to be used for all points, either from their location or attached object.
  text - The string of text to display for text objects.
  start_arrow - Boolean indicating if a line object should have an arrow at its start.
  end_arrow - Boolean indicating if a line object should have an arrow at its end.
  

Usage:

updateTaskVisualization("name", "point", {color={255,0,0,255}, location=loc3d})

Return value:

Whether the visualization was able to be updated.