Gun Asset Reference

Intermediate40-60 minutesWindowsNotepad++Unity Editor

The gun asset is the data definition for every ranged weapon in Unturned™ - automatic rifles, semi-automatic pistols, bolt-action snipers, pump-action shotguns, break-action single-shots, miniguns, rocket launchers, crossbows, and all other projectile-firing equipment. A gun asset determines fire rate, damage per target category, recoil pattern, spread behavior, reload timing, attachment compatibility, caliber linkage, projectile system (ballistic or physics), animation set, audio cues, jamming behavior, and the complete set of firing modes the weapon supports. It is the asset type with the largest configuration surface in the entire Unturned™ item system.

This article is the 57 Studios™ complete field reference for the ItemGunAsset class. It documents every property across all fourteen category tables, every enumeration value, both projectile systems, the caliber-linkage and attachment-hook systems, the reload and rechambering mechanics, the NPC reward integration surface, and the complete blueprint and crafting system that the gun asset inherits from ItemWeaponAsset. Worked .dat examples from shipped vanilla and mod guns provide real-world field validation. This article targets mod authors who have already completed at least one working gun mod and need a comprehensive reference for the full exploitation of the gun asset surface.

Documentation source: This article references the official Smartly Dressed Games modding documentation for class hierarchy and field definitions. Shipped game files from Bundles/Items/Guns/ in the Unturned™ installation directory provide field-level validation. All field names, types, defaults, and enum values are verified against both sources.

Who this article is for

This article is written for Unturned™ mod authors who have already built at least one gun mod following the Gun Mod Tutorial and who are familiar with the Unity prefab pipeline, the .dat authoring workflow, and the master bundle export process. If you are building your first gun mod, start with the tutorial and return to this article when you need to tune a specific system (recoil, jamming, spread, projectile ballistics). Readers who have not completed the prerequisite orientation articles on item asset anatomy and the master bundle workflow should finish those before attempting to use this reference.

What you'll learn

• The complete Unity prefab structure for a gun asset, including child GameObjects for every attachment type, bow-specific setup, and economy item support
• All fourteen property tables covering aim, calibers, damage, effects, firing mechanism, hook attachments, jamming, magazines, ballistics, physics projectiles, rechambering, recoil, shake, and spread
• The four enumerations: EAction, EDriverTurretViewmodelMode, ERechamberGunAfterReloadMode, and the firing-mode flags
• The ballistic projectile system: Ballistic_Travel, Ballistic_Steps, Bullet_Gravity_Multiplier, deterministic simulation, and hitscan fallback
• The physics projectile system: Ballistic_Force, Projectile_Lifespan, Projectile_Penetrate_Buildables, and physics-simulated area-of-effect explosions
• Caliber linkage: Caliber, Magazine_Caliber_#, Magazine_Calibers, Attachment_Caliber_#, Attachment_Calibers, and the Requires_NonZero_Attachment_Caliber flag
• Attachment hook system: Hook_Sight, Hook_Grip, Hook_Tactical, Hook_Barrel, and the legacy ID attachment default fields
• Reload, rechambering, and hammer mechanics
• Jamming configuration: Can_Ever_Jam, Jam_Quality_Threshold, Jam_Max_Chance, Unjam_Chamber_Anim
• NPC reward integration via the Shoot_Quest_ prefix
• Complete worked .dat examples from shipped weapons

How the gun asset system works

The gun asset is part of the ItemGunAsset class, which inherits from ItemWeaponAsset, which inherits from ItemAsset. The inheritance chain determines which fields are available at each level. The ItemAsset base class provides identity fields (ID, GUID, Type, Name, Rarity, Slot, Size_X, Size_Y). The ItemWeaponAsset parent class provides weapon-specific fields such as Range, Player_Damage, Zombie_Damage, Durability, and Wear. The ItemGunAsset subclass adds every field documented in this article.

The fields that appear in a .dat file are read by the Unturned™ parser at load time. The parser maps each key-value pair to the corresponding property on the ItemGunAsset object. Unknown keys are silently ignored; missing keys use their engine defaults. The gun asset must carry Type Gun and Useable Gun to be recognized as a ranged weapon. Without either, the engine does not instantiate the ItemGunAsset class and the weapon does not function.

The engine also requires that the Action property is configured. The Action value determines which projectile system the weapon uses (ballistic or physics), which reload animation plays, and which subset of properties the engine reads. A gun without an Action field will fail to instantiate at load time.

Unity prefab structure

The Unity prefab for a gun asset requires a specific hierarchy of child GameObjects. The root GameObject carries the ItemGunAsset script reference (or more commonly, the prefab is referenced by the .dat file through the Name field, and the engine instantiates the prefab by name from the master bundle).

Required child GameObjects

The root prefab must contain six child GameObjects for a fully functional gun:

MyGunPrefab (root)
├── Barrel
├── Grip
├── Sight
├── Tactical
├── Magazine
└── Eject

The Barrel, Grip, Sight, Tactical, and Magazine child GameObjects determine the position of attachments on the gun. Each child's transform (position, rotation, scale) in the prefab defines where the attachment model appears when equipped. The Sight GameObject also determines where the camera is positioned when the player aims down sights. The Eject GameObject is the emission point for shell casings when the gun is fired. If an Eject GameObject is not present, shell casing particles emit from the root position.

An optional View GameObject provides the camera position for aiming down sights when no sight attachment is equipped. If View is present, its transform overrides the Sight child position for the hip-to-aim camera transition when no sight is attached. If View is absent, the engine falls back to the Sight child position for the unsighted camera position as well.

Caliber-specific attachment positions

When a gun accepts more than one caliber of magazine, the magazine attachment position should be adjusted per caliber to correctly seat different magazine shapes. Add a child to the Magazine GameObject named Caliber_# where # is the caliber ID:

Magazine
├── Caliber_1
├── Caliber_9
└── Caliber_14

This pattern is also supported for the other attachment type GameObjects (Barrel, Grip, Sight, Tactical). When the engine reads a caliber-matching child, it uses that child's transform instead of the parent's for attachment positioning.

Bow-specific setup

Bows and crossbows require additional GameObjects to simulate the drawing of the bowstring. The bowstring simulation is first-person only; third-person bow models do not display the string draw.

MyBowPrefab (root)
├── Rope (inactive by default; Line Renderer component)
├── Left (bowstring endpoint)
├── Right (bowstring endpoint)
├── Rest (bowstring midpoint when aiming down sights)
└── Nock (allows firing without aiming down sights)

The Rope GameObject should be inactive by default in the prefab and must include a Line Renderer component. Vanilla bowstrings use a custom Material named Rope with the Unlit-Rope Shader, but any Line Renderer material is acceptable. The Left and Right GameObjects define the endpoints of the bowstring. If a Rest GameObject is included, its position is used as the middle point of the bowstring when aiming down sights. If a Nock GameObject is included, the bow can be fired without aiming down sights - the Rest GameObject acts as the midpoint when not aiming, and the Nock GameObject acts as the midpoint when aiming. Without Nock, the String action mechanism requires the player to be aiming down sights before the weapon can fire.

Economy item setup (skins)

The economy item system supports several optional child GameObjects for skin rendering:

MyGunPrefab (root)
├── Icon2 (position and orientation for skin icon generation)
├── Stat_Tracker (position for stat tracker displays)
└── Effect (position for mythical effect particle systems)

Custom items (non-economy Workshop items) are ineligible to receive skins, so these GameObjects are not needed for standard Workshop mods. They are relevant only for items participating in the Steam economy item system, which is an advanced distribution path that requires additional configuration beyond the scope of a standard .dat file.

Animation prefabs

In addition to the animation states used by any equippable item (Idle, Equip, Unequip, Inspect), guns have a dedicated set of animation states:

Animation state	Trigger	Purpose
Aim_Start	Player presses aim button	Transition from hip to sighted position
Aim_Stop	Player releases aim button	Transition from sighted to hip position
Attach_Start	Attachment equipped	Plays when an attachment is attached to the gun
Attach_Stop	Attachment removed	Plays when an attachment is detached from the gun
Sprint_Start	Player starts sprinting	Transition from idle to sprinting pose
Sprint_Stop	Player stops sprinting	Transition from sprinting to idle pose
Reload	Player presses reload	Full reload animation cycle
Hammer	Post-reload or post-shot cycle	Manual bolt/pump/break-action cycle or after reloading an empty magazine
UnjamChamber	Jam occurs (jamming-enabled guns)	Animation that clears a jammed chamber
Inspect	Player presses inspect	Idle inspection animation

The Hammer animation plays under specific conditions defined by the RechamberAfterMagazineAttached, RechamberAfterMagazineDetached, and RechamberAfterShotCount fields. The animation state name in the Animator Controller must exactly match the state name used in the animation clip asset. A mismatch produces no animation playback for that event but does not produce an engine error.

Audio clips

Gun prefabs support a dedicated set of Audio Clip references beyond the equippable-item standard:

Audio clip name	When it plays
Shoot	After the gun is fired (primary audio)
Reload	After the reload animation begins
Hammer	When the hammer animation plays after a post-shot or post-reload cycle
Aim	When the player aims down sights (bow draw, sight flip-up)
Minigun	While the minigun is revving (Action Minigun only)
ChamberJammed	When a jam occurs (jamming-enabled guns only)

The Aim Audio Clip is particularly relevant for bows and crossbows, where the draw sound creates the player feedback for the string tension mechanic. The Minigun clip is exclusive to weapons using Action Minigun. The ChamberJammed clip requires Can_Ever_Jam to be set.

Complete property reference

The gun asset properties are organized into fourteen category tables in the official SDG documentation. The sections below reproduce every property from every table, with type, default value, and a prose description of its purpose.

Table 1: Uncategorized

The uncategorized table collects properties that do not fit neatly into any other category but that affect the weapon's behavior at a global level.

Field	Type	Default	Purpose
Aim_In_Duration	float32	0.2	Time in seconds to fully transition from hip to aimed-down-sights position. Lower values produce a faster aim.
Aiming_Movement_Speed_Multiplier	float32	See description	Multiplier on the player's movement speed while aiming. Defaults to 0.75 when Can_Aim_During_Sprint is false. Defaults to 1.0 when Can_Aim_During_Sprint is true.
Alert_Radius	float32	48	Radius in meters within which zombies and animals are alerted when the gun is fired. Higher values produce a larger alert zone.
Can_Aim_During_Sprint	bool	false	When true, the player can sprint while aiming down sights.
Gunshot_Rolloff_Distance	float32	See description	Distance in meters over which the gunshot audio fades to inaudible. Defaults to 16 for Action String, 64 for Action Rocket, and 512 for all other action types.
Must_Aim_To_Shoot	bool	See description	When true, the gun cannot fire unless the player is aiming. Defaults to true for Action Minigun. Action String overrides this behavior regardless of the field value.
Range_Rangefinder	float32	See description	Overrides the maximum distance displayed when a rangefinder tactical attachment is equipped on this weapon. Defaults to the value of the Range property.
Scale_Aim_Animation_Speed	bool	true	When true, the Aim_Start and Aim_Stop animation lengths are scaled to match Aim_In_Duration plus modifiers.
Stop_Aiming_After_Shooting	bool	false	When true, the gun stops aiming regardless of player input after firing.
DriverTurretViewmodelMode	EDriverTurretViewmodelMode	OffscreenWhileAiming	Controls first-person arm visibility for turrets operated from a vehicle driver seat.

The Aim_In_Duration field interacts with Scale_Aim_Animation_Speed. When scaling is enabled (the default), the animation speed is adjusted so that the transition completes in exactly the Aim_In_Duration time regardless of the animation clip's authored length. When scaling is disabled, the animation plays at its authored speed and the engine does not enforce the Aim_In_Duration timing.

Table 2: Calibers

The caliber table controls which magazines and hook attachments are accepted by the gun. This is the string-to-bow connection between the gun asset and the magazine and attachment assets.

Field	Type	Default	Purpose
Caliber	uint16	0	Legacy caliber ID for both magazine and hook attachment compatibility. When Magazine_Calibers is not configured, this value applies to magazines. When Attachment_Calibers is not configured, this value applies to hook attachments. Caliber 0 is universal and accepts any magazine or attachment with caliber ID 0.
Magazine_Calibers	int32	1	Array length for Magazine_Caliber_#. Must equal the number of Magazine_Caliber_# instances in the .dat. When set to a value greater than 0, the Magazine_Caliber_# array is active and each entry defines an accepted magazine caliber.
Magazine_Caliber_#	uint16	See description	One entry in the magazine caliber array. Each entry specifies a caliber ID that this gun accepts for magazine attachments. When unconfigured, defaults to 0. When Magazine_Calibers is not greater than 0, defaults to the value of Caliber.
Attachment_Calibers	int32	See description	Array length for Attachment_Caliber_#. When set to a value greater than 0, the Attachment_Caliber_# array is active. When not greater than 0, defaults to the value of Magazine_Calibers, and the Attachment_Caliber_# entries cannot be customized independently.
Attachment_Caliber_#	uint16	See description	One entry in the attachment caliber array. Each entry specifies a caliber ID that this gun accepts for hook attachments. When unconfigured, defaults to 0. When Attachment_Calibers is not greater than 0, defaults to the corresponding Magazine_Caliber_# value.
Requires_NonZero_Attachment_Caliber	bool	false	When true, hook attachments must specify at least one non-zero caliber ID to be compatible with this gun. Used to exclude vanilla attachments (caliber 0) from custom weapons.

The caliber resolution diagram shows the priority chain. The Magazine_Calibers and Attachment_Calibers arrays give the most precise control. When they are not used, the single Caliber field serves as a fallback for both magazine and attachment compatibility.

Table 3: Damage

The damage table controls body-part-specific multipliers that modify the base damage values inherited from ItemWeaponAsset.

Field	Type	Default	Purpose
Damage_Falloff_Max_Range	float32	1	Percentage of maximum range beyond which damage stops decreasing. A value of 0.6 with Range 200 means damage stops falling off after 120 meters.
Damage_Falloff_Multiplier	float32	1	Percentage of damage applied at maximum range. A value of 0.25 with a base damage of 40 means 10 damage is dealt at maximum range.
Damage_Falloff_Range	float32	1	Percentage of maximum range at which damage begins decreasing. A value of 0.3 with Range 200 means damage begins falling off after 60 meters.
Instakill_Headshots	bool	false	When true, a headshot against a player (not zombies unless the world difficulty has Weapons_Use_Player_Damage enabled) instantly kills the target regardless of remaining HP.

The Damage_Falloff_Max_Range and Damage_Falloff_Range fields define a damage plateau zone. The weapon deals full damage from zero range to Damage_Falloff_Range. Beyond that point, damage linearly decreases until Damage_Falloff_Max_Range, after which damage stays constant at Damage_Falloff_Multiplier of the base value. When both fields are 1, damage is uniform across the entire range envelope.

Table 4: Effects

The effects table controls visual and explosive effect references.

Field	Type	Default	Purpose
Explosion	GUID or uint16	0	GUID or legacy ID of the effect used for explosions caused by Action Rocket physics projectiles.
Muzzle	GUID or uint16	0	GUID or legacy ID of the muzzle flash effect emitted from the Barrel child GameObject after firing.
Shell	GUID or uint16	See description	GUID or legacy ID of the shell casing effect emitted from the Eject child GameObject after firing. Defaults to 33 for Action Pump and Action Break. Defaults to 1 for all other action types except Action Rail. Defaults to 0 for Action Rail.

The Muzzle and Shell effect references point to effect assets defined elsewhere in the content system. The vanilla effect IDs (3 for rifle muzzle flash, 4 for heavy weapon muzzle flash, 33 for shotgun shell ejection, 1 for standard shell ejection) are documented constants in the vanilla .dat files. Custom effects require registering a new effect asset and referencing its GUID.

Table 5: Firing Mechanism

The firing mechanism table defines how the weapon fires and which fire modes are available.

Field	Type	Default	Purpose
Action	EAction	(required)	Determines the weapon's firing behavior, projectile system, and reload type. This is the single most important field on the gun asset.
Auto	flag	not set	When present, the weapon has an automatic firing mode (hold trigger for continuous fire).
Semi	flag	not set	When present, the weapon has a semi-automatic firing mode (one shot per trigger pull).
Safety	flag	not set	When present, the weapon has a safety mode (cannot fire).
Bursts	int32	0	When greater than 0, the weapon has a burst-fire mode that fires this many shots per burst.
Firerate	uint8	0	Minimum number of ticks between consecutive shots. Higher values produce a slower rate of fire. The rate of fire in rounds per second is 50 ÷ (Firerate + 1).
Fire_Delay_Seconds	int32	0	Delay in seconds between the trigger pull and the shot being fired. Used for weapons with a delayed ignition such as a flintlock.

The combination of Auto, Semi, Safety, and Bursts defines the weapon's fire mode selector. A weapon with both Safety and Semi has two modes (safe and semi). A weapon with Safety, Semi, and Auto has three modes (safe, semi, auto). A weapon with Safety, Semi, Auto, and Bursts 3 has four modes (safe, semi, auto, burst). The engine cycles through present modes when the player presses the fire-mode key.

Table 6: Hook Attachments

The hook attachments table controls which attachment types the gun supports and which legacy ID attachments are equipped by default.

Field	Type	Default	Purpose
Hook_Sight	flag	not set	When present, the gun has a sight attachment slot.
Hook_Grip	flag	not set	When present, the gun has a grip attachment slot.
Hook_Tactical	flag	not set	When present, the gun has a tactical attachment slot.
Hook_Barrel	flag	not set	When present, the gun has a barrel attachment slot.
Sight	uint16	0	Legacy ID of a sight attachment to equip by default. Does not require Hook_Sight.
Grip	uint16	0	Legacy ID of a grip attachment to equip by default. Does not require Hook_Grip.
Tactical	uint16	0	Legacy ID of a tactical attachment to equip by default. Does not require Hook_Tactical.
Barrel	uint16	0	Legacy ID of a barrel attachment to equip by default. Does not require Hook_Barrel.

The Hook_* flags control whether the slot is present on the weapon. The Sight, Grip, Tactical, and Barrel legacy ID fields control which specific attachment is equipped by default. A weapon can have a default attachment without declaring the hook slot (the attachment model still attaches to the corresponding child GameObject). The hook slot flag is necessary for the player to be able to remove or replace the attachment in-game.

Table 7: Jamming

The jamming table controls the weapon jamming mechanic. Weapons that jam have a reliability curve based on their current quality value.

Field	Type	Default	Purpose
Can_Ever_Jam	flag	not set	When present, the weapon can jam. Without this flag, all other jamming properties are ignored.
Jam_Quality_Threshold	float32	0.4	The quality percentage below which the weapon can jam. A value of 0.4 means jamming can start occurring below 40% quality.
Jam_Max_Chance	float32	0.1	The maximum decimal-probability of a jam at the lowest quality. A value of 0.1 means a 10% maximum chance per shot. The chance blends from 0% at Jam_Quality_Threshold to Jam_Max_Chance at zero quality.
Unjam_Chamber_Anim	string	UnjamChamber	Name of the animation clip to play when unjamming the weapon. Must match a state in the Animator Controller.

The jamming blend works linearly. At 100% quality, the jam chance is 0%. As quality decreases toward Jam_Quality_Threshold, the chance stays at 0%. Below Jam_Quality_Threshold, the chance linearly ramps up from 0% to Jam_Max_Chance as quality approaches zero. A weapon with Can_Ever_Jam, Jam_Quality_Threshold 0.8, and Jam_Max_Chance 0.5 has a 50% maximum jam chance at zero quality and starts jamming at 80% quality.

The vanilla Cobra_Jam example in the game files shows a weapon configured with Jam_Quality_Threshold 0.9 and Jam_Max_Chance 0.5 - a weapon that starts jamming early and has a high maximum jam rate. This configuration intentionally creates an unreliable weapon as a gameplay constraint.

Table 8: Magazine Attachments

The magazine attachments table controls reload behavior, magazine compatibility, ammunition counts, and magazine replacement logic.

Field	Type	Default	Purpose
Allow_Magazine_Change	bool	true	When false, the magazine cannot be removed, replaced, or reloaded. Functions similarly to Hook_Barrel and Hook_Grip for magazine slots.
Ammo_Min	uint8	0	Minimum amount of ammunition randomly generated in the default magazine attachment when the weapon spawns.
Ammo_Max	uint8	0	Maximum amount of ammunition randomly generated in the default magazine attachment when the weapon spawns.
Ammo_Per_Shot	uint8	1	Number of ammunition units consumed per shot. A value of 3 consumes three rounds per trigger pull. A value of 0 produces infinite ammunition.
Magazine	uint16	0	Legacy ID of the magazine attachment equipped by default.
Magazine_Replacements	int32	0	Array length for Magazine_Replacement_#_ID and Magazine_Replacement_#_Map. When greater than 0, the weapon checks map-level conditions for alternative default magazines.
Magazine_Replacement_#_ID	uint16	0	Legacy ID of an alternative default magazine for a specific map. Used with Magazine_Replacement_#_Map.
Magazine_Replacement_#_Map	string	(empty)	Name of the map on which Magazine_Replacement_#_ID should be used as the default magazine.
Delete_Empty_Magazines	flag	deprecated	Deprecated in version 3.30.3.0. Use Should_Delete_Empty_Magazines instead.
Hammer_Time	float32	1	Multiplier on the hammer pull cooldown after firing. Values below 1 have no effect. The hammer cooldown is the delay before the player can perform other actions after a shot.
Infinite_Ammo	bool	false	When true, ammunition is not depleted from the magazine. The weapon needs a loaded magazine with at least Ammo_Per_Shot rounds to fire, but the rounds are not consumed.
Reload_Time	float32	1	Multiplier on the reload cooldown after starting a reload. Values below 1 have no effect.
Replace	float32	1	Multiplier on the reload animation length before the new magazine model appears. Values below 0.01 have no effect.
Unplace	float32	0	Multiplier on the reload animation length before the old magazine model is removed.
Should_Delete_Empty_Magazines	bool	See description	When true, empty magazine attachments are deleted from inventory when completely depleted. Defaults to true for Action Break, Pump, Rail, Rocket, and String. Defaults to false for all other action types.

The Replace and Unplace fields control the visual timing of magazine swapping during the reload animation. Unplace determines how far into the animation the old magazine disappears. Replace determines how far in the new magazine appears. A weapon that reloads slowly might use long Replace and Unplace values; a weapon with a snappy tactical reload might use short values.

Table 9: Projectiles (Ballistic System)

The ballistic projectile system uses a deterministic simulation for projectile travel. This is the system used by Action Trigger, Bolt, Pump, Rail, String, Break, and Minigun.

Field	Type	Default	Purpose
Ballistic_Drop	float32	deprecated	Deprecated in version 3.23.7.0. Use Bullet_Gravity_Multiplier instead. Existing values are automatically converted if Bullet_Gravity_Multiplier has not been configured.
Ballistic_Steps	uint8	See description	Lifespan of the ballistic projectile in simulation steps. Higher values relative to Ballistic_Travel produce lower muzzle velocity. Must be greater than 0. Defaults to Range / Ballistic_Travel rounded up.
Ballistic_Travel	float32	See description	Travel speed of the ballistic projectile per simulation step. Higher values relative to Ballistic_Steps produce higher muzzle velocity. Must be greater than 0.1. Defaults to 10. When Ballistic_Steps is specified and Ballistic_Travel is not, defaults to Range / Ballistic_Steps.
Bullet_Gravity_Multiplier	float32	4	Multiplier on gravity acceleration for ballistic projectiles. A value of 1 produces realistic bullet drop at 9.81 m/s2. The default of 4 produces exaggerated drop suitable for Unturned's engagement distances.

The ballistic simulation uses a step-based model. The projectile advances Ballistic_Travel units per simulation step for Ballistic_Steps steps. The total distance the projectile can travel before despawning is Ballistic_Travel × Ballistic_Steps. When the ballistics game mechanic is disabled in the server configuration, ballistic projectiles function as hitscan (instantaneous hit detection at any range up to the weapon's Range value).

Common configuration pitfall: Configuring both Ballistic_Travel and Ballistic_Steps independently can produce a mismatch between the weapon's Range field and its actual projectile range. The documented recommendation is to configure either Ballistic_Travel or Ballistic_Steps but not both, and to leave the other field to its calculated default. Configuring neither produces default behavior where both fields are calculated from Range.

Table 10: Projectiles (Physics System)

The physics projectile system uses Unity's physics simulation for projectile behavior. This system is used exclusively by Action Rocket. Physics projectiles are not deterministic and cause area-of-effect explosions on impact.

Field	Type	Default	Purpose
Ballistic_Force	float32	0.002	Force in Newtons applied to the physics projectile. This is the thrust force applied via Unity's Rigidbody.AddForce. Higher values produce faster and more impactful projectiles.
Projectile_Explosion_Launch_Speed	float32	See description	Speed at which players caught in the area-of-effect explosion are launched. Defaults to Player_Damage × 0.1. Used for rocket-jump-style gameplay mechanics.
Projectile_Lifespan	float32	30	Lifespan of the physics projectile in seconds. After this time elapses, the projectile despawns without detonating.
Projectile_Penetrate_Buildables	flag	not set	When present, area-of-effect explosions from physics projectiles penetrate through buildable structures.

Physics projectiles are physical Unity objects with Rigidbody components. Their trajectory is influenced by gravity, collisions, and applied force in a way that is not deterministic across different frame rates or physics simulation timesteps. This makes physics projectiles suitable for explosive munitions where deterministic accuracy is less important than area-of-effect gameplay.

The sequence shows the physics projectile lifecycle. Unlike ballistic projectiles, which are simulated in a deterministic step model, physics projectiles are full Unity physics objects that interact with the world through the physics engine.

Property system	Projectile simulation	Deterministic?	Area-of-effect?	Used by
Ballistic	Step-based, engine-calculated	Yes (same trajectory every time at same inputs)	No	Trigger, Bolt, Pump, Rail, String, Break, Minigun
Physics	Unity physics engine	No (varies by framerate, physics timestep)	Yes, on impact	Rocket

Table 11: Rechambering Properties

The rechambering table controls the hammer animation timing and shell casing ejection behavior after firing and reloading.

Field	Type	Default	Purpose
CasingEjectCountAfterRechamberingAfterShooting	int32	1	Number of shell casing particles ejected after the hammer animation following a shot. Only applicable when RechamberAfterShotCount is non-zero. Ejection occurs after EjectAfterHammerDelay seconds.
CasingEjectCountAfterReload	int32	See description	Number of shell casing particles ejected after a reload. Defaults to Ammo_Max for Action Break guns. Zero for all other action types. Ejection occurs after EjectAfterReloadDelay seconds.
EjectAfterHammerDelay	float32	0.45	Delay in seconds after the hammer animation before shell casing particles eject. Only applicable when RechamberAfterShotCount is non-zero.
EjectAfterReloadDelay	float32	0.5	Delay in seconds after the reload animation before shell casing particles eject. Only applicable when CasingEjectCountAfterReload is greater than zero.
EjectCasingAfterShooting	bool	See description	When true, a shell casing particle ejects on each shot. Defaults to true for Action Trigger and Action Minigun.
RechamberAfterMagazineAttached	ERechamberGunAfterReloadMode	IfAmmoWasEmpty	Determines whether the hammer animation plays after a magazine is attached. This occurs when a magazine replaces another or fills a previously empty slot.
RechamberAfterMagazineDetached	ERechamberGunAfterReloadMode	Always	Determines whether the hammer animation plays after a magazine is detached. This occurs when a magazine is removed without a replacement.
RechamberAfterShotCount	int32	See description	If non-zero, the hammer animation plays after this many consecutive shots. The shot count resets after reloading, hammering, or dequipping the weapon. Defaults to 1 for Action Bolt and Action Pump. Zero for all other action types.
RechamberAfterShotDelay	float32	0.25	Delay in seconds after the last shot before the hammer animation plays. Only applicable when RechamberAfterShotCount is non-zero.

The CasingEjectCountAfterReload field is notably set to Ammo_Max for break-action weapons, which eject all spent shells at once when the weapon is broken open for reloading. Pump-action and bolt-action weapons typically eject one casing per manual cycle.

Table 12: Recoil

The recoil table controls camera recoil values and per-stance multipliers.

Field	Type	Default	Purpose
Aiming_Recoil_Multiplier	float32	1	Multiplier on all recoil values while aiming down sights.
Recoil_Min_X	float32	0	Minimum horizontal recoil in degrees (negative is leftward).
Recoil_Max_X	float32	0	Maximum horizontal recoil in degrees.
Recoil_Min_Y	float32	0	Minimum vertical recoil in degrees (negative is upward).
Recoil_Max_Y	float32	0	Maximum vertical recoil in degrees.
Recover_X	float32	0	Multiplier on horizontal camera recovery over the next 250 milliseconds after recoil settles.
Recover_Y	float32	0	Multiplier on vertical camera recovery over the next 250 milliseconds after recoil settles.
Recoil_Crouch	float32	0.85	Multiplier on camera recoil while crouched.
Recoil_Prone	float32	0.7	Multiplier on camera recoil while prone.
Recoil_Sprint	float32	1.25	Multiplier on camera recoil while sprinting. Only relevant when Can_Aim_During_Sprint is true.
Recoil_Swimming	float32	1.1	Multiplier on camera recoil while swimming.
Recoil_Midair	float32	1.0	Multiplier on camera recoil while jumping or falling.

The recoil system selects a random value between Recoil_Min_X and Recoil_Max_X for horizontal deflection and between Recoil_Min_Y and Recoil_Max_Y for vertical deflection on each shot. The Recover_X and Recover_Y fields apply a counter-animation that brings the camera back toward the original position over 250 milliseconds. A weapon with Recover_Y 0.6 recovers 60% of the vertical deflection over the recovery window.

Table 13: Shake

The shake table controls model shake values, which produce a visual trembling effect on the weapon model independent of camera recoil.

Field	Type	Default	Purpose
Shake_Min_X	float32	0	Minimum horizontal model shake amplitude.
Shake_Max_X	float32	0	Maximum horizontal model shake amplitude.
Shake_Min_Y	float32	0	Minimum vertical model shake amplitude.
Shake_Max_Y	float32	0	Maximum vertical model shake amplitude.
Shake_Min_Z	float32	0	Minimum depth-axis model shake amplitude.
Shake_Max_Z	float32	0	Maximum depth-axis model shake amplitude.

Model shake is a visual-only effect that simulates the mechanical vibration of the weapon after firing. The engine selects random values within the min-max range for each axis on every shot. Shake does not affect aim precision or recoil - it is purely cosmetic feedback.

Table 14: Spread

The spread table controls bullet angle-of-deviation values and per-stance multipliers.

Field	Type	Default	Purpose
Spread_Aim	float32	0	Multiplier on Spread_Angle_Degrees while aiming down sights.
Spread_Angle_Degrees	float32	0	Base bullet angle of deviation in degrees from the aiming direction. A value of 15 means the shot can deviate up to 15 degrees from the crosshair center. All other spread values are multipliers applied to this base.
Spread_Crouch	float32	0.85	Multiplier on Spread_Angle_Degrees while crouched.
Spread_Prone	float32	0.7	Multiplier on Spread_Angle_Degrees while prone.
Spread_Sprint	float32	1.25	Multiplier on Spread_Angle_Degrees while sprinting.
Spread_Swimming	float32	1.1	Multiplier on Spread_Angle_Degrees while swimming.
Spread_Midair	float32	1.5	Multiplier on Spread_Angle_Degrees while jumping or falling.
Spread_Hip	float32	deprecated	Deprecated in version 3.22.20.0. Use Spread_Angle_Degrees instead. Maintained for backward compatibility.

The spread calculation for any given shot is Spread_Angle_Degrees × stance_multiplier. A weapon with Spread_Angle_Degrees 10 and Spread_Aim 0.1 has an effective spread of 1 degree while aiming and 10 degrees while hip-firing (no multiplier applies in hip-fire). The Turret flag, when set, treats the weapon as a vehicular turret and affects the first-person viewmodel independently of the spread system.

Enumerations

The gun asset defines four enumerations that control critical behavior categories.

EAction

The Action field uses the EAction enumeration, which is the single most important field on the gun asset. The action type determines the projectile system, the reload mechanic, and the shell casing behavior.

Named value	Projectile system	Reload type	Shell casing default	Turret behavior
Trigger	Ballistic	Full magazine swap	Defaults to true for EjectCasingAfterShooting	Standard weapon
Bolt	Ballistic	Single-round chamber	RechamberAfterShotCount defaults to 1	Standard weapon
Pump	Ballistic	Single-round chamber	RechamberAfterShotCount defaults to 1; Should_Delete_Empty_Magazines defaults to true	Standard weapon
Rail	Ballistic	Single-round chamber	Shell defaults to 0	Standard weapon
String	Ballistic	Single-round chamber	Bow-specific audio defaults (Gunshot_Rolloff_Distance defaults to 16)	Standard weapon
Break	Ballistic	Single-round chamber	Should_Delete_Empty_Magazines defaults to true; CasingEjectCountAfterReload defaults to Ammo_Max	Standard weapon
Rocket	Physics	Single-round chamber	Uses physics projectile system; area-of-effect explosion on impact	Standard weapon
Minigun	Ballistic	Full magazine swap	EjectCasingAfterShooting defaults to true; Must_Aim_To_Shoot defaults to true	Standard weapon

Each EAction value also determines the audio categories used for the weapon's firing sound. The Gunshot_Rolloff_Distance default is 512 for all actions except String (16) and Rocket (64).

EDriverTurretViewmodelMode

The DriverTurretViewmodelMode enumeration controls how first-person arms are displayed when the weapon is operated from a vehicle's driver seat.

Named value	Description
OffscreenWhileAiming	Default. Pushes first-person arms off-screen while aiming in a turret. Originally implemented for the Fighter Jet where visible arms look incorrect when the camera zooms in.
AlwaysOffscreen	Pushes first-person arms off-screen whenever the weapon is equipped in a turret.
AlwaysOnscreen	First-person arms remain visible regardless of turret aiming state. Included for completeness.

The AlwaysOnscreen value is the least common and exists primarily for debugging and for turret setups where the viewmodel intentionally obscures part of the screen.

ERechamberGunAfterReloadMode

The RechamberAfterMagazineAttached and RechamberAfterMagazineDetached fields use this enumeration.

Named value	Description
IfAmmoWasEmpty	Default. The hammer animation plays only if the ammo count was zero before the magazine attachment or detachment.
Never	The hammer animation never plays after magazine attachment or detachment, regardless of ammo count.
Always	The hammer animation always plays after magazine attachment or detachment, regardless of ammo count.

The IfAmmoWasEmpty setting is the most common for conventional firearms: the hammer cycles only when a fresh magazine is loaded into an empty chamber. The Always setting is used for weapons where the action cycles on every reload, such as some pump-action and break-action designs that eject a chambered round on any reload.

Fire-mode flag combination

The Safety, Semi, Auto, and Bursts fields collectively define the weapon's available firing modes. They are processed as flags and a numeric count rather than as a single enumeration:

Mode presence	Safety	Semi	Auto	Bursts
Safe + Semi	Present	Present	Absent	0
Safe + Semi + Auto	Present	Present	Present	0
Safe + Semi + Burst	Present	Present	Absent	3 (example)
Safe + Auto	Present	Absent	Present	0
Semi + Auto	Absent	Present	Present	0
Semi only	Absent	Present	Absent	0
Auto only	Absent	Absent	Present	0

The engine cycles through the configured modes in order. Each press of the fire-mode key advances to the next available mode. When the last mode is reached, the next press cycles back to the first.

NPC reward integration

Gun assets can define quest rewards that fire when the weapon is used. These rewards use the Shoot_Quest_ prefix and follow the standard Unturned quest reward system. For example, a configuration that spawns an item in the player's inventory every time the gun is fired uses the Shoot_Quest_Rewards field. Every shot fired from the weapon triggers the reward evaluation. This mechanic is exposed in the NPC rewards documentation.

The Shoot_Quest_Rewards array follows the same format as other quest reward arrays. Each entry in the array specifies one or more items to spawn, with optional probability and amount. The rewards fire on every shot unless the reward entry specifies conditions that suppress it.

Worked .dat examples

The examples below are taken from or derived from shipped vanilla .dat files in the Unturned installation. Each example demonstrates a different weapon category and field configuration pattern.

Example 1: Semi-automatic assault rifle (Eaglefire)

The Eaglefire is a semi-automatic and burst-fire assault rifle that accepts NATO 5.56mm (caliber 1) magazines.

GUID b03d581a5c1a490f995f8deba57b0f17
Type Gun
Rarity Rare
Useable Gun
Slot Primary
ID 4

Size_X 4
Size_Y 2
Size_Z 0.4
Size2_Z 0.6

Sight 5
Magazine 6

Hook_Sight
Hook_Tactical
Hook_Grip
Hook_Barrel

Ammo_Min 10
Ammo_Max 30

Safety
Semi
Bursts 3

Caliber 1

Range 200
Firerate 4
Action Trigger

Player_Damage 40
Zombie_Damage 99
Animal_Damage 40
Barricade_Damage 20
Structure_Damage 15
Vehicle_Damage 35
Resource_Damage 15
Object_Damage 25

Durability 0.15

Aim_In_Duration 0.25
Spread_Aim 0.05
Spread_Angle_Degrees 5.71

Recoil_Min_X 0.5
Recoil_Min_Y 3
Recoil_Max_X 1.5
Recoil_Max_Y 4

Recover_X 0.4
Recover_Y 0.4

Shake_Min_X -0.0025
Shake_Min_Y 0.0025
Shake_Min_Z -0.01
Shake_Max_X 0.0025
Shake_Max_Y -0.0025
Shake_Max_Z -0.02

Muzzle 3

This configuration demonstrates a standard NATO-pattern assault rifle: safety, semi-auto, and burst-fire modes; four attachment hooks (sight, tactical, grip, barrel); Caliber 1 for NATO 5.56mm magazine compatibility; moderate recoil with low shake; and a default sight (legacy ID 5) and magazine (legacy ID 6) pre-equipped.

Example 2: Heavy machine gun (Nykorev)

The Nykorev is a belt-fed light machine gun with automatic fire only and an Equipable_Movement_Speed_Multiplier that slows the player while equipped.

GUID cde96a85b86b4ea99389a83eaa603a32
Type Gun
Rarity Epic
Useable Gun
Slot Primary
ID 126

Size_X 5
Size_Y 2
Size_Z 0.3
Size2_Z 0.55

Sight 128
Magazine 127

Hook_Sight
Hook_Tactical
Hook_Grip
Hook_Barrel

Ammo_Min 30
Ammo_Max 200

Safety
Auto

Caliber 10

Equipable_Movement_Speed_Multiplier 0.95

Range 150
Firerate 5
Unplace 0.2
Replace 0.8
Action Trigger

Player_Damage 11
Zombie_Damage 33
Animal_Damage 11
Barricade_Damage 10
Structure_Damage 10
Vehicle_Damage 10
Resource_Damage 10
Object_Damage 10

Durability 0.125

Spread_Aim 0.1
Spread_Angle_Degrees 8.53

Recoil_Min_X -4
Recoil_Min_Y 4
Recoil_Max_X 2
Recoil_Max_Y 6

Recover_X 0.6
Recover_Y 0.6

Shake_Min_X -0.003
Shake_Min_Y 0.003
Shake_Min_Z -0.01
Shake_Max_X 0.003
Shake_Max_Y -0.003
Shake_Max_Z -0.02

Muzzle 3

This configuration demonstrates an LMG with only two fire modes (safe and auto), a large ammo capacity range (30-200 rounds), movement speed penalty (Equipable_Movement_Speed_Multiplier 0.95), and modified reload timing (Unplace 0.2 and Replace 0.8 for belt-fed reload animation timing).

Example 3: Bolt-action sniper rifle (Schofield)

The Schofield is a bolt-action sniper rifle with high per-shot damage, slow fire rate, and no attachment barrel hook.

GUID c9e5a852b9c14206b483e629ee33ade0
Type Gun
Rarity Uncommon
Useable Gun
Slot Primary
ID 101

Size_X 5
Size_Y 2
Size_Z 0.4
Size2_Z 0.8

Sight 102
Magazine 103

Hook_Sight
Hook_Tactical
Hook_Grip
Hook_Barrel

Ammo_Min 1
Ammo_Max 5

Safety
Semi

Caliber 5

Range 200
Firerate 50
Action Bolt

Player_Damage 80
Zombie_Damage 99
Animal_Damage 99
Barricade_Damage 25
Structure_Damage 20
Vehicle_Damage 30
Resource_Damage 20
Object_Damage 20

Durability 0.4

Spread_Aim 0.01
Spread_Angle_Degrees 11.31

Recoil_Min_X -8
Recoil_Min_Y 20
Recoil_Max_X 8
Recoil_Max_Y 25

Recover_X 0.3
Recover_Y 0.3

Shake_Min_X -0.005
Shake_Min_Y 0.005
Shake_Min_Z -0.05
Shake_Max_X 0.005
Shake_Max_Y -0.005
Shake_Max_Z -0.1

Muzzle 4

This configuration demonstrates a bolt-action weapon: Action Bolt for single-round chambering, high Firerate 50 (very slow rate of fire), high Player_Damage 80 and Zombie_Damage 99, narrow Spread_Aim 0.01 for precision shooting, and high recoil with slow recovery. The Ammo_Min 1 and Ammo_Max 5 produce a small magazine capacity consistent with a bolt-action sniper rifle.

Example 4: Rocket launcher (Launcher_Rocket)

The Launcher_Rocket uses Action Rocket for physics projectile behavior with area-of-effect explosions.

GUID af47bb9e0ba7443fa69435f1f594a10b
Type Gun
Rarity Legendary
Useable Gun
Slot Primary
ID 519

Size_X 4
Size_Y 2
Size_Z 0.45
Size2_Z 0.7

Sight 521
Magazine 520

Hook_Sight
Hook_Tactical
Hook_Grip

Ammo_Min 1
Ammo_Max 1

Safety
Semi

Caliber 20

Firerate 50
Replace 0.5
Action Rocket

Player_Damage 200
Zombie_Damage 200
Animal_Damage 200
Barricade_Damage 1000
Structure_Damage 1000
Vehicle_Damage 500
Resource_Damage 2000
Object_Damage 1000

Range 12
Explosion 45

Durability 1
Wear 5

Spread_Aim 0.1
Spread_Angle_Degrees 5.71

Ballistic_Force 2000

Recoil_Min_X -15
Recoil_Min_Y 25
Recoil_Max_X 15
Recoil_Max_Y 30

Recover_X 0.7
Recover_Y 0.7

Shake_Min_X -0.0025
Shake_Min_Y 0.0025
Shake_Min_Z -0.01
Shake_Max_X 0.0025
Shake_Max_Y -0.0025
Shake_Max_Z -0.02

This configuration demonstrates a physics-projectile rocket launcher: Action Rocket, Ballistic_Force 2000 for the projectile thrust, Range 12 as the explosion radius (not bullet range), Explosion 45 as the explosion effect, and extremely high damage values across all categories. The Ammo_Min 1 and Ammo_Max 1 limit the launcher to single-shot capacity.

Example 5: Jamming-enabled pistol (Cobra_Jam variant)

The Cobra_Jam configuration demonstrates the jamming system with a high jam probability curve.

GUID a5f36c8e14c04c0bb886ef2af1b523d7
Type Gun
Rarity Rare
Useable Gun
Slot Secondary
ID 1521

Can_Ever_Jam
Jam_Quality_Threshold 0.9
Jam_Max_Chance 0.5
Unjam_Chamber_Anim Reload

Master_Bundle_Override core.masterbundle
Bundle_Override_Path /Items/Guns/Cobra

Size_X 2
Size_Y 2
Size_Z 0.3
Size2_Z 0.35

Magazine 100

Hook_Barrel
Hook_Tactical

Ammo_Min 5
Ammo_Max 20

Safety
Semi
Auto

Caliber 4

Range 80
Firerate 4
Action Trigger

Player_Damage 25
Zombie_Damage 99
Animal_Damage 25
Barricade_Damage 12
Structure_Damage 12
Vehicle_Damage 25
Resource_Damage 15
Object_Damage 15

Durability 1
Wear 1

Spread_Aim 0.1
Spread_Angle_Degrees 16.7

Recoil_Min_X -6
Recoil_Min_Y 3
Recoil_Max_X 2
Recoil_Max_Y 4.5

Recover_X 0.2
Recover_Y 0.4

Shake_Min_X -0.005
Shake_Min_Y 0.005
Shake_Min_Z -0.05
Shake_Max_X 0.005
Shake_Max_Y -0.005
Shake_Max_Z -0.075

Muzzle 3

This configuration demonstrates jamming support via Can_Ever_Jam, Jam_Quality_Threshold 0.9 (jamming starts at 90% quality), Jam_Max_Chance 0.5 (50% maximum jam chance), and Unjam_Chamber_Anim Reload (uses the reload animation as the unjam animation since no dedicated UnjamChamber clip exists). Additionally, it uses Master_Bundle_Override core.masterbundle with Bundle_Override_Path to reference the core master bundle rather than a mod-specific bundle.

Frequently asked questions

What is the difference between ballistic and physics projectiles?

Ballistic projectiles use a deterministic step-based simulation controlled by Ballistic_Travel, Ballistic_Steps, and Bullet_Gravity_Multiplier. Physics projectiles use Unity's physics engine with a Rigidbody, controlled by Ballistic_Force, Projectile_Lifespan, and Projectile_Penetrate_Buildables. Ballistic projectiles produce no area-of-effect damage on their own; physics projectiles always detonate with an explosion on impact. Ballistic projectiles can function as hitscan when the ballistics setting is disabled on the server.

Which action types use which projectile system?

All action types except Rocket use the ballistic projectile system. Only Action Rocket uses the physics projectile system. This is a hard-coded mapping - configuring Ballistic_Force on a Trigger action weapon has no effect, and configuring Ballistic_Travel on a Rocket action weapon has no effect.

How does the magazine caliber array interact with the single Caliber field?

The Caliber field is used as a fallback when Magazine_Calibers is not configured (or is set to 0 or 1 with no Magazine_Caliber_# entries). When Magazine_Calibers is set to a value greater than 1 and corresponding Magazine_Caliber_# entries exist, those entries are read and the Caliber field is ignored for magazine compatibility. A gun can accept one caliber through the simple Caliber field or multiple calibers through the array.

What is the purpose of Attachment_Calibers?

Attachment_Calibers and Attachment_Caliber_# allow a gun to accept a different set of caliber IDs for hook attachments (sights, grips, tactical, barrels) than for magazines. A gun might accept NATO 5.56mm magazines (caliber 1) but accept only custom grips (caliber 5001). When Attachment_Calibers is not configured, it defaults to whatever Magazine_Calibers is set to, making attachment and magazine calibers identical.

Can I make a gun that has no attachments?

Yes. Omit all Hook_* flags. The gun will not have any attachment slots. The Barrel, Grip, Sight, Tactical, and Magazine child GameObjects in the prefab still need to exist for model positioning, but their hook flags are what control whether the player can equip or remove attachments in-game.

What happens if I omit the Action field?

The gun will not function. The Action field is required. Without it, the engine cannot determine which projectile system to use, which reload mechanic to apply, or which shell casing defaults to use. The gun will load into the inventory and display its model, but attempting to fire produces no behavior.

How do I make a gun that fires underwater?

Underwater firing is controlled by the game mode settings (the Allow_Fire_Underwater level configuration node), not by the gun asset. A gun with high spread and high recoil underwater is the result of the stance multiplier system applying Recoil_Swimming and Spread_Swimming, not a separate underwater capability flag. If the server disables underwater firing, no gun can fire regardless of its configuration.

How does Instakill_Headshots interact with zombie damage?

Instakill_Headshots applies only to player targets by default. Zombies are not instakilled by headshots unless the world difficulty configuration has Weapons_Use_Player_Damage enabled. When that setting is active, zombie damage is calculated using the player damage values and modifiers, and Instakill_Headshots applies to zombies as it would to players.

What does the Turret flag do?

The Turret flag tells the engine to treat the weapon as a vehicular turret. This affects the first-person viewmodel behavior while the weapon is held. The DriverTurretViewmodelMode field provides additional control over how the viewmodel interacts with the driver's perspective. Turret-flagged weapons are typically vehicle-mounted machine guns and cannons, not hand-held weapons.

How is the rate of fire calculated from Firerate?

The rate of fire in rounds per second (RPS) is 50 / (Firerate + 1). A weapon with Firerate 4 fires 50 / 5 = 10 RPS. A weapon with Firerate 50 fires 50 / 51 = 0.98 RPS (approximately one round per second). A weapon with Firerate 0 fires 50 / 1 = 50 RPS (the theoretical maximum).

What is the maximum range a gun can have?

The Range field is a float32, which can hold values up to approximately 3.4 × 10^38. In practice, values beyond approximately 1000 meters exceed any reasonable engagement distance in Unturned. The ballistic projectile system's Ballistic_Steps and Ballistic_Travel interaction imposes a practical constraint: if the projectile despawns before reaching the target (because Ballistic_Travel × Ballistic_Steps is less than the target distance), the shot misses regardless of Range. Configure both fields in tandem to match the intended gameplay envelope.

Can a gun have both ballistic and physics projectiles?

No. The Action field selects exactly one projectile system. A gun configured as Action Trigger uses ballistic projectiles exclusively. A gun configured as Action Rocket uses physics projectiles exclusively. There is no hybrid mode within a single asset.

What is the purpose of Magazine_Replacement_*?

The Magazine_Replacements system allows a gun to spawn with different default magazines on different maps. A gun that spawns with a standard 30-round magazine on most maps but loads with a 10-round magazine on a survival-themed map would use Magazine_Replacement_0_ID and Magazine_Replacement_0_Map. This is a map-conditional magazine system used by the vanilla spawn tables to give weapons regional variation.

Can I make a gun that never fires (a display prop)?

Yes. Set Firerate to a high value and configure no fire mode flags (omit Semi, Auto, and Safety). The gun will equip and display its model but cannot fire because no fire mode is available. For zero-damage functionality, also set all damage fields to 0. For a fully inert display prop, additionally set Allow_Magazine_Change false to prevent reload interactions.

What does Equipable_Movement_Speed_Multiplier do on a gun?

The Equipable_Movement_Speed_Multiplier field is inherited from ItemWeaponAsset and slows the player's movement speed while the weapon is equipped. It is distinct from Aiming_Movement_Speed_Multiplier, which applies only while aiming. The Nykorev LMG uses Equipable_Movement_Speed_Multiplier 0.95 to impose a 5% movement speed penalty while the LMG is equipped, reflecting the weapon's weight.

How do body-part multipliers affect damage calculations?

The Player_Leg_Multiplier, Player_Arm_Multiplier, Player_Spine_Multiplier, and Player_Skull_Multiplier fields (and their zombie and animal equivalents) multiply the base Player_Damage value by the multiplier for the hit body part. A shot to the head on a player with Player_Skull_Multiplier 1.1 and base Player_Damage 40 deals 44 damage. A shot to the leg with Player_Leg_Multiplier 0.6 deals 24 damage. These multipliers exist for all three humanoid target categories.

Best practices

• Set Caliber to a custom value (5000+ range) for mod guns to avoid unintended compatibility with vanilla magazines. Use caliber 0 only for intentional universal compatibility.
• Configure either Ballistic_Travel or Ballistic_Steps but not both to avoid range mismatch between the projectile simulation and the Range field.
• Test jamming thresholds on a development server before shipping. A weapon that jams every few shots at 80% quality feels unreliable; a weapon that jams at 20% quality feels durable but occasionally malfunctioning.
• Author Replace and Unplace values to match the reload animation timing in the Animator Controller. A mismatch between the .dat timing and the animation clip length produces visually incorrect magazine swapping (the new magazine appears before the reload animation reaches it).
• Set all four Hook_* flags on a standard assault rifle to give players full attachment flexibility. Omit hooks only for deliberately minimalist weapons.
• Use Ammo_Min and Ammo_Max to vary the starting ammunition in spawned weapons. A weapon that always spawns with a full magazine (Ammo_Min equals Amount) produces predictable loot; a weapon with variable starting ammo (Ammo_Min lower than Ammo_Max) creates loot variety.
• Set Equipable_Movement_Speed_Multiplier below 1.0 for heavy weapons (LMGs, rocket launchers, anti-materiel rifles). Leave at 1.0 or omit for light weapons.
• Configure Damage_Falloff_Range and Damage_Falloff_Max_Range to match the intended damage curve. A close-quarters weapon should have short falloff range; a sniper rifle should have long or no falloff.
• Apply scale in Blender before FBX export. Non-unit scale on the mesh produces incorrect in-game size on the gun model.
• Verify Firerate with the rate-of-fire formula before setting a value. A weapon with Firerate 200 has a theoretical rate of approximately 0.25 rounds per second, which may produce a disappointing firing feel.

Advanced considerations

Multi-caliber weapon design

A gun that accepts multiple caliber families (e.g., a survival rifle that fires both 5.56mm and .22 LR through barrel inserts) should configure both Magazine_Calibers and Attachment_Calibers arrays with the full set of accepted caliber IDs. The Unity prefab should have caliber-specific Magazine child GameObjects (Caliber_1, Caliber_14) to position each magazine type correctly in the magazine well. The weapon's ballistic performance (Ballistic_Travel, Ballistic_Steps, Bullet_Gravity_Multiplier) applies uniformly regardless of which caliber is loaded - the caliber-specific ballistic tuning comes from the magazine asset's Speed field, not from the gun.

Custom master bundle overrides

The Master_Bundle_Override and Bundle_Override_Path fields allow a gun asset to reference a prefab in a different master bundle than the default. The vanilla Cobra_Jam example uses this to reference the core master bundle while keeping the .dat file in a mod-specific folder. This pattern is useful when multiple weapons share a common prefab structure or when a weapon needs to override only the .dat configuration while using the vanilla model bundle.

Vehicle turret weapons

Weapons with the Turret flag behave differently in first-person view when mounted on a vehicle. The DriverTurretViewmodelMode controls whether the player's arms are visible. When authoring a turret weapon, set Slot Primary and verify that the prefab hierarchy uses the same child GameObject structure (Barrel, Grip, Sight, Tactical, Magazine, Eject) as a hand-held weapon. The engine applies the turret viewmodel logic based on the vehicle's seat configuration, not on the weapon asset itself.

Weapon durability and quality interactions

The Durability field (inherited from ItemWeaponAsset) interacts with the jamming system when Can_Ever_Jam is set. As the weapon's quality drops due to use (governed by Wear), the jamming probability increases linearly below Jam_Quality_Threshold. A non-jamming weapon with low Durability simply becomes less effective visually; a jamming-enabled weapon with low durability becomes mechanically unreliable. The Invulnerable flag (also inherited from ItemWeaponAsset) prevents durability loss entirely, making the weapon indestructible.

Appendix A: Gun asset .dat quick-reference card

Category	Field	Type	Required	Default
Identity	ID	uint16	Yes	,
Identity	GUID	uint128	Yes	,
Identity	Type	enum (Gun)	Yes	,
Identity	Useable	enum (Gun)	Yes	,
Identity	Name	string	Yes	,
Identity	Rarity	enum	No	Common
Identity	Slot	enum	Yes	,
Identity	Size_X	uint8	Yes	,
Identity	Size_Y	uint8	Yes	,
Firing	Action	EAction	Yes	,
Firing	Auto	flag	No	not set
Firing	Semi	flag	No	not set
Firing	Safety	flag	No	not set
Firing	Bursts	int32	No	0
Firing	Firerate	uint8	No	0
Firing	Fire_Delay_Seconds	int32	No	0
Caliber	Caliber	uint16	No	0
Caliber	Magazine_Calibers	int32	No	1
Caliber	Magazine_Caliber_#	uint16	No	0
Caliber	Attachment_Calibers	int32	No	(see Magazine_Calibers)
Caliber	Attachment_Caliber_#	uint16	No	0
Caliber	Requires_NonZero_Attachment_Caliber	bool	No	false
Hooks	Hook_Sight	flag	No	not set
Hooks	Hook_Grip	flag	No	not set
Hooks	Hook_Tactical	flag	No	not set
Hooks	Hook_Barrel	flag	No	not set
Hooks	Sight	uint16	No	0
Hooks	Grip	uint16	No	0
Hooks	Tactical	uint16	No	0
Hooks	Barrel	uint16	No	0
Magazine	Allow_Magazine_Change	bool	No	true
Magazine	Ammo_Min	uint8	No	0
Magazine	Ammo_Max	uint8	No	0
Magazine	Ammo_Per_Shot	uint8	No	1
Magazine	Magazine	uint16	No	0
Magazine	Magazine_Replacements	int32	No	0
Magazine	Magazine_Replacement_#_ID	uint16	No	0
Magazine	Magazine_Replacement_#_Map	string	No	(empty)
Magazine	Infinite_Ammo	bool	No	false
Magazine	Reload_Time	float32	No	1
Magazine	Replace	float32	No	1
Magazine	Unplace	float32	No	0
Magazine	Hammer_Time	float32	No	1
Magazine	Should_Delete_Empty_Magazines	bool	No	(see Action default)
Ballistic	Ballistic_Steps	uint8	No	Range / Ballistic_Travel
Ballistic	Ballistic_Travel	float32	No	10
Ballistic	Bullet_Gravity_Multiplier	float32	No	4
Physics	Ballistic_Force	float32	No	0.002
Physics	Projectile_Explosion_Launch_Speed	float32	No	Player_Damage × 0.1
Physics	Projectile_Lifespan	float32	No	30
Physics	Projectile_Penetrate_Buildables	flag	No	not set
Damage	Damage_Falloff_Range	float32	No	1
Damage	Damage_Falloff_Max_Range	float32	No	1
Damage	Damage_Falloff_Multiplier	float32	No	1
Damage	Instakill_Headshots	bool	No	false
Effects	Muzzle	GUID/uint16	No	0
Effects	Shell	GUID/uint16	No	(see Action default)
Effects	Explosion	GUID/uint16	No	0
Jamming	Can_Ever_Jam	flag	No	not set
Jamming	Jam_Quality_Threshold	float32	No	0.4
Jamming	Jam_Max_Chance	float32	No	0.1
Jamming	Unjam_Chamber_Anim	string	No	UnjamChamber
Recoil	Recoil_Min_X	float32	No	0
Recoil	Recoil_Max_X	float32	No	0
Recoil	Recoil_Min_Y	float32	No	0
Recoil	Recoil_Max_Y	float32	No	0
Recoil	Recover_X	float32	No	0
Recoil	Recover_Y	float32	No	0
Recoil	Aiming_Recoil_Multiplier	float32	No	1
Recoil	Recoil_Crouch	float32	No	0.85
Recoil	Recoil_Prone	float32	No	0.7
Recoil	Recoil_Sprint	float32	No	1.25
Recoil	Recoil_Swimming	float32	No	1.1
Recoil	Recoil_Midair	float32	No	1.0
Shake	Shake_Min_X	float32	No	0
Shake	Shake_Max_X	float32	No	0
Shake	Shake_Min_Y	float32	No	0
Shake	Shake_Max_Y	float32	No	0
Shake	Shake_Min_Z	float32	No	0
Shake	Shake_Max_Z	float32	No	0
Spread	Spread_Aim	float32	No	0
Spread	Spread_Angle_Degrees	float32	No	0
Spread	Spread_Crouch	float32	No	0.85
Spread	Spread_Prone	float32	No	0.7
Spread	Spread_Sprint	float32	No	1.25
Spread	Spread_Swimming	float32	No	1.1
Spread	Spread_Midair	float32	No	1.5
Uncategorized	Aim_In_Duration	float32	No	0.2
Uncategorized	Aiming_Movement_Speed_Multiplier	float32	No	(see Can_Aim_During_Sprint)
Uncategorized	Alert_Radius	float32	No	48
Uncategorized	Can_Aim_During_Sprint	bool	No	false
Uncategorized	Gunshot_Rolloff_Distance	float32	No	(see Action default)
Uncategorized	Must_Aim_To_Shoot	bool	No	(see Action default)
Uncategorized	Range_Rangefinder	float32	No	(see Range)
Uncategorized	Scale_Aim_Animation_Speed	bool	No	true
Uncategorized	Stop_Aiming_After_Shooting	bool	No	false
Uncategorized	DriverTurretViewmodelMode	enum	No	OffscreenWhileAiming
Turret	Turret	flag	No	not set
Rechamber	RechamberAfterMagazineAttached	enum	No	IfAmmoWasEmpty
Rechamber	RechamberAfterMagazineDetached	enum	No	Always
Rechamber	RechamberAfterShotCount	int32	No	(see Action default)
Rechamber	RechamberAfterShotDelay	float32	No	0.25
Rechamber	CasingEjectCountAfterRechamberingAfterShooting	int32	No	1
Rechamber	CasingEjectCountAfterReload	int32	No	(see Action default)
Rechamber	EjectAfterHammerDelay	float32	No	0.45
Rechamber	EjectAfterReloadDelay	float32	No	0.5
Rechamber	EjectCasingAfterShooting	bool	No	(see Action default)
Bundle	Master_Bundle_Override	string	No	(empty)
Bundle	Bundle_Override_Path	string	No	(empty)

Appendix B: Action type projectile system and reload comparison

The table below summarizes the relationship between each EAction value, its projectile system, reload type, and notable default field values.

Action	Projectile system	Reload type	Eject casing default	Delete empty mag default	RechamberAfterShotCount default	Gunshot rolloff default
Trigger	Ballistic	Full swap	True	False	0	512
Bolt	Ballistic	Single-round	,	,	1	512
Pump	Ballistic	Single-round	,	True	1	512
Rail	Ballistic	Single-round	,	True	,	512
String	Ballistic	Single-round	,	True	,	16
Break	Ballistic	Single-round	,	True	,	512
Rocket	Physics	Single-round	,	True	,	64
Minigun	Ballistic	Full swap	True	,	,	512

Appendix C: Attachment compatibility matrix

The table below shows which attachment slot types each gun type commonly supports and which fields enable compatibility.

Attachment type	Hook flag field	Default attachment field	Caliber matching	Prefab child
Sight (optic)	Hook_Sight	Sight	Attachment_Caliber_#	Sight
Grip (foregrip)	Hook_Grip	Grip	Attachment_Caliber_#	Grip
Tactical (laser, flashlight, rangefinder)	Hook_Tactical	Tactical	Attachment_Caliber_#	Tactical
Barrel (muzzle brake, suppressor)	Hook_Barrel	Barrel	Attachment_Caliber_#	Barrel

Appendix D: Diagnostic table

Symptom	Most likely cause	Resolution
Gun does not appear in inventory after @give	ID mismatch, Bypass_ID_Limit missing, or folder path wrong	Confirm ID is unique; add Bypass_ID_Limit True if ID > 2000; check folder path
Gun appears but cannot be equipped	Useable Gun missing or Slot not configured	Add Useable Gun and set Slot Primary, Secondary, or Tertiary
Gun equips but does not fire on trigger pull	Action field missing or fire mode flags not set	Add Action Trigger (or appropriate action) and at least one fire mode flag (Semi or Auto)
Gun fires but no projectile is visible	Magazine caliber mismatch or Caliber not matching magazine	Confirm Caliber on gun matches Caliber_Reference on magazine
Attachment cannot be equipped on the gun	Hook flag for that slot type is missing	Add Hook_Sight, Hook_Grip, Hook_Tactical, or Hook_Barrel as appropriate
Attachment equips but floats at wrong position	Caliber-specific child position missing in prefab	Add Caliber_# child under the attachment's GameObject in the prefab
Reload animation does not play	Reload animation state missing from Animator Controller	Add the Reload animation state matching the clip name
Shell casing does not eject	EjectCasingAfterShooting set to false or Eject child missing	Set EjectCasingAfterShooting true; confirm Eject child GameObject in prefab
Weapon fires too fast or too slow	Firerate set to incorrect value	Use 50 / (Firerate + 1) to calculate rounds per second; tune accordingly
No muzzle flash	Muzzle field not set or effect ID invalid	Set Muzzle to a valid effect GUID or legacy ID (vanilla: 3 for rifles, 4 for heavy)
Weapon makes no sound	Gunshot_Rolloff_Distance too low or Shoot Audio Clip missing	Increase rolloff distance; add Shoot Audio Clip to prefab
Weapon jams on every shot	Can_Ever_Jam set with low quality	Confirm Jam_Quality_Threshold and Jam_Max_Chance are appropriate; add an UnjamChamber_Anim state or set Unjam_Chamber_Anim Reload
Damage does not decrease at range	Damage_Falloff_Range and Damage_Falloff_Max_Range both at default 1	Set Damage_Falloff_Range 0.3 to start falloff at 30% of Range; set Damage_Falloff_Multiplier 0.25 for 75% reduction at max range
Player moves too slowly with weapon equipped	Equipable_Movement_Speed_Multiplier set below 1.0 unintentionally	Set Equipable_Movement_Speed_Multiplier 1.0 or omit the field
Headshots do not kill players instantly	Instakill_Headshots not set or set to false	Add Instakill_Headshots True to the .dat

Authoring checklist

Before publishing a gun mod to the Steam Workshop, confirm the following:

• [ ] GUID is unique - generated fresh, not copied from another asset
• [ ] ID is in the 50000+ range
• [ ] Type Gun and Useable Gun are present
• [ ] Action is set to the correct EAction value for the weapon type
• [ ] At least one fire mode flag (Safety, Semi, Auto, Bursts) is present
• [ ] Caliber (or Magazine_Calibers array) matches the intended magazine caliber
• [ ] Hook_* flags are present for every intended attachment slot type
• [ ] Prefab has all six child GameObjects (Barrel, Grip, Sight, Tactical, Magazine, Eject)
• [ ] Animator Controller has states for Reload, Hammer, and UnjamChamber (if jamming is enabled)
• [ ] Ballistic_Travel and Ballistic_Steps are not both manually configured (range mismatch risk)
• [ ] Firerate is calculated using the 50 / (Firerate + 1) formula
• [ ] Replace and Unplace values match reload animation timing
• [ ] Scale has been applied in Blender before FBX export
• [ ] Master bundle is built and copied to the mod's Bundles/ folder
• [ ] English.dat is authored with Name and Description fields
• [ ] Tested in single-player: model visible, fires, reloads, attachments equip correctly
• [ ] Tested caliber linkage with at least one magazine
• [ ] Tested all fire modes cycle correctly
• [ ] Tested jamming behavior if Can_Ever_Jam is set

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete gun asset field reference covering all 14 property tables, 4 enumerations, both projectile systems, attachment compatibility, jamming system, NPC rewards, 5 worked .dat examples, and full FAQ.

Cross-references

• Tactical Asset Reference - the previous article in this section; covers the tactical attachment asset type.
• Weapon Asset Reference - the next article; covers the weapon asset type and its relationship to the gun asset hierarchy.
• Magazine Asset Reference - the magazine-side of the caliber linkage system; every gun asset requires at least one paired magazine.
• Attachment Slots: Sight, Grip, Tactical, Barrel - the attachment slot configuration for the hook system.
• Caliber Asset - the caliber-linkage system that binds guns, magazines, and attachments.
• Gun Mod Tutorial - the end-to-end gun mod authoring tutorial; the prerequisite for using this reference effectively.
• Melee Asset - the melee weapon asset type; shares the damage field conventions with guns.
• Item Asset Anatomy - the shared field reference for all item types.
• Master Bundle Export - the Unity bundling workflow for gun prefabs.
• Project Folder Structure and GUIDs - GUID generation and folder layout for gun mod projects.
• Animations Export (Blender to Unity) - the animation export pipeline for gun animation clips.
• Data File Format Reference - the .dat file format grammar and parser behavior.
• Smartly Dressed Games modding documentation - official SDG field reference for the ItemGunAsset class.
• Unturned on Steam - the Unturned Store page and community hub.