suaveplan/openspec/changes/enterprise-gaming-r3f-combat/proposal.md

OpenSpec Change: enterprise-gaming-r3f-combat

• Change ID: enterprise-gaming-r3f-combat
• Package: @suaveplan/r3f-combat
• Category: gaming/gameplay
• Target path: gaming/gameplay/r3f-combat
• Status: PROPOSED
• Date: 2026-04-24

---

Summary

Deliver @suaveplan/r3f-combat on the genesis branch from scratch at enterprise quality. The package is the R3F rendering layer for @suaveplan/combat: hitbox debug wireframes (per-bone capsule/sphere overlays toggled by flag), projectile trail meshes (instanced TubeGeometry with fade-out), muzzle flash billboard sprites, impact effect particle bursts (pooled instanced meshes), and floating damage numbers (billboarded Text via @react-three/drei). All effects are event-driven, subscribing to @suaveplan/combat and @suaveplan/weapons event buses. Genesis adds 100% coverage and Storybook stories.

---

Available workspace deps

@suaveplan/combat, @suaveplan/weapons, @suaveplan/hitbox, @suaveplan/error, @suaveplan/types, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

function HitboxDebug(props: HitboxDebugProps): JSX.Element
// entityId, color, opacity, visible

function ProjectileTrails(props: ProjectileTrailsProps): JSX.Element
// maxTrails, fadeTime, color

function MuzzleFlash(props: MuzzleFlashProps): JSX.Element
// weaponRef, duration, intensity

function ImpactEffects(props: ImpactEffectsProps): JSX.Element
// poolSize, particleCount, gravity

function DamageNumbers(props: DamageNumbersProps): JSX.Element
// floatHeight, duration, criticalColor, normalColor

function CombatEffectsProvider(props: PropsWithChildren): JSX.Element
// subscribes to combat events; required ancestor

function useCombatEffects(): CombatEffectsCon```text

---

## File layout

```text
gaming/gameplay/r3f-combat/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    context/combat-effects-provider.tsx + md + test
    hooks/use-combat-effects.ts + md + test
    components/
      HitboxDebug/ (tsx + md + test + stories + index)
      ProjectileTrails/ (tsx + md + test + stories + index)
      MuzzleFlash/ (tsx + md + test + stories + index)
      ImpactEffects/ (tsx + md + test + stories + index)
      DamageNumbers/ (tsx + md + test + stories + index)
  tests/integration.test.ts