Weapon Customization (Workbench & Field)

Authoritative project 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. Core action times are confirmed below; remaining jam chances and stock stat curves are [TBD] — do not invent those 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 does not require a tool item in the current design, whether performed in the field or at a workbench — [CONFIRMED].

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 are not consumed (returned / never deducted).

• Install or remove an attachment: 3 seconds.
• Repair or salvage a firearm: 10 seconds.

Attachment slots — [CONFIRMED]

Phase 1 slot types:

Underbarrel launchers / bipods are out of v1 slot list.

Compatibility — [CONFIRMED] rule, catalog [TBD]

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

Every weapon and attachment Data Asset owns an explicit compatibility whitelist for allowed weapon families and/or exact item IDs — [CONFIRMED]. The server validates both sides of the pairing before installation. The L1810 pairings are confirmed content entries. The remaining roster and runtime whitelist mappings remain [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 or in the field takes 3 seconds and does not require or consume a tool item. Repair consumes either a kit or matching family parts as described 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. That instance state persists with the item — [CONFIRMED 2026-09-14].
• 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].
• Mixed-ammo fire order: rounds are chambered and fired in the same order in which the player loaded them into the magazine. The first round loaded is the first round selected for chambering; the system preserves the per-round sequence and never groups or sorts by ammo type — [CONFIRMED].

Field inspection inputs — [CONFIRMED 2026-09-08]

• Check chamber: IA_CheckChamber, Shift + R, action duration 3 seconds per firearm.
• Check magazine: IA_CheckMagazine, Alt + R, action duration 5 seconds per firearm.
• Press once to start; holding the keys is not required.
• When holding two firearms, inspect the right-hand firearm first, then the left-hand firearm — owner confirmed 2026-09-09. Total time is 6 seconds for chambers or 10 seconds for magazines.
• Owner confirmed 2026-09-09: An interrupted sequence does not retain newly collected inspection results, including the completed first firearm. Ammo/chamber truth comes from actual item data; do not impose empty defaults or use debug counts as production truth. Treatment of older observations predating the interrupted sequence remains unspecified.
• Only the completed corresponding check reveals that observed chamber/magazine state, following FEAT-HUD-UI. The existing field-action interruption contract remains applicable. [CONFIRMED 2026-09-14] Observed knowledge is client-only and is not saved. Every fired round clears chamber and magazine observation to UNKNOWN.

G3 source, 2026-09-10: Item.Weapon.L1810 used instance chamber/magazine counts (capacity 18, G3 new stacks full mag / empty chamber) so field checks did not require a magazine item. Firearm hand cards show Chamber/Mag knowledge even when the gun also tracks durability. HUD knowledge is applied only after the whole timed sequence finishes. Check Magazine uses the same Enhanced Input chord path as Check Chamber (IMC_Default R + IA_Alt). Owner reported Alt chord inspection on 2026-09-10. Debug UI_G3ObserveWeapon remains.

[CONFIRMED 2026-09-10 G3.2] New L1810 stacks spawn with no magazine and an empty chamber. Magazine-as-item rules in this document now apply: load/unload ammo from inventory anywhere (instant); install/remove magazine 3 s with no tool; removing a magazine can leave a chambered round. MCP created and saved DA_Item_L1810_Magazine / DA_Item_Ammo_9x19 on 2026-09-11. [OWNER-REPORTED PASS 2026-09-11] Owner reported load, 3 s install, move-cancel, unload and remove. See G3.2.

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, condition bands [TBD]

• A gun repair kit restores the target firearm to 100% durability in one completed 10-second repair action.
• A firearm can be salvaged into 2–4 parts for that weapon family (e.g. break down an AR-family gun → AR parts). Better-condition donor weapons yield more parts. The exact durability bands that award 2, 3, or 4 parts remain [TBD].
• Salvage consumes the donor weapon. Any mounted attachments are automatically removed and returned rather than destroyed — [CONFIRMED]. The destination behavior when the receiving inventory has no capacity remains [TBD].
• Each repair action uses either one gun repair kit or matching family parts, never both. Kit and parts cannot be mixed in the same action — [CONFIRMED]. The amount of durability restored and number of parts consumed by a parts-only repair remain [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 repair-kit item ID and recipe; attachment install/remove currently uses no tool item.
• Salvage durability bands for the confirmed 2–4-part yield, plus attachment-return behavior when receiving inventory is full.
• Field repair vs workbench-only repair.
• Parts-only repair cost and restored-durability amount.
• Per-weapon rail socket lists and which stocks have a length slider.
• Interaction range of the workbench; core channel durations are confirmed at 3 seconds for attach/remove and 10 seconds for repair/salvage.
• Laser input binding; visible vs IR variants.
• Whether world (non-player) workbenches exist.
• Remaining attachment catalog and family compatibility matrix beyond the confirmed L1810 pairings.
• TBD-8EF6FAED — LRD-01 brightness control-button text was not supplied and remains TBD, alongside the existing unresolved defaults tracked by this decision.