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

OpenSpec Change: enterprise-gaming-r3f-particles

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

---

Summary

Deliver @suaveplan/r3f-particles on the genesis branch from scratch at enterprise quality. The package provides GPU-accelerated particle systems for React Three Fiber using InstancedMesh. A ParticleSystem manages a fixed-size particle pool with configurable spawn rate, lifetime, initial velocity spread, gravity, and color-over-lifetime; a ParticleEmitter component controls burst/continuous emission; preset effects include muzzle flash, explosion, smoke, and magic sparkles. Genesis adds Zod emitter config schemas, structured errors, OTel active-particle gauge, and 100% coverage.

---

Available workspace deps

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

---

Public API surface

function ParticleEmitter(props: ParticleEmitterProps): JSX.Element
// preset | config, rate, burst, position, direction, onEmpty

function useParticleSystem(): ParticleSystemHandle
// emit(count, origin, velocity): void; clear(): void

// Preset effects
const PARTICLE_PRESETS: Record<'muzzle_flash' | 'explosion' | 'smoke' | 'sparkles', ParticleConfig>

---

File layout

gaming/effects/r3f-particles/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    core/
      particle-system/ (ts + md + types + test + index)
    presets/index.ts
    components/
      ParticleEmitter/ (tsx + md + test + stories + index)
    hooks/use-particle-system.ts + md + test
  tests/integration.test.ts