Weapon Customization (Workbench & Field)

Canonical GDD content

Firearms can be customized with attachments, loaded like a Tarkov-style magazine/chamber loop, repaired, and (later) adjusted. All of this is server-authoritative. Numeric tuning (times, jam chances, stock stat curves) is [TBD] — do not invent values in implementation.

Weapon dirt / fouling is cancelled (no dirt meter, no cleaning kit, no jam/spread-from-dirt). Melee blood stains are a separate visual system: 10-Blood-Visual.md.

Related: 03-Combat-System.md, 06-Inventory-and-Items.md, 07-Crafting-and-Progression.md, 05-Building-System.md, 10-Blood-Visual.md.

Phasing — [CONFIRMED]

Station — [CONFIRMED]

• Uses the same workbench as crafting. The station gains a firearm work mode (inspect / attach / adjust / repair) rather than a separate gunsmith deployable.
• Anyone nearby may use a placed workbench (no owner/clan lock for this interaction). Raiders can use a bench they find.
• Workbench is still a player-placed deployable (see 05-Building-System.md). World-placed benches are [TBD] and are not required for this feature.

Where actions happen — [CONFIRMED]

Install/remove always requires a tool item in inventory (field and bench). Exact tool item is [TBD] (e.g. screwdriver / multi-tool).

Interruption — [CONFIRMED]

Timed bench (or field) actions are channels. If the player moves, takes damage, or dies, the channel cancels. Consumed time is lost; materials/tools are not consumed (returned / never deducted). Exact channel durations are [TBD].

Attachment slots — [CONFIRMED]

Phase 1 slot types:

Underbarrel launchers / bipods are out of v1 slot list.

Compatibility — [CONFIRMED] rule, catalog [RECOMMENDATION]

Compatibility is by weapon family, not “any optic on any gun” and not a full rail-standard simulation.

[RECOMMENDATION] family list (replace with a real catalog when content exists):

• Pistol
• SMG
• Assault rifle (AR)
• DMR
• Shotgun
• Sniper

Per-attachment and per-weapon allowed family / allowed items live in data. Exact pairing tables are [TBD].

Persistence & presentation — [CONFIRMED]

• Attachments are instance state on the weapon. They stay mounted when the weapon is dropped, looted, or left on a corpse.
• Equipped weapons show real attachment meshes. Other players see the same configuration (replicated).
• Workbench UI is a 3D inspect of the weapon (not a 2D slot grid as the primary UX).

Install/remove at the bench (and in the field) takes time and requires the tool. It does not consume a separate crafting resource beyond that tool being present. Repair consumes kits/parts (below).

Magazines & ammunition (Tarkov-like) — [CONFIRMED]

• A magazine is an item that holds ammo. The player loads ammo into the mag; the mag is then installed on a compatible firearm.
• Loading and unloading ammo into/from a mag is done from inventory anywhere (no workbench required).
• Magazines do not stack. Each mag is its own instance with its own loaded rounds.
• Magazines may be partially filled (e.g. 15/30) and keep that count when stored, dropped, or left on a weapon.
• The player may unload a mag back into ammo piles/stacks.
• Mixed ammo types in one mag are allowed if each type is compatible with that mag (typically same caliber, different projectile). Incompatible caliber/family cannot be inserted. Which types a mag accepts is data [TBD].
• Fire order when mixed (which round is chambered next) is [TBD]. Do not assume a formula until decided.

Chamber and bolt — [CONFIRMED] design

The firearm has a chambered round separate from the magazine, plus Tarkov-like handling:

• Check chamber
• Charge / rack
• Release bolt / bolt catch as applicable to the weapon

Removing the mag can leave one round in the chamber. Exact per-weapon bolt types (closed bolt, break action, etc.) are [TBD] per firearm.

[RISK] This is high animation, audio, and input-surface cost. Keep it data-driven per weapon family so content does not require unique code per gun.

Laser / light — [CONFIRMED]

• Occupies the laser slot.
• Toggle on/off (input [TBD]).
• Beam / IR or visible point is shown in the world; other players can see it.
• When on, it makes zombies more likely to detect / aggro the user. Exact detection bonuses are [TBD].

Scope rail position — [CONFIRMED] (Phase 2+)

• Each firearm defines its own rail / mount points (count and spacing per weapon, not a global 2–3 preset).
• Adjustment is done only at the workbench.
• Effect is visual / ADS presentation only (eye relief, how the optic sits in ADS, perceived FOV/framing). It does not change combat numbers (damage, spread, recoil).

Exact rail authoring (sockets vs spline) is an implementation detail; gameplay requirement is per-weapon mount positions.

Stock length — [CONFIRMED] (Phase 2+)

• Some stocks expose a continuous length slider (collapsed ↔ extended). Which stocks support it is per-item data.
• Adjustment is workbench-only.

• The slider does affect combat handling:

• Recoil / stability

• ADS speed / sway

• Mobility / ergonomics (move-while-aimed feel)

• Curves and magnitudes are [TBD]. Collapsed size / holster profile is not confirmed (do not implement concealment-size rules unless added later).

Durability — [CONFIRMED]

There is no dirt meter. Use still reduces durability. Blood on a firearm happens only if that gun is used to deal melee damage to a living target; it is visual-only (BloodAmount). See 10-Blood-Visual.md.

Durability is [CONFIRMED] for firearms and tools (including melee tools/weapons that use durability).

Repair & salvage — [CONFIRMED] rule, yields [TBD]

• Gun repair kit restores durability. Amount per use [TBD].
• A firearm can be salvaged into parts for that weapon family (e.g. break down an AR-family gun → AR parts). Salvage destroys (or consumes) the donor weapon. Part types, quantities, and whether attachments on the donor drop separately are [TBD] — [RECOMMENDATION]: drop/uninstall attachments before or as part of salvage so they are not silently deleted.
• Repair consumes kit and/or matching family parts. Mixing kit vs parts in one repair action is [TBD].

Phase 2 Firearms skill may improve repair quality/time (see 07-Crafting-and-Progression.md); it does not gate Phase 1 install/remove.

Open questions still [TBD]

Do not implement as if decided:

• Exact tool and repair-kit item IDs and recipes.
• Salvage yield tables and whether attachments survive salvage.
• Field repair vs workbench-only repair.
• Mixed-ammo fire order and chambering rules when types differ.
• Per-weapon rail socket lists and which stocks have a length slider.
• Channel durations; interaction range of the workbench.
• Laser input binding; visible vs IR variants.
• Whether world (non-player) workbenches exist.
• Full attachment catalog and family compatibility matrix.