Guns4d | The ultimate 3d gun mod.
Previous
Next

## Class `gun` ¶

the following is documentation of gun fields. Methods are currently not present in this list.

See also defining_guns

properties¶ | properties which define the vast majority of gun attributes and may change accross instances
consts¶ | constants which define gun attributes and should not be changed in an instance of the gun
offsets¶ | runtime storage of offsets generated by recoil sway wag or any other element.
name¶ | `string` the name of the gun. Set to __template for guns which have no instances and serve as a template. It is safe to set name to the same as gun.itemstring
itemstring¶ | `string` the itemstring of the gun- i.e. `"guns4d_pack_1:m4"`. Set to `""` for `__template` guns.
itemstack¶ | `ItemStack` the gun itemstack. Remember to player:set_wielded_item(self.itemstack) when making meta or itemstack changes.
player¶ | `ObjRef` the operator of the weapon. This may at some point be deprecated when I start to implement AI/mob usage
meta¶ | `MetaDataRef` itemstack meta
id¶ | `string` the ID of the gun used for tracking of it's inventory
gun_entity¶ | `ObjRef` the gun entity
_registered¶ | list of registered guns, DO NOT MODIFY I really need a metatable for this class...
bolt_charged¶ | `bool` is the bolt charged
particle_spawners¶ | `table` list of particle spawner handles (generated by firing)
current_firemode¶ | `int` the active index of the firemode from firemodes
walking_tick¶ | `float` walking time used to generate the figure 8 for wag
time_since_last_fire¶ | `float`
time_since_creation¶ | `float`
rechamber_time¶ | `float` time left for the chamber to cycle (for firerates)
burst_queue¶ | `int` number of rounds left that need to be fired after a burst fire
gun_translation¶ | `vec3` translation of the gun relative to the "gun" bone or the player axial rotation.
property_modifiers¶ | `table` indexed list of functions which are called when the gun's properties need to be built. This is used for things like attachments, etc.
attached_objects¶ | `table` a list of ObjRefs that are attached to the gun as a result of attached_objects
subclass_instances¶ | `table` list of subclass instances (i.e. Sprite_scope)
animation_rotation¶ | `vector` containing the rotation offset from the current frame, this will be factored into the gun's direction if consts.ANIMATIONS_OFFSET_AIM=true
animation_translation¶ | `vector` containing the translational/positional offset from the current frame
total_offsets¶ | all offsets from gun.offset of a type added together gun in the same format as a an offset (that is, five vectors, `gun_axial`, `player_axial`, etc.). Note that if offsets are changed after update, this will not be updated automatically until the next update. update_rotations() must be called to do so.
velocities¶ | velocities in the format of offsets, but only containing angular (`gun_axial` and `player_axial`) offsets.

## properties ¶

the table containing every attribute of the gun.

hip¶ | `table` hipfire properties
ads¶ | `table` aiming ("aiming down sights") properties
firemodes¶ | `table` list of firemodes
recoil¶ | `table` defines the guns recoil
sway¶ | `table` defines the guns idle sway
wag¶ | `table` defines the movement of the gun while walking
charging¶ | `table` defines how rounds are chambered into the gun
ammo¶ | `table` defines what ammo the gun uses
visuals¶ | `table` defines visual attributes of the gun
sounds¶ | `table` defines sounds to be used by functions of the gun
inventory¶ | `table` inventory related attributes
initial_vertical_rotation¶ | `float` starting vertical rotation of the gun
breathing_scale¶ | `float`=.5 max angular deviation (vertical) from breathing
flash_offset¶ | `vector` the offset from the center of the muzzle flash. Used by fire()
firerateRPM¶ | `int`=600 The number of rounds (cartidges) this gun can throw per minute. Used by update(), fire() and default controls
reload¶ | an ordered list of reloading states used by default_controls. the default reload states for a magazine operated weapon, copied from the m4. ##### Example
    {action="charge", time=.5, anim="charge", sounds={sound="ar_charge", delay = .2}},
    {action="unload_mag", time=.25, anim="unload", sounds = {sound="ar_mag_unload"}},
    {action="store", time=.5, anim="store", sounds = {sound="ar_mag_store"}},
    {action="load", time=.5, anim="load", sounds = {sound="ar_mag_load", delay = .25}},
    {action="charge", time=.5, anim="charge", sounds={sound="ar_charge", delay = .2}}
model_bounding_box¶ | `table` (optional) a table `{x1,y1,z1, x2,y2,z2}` specifying the bounding box of the model. The first 3 (x1,y1,z1) are the lower of their counterparts. This is autogenerated from the model when not present, reccomended that you leave nil.
infinite_inventory_overlay¶ | `string` overlay on the item to use when infinite ammo is on
burst¶ | `int`=3 how many rounds in burst using when firemode is at "burst"
pc_control_actions¶ | `table` containing a list of actions for PC users passed to Control_handler. `__replace_only = true` in this table, meaning if the table exists in the new definition, it will be replaced.
touch_control_actions¶ | `table` containing a list of actions for touch screen users passed to Control_handler. `__replace_only = true` in this table, meaning if the table exists in the new definition, it will be replaced.

## properties.inventory ¶

See also properties

render_size¶ | the size in meters to render the gun in it's inventory opened with /guns4d_inv
render_image¶ | the image of the gun in it's inventory opened with /guns4d_inv
firemode_inventory_overlays¶ | table of firemodes and their overlays in the player's inventory when the gun is on that firemode
inventory_image_magless¶ | `string` (optional) inventory image for when the gun has no magazine
inventory_image¶ | `string` inventory image for when the gun is loaded. This is added automatically during construction as the item's wield image.

## properties.subclasses ¶

See also properties

ammo_handler¶ | `Ammo_handler` the class (based on) ammo_handler to create an instance of and use. Default is `Guns4d.ammo_handler`
part_handler¶ | `part_handler` Part_handler class to use. Default is `Guns4d.part_handler`
sprite_scope¶ | `Sprite_scope` sprite scope class to use. Nil by default, inherit Sprite_scope for class (documentation needed, reccomended contact for help if working with it)
crosshair¶ | `Dynamic_crosshair` crosshair class to use. Nil by default, set to `Guns4d.Dynamic_crosshair` for a generic circular expanding reticle.

## properties.ads ¶

See also properties

offset¶ | `vector` the offset of the gun relative to the eye's position at hip.
horizontal_offset¶ | `float` the horizontal offset of the eye when aiming
aim_time¶ | the time it takes to go into full aim

## properties.hip ¶

See also properties

offset¶ | `vector` the offset of the gun (relative to the right arm's default position) at hip.
axis_rotation_ratio¶ | the ratio that the look rotation is expressed through player_axial (rotated around the viewport) rotation as opposed to gun_axial (rotating the entity).
sway_vel_mul¶ | sway speed multiplier while at hip
sway_angle_mul¶ | sway angle multiplier while at hip

## properties.firemodes ¶

list containing the firemodes of the gun. Default only contains "single". Strings allowed by default:

See also properties

"single"¶
"burst"¶
"auto"¶

## properties.recoil ¶

IMPORTANT: expects fields to be tables containing a "gun_axial" and "player_axial" field.

See also properties

##### Example

    property = {
        gun_axial = type
        player_axial = type
    }
    --using a vector...
    property = {
        gun_axial={x=float, y=float},
        player_axial={x=float, y=float}
    }`

velocity_correction_factor¶ | `float` TL:DR higher decreases recoil at expense of smoothness. 1/value is the deviation of a normalized bell curve, where x is the time since firing. this means that increasing it decreases the time it takes for the angular velocity to fully "decay".
target_correction_factor¶ | `float` Correction of recoil offset per second is calculated as such: `target_correction_factor[axis]*time_since_fire*recoil[axis]`
target_correction_max_rate¶ | `float` The maximum rate per second of recoil offset as determined with gun.properties.recoil.target_correction_factor
angular_velocity_max¶ | `float` caps the recoil velocity that can stack up from shots.
angular_velocity¶ | `vector` {x=`float`, y=`float`}, defines the initial angular velocity produced by firing the gun
bias¶ | `vector` {x=`float`, y=`float`}, ranges -1 to 1. Defines the probability of the recoil being positive or negative for any given axis.
hipfire_multiplier¶ | `float` angular velocity multiplier when firing from the hip

## properties.sway ¶

IMPORTANT: expects fields to be tables containing a "gun_axial" and "player_axial" field. In the same format as gun.properties.recoil

See also properties

max_angle¶ | `float` maximum angle of the sway
angular_velocity¶ | `float` angular velocity the sway
hipfire_angle_multiplier¶ | `float` maximum angle multiplier while the gun is at the hip
hipfire_velocity_multiplier¶ | `float` velocity multiplier while the gun is at the hip

## properties.wag ¶

See also properties

cycle_speed¶ | `float`=1.6 the cycle speed multiplier
decay_speed¶ | `float`=1 decay factor when walking has stopped and offset remains.
offset¶ | `table` containing angular deviation while walking in the same format as an offset vector. Acts as a multiplier on the figure-8 generated while walking.

## properties.charging ¶

See also properties

require_draw_on_swap¶ | `bool` defines wether the draw animation is played on swap (when loaded). Default true.
bolt_charge_mode¶ | `string` "none" bolt will never need to be charged after reload, "catch" when fired to empty bolt will not need to be charged after reload, "no_catch" bolt will always need to be charged after reload.
draw_time¶ | `float` the time it takes to swap to the gun
draw_animation¶ | `string` name of the animation to play from visuals.animations. Default "draw"
draw_sound¶ | `string` name of the sound to play from sounds. Default "draw"

## properties.ammo ¶

See also properties

magazine_only¶ | `bool` wether the gun only uses a magazine or accepts raw ammunition too.
accepted_rounds¶ | `table` a list of accepted bullet itemstrings
accepted_magazines¶ | `table` a list of accepted magazine itemstrings
initial_mag¶ | `string` the mag the gun starts with. Set to "empty" for no mag, otherwise it defaults to accepted_magazines[1] (if present)

## properties.visuals ¶

See also properties

mesh¶ | name of mesh to display. Currently only supports b3d
textures¶ | list of textures to use.
scale¶ | scale multiplier. Default 1
attached_objects¶ | objects that are attached to the gun. This is especially useful for attachments ##### Example
    my_object = {
        textures = {"blank.png"},
        visual_size = {x=1,y=1,z=1},
        offset = {x=0,y=0,z=0},
        bone = "main",
        backface_culling = false,
        glow = 0
    }
backface_culling¶ | toggles backface culling. Default true
animations¶ | a table of animations. Indexes define the name of the animation to be refrenced by other functions of the gun. should be in the format `{x=integer,y=integer}` ##### Example
    animations = {
        empty = {x=0,y=0}
        loaded = {x=1,y=1}
        fire = {x=10,y=20}
        draw = {x=24,y=30} --DEFAULT of charging.draw_animation.
    }
There are other animations which are variable which are not listed here, these are usually defined by properties such as: reload, draw_animation

## properties.sounds ¶

other fields are defined by other properties such as properties.charging.draw_sound and properties.reload

See also properties
See also soundspec

fire¶ | sound player when firing the weapon

## offsets ¶

a list of tables each containing offset vectors These are required for automatic initialization of offsets. note rotations are in degrees, and translations are in meters.

##### Example

    recoil = {
        gun_axial = {x=0, y=0}, --rotation of the gun around it's origin.
        player_axial = {x=0, y=0}, --rotation of the gun around the bone it's attached to
        --translations of gun
        player_trans = {x=0, y=0, z=0}, --translation of the bone the gun is attached to
        eye_trans = {x=0, y=0, z=0}, --trnaslation of the player's look
        gun_tran = {x=0, y=0, z=0}s  --translation of the gun relative to the bone it's attachted to.
    }

recoil¶
sway¶
walking¶
breathing¶
look¶

## consts ¶

These are variables that are constant across the class and should usually not ever be changed by instnaces

KEYFRAME_SAMPLE_PRECISION¶ | frequency of keyframe samples for animation offsets and
DEFAULT_MAX_HEAR_DISTANCE¶ | default max hear distance when not specified
DEFAULT_FPS¶ | `fps`=60 animation fps i.e. during firing when no length is specified
HAS_RECOIL¶ | `bool`
HAS_BREATHING¶ | `bool`
HAS_SWAY¶ | `bool`
HAS_WAG¶ | `bool`
HAS_GUN_AXIAL_OFFSETS¶ | `bool` wether the gun rotates on it's own axis instead of the player's view (i.e. ironsight misalignments)
ANIMATIONS_OFFSET_AIM¶ | wether animations create an offset
LOOP_IDLE_ANIM¶ | whether the idle animation changes or not
THIRD_PERSON_GAIN_MULTIPLIER¶ | general gain multiplier for third persons when hearing sounds
ROOT_BONE¶ | the root bone of the gun (for animation offsets)
MAG_BONE¶ | `string`="magazine",the bone of the magazine in the gun (for dropping mags)
ARM_RIGHT_BONE¶ | `string`="right_aimpoint", the bone which the right arm aims at to
ARM_LEFT_BONE¶ | `string`="left_aimpoint", the bone which the left arm aims at to
VERSION¶ | `table` version of 4dguns this gun is made for. If left empty it will be assumed it is before 1.3.