Module particles 

Deterministic fixed-step simulations and coupled analytic particles.

use motion_content::prelude::*;
use motion_core::prelude::*;
use motion_core::{
    DisplayList, RasterLimits, ResourceStore, ValidatedDisplayList, MAX_PATH_VERBS,
    MAX_STROKE_VERBS, MAX_SVG_PATH_BYTES, sample_offsets,
};
use motion_render::{Composition, RenderPrepare, RenderOptions, BackendKind, render_still};
use motion_content::particles::*;
let cache = SceneCache::new(16);
let context = SceneContext::new(
    50.milliseconds().after_origin(),
    fps!(30),
    Size::new(16.0, 16.0),
    &cache,
)
.with_clip_duration(100.milliseconds());
let simulation = context.try_cache(("sparks", 42_u64, 100_i64), || {
    ParticleSimulation::new(42)
        .duration(100.milliseconds())
        .emitter(BurstEmitter::new(Time::ZERO, 4, Point::new(8.0, 8.0)).speed(0.0))
        .modifier(Gravity::new(Vector2::new(0.0, 10.0)))
        .style(ParticleStyle::Dots { radius: 2.0 })
        .build()
})?;
assert_eq!(simulation.sample(50.milliseconds().after_origin())?.len(), 4);
let frame = simulation
    .try_render(&context)?
    .compile(
        context.size(),
        PixelSize::new(16, 16),
        ValidationLimits::default(),
    )?
    .prepare(ValidationLimits::default(), RasterLimits::default())?
    .render_linear(RasterLimits::default())?;
assert!(frame.linear_pixel(8, 8).unwrap()[3] > 0.0);

Modules

presets

Deterministic particle recipes returning ordinary, further configurable simulations.

Structs

Attractor

Softened inverse-square attraction without singular acceleration at the center.

Ballistic

Coupled constant gravity and linear drag, including the zero-drag limit.

Boids

Spatially hashed flocking evaluated from one immutable population snapshot.

BounceBox

Reflects predicted next positions against a rectangle. Place last when other operators change velocity; arbitrary multiple wall crossings are supported.

BurstEmitter

A point burst emitted once at the first fixed boundary at/after its authored time.

CircleCollider

Solid circular obstacle with swept collision detection.

CollisionResponse

Bounded normal restitution and tangential friction.

ColorCurve

Nonuniform premultiplied color keyframes, evaluated without accumulated state.

ColorField

Color sampled from position or speed, with an explicit normalization interval.

ColorOverLifetime

Piecewise-linear linear-premultiplied RGBA over normalized lifetime.

Converge

Smoothstep convergence between deterministic point sets, cycling the shorter.

CurlNoise

Divergence-free curl of the shared seeded Perlin potential, advected over time.

DiskEmitter

A uniform area disk source, not a circumference distribution.

Drag

Per-step exponential velocity damping; simulation operator order is explicit.

FlowField

Time-evolving noise or image flow, with no mutable frame cursor.

Gravity

Constant acceleration, applied before semi-implicit integration.

ImageEmitter

An image source weighted by alpha or linear luminance, inheriting pixel colors.

IntensityOverLifetime

RGB energy multiplier; alpha is unchanged and HDR energy is not clipped.

NoiseDrift

Closed smooth value-noise displacement and its analytic velocity derivative.

Orbit

Exact circular orbits and tangent velocity, parameterized in radians/second.

Particle

72-byte particle record; colors are finite linear-premultiplied RGBA.

ParticleBatch

Validated opaque instance payload, consumed directly by CPU/GPU paths.

ParticleCollisions

Optional equal-mass sphere contacts using stable spatial-hash pair ordering.

ParticleCurve

Bounded nonnegative scalar keyframes with explicit normalized times and easing.

ParticleEvent

Event payload ordered by stable nonrecycled particle ID.

ParticleSimulation

Lazy fixed-step replay, created by ParticleSimulationBuilder::build. The first clip duration fixes a shared preparation; reusing one cache instance with a different duration is rejected explicitly. The configuration never changes after building.

ParticleSimulationBuilder

Collects a particle simulation’s settings; build validates them.

ParticleTrajectory

Pure coupled-trajectory collection, without snapshots or previous-frame state.

PathEmitter

An arc-length path source inheriting its tangent direction.

PointEmitter

A point source with stable fixed-boundary births.

PolygonCollider

Bounded simple polygon obstacle, prepared once rather than per particle.

RadialForce

Radius-bounded attraction/repulsion using an explicit attenuation policy.

RectEmitter

A uniform rectangular source in local design coordinates.

SdfCollider

Grid collision; velocity*step must remain below the smallest cell dimension.

Seek

Stable-index seeking to a point set, for example VectorTree::sample_points.

SegmentCollider

Two-sided finite segment, including endpoint contacts.

SignedDistanceGrid

Precomputed signed samples plus exact cached boundary guards for thin features. All data is immutable and can be shared through SceneContext::cache.

SimulationLimits

Logical snapshot/replay allowances, not a process-wide RSS sandbox.

SimulationStats

Actual immutable snapshot preparation facts.

SizeOverLifetime

Linear nonnegative size multiplier over normalized lifetime.

SpeedStretch

Deterministic velocity-aligned elongation.

Spring

Consecutive stable IDs coupled by Hooke springs, optionally forming a closed chain.

SpriteAtlas

An immutable, uniformly sized atlas; unused cells are transparent.

SpriteSheet

Uniform row-major sheet cells. Sampling clamps inside the selected cell.

StyleOptions

Optional policies grouped separately from each style’s basic geometry.

SubEmitter

Event-triggered emitter. It receives local step zero and Time::ZERO for each trigger.

SurfaceEmitter

An area-uniform shared VectorSurface source.

Temperature

Deterministic blackbody approximation, 1000..=40000 Kelvin, decoded to linear RGB. As a modifier it replaces the particle’s RGB with the premultiplied blackbody color, discarding any earlier hue; alpha is unchanged.

TrailOptions

Historical sampling shared by all particles at each requested boundary.

Vortex

Tangential acceleration about a softened point vortex.

Wind

Constant wind acceleration, independent of elapsed scene time.

Enums

BokehShape

Aperture geometry for depth-aware particles.

FieldCoordinate

Scalar coordinate used by a particle color field.

FlowSource

Immutable source for an evolving velocity field.

ForceFalloff

Spatial attenuation with no singular denominator at a force center.

ImageDensity

Density policy, independent of inherited color.

Inherit

Parent properties added to an emitter’s local child record.

ParticleEventKind

Fixed-boundary particle event.

ParticleShape

Built-in analytic particle silhouettes.

ParticleStyle

particle presentation. Built-ins share an instance protocol; custom callbacks run on CPU and return ordinary content or a validation error, never custom WGSL.

ProceduralSprite

Built-in image materials requiring no external assets.

SpriteSheetMode

Stateless sprite-frame selection.

Traits

ParticleEmitter

Fixed-step emitter. Callbacks are deterministic and cooperative: output is bounded after return, not a hard allocator sandbox. IDs/age are assigned by the simulation. Random streams are keyed per emitter and step.

ParticleGroupModifier

A stable-order population operator, evaluated before independent modifiers.

ParticleModifier

Ordered per-particle simulation operator, followed by velocity integration.

TrajectoryModel

A whole random-access particle trajectory, not separately composable forces.

Type Aliases

ParticleBlend

Explicit batch compositing, independent of primitive kind.