Guide

Game weapon swap and holster systems explained

Harbor Arsenal's ranked duel pit is a three-lane arena: rifle at range, shotgun in the mid corridor, pistol for the final push. The first build treated weapon change as a cinematic — 0.9 s holster animation, 0.7 s draw, no input cancel, and a full-body lock that blocked sprint and dodge. Players who read the engagement correctly still died mid-swap: telemetry logged 47% of deaths during holster or draw, 62% of players avoiding secondary weapons entirely, and average time-to-kill in duels stretching 38% longer than design targets because nobody switched under pressure. After a refactor built around a swap FSM with partial cancel windows, last-weapon quick-swap, class-based draw speeds, and wheel slow-mo that pauses combat but not the player's aim cursor, swap deaths fell to 11%, secondary weapon usage rose to 74%, and duel length normalized — without raising base damage on any gun.

Weapon swap and holster systems govern how players move between equipped firearms, melee sidearms, and gadgets. They sit between raw ranged combat (hitscan, falloff, engagement bands) and ammo and reload (magazine pacing, tactical reloads). Swap is often the faster answer to an empty mag — but only if draw time beats reload time and the player survives the transition. This guide covers swap input models, holster/draw FSM design, timing and cancel rules, ammo state carryover, animation and camera coupling, multiplayer authority, the Harbor Arsenal refactor, a technique decision table, pitfalls, and a checklist.

What weapon swap is (and is not)

Weapon swap is not inventory management. Picking up a new gun from the ground, looting a crate, or editing a pre-match loadout are separate flows. Swap handles the already-owned kit: moving from primary to secondary, cycling gadgets, or pulling a sidearm when the rifle runs dry. Confusing swap with pickup creates double animations and input fights.

Swap archetypes

Number-key direct select — press 1/2/3 to equip slot. Fastest for PC arena shooters; requires fixed slot memory.
Scroll wheel cycle — next/previous weapon in a ring. Common on PC; risk of overshooting under stress unless UI highlights target.
Radial weapon wheel — hold button, aim selection, release to equip. Paired with radial menu patterns; needs slow-mo or blur so players can aim the wedge.
Last-weapon quick swap — single button toggles primary and secondary (Q on many PC shooters). Essential for reload-escape routes.
Contextual swap — auto-pull sidearm when primary empties and player fires again. Reduces button load; must be opt-out for skilled players.
Instant switch (no holster) — zero-time swap, often with a brief lower-accuracy debuff. Arcade and hero shooters; trades realism for flow.

Holster and draw FSM

Treat every weapon change as a finite-state machine, not a single animation clip. States define what input is legal and when damage can be dealt.

Core states

Ready (weapon active) — full fire, ADS, reload, and grenade access per weapon rules.
Holstering (stow current) — weapon lowers; firing disabled; partial movement may remain. Duration scales by weapon class (LMG slower than pistol).
Drawing (equip target) — new weapon rises; firing disabled until a ready frame. Shorter than holster+draw combined if you skip full stow on quick-swap.
Swap ready — crosshair valid, spread tables active, can cancel into ADS or melee per design.
Interrupted — hit-stun, stagger, or forced melee cancels swap; must define whether partial progress resets or resumes.

Quick-swap vs full holster

Full holster + draw plays both animations sequentially — total downtime is the sum. Harbor Arsenal's 1.6 s vulnerability window came from this. Quick-swap skips visible holster on the outgoing weapon: the new gun overlays while the old model drops or blends out. Total time becomes max(holster, draw) or a single blended clip, often 40–60% faster. Reserve full holster for deliberate weapon discard or when switching to a physically large secondary (rocket launcher on back).

Cancel windows

Skilled players expect animation cancel routes: sprint, slide, dodge, or melee during holster frames to abort a bad swap. Without cancels, mis-presses are punished for the full duration. Define which states are cancelable — usually holster yes, draw ready-frame no — and whether cancel returns to the previous weapon or leaves the player empty-handed.

Timing, ammo carryover, and reload interaction

Swap competes directly with reload. Players choose whichever is shorter and safer for the current threat.

Draw speed budgeting

Rule of thumb for tactical shooters: draw time + first-shot ready should be less than tactical reload time for the primary, but greater than empty reload if you want reload mastery to matter. Sidearms draw fast (0.25–0.40 s ready); primaries slower (0.45–0.65 s). If draw beats every reload, players never reload under fire — only swap.

Ammo state on swap

Persistent mag state — each slot remembers its own magazine and reserve count. Switching away mid-reload should either cancel reload progress or complete in background (pick one; mixing confuses UI).
Shared ammo pool — all weapons draw from one reserve; swap does not restore ammo. Simpler UI; reduces sidearm-as-free-clip exploits.
Drop partial mag — tactical reload discards remaining rounds; swapping without reload preserves partial mag on the stowed weapon. Document clearly in tutorials.

ADS and swap overlap

If the player was in ADS when swapping, decide whether the new weapon enters ADS automatically, returns to hip, or forces exit ADS during draw. Auto-ADS on swap feels smooth for sniper-to-pistol transitions; forced hip prevents optic mismatch bugs.

Presentation, fairness, and multiplayer

Animation and camera

Third-person cover shooters exaggerate holster motion so allies read your state; first-person games often shorten or hide stow clips. Camera should not whip FOV during swap unless the new weapon has a different optic — sudden zoom changes disorient. Audio cues (holster click, slide rack on draw) telegraph vulnerability to enemies in PvP.

PvP fairness

Enemy hears draw audio at realistic radius — not silent swaps.
Hitbox exposure: some games widen hurtbox during holster; others keep competitive hitbox unchanged. Pick explicitly.
Wheel slow-mo in multiplayer must affect all players equally or only pause local simulation — asymmetric freeze is exploitable.

Authority

Server should authoritate active weapon ID and ready-frame timestamp. Client prediction can play draw animation early; reconcile if the player was stunned server-side. Desync where the client fires pistol while server still sees rifle is a classic cheat and feel bug.

Harbor Arsenal refactor (worked example)

Problem: sequential holster+draw, no quick-swap, wheel without slow-mo, reload and swap sharing no timing budget. Players either hard-stuck to one gun or died swapping.

Changes shipped

Quick-swap on Q toggles primary/secondary in 0.42 s ready-frame (was 1.6 s).
Holster cancel into slide after frame 8; draw cancel into melee after frame 4.
Weapon wheel: 0.35 s local slow-mo, combat timers paused, cursor unaffected.
Class draw tiers: pistol 0.28 s, SMG 0.38 s, rifle 0.52 s, shotgun 0.48 s.
Persistent per-slot mag; mid-reload swap cancels reload and saves partial mag.
Telemetry dashboards: deaths by combat state, swap attempts per duel, slot usage.

Result: swap deaths 47% → 11%, secondary usage 26% → 74%, median duel duration back within 8% of target. Esports observers noted more intentional shotgun pushes after rifle tags — the loop designers wanted.

Technique decision table

Technique	Best for	Weak when	Harbor-style signal
Instant switch	Arena hero shooters, fast TTK	Tactical realism fantasy	Swap deaths near zero; loadout identity weak
Quick-swap (no full holster)	Competitive tac-shooters, duel modes	Heavy sim where weight matters	Swap deaths high until quick-swap added
Full holster + draw	Milsim, survival, weighty RPG	High-pressure PvP under 10 s TTK	Players never use secondary
Radial wheel + slow-mo	Controller, many gadgets	PC sweat meta needing sub-200 ms swap	Wheel opens but picks wrong wedge
Auto sidearm on empty	Casual campaigns, onboarding	Ranked skill expression	Skilled players disable in settings

Common pitfalls

Holster + draw stacked sequentially — Harbor's 47% swap-death root cause; use quick-swap or parallel blend.
Draw slower than every reload — sidearm never wins; swap button becomes decorative.
No last-weapon toggle — forces wheel or scroll under stress.
Wheel without time dilation — players pick wrong weapon while taking damage.
Mid-reload state ambiguous — UI shows reloading on stowed gun; players think swap failed.
Silent swaps in PvP — enemies cannot read transitions; feels unfair in duels.
Identical draw for all classes — pistol and LMG feel same; breaks weapon identity.
Swap locked during sprint — run-and-gun heroes cannot adapt; forces stop-shoot-only loop.

Engineer checklist

Pick input model: number keys, scroll, wheel, quick-swap, or hybrid per platform.
Implement holster/draw FSM with explicit ready-frame and interrupt rules.
Budget draw times against tactical and empty reload durations per weapon.
Define per-slot ammo persistence and mid-reload swap behavior.
Author quick-swap blend clips; reserve full holster for heavy weapons.
Wire cancel routes into sprint, slide, dodge, and melee systems.
Couple ADS exit/enter on swap; test optic FOV transitions.
Add draw/holster audio with PvP-appropriate attenuation.
Server-authoritate weapon ID and ready timestamp; predict on client.
Log deaths by combat state and per-slot usage for tuning.
Playtest PC keys vs controller wheel; verify slow-mo fairness.
Document swap-vs-reload decision in onboarding range.

Key takeaways

Swap is a combat timer — holster plus draw is downtime players must survive or cancel.
Quick-swap saves duels — Harbor cut swap deaths 47% → 11% without touching gun damage.
Draw speed must beat tactical reload — or players will never switch under pressure.
Ammo state needs clear rules — per-slot mags and mid-reload cancel must be explicit.
Pair with reload, cancel, and ADS systems — swap is the third leg of shooter pacing.