55 lines
1.8 KiB
Markdown
55 lines
1.8 KiB
Markdown
# 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
|
|
```
|