Gun Mod Tutorial

A custom firearm is the most-requested mod category in the Unturned™ modding community. It is also the mod category with the highest configuration surface area: a single working gun mod combines a Blender model, a Unity 2022.3 prefab, a Generic-rigged armature, four or more animation clips, a Unity material with the cohort-validated weapon shader, a master bundle export, a .dat file with thirty-plus fields, a magazine .dat, optional attachment .dat files, an English.dat localization entry, and in-game testing across single-player and dedicated servers. Any one of these steps can break the gun, and the failure modes are not always traceable to a single root cause.

This article is the cohort-validated end-to-end gun mod tutorial. It walks through every step from a finished modeled mesh to a working in-game firearm. The tutorial is structured so that a modder can follow it linearly from a Blender starting point through to a Steam Workshop submission. Cross-references to the prerequisite articles are provided at each step; a modder who is missing a prerequisite (Blender install, Unity install, FBX export pipeline) should complete the prerequisite first and then return to this article.

Prerequisites

• Blender 4.x or later. See How to Install Blender.
• Unity 2022.3 LTS. See How to Install Unity Editor.
• Notepad++. See How to Install Notepad++.
• Familiarity with the FBX export workflow. See How to Export an FBX.
• Familiarity with the animation transfer workflow. See Animations Export Blender to Unity.
• Familiarity with the project folder structure. See Project Folder Structure and GUIDs.
• A local Unturned™ install with single-player available for testing.
• Approximately 6–18 hours of authoring time for a first-time gun modder; 2–4 hours for an experienced gun modder.

What you'll learn

• How to author a weapon mesh in Blender with the correct topology, scale, and pivot.
• How to UV-unwrap and texture a weapon with appropriate texel density for in-game viewing.
• How to export the weapon as an FBX with the cohort-validated settings for weapons.
• How to import the FBX into Unity 2022.3 and configure the Generic rig.
• How to build the weapon prefab with attachment hooks, muzzle flash position, and ejection port position.
• How to wire animations into an Animator Controller with idle, fire, reload, and aim states.
• How to package the prefab into a master bundle.
• How to author the .dat file with the correct caliber, firemode, magazine, recoil, and sway fields.
• How to author the magazine .dat that pairs with the gun.
• How to author the attachment slot configuration for sights, grips, barrels, and tactical attachments.
• How to add a localization entry to English.dat.
• How to test the gun in single-player and validate every field.
• How to diagnose the most common gun mod bugs.

Background: how Unturned's gun system works

Unturned's gun runtime is built around the UseableGun script and the ItemGunAsset configuration. The ItemGunAsset reads the .dat file at load time and applies the configuration to the gun. The UseableGun is the runtime behavior — fire control, recoil application, animation triggers, audio cues, projectile spawning. The prefab is the visual template; the .dat is the parameter set; the script is the gameplay logic.

The sequence diagram above is the cohort's reference mental model for what happens when a player fires a custom gun mod. Every step in this tutorial maps back to one of the components in the diagram: the prefab provides the visual structure, the .dat provides the parameter set, the animator drives the visual sequence, the UseableGun script ties them together, and the runtime invokes the cycle on player input.

Step 1: Model the weapon in Blender

The first step is to model the weapon in Blender. The cohort's recommended workflow for new gun modders is to start with a reference image and to model in low-poly first, then add detail iteratively.

Topology recommendations

Aspect	Cohort-validated recommendation
Total polycount	8,000–15,000 tris for the body. Up to 25,000 with attachments.
Topology	Quad-dominant. Avoid n-gons.
Edge flow	Edge loops follow the form of the weapon. Loops at hard transitions (e.g., barrel-to-receiver).
Sub-meshes	Body, slide, trigger, magazine, sight rails as separate sub-meshes if they animate independently.
Smoothing	Smooth shading with edge-split modifier or hard edges marked explicitly.

Scale and pivot

The weapon mesh must be modeled at real-world scale. A typical rifle is approximately 90 cm long. The cohort recommendation is to use Blender's metric unit system and to model with millimeter precision.

The mesh origin should be at the position where the player's primary hand grips the weapon. For a rifle, this is typically at the front of the trigger guard, slightly below the bore line. For a pistol, this is at the center of the grip. Setting the origin correctly here saves time in the Unity step.

Pro tip

Reference real-world weapon photography for proportions. Online image libraries (e.g., manufacturer product pages, Wikipedia firearm articles) provide top, side, and front views. The cohort's recommended workflow is to import three reference images on three perpendicular reference planes in Blender, then to model against the references simultaneously.

Sub-meshes for animation

Sub-meshes that animate independently from the body must be separate Blender objects parented to the armature. Common animated sub-meshes for a rifle:

Sub-mesh	Animation
Slide	Reciprocates during fire and reload
Trigger	Pivots back during fire
Magazine	Detaches during reload
Bolt handle	Cycles during bolt-action reload
Hammer	Cocks during single-action fire
Charging handle	Cycles during charging animation

Each animated sub-mesh should be a separate Blender object so that the armature can drive its position independently.

Step 2: UV unwrap and texture

The UV layout determines the texel density of the in-game weapon. Texel density is the relationship between the texture resolution and the surface area of the mesh; the cohort-validated target for Unturned™ weapons is approximately 10–15 texels per centimeter of mesh surface.

UV unwrapping workflow

1. Mark seams along edges that will be hidden in the final view (typically the underside of the barrel, the inside of the receiver).
2. Apply Blender's Smart UV Project or unwrap manually with U → Unwrap.
3. Open the UV Editor and inspect the layout.
4. Use Blender's Pack Islands feature to pack the UV islands efficiently into the 0–1 UV space.
5. Confirm texel density is consistent across islands. Islands with significantly different texel density will appear at inconsistent detail levels in-game.

Texture authoring

The cohort's recommended texture workflow is to author in Substance Painter, Substance Designer, or Photoshop with a PBR workflow. The required texture maps for an Unturned™ weapon are:

Texture	Resolution	Purpose
Albedo	2048×2048	Base color of the weapon.
Normal Map	2048×2048	Surface detail without geometry cost.
Metallic/Roughness	2048×2048	PBR material parameters.
Ambient Occlusion	1024×1024	Pre-baked ambient occlusion.
Emissive (optional)	1024×1024	Glowing elements (tracer rounds, sight illumination).

Texture sizing

Textures larger than 2048×2048 increase the master bundle size noticeably and slow down the in-game load. The cohort recommendation is to cap weapon textures at 2048×2048 unless the weapon is intended as a hero/showcase piece.

Step 3: Rig and animate

Rig the weapon with an armature following the cohort-validated bone naming convention documented in Animations Export Blender to Unity. The minimum bone set for a semi-auto rifle is:

• Weapon_Root (root bone)
• Slide (reciprocating slide/bolt)
• Trigger
• Magazine
• MuzzleFlash (empty bone for muzzle position)
• EjectionPort (empty bone for shell ejection position)
• Sight_Iron (iron sight alignment)
• Hook_Sight, Hook_Grip, Hook_Tactical, Hook_Barrel, Hook_Magazine (attachment points)

Author the animations in Blender. The minimum animation set is:

Animation	Length (frames at 30 fps)	Loop?
Idle	60–120 (2–4 sec breathing cycle)	Yes
Fire	6–10 (0.2–0.33 sec)	No
Reload	60–90 (2–3 sec)	No
Aim	8–12 (0.27–0.4 sec)	No
Scope_On (optional)	8–12	No
Inspect (optional)	90–150	No

Push each animation down to the NLA track so that the FBX exporter captures them as separate clips.

Step 4: Export FBX

Export the rigged and animated weapon as an FBX using the cohort-validated settings documented in How to Export an FBX and Animations Export Blender to Unity.

Key settings:

• Forward: -Z Forward
• Up: Y Up
• Apply Transform: Enabled
• Only Deform Bones: Enabled
• Add Leaf Bones: Disabled
• Bake Animation: Enabled
• NLA Strips: Enabled
• All Actions: Enabled
• Simplify: 0.0

Save the FBX to a temporary location; the next step copies it into the Unity project.

Step 5: Import to Unity 2022.3

Open Unity Hub and create a new Unturned™ modding project, or open an existing one. The project's folder structure should follow the cohort convention documented in Project Folder Structure and GUIDs.

1. Drag the FBX into the project's Assets/Weapons/MyRifle/ folder.
2. Select the FBX in the Project window.
3. Inspector → Model tab:
   • Scale Factor: 1
   • Convert Units: Disabled
   • Bake Axis Conversion: Enabled
   • Mesh Compression: Off
   • Generate Colliders: Disabled
4. Inspector → Rig tab:
   • Animation Type: Generic
   • Avatar Definition: Create From This Model
   • Root node: Weapon_Root
   • Apply
5. Inspector → Animation tab:
   • For each clip, confirm Start and End frames match the Blender action range.
   • Idle and Aim: Enable Loop Time.
   • Fire and Reload: Disable Loop Time.
   • For all clips: Enable Root Transform Position (XZ) → Bake Into Pose.
6. Inspector → Materials tab:
   • Set Texture Search Mode to Project-Wide.
   • Confirm each material is wired to the corresponding texture.

Material configuration

The cohort-validated material for an Unturned™ weapon is:

Material slot	Texture
Albedo	The weapon's albedo texture.
Normal Map	The weapon's normal map. Mark as Normal Map in import settings.
Metallic	The weapon's metallic/roughness texture. R channel = metallic, A channel = smoothness.
Occlusion	The weapon's ambient occlusion texture (optional).
Emission	The weapon's emissive texture (optional).

The cohort's recommended shader for Unturned™ weapons is the Standard shader (Built-in render pipeline) with Smoothness Source set to Metallic Alpha. The Universal Render Pipeline (URP) is not the default for Unturned modding; check the Smartly Dressed Games modding documentation for the current render pipeline target.

Step 6: Build the prefab

The prefab is the assembled Unity scene-graph structure that becomes the in-game weapon. The cohort-validated prefab hierarchy is:

MyRiflePrefab (root, with UseableGun script)
├── Body (MeshRenderer + MeshFilter for receiver/barrel)
├── Animator (Animator component, parent for animated sub-meshes)
│   ├── Slide (MeshRenderer + MeshFilter)
│   ├── Trigger (MeshRenderer + MeshFilter)
│   ├── Magazine (MeshRenderer + MeshFilter)
│   └── Armature (the armature from the FBX)
├── MuzzleFlash (empty GameObject at muzzle position, with particle system anchor)
├── EjectionPort (empty GameObject at ejection position)
├── Hook_Sight (empty GameObject at sight rail position)
├── Hook_Grip (empty GameObject at fore-grip rail position)
├── Hook_Tactical (empty GameObject at tactical rail position)
├── Hook_Barrel (empty GameObject at muzzle threading)
├── Hook_Magazine (empty GameObject at magazine well)
└── AudioSource (configured for spatial 3D)

Building the prefab

1. In the Project window, right-click the FBX asset and select Create → Prefab. Name the prefab MyRiflePrefab.
2. Open the prefab in Prefab Mode (double-click).
3. Confirm the prefab root has an Animator component. If not, add one.
4. Assign the Animator Controller to the Animator component. (The controller is created in Step 7.)
5. Inspect the empty bone GameObjects (MuzzleFlash, EjectionPort, Hook_*) and confirm each is at the correct local position.
6. Add a Capsule Collider or Box Collider to the root if the prefab needs world collision. Most weapons do not collide with the world while held; the collider is used only for the dropped-on-ground state.
7. Add an AudioSource to the root, configured with Spatial Blend 1.0, Play On Awake disabled, Loop disabled.
8. Save the prefab with Ctrl+S.

Common mistake

Placing the MuzzleFlash GameObject at the muzzle position in world space rather than as a child of the prefab. The MuzzleFlash position is read in local space; if it is not parented to the prefab, it will not follow the prefab when the weapon moves.

Step 7: Configure the Animator Controller

Create an Animator Controller for the weapon following the workflow in Animations Export Blender to Unity.

1. Project window → right-click → Create → Animator Controller. Name it MyRifleAnimator.
2. Drag the Idle, Fire, Reload, and Aim clips into the Animator window.
3. Set Idle as the Default State.
4. Create transitions: Idle → Fire, Idle → Reload, Idle → Aim, Aim → Idle, Aim → Fire, Fire → Idle, Reload → Idle.
5. Create parameters: fire (Trigger), reload (Trigger), aim (Bool).
6. Wire conditions on each transition.
7. Place animation events on the Fire and Reload clips at the cohort-validated frames documented in the animations article.
8. Assign the Animator Controller to the prefab's Animator component.

Step 8: Bundle the prefab

The prefab and its dependencies (mesh, materials, textures, animator, clips) must be packaged into a master bundle for Unturned™ to load. See Master Bundle Export for the full bundling workflow. The summary is:

1. Set the prefab's Asset Bundle name to myriflemod (lowercase, no spaces).
2. Confirm all dependencies inherit the bundle assignment.
3. Build the bundle using the cohort's bundle build script.
4. Output is a .unity3d file in the bundle output directory.

Copy the resulting .unity3d file into the mod's distribution folder alongside the .dat files.

Step 9: Author the Gun.dat file

The .dat file is the parameter set that Unturned™ applies to the gun at load time. Author it in Notepad++ with the cohort-validated field set documented below.

Identity fields

Field	Type	Example	Purpose
ID	uint16	3001	The unique gun ID. Must not collide with vanilla or other mod IDs.
GUID	uint128	f47ac10b58cc4372a5670e02b2c3d479	The 128-bit globally unique identifier.
Type	enum	Gun	The item category.
Name	string	MyRifle	The internal name.
Rarity	enum	Uncommon	The item rarity. Common, Uncommon, Rare, Epic, Legendary, Mythical.
Slot	enum	Primary	The inventory slot. Primary, Secondary.
Size_X / Size_Y	uint8	4 / 1	The inventory grid footprint.

Caliber and magazine fields

Field	Type	Example	Purpose
Caliber	uint16	0	The caliber ID. Magazines and barrels with matching Caliber_Reference are compatible.
Magazine	uint16	3002	The default magazine ID. Must match the magazine's ID.
Magazines	uint8	3	The number of additional compatible magazines that follow.
Magazine_0	uint16	3002	Compatible magazine ID 0.
Magazine_1	uint16	3003	Compatible magazine ID 1.
Magazine_2	uint16	3004	Compatible magazine ID 2.

Critical linkage

The Caliber field on the gun must match the Caliber_Reference field on the magazine. If the calibers do not match, the magazine will not be accepted by the gun at runtime. This is the single most common error in first-time gun mods. Confirm caliber linkage by inspecting both .dat files side-by-side.

Firemode fields

Field	Type	Example	Purpose
Firemodes	uint8	2	The number of firemodes the gun supports.
Firemode_0	enum	Safety	The first firemode.
Firemode_1	enum	Auto	The second firemode.
Firemode_2	enum	Semi	The third firemode.
Firerate	uint8	8	Rounds per second in Auto. Higher = faster.
Action	enum	Trigger	The cycle action: Trigger, Bolt, Pump, Break.

Common firemode values:

Firemode	Behavior
Safety	Trigger disabled.
Semi	One shot per trigger pull.
Auto	Continuous fire while trigger held.
Burst	Fixed N rounds per trigger pull. Pair with Burst field.

Recoil and sway fields

Field	Type	Cohort default	Purpose
Recoil_Min_X	float	-0.4	Minimum horizontal recoil per shot.
Recoil_Max_X	float	0.4	Maximum horizontal recoil per shot.
Recoil_Min_Y	float	1.6	Minimum vertical recoil per shot.
Recoil_Max_Y	float	2.0	Maximum vertical recoil per shot.
Recover_X	float	0.5	Horizontal recoil recovery rate.
Recover_Y	float	0.5	Vertical recoil recovery rate.
Shake_Min_X	float	-0.1	Minimum camera shake X.
Shake_Max_X	float	0.1	Maximum camera shake X.
Shake_Min_Y	float	-0.1	Minimum camera shake Y.
Shake_Max_Y	float	0.1	Maximum camera shake Y.
Spread_Hip	float	0.2	Bullet spread when firing from the hip.
Spread_Aim	float	0.05	Bullet spread when aiming down sights.
Sway	float	1.0	Multiplier on player sway while holding the weapon.

Ballistics fields

Field	Type	Cohort default	Purpose
Ballistic_Steps	uint8	10	Number of steps in the projectile ballistic trajectory.
Ballistic_Drop	float	0.05	Per-step projectile drop. Higher = more pronounced bullet drop.
Range	float	400	Maximum effective range in meters.
Muzzle	uint16	0	The default barrel attachment ID. 0 = none.
Player_Damage	float	40	Damage to a player on hit.
Zombie_Damage	float	60	Damage to a zombie on hit.
Animal_Damage	float	50	Damage to an animal on hit.
Barricade_Damage	float	15	Damage to a barricade on hit.
Structure_Damage	float	15	Damage to a structure on hit.
Vehicle_Damage	float	25	Damage to a vehicle on hit.
Resource_Damage	float	5	Damage to a resource node on hit.
Object_Damage	float	10	Damage to an object on hit.

Attachment slot fields

Field	Type	Example	Purpose
Sight	uint16	0	The default sight attachment ID. 0 = none.
Hook	uint16	0	The default tactical attachment ID. 0 = none.
Grip	uint16	0	The default grip attachment ID. 0 = none.
Barrel	uint16	0	The default barrel attachment ID. 0 = none.
Tactical	uint16	0	The default tactical attachment ID. 0 = none.

Audio fields

Field	Type	Example	Purpose
Shoot	enum	Heavy_Rifle	The audio category for fire. Match to existing categories or define a custom one.

Example Gun.dat

A minimal cohort-validated Gun.dat for a semi-auto rifle:

ID 3001
GUID f47ac10b58cc4372a5670e02b2c3d479
Type Gun
Name MyRifle
Rarity Uncommon
Slot Primary
Size_X 4
Size_Y 1

Caliber 0
Magazine 3002
Magazines 0

Firemodes 2
Firemode_0 Safety
Firemode_1 Semi
Firerate 4
Action Trigger

Recoil_Min_X -0.4
Recoil_Max_X 0.4
Recoil_Min_Y 1.6
Recoil_Max_Y 2.0
Recover_X 0.5
Recover_Y 0.5

Shake_Min_X -0.1
Shake_Max_X 0.1
Shake_Min_Y -0.1
Shake_Max_Y 0.1

Spread_Hip 0.2
Spread_Aim 0.05
Sway 1.0

Ballistic_Steps 10
Ballistic_Drop 0.05
Range 400
Player_Damage 40
Zombie_Damage 60
Animal_Damage 50
Barricade_Damage 15
Structure_Damage 15
Vehicle_Damage 25
Resource_Damage 5
Object_Damage 10

Sight 0
Hook 0
Grip 0
Barrel 0
Tactical 0

Shoot Heavy_Rifle

Step 10: Author the Magazine.dat

The magazine .dat is a separate file that pairs with the gun. The magazine .dat defines the round count, the round damage, the caliber reference (which must match the gun's caliber), and the projectile type.

Magazine fields

Field	Type	Example	Purpose
ID	uint16	3002	The unique magazine ID.
GUID	uint128	5b8c3a2e7d1f4b6a9e2c5d8a1f3b6c9e	The 128-bit GUID.
Type	enum	Magazine	The item category.
Name	string	MyRifleMagazine	The internal name.
Caliber_Reference	uint16	0	Must match the gun's Caliber field.
Amount	uint8	30	Round capacity.
Pellets	uint8	1	Pellets per shot (>1 for shotguns).
Speed	float	850	Projectile muzzle velocity in m/s.
Player_Damage	float	40	Round damage to a player (multiplied by gun's Player_Damage).
Range	float	400	Effective range of the round (modifies gun's Range).
Explosion	float	0	Explosion radius on impact (>0 for explosive rounds).

Example Magazine.dat

ID 3002
GUID 5b8c3a2e7d1f4b6a9e2c5d8a1f3b6c9e
Type Magazine
Name MyRifleMagazine
Rarity Common
Slot None
Size_X 1
Size_Y 1

Caliber_Reference 0
Amount 30
Pellets 1
Speed 850
Player_Damage 1.0
Range 400

Caliber matching

The Caliber_Reference field on the magazine MUST match the Caliber field on the gun. If the gun has Caliber 0 and the magazine has Caliber_Reference 1, the magazine will not be accepted. Confirm the values match before testing.

Step 11: Add the English.dat localization entry

Each item in Unturned™ has a localization file that provides the display name and description shown in-game. The English localization file is English.dat and lives in the same folder as the gun's main .dat.

English.dat fields

Field	Purpose
Name	The display name shown in inventory and tooltips.
Description	The flavor text shown in tooltips.

Example English.dat for the gun

Name MyRifle
Description A custom rifle authored as a 57 Studios mod tutorial example.

Example English.dat for the magazine

Name MyRifle Magazine
Description Holds 30 rounds for the MyRifle.

Each item (gun, magazine, attachments) has its own English.dat file in its own folder.

Step 12: Test in single-player

The cohort-validated single-player testing workflow is:

1. Copy the master bundle (.unity3d) and all .dat files to the local Unturned™ install's mod folder. The folder structure should be Workshop/Content/304930/<modID>/Bundles/.
2. Launch Unturned™ in single-player.
3. Open the in-game console with ~.
4. Spawn the gun: @give <gunID>.
5. Spawn the magazine: @give <magazineID>.
6. Equip the gun and confirm it appears correctly in-game.
7. Test fire:
   • Press the fire button. Confirm the muzzle flash spawns at the MuzzleFlash GameObject position.
   • Confirm the shell ejects from the EjectionPort GameObject position.
   • Confirm the audio plays.
   • Confirm the round count decrements.
   • Confirm recoil applies to the camera.
8. Test reload:
   • Press the reload button. Confirm the reload animation plays.
   • Confirm the magazine model detaches and re-attaches at the cohort-validated frames.
   • Confirm the round count refills to the magazine's Amount.
9. Test aim:
   • Press the aim button. Confirm the camera transitions to the sight position.
   • Confirm the spread reduces to Spread_Aim.
10. Test firemode cycling (if more than one firemode):

• Press the firemode toggle. Confirm the firemode advances through the configured list.

Step 13: Diagnose common gun mod bugs

The table below matches symptoms to causes for the most common gun mod bugs.

Symptom	Most likely cause	Resolution
Gun does not appear in inventory after @give	Mod folder path or ID mismatch	Confirm bundle in Bundles/, confirm .dat ID matches command
Gun appears but is invisible when equipped	Prefab reference broken	Open prefab, confirm all child renderers active
Gun appears but has pink material	Shader missing or material not assigned	Re-assign material in Unity, rebuild bundle
Trigger does not fire	Firemode_0 is Safety	Confirm Firemode_1+ has Semi or Auto
Muzzle flash at wrong position	MuzzleFlash GameObject misplaced in prefab	Reposition MuzzleFlash to barrel exit
Magazine model does not detach during reload	Animation event missing or method name wrong	Confirm OnMagazineDrop event at correct frame
Magazine accepted at runtime is the wrong one	Caliber mismatch	Confirm gun's Caliber matches magazine's Caliber_Reference
Recoil too violent	Recoil_Max_Y too high	Reduce Recoil_Max_Y to ~2.0
Recoil too weak	Recoil_Max_Y too low	Increase Recoil_Max_Y
Spread too wide when aiming	Spread_Aim too high	Reduce Spread_Aim to ~0.05
No audio on fire	Shoot category not recognized	Use an existing category (Heavy_Rifle, Light_Rifle, Pistol, Shotgun)
Animation does not play on fire	Animator Controller not wired	Open prefab, confirm Animator Controller assigned
Animation plays but bones are wrong	Rig type set to Humanoid instead of Generic	Reconfigure rig as Generic
Reload finishes too fast	Reload clip too short	Extend reload clip in Blender, re-export
Reload finishes too slow	Reload clip too long	Trim reload clip, or accept long reload as a balance choice
Sights misaligned in ADS	Sight_Iron bone position off	Reposition Sight_Iron bone in Blender, re-export
Attachment does not snap correctly	Hook_* GameObject at wrong position	Reposition Hook_* in prefab
Round count does not decrement	Magazine .dat Amount field wrong	Set Amount in magazine .dat
Gun explodes on impact	Magazine has Explosion >0 by mistake	Set Explosion to 0 in magazine .dat
Damage too high or low	Player_Damage off	Tune Player_Damage in gun .dat (typical range 30–80)
Bullet drop too aggressive	Ballistic_Drop too high	Reduce Ballistic_Drop to ~0.05
Bullet has no drop	Ballistic_Drop too low	Increase Ballistic_Drop

Step 14: Test on a dedicated server

After single-player testing passes, the next step is dedicated server testing. Dedicated servers exercise additional code paths (network replication, server-authoritative state) that single-player does not.

1. Install a local Unturned™ dedicated server. See the Smartly Dressed Games server documentation.
2. Copy the mod's Bundles/ folder to the server's Workshop/Content/304930/<modID>/ directory.
3. Configure the server to load the mod by adding the mod ID to the server's workshop manifest.
4. Start the server.
5. Join the server as a client.
6. Repeat the single-player tests on the dedicated server.
7. Test multiplayer-specific scenarios:
   • Multiple players firing the gun simultaneously.
   • One player observing another player fire the gun.
   • Server restart with the gun in a player's inventory.

Pro tip

Test on a dedicated server before submitting to the Steam Workshop. Single-player and dedicated server have subtle behavioral differences (e.g., network jitter on animations) that surface only on a server. The cohort recommendation is to run at least two hours of dedicated server testing before publishing.

Advanced considerations

Authoring custom firemodes

The standard firemodes (Safety, Semi, Auto, Burst) cover most weapons. For specialty weapons (lever-action rifles, double-action revolvers, charging-handle SMGs), the cohort recommendation is to combine the standard firemodes with custom animation timing rather than authoring a new firemode. Custom firemodes require modification of the UseableGun script's source code, which is outside the scope of a standard mod.

Scope sights and zoom

Scope sights use the Sight attachment slot. The scope attachment is a separate .dat file with its own GUID, prefab, and zoom configuration. The cohort recommendation for new modders is to use vanilla scope attachments initially and to author custom scopes only once the base gun is shipping reliably.

Suppressors and barrel attachments

Barrel attachments (suppressors, compensators, flash hiders) use the Barrel attachment slot. The barrel attachment is a separate .dat with its own GUID and prefab. The barrel attachment can modify the gun's Range, Shoot audio category, and muzzle flash visibility.

Tactical attachments

Tactical attachments (lasers, flashlights, foregrip lasers) use the Tactical attachment slot. The tactical attachment's .dat defines whether the attachment is a laser (visible beam) or a light (illuminated area). The cohort's recommendation for new modders is to defer tactical attachment authoring to a later mod iteration.

Balance considerations

A custom gun's balance is the most subjective part of the mod. The cohort's recommended starting point is to copy the values from a similar vanilla weapon and to tune from there. The vanilla weapon .dat files are available in the Unturned™ install at Bundles/Items/Guns/<weaponName>/.

Weapon class	Suggested Player_Damage	Suggested Range	Suggested Firerate
Pistol	30–40	100–150	4
SMG	25–35	150–200	12
Assault rifle	35–45	250–350	8
Battle rifle	50–65	350–500	6
Sniper rifle	80–120	600–1000	1
Shotgun (per pellet)	15–25	30–60	2
LMG	40–55	300–400	10

Avoiding ID collisions

Mod IDs above 2000 are reserved for community mods. The cohort recommendation for new modders is to choose IDs in the 50000+ range to avoid collisions with established community mods. The Smartly Dressed Games modding documentation maintains a list of reserved ID ranges.

Gun mod authoring benchmark

The 57 Studios cohort measured end-to-end gun mod authoring times across cohort members. The benchmark is the time from a finished modeled weapon to a working in-game gun.

Modder experience level	Median authoring time	Notes
First gun mod	16 hours	Most time is in learning the .dat fields and the animation pipeline.
Second gun mod	6 hours	Pipeline knowledge transfers from the first mod.
Cohort-experienced (5+ guns)	2.5 hours	Cohort templates in use, .dat field defaults applied.
Cohort-master (15+ guns)	1.5 hours	Authoring is largely automated via cohort scripts.

The cohort's instrumentation identified that the largest single time sink for first-time gun modders is the .dat field configuration. The second largest is animation event placement. The third largest is texture authoring. The cohort recommendation is to start with a cohort template .dat and tune fields incrementally.

Frequently asked questions

My gun appears in single-player but fires nothing. What is wrong?

The most likely cause is a caliber mismatch between the gun and the magazine. Confirm the gun's Caliber field matches the magazine's Caliber_Reference field. The second possible cause is that Firemode_0 is set to Safety and the firemode has not been toggled; press the firemode key to advance to Semi or Auto.

Why does the muzzle flash spawn behind the gun?

The MuzzleFlash GameObject is at the wrong position in the prefab. Open the prefab in Unity, select the MuzzleFlash GameObject, and confirm its local position is at the muzzle exit (the end of the barrel). The cohort recommendation is to position MuzzleFlash so that its forward axis points in the firing direction.

How do I make a shotgun?

A shotgun is a gun with a magazine that has Pellets set to a value greater than 1. The cohort default for a 12-gauge buckshot magazine is Pellets 9. The gun's Spread_Hip should be increased to approximately 0.5 to spread the pellets visibly. The Range should be limited to approximately 50 meters.

How do I make an explosive grenade launcher?

A grenade launcher is a gun with a magazine that has Explosion set to a positive value. The cohort default for a 40mm grenade is Explosion 6.0 and Range 200. The gun's Ballistic_Drop should be increased to approximately 0.15 to produce a visible arcing trajectory.

Can I have a gun with multiple compatible magazines?

Yes. Set Magazines to the count of additional magazines and list each with Magazine_0, Magazine_1, etc. Each compatible magazine must have a matching Caliber_Reference. The cohort recommendation is to author one base magazine and additional drum or extended magazines as separate .dat files.

How do I add a unique sound for my gun?

Custom audio is a separate workflow. The audio file must be packaged into the master bundle and the gun's Shoot field must reference the custom audio category. See Audio Packaging for Unturned for the audio packaging workflow.

My gun has tracer rounds. How do I configure them?

Tracer rounds are a property of the magazine, not the gun. Set the magazine's projectile type to Tracer in the magazine .dat. The tracer effect is applied automatically at runtime.

How do I make a gun that fires in 3-round bursts?

Set Firemodes 2, Firemode_0 Safety, Firemode_1 Burst, and add a Burst field with value 3. The gun will fire three rounds per trigger pull.

Why does my reload animation play at the wrong speed?

Animation playback speed is controlled by the Animator Controller's clip Speed property. Open the Animator window, select the Reload state, and inspect the Speed field. The default is 1.0. Values greater than 1.0 play the clip faster; values less than 1.0 play it slower. The cohort recommendation is to author the animation at the desired in-game speed in Blender and to leave the Animator Speed at 1.0.

Can I make a gun that does not need to be reloaded?

A gun with an effectively infinite magazine can be authored by setting the magazine's Amount to a very high value (e.g., 9999). The cohort recommendation for special weapons (admin-only spawn weapons, debug weapons) is to use a high Amount value rather than modifying the source code to disable reload entirely.

What is the difference between Action types Trigger, Bolt, Pump, and Break?

Trigger is the default for semi-auto and full-auto weapons; the next round is chambered automatically after each shot. Bolt is for bolt-action rifles; the player must manually cycle the bolt between shots. Pump is for pump-action shotguns; the player must pump after each shot. Break is for break-action shotguns; the player must reload after each shot or burst.

How do I configure attachment compatibility?

Each attachment has a Caliber_Reference field (for barrel attachments) or an attachment slot type. The gun accepts attachments that match the slot type. To restrict compatibility (e.g., a gun that accepts only a specific sight), the cohort recommendation is to use a custom slot type via the Unturned modding API's extension points.

My gun looks correct in Unity but appears stretched in-game. Why?

The mesh has a non-unit scale that was not applied in Blender. Return to Blender, select the mesh, and apply scale with Ctrl+A → Scale. Re-export the FBX and re-import to Unity. Rebuild the master bundle.

How do I publish my gun mod to the Steam Workshop?

See Steam Workshop Submission for the publishing workflow. The summary is to use the Unturned™ workshop tools to package the mod, fill in the workshop description, upload, and configure visibility.

What is the cohort's recommended workflow for iterating on gun balance after publication?

The cohort recommendation is to maintain a balance test server with the latest unreleased iteration of the gun and to invite community feedback before publishing balance changes. Balance iteration without community testing tends to produce balance that satisfies the modder but does not satisfy the broader community.

Best practices

• Start with the cohort's reference gun template rather than authoring from scratch.
• Confirm the Caliber / Caliber_Reference linkage between gun and magazine before testing.
• Apply mesh scale in Blender before exporting. Non-unit scale produces stretched in-game appearance.
• Use the cohort's bone naming convention. The cohort's authoring scripts depend on the convention.
• Place animation events at the frames that visually correspond to the gameplay action.
• Author textures at 2048×2048 and cap there. Larger textures inflate bundle size.
• Tune recoil incrementally. Start at the cohort defaults and adjust from there.
• Test in single-player first, then dedicated server.
• Use balance reference values from comparable vanilla weapons.
• Choose mod IDs in the 50000+ range to avoid collisions with established community mods.
• Maintain a balance test server before publishing balance changes.
• Document the gun's intended role in the workshop description (e.g., "mid-range assault rifle", "close-quarters submachine gun") so players have correct expectations.

Cross-references

• How to Install Blender — the prerequisite Blender install.
• How to Install Unity Editor — the prerequisite Unity install.
• How to Install Notepad++ — the recommended .dat editor.
• How to Export an FBX — the FBX export workflow.
• Animations Export Blender to Unity — the animation pipeline this tutorial uses.
• Vehicle Mod Basics — the previous article; uses similar prefab and .dat conventions.
• Master Bundle Export — the bundling step.
• Project Folder Structure and GUIDs — the folder layout and GUID workflow.
• Audio Packaging for Unturned — the audio workflow for custom fire sounds.
• Steam Workshop Submission — the next article; the publishing workflow.
• Smartly Dressed Games Modding Documentation — the official modding documentation.
• Unity AssetBundles Introduction — the official Unity asset bundle documentation.

Document history

Version	Date	Author	Notes
1.0	2024-04-22	57 Studios	Initial publication. End-to-end gun mod walkthrough.
1.1	2024-07-30	57 Studios	Added .dat field tables and example files.
1.2	2024-11-12	57 Studios	Added attachment slot guidance and balance reference table.
1.3	2025-02-08	57 Studios	Added dedicated server testing section.
2.0	2025-05-18	57 Studios	Major revision. Added diagnostic flowcharts, balance benchmark, advanced considerations.

Closing note

A custom gun mod is the most-requested mod category and one of the most rewarding to ship. The configuration surface area is broad — model, texture, rig, animate, bundle, .dat, magazine, attachments, localization, test — but every step is documented and the failure modes are catalogued. A modder who follows this tutorial linearly can ship a working gun mod within their authoring-time budget; a modder who has internalised the cohort's templates and conventions can ship in less than half the time of a first-time authoring pass.

The cohort recommendation is to ship a minimum-viable gun first (one firemode, one magazine, no attachments, default audio) and to iterate on polish (recoil tuning, custom audio, attachment slots, balance) after the base mod is shipping cleanly. The fastest path to a shipped gun mod is to satisfy the minimum requirements first and to add polish in subsequent iterations.

Next steps

Continue to Steam Workshop Submission for the publishing workflow that takes the working gun mod from local testing to the Steam Workshop. Return to the section overview at Items for the full list of items-section articles.