ParticleEmitter

ParticleEmitter is a declarative component for creating particle effects. Drop it into a scene or as a child of an Actor to add fire, smoke, explosions, and other visual effects.

tsx

import { ParticleEmitter } from "@carverjs/core/components";

For imperative control (burst on demand, start/stop programmatically), use the useParticles hook instead.

Quick Start #

tsx

import { ParticleEmitter } from "@carverjs/core/components";

// One-line fire effect
<ParticleEmitter preset="fire" position={[0, 1, 0]} />

// Snow weather
<ParticleEmitter preset="snow" position={[0, 15, 0]} />

// Magic aura on an actor
<Actor type="primitive" shape="sphere" color="#333">
  <ParticleEmitter preset="magic" position={[0, 0, 0]} space="local" />
</Actor>

Props #

ParticleEmitter accepts all ParticleEmitterConfig fields plus:

Prop	Type	Default	Description
`preset`	`ParticlePreset`	—	Base preset. Props override preset values
`position`	`Vector3`	`[0, 0, 0]`	Emitter position in parent space
`rotation`	`Euler`	—	Emitter rotation
`enabled`	`boolean`	`true`	Toggle emission on/off

All ParticleEmitterConfig options are also accepted as props. See useParticles for the full list.

Presets #

Preset	Description
`"fire"`	Ascending glow, orange to transparent, additive blend
`"smoke"`	Slow rising grey particles, expanding over lifetime
`"explosion"`	Radial burst with quick fade
`"sparks"`	Fast bright particles with gravity
`"rain"`	Vertical downpour
`"snow"`	Gentle falling white particles
`"magic"`	Colorful orbiting particles, additive blend
`"confetti"`	Tumbling colored particles with gravity

Custom Configuration #

Override any preset value or build from scratch:

tsx

<ParticleEmitter
  preset="fire"
  maxParticles={500}
  rate={120}
  particle={{
    speed: [3, 8],
    lifetime: [0.5, 1.5],
    size: [0.2, 0.5],
    color: ["#ff4400", "#ffaa00"],
    gravity: -2,
  }}
  overLifetime={{
    alpha: [
      { t: 0, value: 1 },
      { t: 0.7, value: 0.8 },
      { t: 1, value: 0 },
    ],
    size: [
      { t: 0, value: 1 },
      { t: 1, value: 0 },
    ],
  }}
  blendMode="additive"
  position={[0, 0, 0]}
/>

Ref Forwarding #

ParticleEmitter supports forwardRef for accessing the underlying <group>:

tsx

import { useRef } from "react";
import { ParticleEmitter } from "@carverjs/core/components";
import type { Group } from "@carverjs/core/types";

function MyScene() {
  const emitterRef = useRef<Group>(null);

  return <ParticleEmitter ref={emitterRef} preset="smoke" />;
}

World vs Local Space #

tsx

// World space (default): particles stay where they were born
<ParticleEmitter preset="fire" position={[0, 1, 0]} space="world" />

// Local space: particles follow the parent Actor
<Actor type="primitive" shape="box" color="#888">
  <ParticleEmitter preset="magic" space="local" />
</Actor>

Type Definitions #

See Types for ParticleEmitterProps, ParticleEmitterConfig, ParticlePreset, and EmitterShapeConfig.