# useParticleSystem

```ts
import { useParticleSystem } from "@pibbl/core/particles";
```

Creates a stable component-owned system for an immutable 2D definition.
Its controls are `play`, `pause`, `resume`, `restart`, `emit`, and `stop`.
`status` and `execution` are readonly Pibbl signals.

Commands enter the shared scheduler's Begin phase. Population advances in
Advance, metadata publishes in Commit, renderer work plans and paints, and
events/errors deliver in Complete. Removal cancels queued commands, unregisters
the scheduler participant, releases the renderer binding and parameter epochs,
and makes retained controls inert.

Use explicit system mode when event handlers need manual bursts or lifecycle
controls. Canvas supports both automatic emission and manual births.

Types: [`PibblParticleSystem`](/reference/types/particles/#pibblparticlesystem),
[`PibblParticleSystemOptions`](/reference/types/particles/#pibblparticlesystemoptions),
[`PibblParticleSystemStatus`](/reference/types/particles/#pibblparticlesystemstatus), and
[`PibblParticleExecution`](/reference/types/particles/#pibblparticleexecution).

## API details from source

<span id="api-useParticleSystem"></span>

Creates a mount-owned system retaining the effect's emitter and parameter types. See
PibblParticleEffect2D, PibblParticleSystemOptions, and PibblParticleSystem.
Creates one stable particle-system handle owned by the current hook slot.

```ts
useParticleSystem: <EmitterName extends string, Parameters extends PibblParticleParameterValues>(effect: SignalValue<PibblParticleEffect2D<EmitterName, Parameters>>, options?: SignalValue<SignalFields<PibblParticleSystemOptions>>) => PibblParticleSystem<EmitterName, Parameters>
```

Related API: [useParticleSystem](/reference/hooks/use-particle-system/), [PibblParticleParameterValues](/reference/types/particles/#pibblparticleparametervalues), [SignalValue](/reference/types/signal-inputs/#signalvalue), [PibblParticleEffect2D](/reference/types/particles/#pibblparticleeffect2d), [PibblParticleSystemOptions](/reference/types/particles/#pibblparticlesystemoptions), [PibblParticleSystem](/reference/types/particles/#pibblparticlesystem).

### Parameters

- **`effect`** — Effect definition, optionally supplied by a signal. See [SignalValue](/reference/types/signal-inputs/#signalvalue) ,
[PibblParticleEffect2D](/reference/types/particles/#pibblparticleeffect2d) .

- **`options`** — Playback and simulation options, optionally supplied by a signal. See
[SignalValue](/reference/types/signal-inputs/#signalvalue) , `SignalFields` , [PibblParticleSystemOptions](/reference/types/particles/#pibblparticlesystemoptions) .

- **`effectInput`** — Effect definition, optionally supplied by a signal. See [SignalValue](/reference/types/signal-inputs/#signalvalue)
, [PibblParticleEffect2D](/reference/types/particles/#pibblparticleeffect2d) .

- **`optionsInput`** — Playback and simulation options, optionally supplied by a signal. See
[SignalValue](/reference/types/signal-inputs/#signalvalue) , `SignalFields` , [PibblParticleSystemOptions](/reference/types/particles/#pibblparticlesystemoptions) .

### Returns

Stable mount-owned controls for the particle simulation. See [PibblParticleSystem](/reference/types/particles/#pibblparticlesystem).

### See also

[SignalValue](/reference/types/signal-inputs/#signalvalue)

[PibblParticleEffect2D](/reference/types/particles/#pibblparticleeffect2d)

[PibblParticleSystemOptions](/reference/types/particles/#pibblparticlesystemoptions)

[PibblParticleSystem](/reference/types/particles/#pibblparticlesystem)

[View source — packages/core/src/features/particles/lib/system/hook.ts:39](/source/packages/core/src/features/particles/lib/system/hook-ts/#L39)

## Implementation guidance for agents

Read the [Canvas particles companion](/agents/topics/particles/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Mounted particle system](/minimal-examples/particles/system/): Mount a manual burst effect and trigger it with pointer input. [Plain source](/minimal/particles/system.tsx)
## Interactive examples

- [Fire and Flow](/examples/fire-and-flow/) · [Full page](/experience/fire-and-flow/)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.