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`.