VR-Forces 5.1.1 Lua Function Documentation

weaponUtils

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


Weapon Utilities

Summary

Provides functions for the use of weaponInfo data on the host entity.

Dependencies

Please make sure that this is preceded by these inclusions:

require "vrfutil"

Usage

require "weaponUtils"

Function List

canAutonomousFireOn (targetType) Use weapon info to determine if any weapon is configured to autonomously fire on the specified target type.
canWeaponSuppress (weaponInfo) Return whether or not a weapon has the "allow-suppress" weapon property set to true.
createFireTask (weaponInfo, targetLocRef) Checks for a custom fire task defined in Lua and returns that if found.
createFireTaskForTarget (targetLocRef, options) Find a weapon which can fire on the specified target and generate a task to instruct that weapon to fire on that target.
customFireTask (weapInfo, targetLocRef) Gets the custom fire task from TheCustomFireTaskTable, if there is one for this weapon.
findWeaponIdForFireTask (fireTask) Searches the weapon info list on the host entity and returns the first weapon it finds that can execute the specified fire task type.
isWeaponBusy (weapInfo) Determines if the weapon is busy.
isWeaponDisabled (weapInfo) Determines if the weapon is disabled.
isWeaponOutOfAmmunition (weapInfo) Determines if the weapon has ammunition.
isWeaponStowed (weapInfo) Determines if the weapon is stowed.
isWeaponSuppressed (weapInfo) Determines if the weapon is suppressed.
parseWeaponSystem (weaponStr) Parses a weapon string typically passed as a task parameter from VRF GUI to determine the weapon ID and potentially specified ammo.
printAllWeaponInfo (printFcn) Prints the contents of all weapons for this entity.
printWeaponInfo (weapInfo, printFcn) Prints the contents of a WeaponInfo structure.
prioritizeTargets (targets) Sorts a list of SimObjects for target prioritization.


Functions

canAutonomousFireOn (targetType)
Use weapon info to determine if any weapon is configured to autonomously fire on the specified target type.

Parameters:

  • targetType: (string) An entity type string.

Return value:

    (boolean) True if allowed
canWeaponSuppress (weaponInfo)
Return whether or not a weapon has the "allow-suppress" weapon property set to true.

Parameters:

  • weaponInfo: (WeaponInfo) Weapon Info of weapon to check.

Return value:

    (boolean) Value of allow-suppress property, or true if property is not specified.
createFireTask (weaponInfo, targetLocRef)
Checks for a custom fire task defined in Lua and returns that if found. Otherwise, returns the fire task created by the weaponInfo directly.

Parameters:

  • weaponInfo: (WeaponInfo) The weapon of interest.
  • targetLocRef: (LocationReference) The target location.
createFireTaskForTarget (targetLocRef, options)
Find a weapon which can fire on the specified target and generate a task to instruct that weapon to fire on that target. This fire task is returned in a form that is appropriate to pass to vrf:startSubtask() and similar functions.

Parameters:

  • targetLocRef: (LocationReference) A target for the weapon.
  • options: (table) Contains a list of optional arguments that can be specified:
    • autonomousOnly (bool) If true, then only weapons marked as AutonomousFire are considered. Defaults to false.
    • weaponList (list) List of weaponIds. If specified, only weapons from this list will be considered. Otherwise all weapons will be considered.
    • suppressOnly> (bool) If true, only weapons that can suppress targets are considered.

Return values:

  1. (table) A fire task in the form {name = taskType, paramters = taskParameters} if a valid weapon and task can be found, or nil if nothing is found.
  2. (WeaponInfo) weapon info for used weapon as second return value
customFireTask (weapInfo, targetLocRef)
Gets the custom fire task from TheCustomFireTaskTable, if there is one for this weapon. The function searches through the fire tasks in the weaponInfo and looks for each of them in TheCustomFireTaskTable. If it finds an entry in the table, it runs the function found to get the task parameters and fills in the return table. The first fire task found is returned.

Parameters:

  • weapInfo: (WeaponInfo) The info object for the weapon.
  • targetLocRef: (LocationReference) The target location.

Return value:

    (table) A structure with the form {name = task name string, parameters = task parameters table}. The task parameters table is to be used when starting the given task.
findWeaponIdForFireTask (fireTask)
Searches the weapon info list on the host entity and returns the first weapon it finds that can execute the specified fire task type.

Parameters:

  • fireTask: (string) The name of the fire task.

Return value:

    weapon ID or nil if no weapon found.
isWeaponBusy (weapInfo)
Determines if the weapon is busy.

Parameters:

  • weapInfo: (WeaponInfo) The WeaponInfo structure for the weapon.

Return value:

    True if the weapon is out of ammunition.
isWeaponDisabled (weapInfo)
Determines if the weapon is disabled.

Parameters:

  • weapInfo: (WeaponInfo) The WeaponInfo structure for the weapon.

Return value:

    True if the weapon is out of ammunition.
isWeaponOutOfAmmunition (weapInfo)
Determines if the weapon has ammunition.

Parameters:

  • weapInfo: (WeaponInfo) The WeaponInfo structure for the weapon.

Return value:

    True if the weapon is out of ammunition.
isWeaponStowed (weapInfo)
Determines if the weapon is stowed.

Parameters:

  • weapInfo: (WeaponInfo) The WeaponInfo structure for the weapon.

Return value:

    True if the weapon is out of ammunition.
isWeaponSuppressed (weapInfo)
Determines if the weapon is suppressed.

Parameters:

  • weapInfo: (WeaponInfo) The WeaponInfo structure for the weapon.

Return value:

    True if the weapon is out of ammunition.
parseWeaponSystem (weaponStr)
Parses a weapon string typically passed as a task parameter from VRF GUI to determine the weapon ID and potentially specified ammo. The weapon string generated by a pre VRF 5.1 is formatted differently from later weapon strings and this function will determine which format it is and decode it.

Parameters:

  • weaponStr: The string specifing a weapon (and optionally ammo) from a task parameter.

Return values:

  1. (string) The weapon ID of the weapon.
  2. (string) The ammo name specified, if any
  3. (boolean) True if the weaponStr was in VRF 5.1 format. False if pre5.1.
printAllWeaponInfo (printFcn)
Prints the contents of all weapons for this entity. I.e., weapons that are returned by getWeaponInfoList.

Parameters:

  • printFcn: (function) The function to use to print.
printWeaponInfo (weapInfo, printFcn)
Prints the contents of a WeaponInfo structure.

Parameters:

  • weapInfo: (WeaponInfo) The structure to print.
  • printFcn: (function) The print function to use to print.
prioritizeTargets (targets)
Sorts a list of SimObjects for target prioritization. Targets are considered higher priority based on these criteria (in this order):
  1. If target is on the target priority list (via Set Target Priority List). Better priority targets on this list are preferred.
  2. If target is within the current sector of responsibility.
  3. If target has a greater threat level (determined by the threatLevelUtil lua module)
  4. Closer targets are prefered over farther

Parameters:

  • targets: A list of target SimObjects. The table will be sorted in place.

Return value:

    The sorted targets list.

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