# 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

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

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