templates: weapon sample — pistol with recoil, muzzle flash, shells, ammo/reload (project scripts)

[shadow-kernel]

Context

The proof that the whole epic works end-to-end — and the reference every Vortex game copies. Gameplay stays in PROJECT scripts (never engine code): the Horror Starter template gains a complete, polished pistol. 'Smooth' is the acceptance bar: one animation event triggers recoil + flash + light pulse + smoke + shell + bang + hitscan in the same frame.

Goal

Template content: rigged first-person arms + pistol prefab wired with socket attachment, layered aim animation, synced reload pair, WeaponBase script (ammo, fire rate, reload states), recoil via CameraFX, muzzle flash (billboard + scripted point-light pulse — the v2.7 'lite' VFX), shell ejection (pooled prefabs), impact decal placeholder + audio via random containers.

Acceptance Criteria

• Pistol prefab attaches to the hand socket of the FP arms; walk + aim layered animation runs smooth
• Fire: animation event → raycast from muzzle bone (GetBoneWorldTransform) → hit feedback; recoil kick via CameraFX; muzzle flash billboard + light pulse ≤ 2 frames latency
• Shell ejection: pooled shell prefabs with simple arc + despawn (Instantiate/pool from the v2.7 API)
• Reload: synced character+weapon clips, ammo HUD via VUI, interruption handling (sprint cancels reload)
• All sounds via audio random containers (shot variations, dry-fire click, reload foley)
• Zero engine-side gameplay code — everything demonstrably in template project scripts
• Runs identically in editor play mode and shipped .vpak build

Technical Notes

Muzzle smoke stays minimal here (single animated billboard); the full particle version is the v3.3 follow-up issue. Document the event-wiring pattern in the wiki as the canonical 'weapon recipe'.

Dependencies

• Everything in this epic + physics: Physics.Raycast + scripting: coroutines + audio: random sound containers + ui-vui HUD basics