Initial Commit

openspec/changes/enterprise-gaming-weapons/proposal.md

@@ -0,0 +1,177 @@
+# OpenSpec Change: enterprise-gaming-weapons
+
+- **Change ID**: enterprise-gaming-weapons
+- **Package**: `@suaveplan/weapons`
+- **Category**: gaming/combat
+- **Target path**: `gaming/combat/weapons`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/weapons.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/weapons` on the genesis branch from scratch at enterprise quality. The package provides a weapon system with projectile ballistics, melee attacks, recoil patterns, ammo management, and attachment slots. A `WeaponRegistry` holds typed `WeaponDefinition` descriptors; `WeaponInstance` tracks runtime state (current ammo, reload timer, heat); `ProjectileSimulator` advances projectile positions each tick applying drag and gravity. All outputs are damage events consumable by `@suaveplan/combat`. Genesis adds Zod schemas for weapon definitions, structured errors, OTel shot counters, and 100% coverage.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis yet — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `WeaponError`; `WEAPON.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock`, `IdGenerator` |
+| `@suaveplan/events` (`workspace:^`) | `weapon:fire`, `weapon:reload`, `weapon:empty` events |
+| `@suaveplan/combat` (`workspace:^`) | `DamageEvent` type consumed by fire logic |
+| `zod` (`catalog:forms`) | `WeaponDefinition`, `AmmoConfig` schemas |
+| `@opentelemetry/api` (`catalog:observability`) | Shots-fired counter, reload timer histogram |
+
+---
+
+## Public API surface
+
+```ts
+type WeaponClass = 'pistol' | 'rifle' | 'shotgun' | 'sniper' | 'smg' | 'melee' | 'explosive'
+
+interface WeaponDefinition {
+  id: string
+  name: string
+  class: WeaponClass
+  damage: number
+  damageType: DamageType
+  fireRate: number          // rounds per second
+  magazineSize: number
+  reloadTime: number        // seconds
+  projectileSpeed?: number  // m/s; undefined = instant hitscan
+  spread: number            // degrees
+  recoilPattern?: Vec2[]    // sequence of screen-space offsets
+  attachmentSlots?: string[]
+  isMelee?: boolean
+  meleeRange?: number       // meters
+}
+
+function createWeaponRegistry(): WeaponRegistry
+interface WeaponRegistry {
+  register(def: WeaponDefinition): void
+  get(id: string): WeaponDefinition | undefined
+  list(): WeaponDefinition[]
+}
+
+function createWeaponInstance(def: WeaponDefinition, options?: WeaponInstanceOptions): WeaponInstance
+
+interface WeaponInstance {
+  readonly definition: WeaponDefinition
+  readonly ammo: number
+  readonly isReloading: boolean
+  readonly nextFireTime: number
+  fire(origin: Vec3, direction: Vec3, shooterId: string): FireResult | null
+  reload(): void
+  tick(dt: number): void
+  addAttachment(slot: string, attachment: Attachment): void
+  removeAttachment(slot: string): void
+}
+
+interface FireResult {
+  projectileId?: string       // present for ballistic projectiles
+  damageEvent?: DamageEvent   // present for hitscan
+  muzzlePosition: Vec3
+  direction: Vec3
+}
+
+// Projectile simulator (ballistic weapons)
+function createProjectileSimulator(options?: ProjectileSimulatorOptions): ProjectileSimulator
+
+interface ProjectileSimulator {
+  spawn(id: string, origin: Vec3, velocity: Vec3, def: WeaponDefinition): void
+  tick(dt: number): ProjectileUpdate[]
+  destroy(id: string): void
+}
+
+interface ProjectileUpdate {
+  id: string
+  position: Vec3
+  velocity: Vec3
+  traveledMeters: number
+  expired: boolean
+}
+
+interface Attachment {
+  id: string
+  slot: string
+  damageMultiplier?: number
+  fireRateMultiplier?: number
+  spreadModifier?: number
+  displayName: string
+}
+```
+
+### Error codes
+
+```ts
+type WeaponErrorCode =
+  | 'WEAPON_NOT_FOUND'
+  | 'WEAPON_EMPTY'
+  | 'WEAPON_RELOADING'
+  | 'WEAPON_FIRE_RATE_EXCEEDED'
+  | 'WEAPON_INVALID_ATTACHMENT'
+```
+
+---
+
+## New additions for genesis
+
+1. **Ballistic drop** — projectile velocity decreases by `gravity * dt`; configurable drag coefficient.
+2. **Recoil pattern playback** — `recoilPattern` cycles through offsets each shot, resetting after trigger release.
+3. **Attachment modifiers** — multiplicative stacking for damage, fire rate, spread; additive for reload time.
+4. **OTel** — `weapon.shots_fired_total` counter (by weapon class); `weapon.reload_duration_ms` histogram.
+
+---
+
+## File layout
+
+```text
+gaming/combat/weapons/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/common.ts
+    types/common.md
+    core/
+      weapon-registry/
+        weapon-registry.ts
+        weapon-registry.md
+        weapon-registry.types.ts
+        weapon-registry.test.ts
+        index.ts
+      weapon-instance/
+        weapon-instance.ts
+        weapon-instance.md
+        weapon-instance.types.ts
+        weapon-instance.test.ts
+        index.ts
+      projectile-simulator/
+        projectile-simulator.ts
+        projectile-simulator.md
+        projectile-simulator.types.ts
+        projectile-simulator.test.ts
+        index.ts
+  tests/
+    integration.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: `@suaveplan/r3f-combat` renders muzzle flash and projectile trails from fire events. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/combat`.

openspec/changes/enterprise-gaming-weapons/tasks.md

@@ -0,0 +1,47 @@
+# Tasks: enterprise-gaming-weapons
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## Phase 1 — Scaffold
+
+- [ ] Create `gaming/combat/weapons/` (`@suaveplan/weapons`, `0.1.0`, `sideEffects: false`)
+- [ ] `tsconfig.json`, `vitest.config.ts`
+
+## Phase 2 — Error codes & constants
+
+- [ ] `src/error-codes.ts` + `src/constants/index.ts` — default gravity, drag, max projectile lifetime
+
+## Phase 3 — Types
+
+- [ ] `src/types/common.ts` + `common.md`
+
+## Phase 4 — Weapon registry
+
+- [ ] `src/core/weapon-registry/weapon-registry.ts` — register/get/list, Zod validation on register
+- [ ] Tests + docs
+
+## Phase 5 — Weapon instance
+
+- [ ] `src/core/weapon-instance/weapon-instance.ts` — fire/reload/tick/attachments, rate limiting, events, OTel
+- [ ] Tests (fire rate guard, empty clip, reload timer)
+- [ ] Docs
+
+## Phase 6 — Projectile simulator
+
+- [ ] `src/core/projectile-simulator/projectile-simulator.ts` — Euler integration with drag + gravity
+- [ ] Tests (trajectory over time, expiry at max range)
+- [ ] Docs
+
+## Phase 7 — Integration tests
+
+- [ ] `tests/integration.test.ts` — fire → projectile tick → impact → damage event → combat.processHit
+
+## Phase 8 — Pre-publish gate
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/weapons` green
+- [ ] 100% coverage
+- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/weapons`