# 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

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