# Particle descriptors
```ts
import {
particleChoice,
particleCurve,
particleGradient,
particleInteger,
particleParameter,
particleRange,
} from "@pibbl/core/particles";
```
These direct, tree-shakable functions create immutable definition descriptors.
They do not pick a value when called. The particle compiler assigns stable
random channels, and the executor samples them from the system seed, emitter,
particle ordinal, and property channel.
- `particleRange(min, max)` describes a continuous inclusive range.
- `particleInteger(min, max)` describes a safe-integer inclusive range.
- `particleChoice([{ value, weight }])` describes weighted selection.
- `particleParameter(name)` references a typed effect parameter.
- `particleCurve(keys, options?)` samples a scalar or two-dimensional value
over normalized lifetime.
- `particleGradient(keys, options?)` samples color over normalized lifetime.
Curves and gradients require strictly increasing keys covering `0` through
`1`. These APIs are particle-specific because their descriptors participate in
deterministic channel compilation, parameter timing, and GPU lookup-table
generation; they are not general random-number or interpolation utilities.
Types: [`PibblParticleRange`](/reference/types/particles/#pibblparticlerange),
[`PibblParticleIntegerRange`](/reference/types/particles/#pibblparticleintegerrange),
[`PibblParticleChoice`](/reference/types/particles/#pibblparticlechoice),
[`PibblParticleParameterReference`](/reference/types/particles/#pibblparticleparameterreference),
[`PibblParticleCurve`](/reference/types/particles/#pibblparticlecurve), and
[`PibblParticleGradient`](/reference/types/particles/#pibblparticlegradient).
## API details from source
### particleChoice
Describes weighted choices sampled by a particle effect.
```ts
particleChoice: (choices: readonly Readonly<{ value: T; weight: number; }>[]) => PibblParticleChoice
```
Related API: [particleChoice](/reference/functions/particle-descriptors/), [PibblParticleChoice](/reference/types/particles/#pibblparticlechoice).
#### Parameters
- **`choices`** — Nonempty weighted values; every weight and their total must be positive and
finite.
#### Returns
An immutable descriptor containing copied choices. See [PibblParticleChoice](/reference/types/particles/#pibblparticlechoice).
#### See also
[PibblParticleChoice](/reference/types/particles/#pibblparticlechoice)
[View source — packages/core/src/features/particles/lib/particle.ts:252](/source/packages/core/src/features/particles/lib/particle-ts/#L252)
### particleCurve
Describes keyframed scalar or vector values over normalized particle lifetime.
```ts
particleCurve: (keys: readonly (readonly [time: number, value: T])[], options?: PibblParticleCurveOptions) => PibblParticleCurve
```
Related API: [particleCurve](/reference/functions/particle-descriptors/), [PibblParticleCurveValue](/reference/types/particles/#pibblparticlecurvevalue), [PibblParticleCurveOptions](/reference/types/particles/#pibblparticlecurveoptions), [PibblParticleCurve](/reference/types/particles/#pibblparticlecurve).
#### Parameters
- **`keys`** — Scalar or 2D-vector keys with strictly increasing normalized times, starting at 0
and ending at 1.
- **`options`** — Optional segment easing. See [PibblParticleCurveOptions](/reference/types/particles/#pibblparticlecurveoptions).
#### Returns
An immutable lifetime curve containing copied keys. See [PibblParticleCurve](/reference/types/particles/#pibblparticlecurve).
#### See also
[PibblParticleCurveOptions](/reference/types/particles/#pibblparticlecurveoptions)
[PibblParticleCurve](/reference/types/particles/#pibblparticlecurve)
[PibblParticleCurveValue](/reference/types/particles/#pibblparticlecurvevalue)
[View source — packages/core/src/features/particles/lib/particle.ts:274](/source/packages/core/src/features/particles/lib/particle-ts/#L274)
### particleGradient
Describes keyframed colors over normalized particle lifetime.
```ts
particleGradient: (keys: readonly (readonly [time: number, color: string])[], options?: PibblParticleCurveOptions) => PibblParticleGradient
```
Related API: [particleGradient](/reference/functions/particle-descriptors/), [PibblParticleCurveOptions](/reference/types/particles/#pibblparticlecurveoptions), [PibblParticleGradient](/reference/types/particles/#pibblparticlegradient).
#### Parameters
- **`keys`** — Color keys with strictly increasing normalized times, starting at 0 and ending at
1.
- **`options`** — Optional segment easing. See [PibblParticleCurveOptions](/reference/types/particles/#pibblparticlecurveoptions).
#### Returns
An immutable lifetime color gradient containing copied keys. See
[PibblParticleGradient](/reference/types/particles/#pibblparticlegradient) .
#### See also
[PibblParticleCurveOptions](/reference/types/particles/#pibblparticlecurveoptions)
[PibblParticleGradient](/reference/types/particles/#pibblparticlegradient)
[View source — packages/core/src/features/particles/lib/particle.ts:287](/source/packages/core/src/features/particles/lib/particle-ts/#L287)
### particleInteger
Describes a random integer range for particle sampling.
```ts
particleInteger: (min: number, max: number) => PibblParticleIntegerRange
```
Related API: [particleInteger](/reference/functions/particle-descriptors/), [PibblParticleIntegerRange](/reference/types/particles/#pibblparticleintegerrange).
#### Parameters
- **`min`** — Inclusive lower bound, a safe integer.
- **`max`** — Inclusive upper bound; the inclusive span must be a safe integer.
#### Returns
An immutable integer sampling descriptor. See [PibblParticleIntegerRange](/reference/types/particles/#pibblparticleintegerrange).
#### See also
[PibblParticleIntegerRange](/reference/types/particles/#pibblparticleintegerrange)
[View source — packages/core/src/features/particles/lib/particle.ts:242](/source/packages/core/src/features/particles/lib/particle-ts/#L242)
### particleParameter
References a named parameter declared by a particle effect.
```ts
particleParameter: (name: Name) => PibblParticleParameterReference
```
Related API: [particleParameter](/reference/functions/particle-descriptors/), [PibblParticleParameterReference](/reference/types/particles/#pibblparticleparameterreference).
#### Parameters
- **`name`** — Nonempty name of a parameter declared by the effect.
#### Returns
A typed parameter reference. See [PibblParticleParameterReference](/reference/types/particles/#pibblparticleparameterreference).
#### See also
[PibblParticleParameterReference](/reference/types/particles/#pibblparticleparameterreference)
[View source — packages/core/src/features/particles/lib/particle.ts:261](/source/packages/core/src/features/particles/lib/particle-ts/#L261)
### particleRange
Describes a continuous random range for particle sampling.
```ts
particleRange: (min: number, max: number) => PibblParticleRange
```
Related API: [particleRange](/reference/functions/particle-descriptors/), [PibblParticleRange](/reference/types/particles/#pibblparticlerange).
#### Parameters
- **`min`** — Finite lower bound, no greater than max.
- **`max`** — Finite upper bound; the span must also be finite.
#### Returns
An immutable continuous sampling descriptor. See [PibblParticleRange](/reference/types/particles/#pibblparticlerange).
#### See also
[PibblParticleRange](/reference/types/particles/#pibblparticlerange)
[View source — packages/core/src/features/particles/lib/particle.ts:232](/source/packages/core/src/features/particles/lib/particle-ts/#L232)
## 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
- [Particle descriptors](/minimal-examples/particles/descriptors/): Define randomized spawn values and lifespan curves. [Plain source](/minimal/particles/descriptors.ts)
## Documentation version
Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.