Struct ParticleSystem 

pub struct ParticleSystem { /* private fields */ }

A self-contained particle simulation: emitters, a shared particle pool with a budget, and a deterministic seeded RNG. Host-owned; per frame call update (pure simulation, no renderer) then — from PS.1 — sync(&mut SceneRenderer) to mirror the pool into dynamic sprite instances.

Budget semantics: when the pool is full, spawns are dropped (never evict a live particle — a visible pop); dropped_spawns makes the cap observable instead of silent.

Implementations

impl ParticleSystem

pub fn new(seed: u64) -> Self

A system with the given RNG seed and the default budget (DEFAULT_MAX_PARTICLES). Same seed + same call sequence ⇒ bit-identical simulation.

pub fn set_max_particles(&mut self, max: usize)

Set the particle budget. Lowering it below the current live count kills nothing — it only gates future spawns.

pub fn set_carve_debris_cap(&mut self, cap: usize)

Tune how many debris particles one carve_debris call may spawn (default CARVE_DEBRIS_CAP) — the per-explosion load knob. Bigger carves stride-sample an even spatial subset down to this; clamped to ≥ 1.

pub fn add_emitter(&mut self, def: ParticleEmitterDef) -> EmitterId

Register an emitter. SpawnMode::Burst fires immediately.

pub fn remove_emitter(&mut self, id: EmitterId) -> bool

Retire an emitter: it stops spawning immediately and its handle goes stale, but particles already in flight live out their lifetimes (the state drains away with the last one). Returns false on a stale handle.

pub fn set_emitter_pos(&mut self, id: EmitterId, pos: [f32; 3]) -> bool

Move an emitter (attach effects to moving things). Returns false on a stale handle.

pub fn burst(&mut self, id: EmitterId, n: u32) -> u32

Spawn n particles from id right now (any SpawnMode). Returns how many actually spawned (budget may drop the rest); 0 on a stale handle.

pub fn update(&mut self, dt: f64)

Advance the simulation by dt seconds: integrate + age + fade every particle, retire the dead (their facade instances queue in drain_dead_instances), then run SpawnMode::Rate emitters. Pure simulation — no facade calls, unit-testable without a window or GPU. Never collides; for CollisionMode emitters use update_with_scene.

pub fn update_with_scene(&mut self, dt: f64, scene: &Scene)

update + voxel collision (PS.3): emitters with a non-None CollisionMode test each particle’s post-step position against scene’s solid voxels. See CollisionMode for the sampling caveats.

pub fn particles(&self) -> &[Particle]

The live particles, unordered (the pool swap-removes).

pub fn particle_count(&self) -> usize

Number of live particles.

pub fn emitter_count(&self) -> usize

Number of active (non-retired) emitters.

pub fn dropped_spawns(&self) -> u64

Spawns dropped by the budget since construction. A steadily climbing value means the effect design outruns set_max_particles.

pub fn drain_dead_instances( &mut self, ) -> impl Iterator<Item = SpriteInstanceId> + '_

Drain the facade instances of particles that died since the last drain. sync removes each via remove_sprite_instance; hosts doing their own rendering can consume it directly.

pub fn stale_model_kills(&self) -> u64

Newborn spawns that failed because the emitter’s SpriteModelId went stale (the model was removed / the registry was reset). Each failure kills its particle — a climbing value means an emitter outlived its model.

pub fn sync(&mut self, renderer: &mut SceneRenderer)

Mirror the simulation into renderer (PS.1): despawn the dead, spawn newborns pre-posed (the documented streaming-spawn path — no one-frame axis-aligned flash) with their one-time material/lighting/shadow/tint setup, batch-move everything else via one set_sprite_instance_transforms, and write alpha only for particles whose fade actually changed (alpha has no batch API). Call after update, before render — or use tick.

pub fn tick(&mut self, renderer: &mut SceneRenderer, dt: f64)

update + sync in one call — the per-frame default, named after the facade’s own tick.

pub fn tick_with_scene( &mut self, renderer: &mut SceneRenderer, dt: f64, scene: &Scene, )

update_with_scene + sync — tick for hosts using CollisionMode emitters. Call before handing the same scene to render.

pub fn carve_debris( &mut self, scene: &mut Scene, grid: GridId, centre: IVec3, radius: u32, outward: Range<f32>, def: &ParticleEmitterDef, ) -> u32

Carve a sphere out of a grid and burst its actual voxel colours as debris (PS.5) — the “shoot the wall, the wall’s colours fly off” effect: sample the solid voxels inside the ball, set_sphere(…, None) them away, then spawn one def-driven debris particle per sampled voxel, positioned at its voxel’s world centre (transform-correct for rotated grids), tinted with its colour, and kicked radially away from the carve centre at a speed from outward (on top of the def’s normal velocity terms).

def supplies the model, physics, lifetime and curves; its pos/shape/spawn/tint are ignored (position and tint are per-voxel; nothing else auto-spawns — the transient emitter retires immediately and drains with its last particle). tint_end still applies, lerping from the voxel colour.

Big carves are stride-sampled down to the system’s debris cap (CARVE_DEBRIS_CAP by default — set_carve_debris_cap tunes it) debris (an even spatial subset, not the first N); the pool budget then applies on top, counting overflow in dropped_spawns. Returns how many debris actually spawned. A stale grid or an all-air ball carves/spawns nothing.

pub fn voxel_debris( &mut self, sites: &[([f32; 3], Rgb)], from: [f32; 3], outward: Range<f32>, def: &ParticleEmitterDef, ) -> u32

Burst a set of world-space voxel sites as debris — the spawn half of carve_debris, factored out (DT.3) so a landed island’s voxels can shatter without a carve: one def-driven particle per site, positioned there, tinted with the site’s colour, kicked radially away from from at a speed from outward (a site at from itself scatters in a random direction).

Same contract as carve_debris (which is now this on top of a sphere sample+carve): def’s pos/shape/spawn/tint are ignored, tint_end lerps from the site colour, big sets are stride-sampled to the debris cap, the pool budget counts overflow in dropped_spawns. Returns how many debris actually spawned.