Module ORGM.Firearm

Firearm Functions.

This file handles functions dealing with firearms data, and manipulating HandWeapon/InventoryItem methods. Dynamic stat settings, reloadable setup and ORGM version updates are contained.

Info:

  • Copyright: 2018 File: shared/2LoadOrder/ORGMFirearms.lua
  • Release: 3.09
  • Author: Fenris_Wolf

Functions

applyRarity (gunType, gunData[, safe]) Applies rarity settings for the firearm.
removeRarity (gunType) Removes the firearm from the RarityTable and subtables.
randomRarity (civilian, police, military) Gets a list of firearms from a random RarityTable.
getRarityTable (name, rarity) Returns the specified RarityTable.
register (name, gunData) Registers a firearm type with ORGM.
deregister (name) Deregisters a firearm with ORGM.
random ([thisTable]) Returns the name of a random firearm.
getTable () Gets the table of registered firearms.
getData (itemType[, moduleName]) Gets the data of a registered firearm, supports module checking.
isFirearm (itemType[, moduleName]) Checks if itemType is a ORGM Firearm.
filter (compareFunction, gunTable) Filters results from ORGM.Firearm.getTable() based on the supplied function.
setup (gunData, weaponItem) Sets up a gun, applying key/values into the items modData.
needsUpdate (weaponItem) Checks if the InventoryItem needs updating/replacing.
replace (weaponItem, container) Replaces a HandWeapon/InventoryItem a new version of itself.
isFullAuto (weaponItem[, gunData]) Returns if the firearm is currently in full auto mode.
toggleFireMode (item[, mode[, playerObj]]) Toggles the position of the Select Fire switchon a firearm.
isSelectFire (item[, itemData]) Checks if a firearm is select fire.
isLoaded (item) Checks if a firearm is loaded.
Hammer.type (item[, itemData]) Returns the hammer/trigger type of the firearm.
Hammer.isSA (item[, itemData]) Checks if the hammer/trigger is single-action.
Hammer.isDA (item[, itemData]) Checks if the hammer/trigger is double-action.
Hammer.isDAO (item[, itemData]) Checks if the hammer/trigger is double-action-only.
Hammer.isCocked (item) Checks if the hammer is cocekd.

Barrel Table

Barrel.getLength (weaponItem[, gunData]) Gets the barrel length for the firearm.
Barrel.getWeight (weaponItem[, gunData]) Gets the weight modifier for the firearm based on its barrel length.

Stats Table

Stats.set (weaponItem) Sets the HandWeapon/InventoryItem properties dynamically.
Stats.initial (gunData, ammoData) Gets the initial stats table for the firearm.
Stats.adjustByCategory (category, statsTable, effectiveWgt) Adjusts the values in the statsTable for HitChance and AimingTime based on values in the ORGM.Settings table.
Stats.adjustByComponents (compTable, statsTable) Adjusts the values in the statsTable based on the items in the compTable.
Stats.adjustByBarrel (weaponItem, gunData, ammoData, statsTable, effectiveWgt) Adjusts the values in the statsTable based on the firearms barrel length.
Stats.adjustByFeed (weaponItem, gunData, statsTable) Makes adjustments to SwingTime, applying limits and setting up full auto.
Stats.setPenetration (weaponItem, value) Sets the PiercingBullets flag on a gun, dependent on the round.
Stats.setPenetration_DEPRECIATED (weaponItem, ammoData) Sets the PiercingBullets flag on a gun, dependent on the round.


Functions

Methods
applyRarity (gunType, gunData[, safe])
Applies rarity settings for the firearm.

This is required after editing the spawn rarity settings of a firearm that has already been registered with ORGM.Firearm.register. It is called automatically when registering.

Parameters:

Usage:

    local gunData = ORGM.Firearm.getData('Ber92')
    gunData.isPolice = ORGM.RARE
    ORGM.Firearm.applyRarity('Ber92', gunData)
removeRarity (gunType)
Removes the firearm from the RarityTable and subtables.

This is a handy way of removing a gun from spawning.

Parameters:

randomRarity (civilian, police, military)
Gets a list of firearms from a random RarityTable.

Parameters:

  • civilian int
  • police int
  • military int

Returns:

    table

See also:

getRarityTable (name, rarity)
Returns the specified RarityTable.

Parameters:

Returns:

    table
register (name, gunData)
Registers a firearm type with ORGM.

Parameters:

  • name string name of the firearm without module prefix
  • gunData table

    Valid table keys/value pairs are:

    Sound options:

    These sound keys are automatically set by the soundProfile, but can be over written. They are all nil, or the string name of a sound file in media/sound/*.ogg.

    • clickSound = nil | filename

    • insertSound = nil | filename

    • ejectSound = nil | filename

    • rackSound = nil | filename

    • openSound = nil | filename

    • closeSound = nil | filename

    • cockSound = nil | filename

    Firearm details, these string fill out the ‘Inspection’ window.

    • classification = nil | string, the ‘type’ of weapon (Revolver, Assault Rifle, etc)

    • country = nil | string, the initial country of manufacture

    • manufacturer = nil | string, the initial company (or factory) of manufacture

    • year = nil | integer, the initial year of manufacture, this is used by ORGM.Settings.LimitYear

    • description = nil | string, background information

Returns:

    bool true on success.
deregister (name)
Deregisters a firearm with ORGM.

WARNING: Incomplete code, do not use.

Parameters:

  • name string name of the firearm to deregister.

Returns:

    bool true on success
random ([thisTable])
Returns the name of a random firearm.

Parameters:

  • thisTable table table to select from. (optional)

Returns:

    string the random firearm name.
getTable ()
Gets the table of registered firearms.

Returns:

    table all registered firearms setup by ORGM.Firearm.register
getData (itemType[, moduleName])
Gets the data of a registered firearm, supports module checking.

Parameters:

  • itemType string or HandWeapon
  • moduleName string module to compare (optional)

Returns:

    nil or table data of a registered firearm setup by ORGM.Firearm.register

Usage:

    local gunData = ORGM.Firearm.getData('Ber92')
isFirearm (itemType[, moduleName])
Checks if itemType is a ORGM Firearm.

Parameters:

  • itemType string or HandWeapon
  • moduleName string module to compare (optional)

Returns:

    bool true if it is a ORGM registered firearm

Usage:

    local result = ORGM.Firearm.isFirearm('Ber92')
filter (compareFunction, gunTable)
Filters results from ORGM.Firearm.getTable() based on the supplied function.

Parameters:

  • compareFunction function , a function that takes 2 arguments: gunType and gunData, and returns a boolean
  • gunTable table

Returns:

    table
setup (gunData, weaponItem)
Sets up a gun, applying key/values into the items modData. This should be called whenever a firearm is spawned. Basically the same as ReloadUtil:setupGun and ISORGMWeapon:setupReloadable but called without needing a player or reloadable object.

Parameters:

Usage:

    ORGM.Firearm.setup(Firearm.getData(weaponItem), weaponItem)
needsUpdate (weaponItem)
Checks if the InventoryItem needs updating/replacing.

Returns true/false if the firearm needs to be updated due to ORGM version changes. This compares the mods BUILD_ID with the weaponItem’s mod data BUILD_ID and the definitions lastChanged property.

This nomally called OnEquipPrimary event.

Parameters:

  • weaponItem HandWeapon

Returns:

    nil or bool true if update is needed, or nil if not a ORGM firearm.

Usage:

    local result = ORGM.Firearm.needsUpdate(weaponItem)
replace (weaponItem, container)
Replaces a HandWeapon/InventoryItem a new version of itself.

This is primarily for backwards compatibility with older versions of ORGM when the guns stats have changed. The new gun will be in the same condition as the old, and have the same upgrades attached. Any ammo loaded will be returned to the container.

Parameters:

  • weaponItem HandWeapon item to replace
  • container ItemContainer container the weaponItem exists in (usually player inventory)

Returns:

    HandWeapon

Usage:

    local newItem = ORGM.Firearm.replace(weaponItem)
isFullAuto (weaponItem[, gunData])
Returns if the firearm is currently in full auto mode.

Parameters:

Returns:

    boolean or nil

Usage:

    local isFull = ORGM.Firearm.isFullAuto(weaponItem)
toggleFireMode (item[, mode[, playerObj]])
Toggles the position of the Select Fire switchon a firearm.

Parameters:

isSelectFire (item[, itemData])
Checks if a firearm is select fire.

Parameters:

Returns:

    nil or bool nil if not a firearm, else true or false.
isLoaded (item)
Checks if a firearm is loaded.

Parameters:

  • item HandWeapon

Returns:

    bool true if the firearm has any ammo in it.
Hammer.type (item[, itemData])
Returns the hammer/trigger type of the firearm.

Parameters:

Returns:

    nil or bool nil if not a firearm, else true or false.
Hammer.isSA (item[, itemData])
Checks if the hammer/trigger is single-action.

Parameters:

Returns:

    bool
Hammer.isDA (item[, itemData])
Checks if the hammer/trigger is double-action.

Parameters:

Returns:

    bool
Hammer.isDAO (item[, itemData])
Checks if the hammer/trigger is double-action-only.

Parameters:

Returns:

    bool
Hammer.isCocked (item)
Checks if the hammer is cocekd.

Parameters:

  • item HandWeapon

Returns:

    nil or bool nil if not a firearm, else true or false.

Barrel Table

These functions pimarly return info on the barrel.
Barrel.getLength (weaponItem[, gunData])
Gets the barrel length for the firearm.

Parameters:

Returns:

    nil or number length of the barrel

Usage:

    local length = ORGM.Firearm.Barrel.getLength(weaponItem)
Barrel.getWeight (weaponItem[, gunData])
Gets the weight modifier for the firearm based on its barrel length.

Parameters:

Returns:

    nil or number

Usage:

    local wgtAdj = ORGM.Firearm.Barrel.getWeight(weaponItem)

Stats Table

This table Contains functions for modifing the stats on a HandWeapon/InventoryItem. It calculates the weight and ammo used, attachment bonuses, barrel length effects and every thing else that needs to be changed dynamically.

Note ‘optimal barrel length’ is a completely subjective term. In this I’m referring to the length required to achieve full powder burn, where the bullet reaches maximum velocity. Also note ‘full powder burn’ is completely relative, different powders burn at different rates. While one might reach max velocity from a 26" barrel, another might require a 28". Bullet weight also plays a important factor here, but for the sake of simplicity should not be factored in (yet).

  1. action type has a effect, especially in automatics. Pressure is lost in blowback designs, gas feed systems etc. This means a shorter barrel will have the same effect as a longer one in bolt actions and such. These action types should have a lower ‘optimal barrel’ length.

  2. Barrel length has a effect on damage, below optimal length the bullet does not reach its intended velocity, above optimal it starts to slow down due to friction.

  3. Length of barrels has a effect on noise. A longer barrel is quieter then a shorter one, as less gas escapes.

  4. Barrel lengths effect on accuracy is a mixed bag when it comes to long range. While longer barrels are generally more accurate when the barrel is resting, it also means the bullet has longer ‘barrel time’ which means more chance to waiver off target. Above/below optimal length and velocity causes additional bullet drop. Luckly long range shooting isn’t really a thing in PZ, so this isn’t much of a problem.

  5. Below optimal length, the extra gas escaping causes additional recoil.

  6. Action type effect on recoil: some action types absorb recoil more then others, but this is also a mixed bag. Take the AK for example. It uses a long gas piston feed system, the gas chamber absorbs some recoil effect from the gas that escapes the muzzle, but causes additional recoil due to the design of the long piston above the barrel and the center of weight changes while cycling.

  7. The effect on velocity from a barrel above/below is a definite curve. The closer we are to optimal length the less the effect is.

fps-fps*((((o-b)/o)3)2) this is pretty damn close to matching the curve. After tons of pissing around with handloading simulation software, it looks like ‘o’ needs to be 80 for rifles, 30 for pistols, 60 for shotguns to find a close match.

These are defined in the calls to ORGM.Ammo.register.

Stats.set (weaponItem)
Sets the HandWeapon/InventoryItem properties dynamically.

This is crucial to the ORGM Framework’s dynamic stats for guns. It calculates the stats for firearms based on:

ammo, weight, accessories attached, barrel length, action type, select fire type (and other modData)

Parameters:

  • weaponItem HandWeapon
Stats.initial (gunData, ammoData)
Gets the initial stats table for the firearm.

This function is called by Stats.set

Parameters:

Returns:

    table initial values
Stats.adjustByCategory (category, statsTable, effectiveWgt)
Adjusts the values in the statsTable for HitChance and AimingTime based on values in the ORGM.Settings table.

This function is called by Stats.set

Parameters:

  • category int constant defined in ORGMCore.lua
  • statsTable table table of the firearm stats.
  • effectiveWgt number the weight of the firearm and all attachments excluding slings.
Stats.adjustByComponents (compTable, statsTable)
Adjusts the values in the statsTable based on the items in the compTable.

Note only specific key/values defined by components can be changed here.

This function is called by Stats.set

Parameters:

  • compTable table return value of {ORGM.Component.getAttached}
  • statsTable table table of the firearm stats.
Stats.adjustByBarrel (weaponItem, gunData, ammoData, statsTable, effectiveWgt)
Adjusts the values in the statsTable based on the firearms barrel length.

Adjustments to compensate for automatic feed systems are also done here.

This function is called by Stats.set

Parameters:

Stats.adjustByFeed (weaponItem, gunData, statsTable)
Makes adjustments to SwingTime, applying limits and setting up full auto.

The bulk of full auto behavior is defined in the function.

This function is called by Stats.set

Parameters:

Stats.setPenetration (weaponItem, value)
Sets the PiercingBullets flag on a gun, dependent on the round.

This is called when pulling the trigger.

Parameters:

  • weaponItem HandWeapon
  • value int percentge chance of penetration

Returns:

    bool true if the flag is set
Stats.setPenetration_DEPRECIATED (weaponItem, ammoData)
Sets the PiercingBullets flag on a gun, dependent on the round.

This is called when loading a new round into the chamber.

Parameters:

Returns:

    bool true if the flag is set
generated by LDoc 1.4.3 Last updated 2019-04-11 18:37:45