Struct DebrisSystem 

pub struct DebrisSystem {
    pub gravity: f64,
    pub terminal_speed: f64,
    pub max_yaw_rate: f32,
    pub solidity: Solidity,
    pub fracture_impulse: f64,
    /* private fields */
}

Host-owned falling-island simulation + facade binding. Construct once, Self::spawn_island per detected island, Self::tick per frame, Self::drain_impacts to shatter.

Fields

gravity: f64

Gravity in world units/s², +z is down. Matches the particle default so debris and dust fall together.

terminal_speed: f64

Terminal-speed clamp on the fall, world units/s.

max_yaw_rate: f32

Cosmetic spin cap, rad/s: each island gets a deterministic per-island rate in [-max, max] (hashed from its position — no RNG state, replays are bit-identical).

solidity: Solidity

What counts as solid ground (bedrock-placeholder policy) — the same knob box_overlaps_solid takes.

fracture_impulse: f64

DT.5 — outward drift a fracture fragment inherits, world units/s (directed from the parent island’s centre to the fragment’s; zero for unsplit islands).

Implementations

impl DebrisSystem

pub fn new() -> Self

A system with the stock tuning: particle-matched gravity, a generous terminal clamp, a barely-perceptible spin.

pub fn set_fracture_patterns( &mut self, colour_map: &[(Rgb, u8)], patterns: &[(u8, FracturePattern)], )

DT.5 — install the fracture side tables: colour_map is the host’s colour→material terrain map (also switches island models to material-mapped registration, so translucent / emissive voxels keep their look in flight), patterns maps material ids to FracturePatterns. An island splits per material group before falling: its rock breaks per the rock pattern, its crystal per the crystal pattern, each fragment its own body with a small outward Self::fracture_impulse. Empty tables (the default) keep every island Whole.

pub fn spawn_island( &mut self, scene: &mut Scene, grid: GridId, island: Island, bake: BakeMode, ) -> bool

Extract island from grid (via Island::extract — carve + bake_bbox; mips are the caller’s obligation, same as any edit), split it per the fracture tables (DT.5 — Self::set_fracture_patterns; no tables ⇒ one piece), and register each fragment as a falling body at the exact world pose of the voxels it replaced, with an outward drift for fragments of a split. Sprite models/instances appear on the next Self::sync. Returns false (and does nothing) for a missing grid or an empty island.

Spawn inside geometry (an L-shaped island whose bbox wraps a surviving support, a detach flush under a shelf): a fragment’s AABB already overlapping foreign solid cannot fall — it is queued as an immediate DebrisImpact at zero speed (the shatter replaces it in place) and never becomes a body. An explicit policy, not an accident of the contact search: the accepted degradation of AABB-only collision (decision 4).

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

Advance every body by dt seconds: semi-implicit Euler with the terminal clamp, cosmetic yaw, then the vertical collision march against scene. The frame’s displacement is walked in substeps of half the collision window (half.z + vws/2 — the thinnest thing a voxel scene can contain is one voxel), so a fast body cannot tunnel through a one-voxel shelf on a slow frame (vel·dt is unbounded: hosts pass real dt, hitches included). A blocked substep is binary-searched to flush contact; the body retires as a DebrisImpact. Pure simulation — no facade calls (see Self::sync).

A body whose horizontal drift carries it into a wall finds every vertical probe blocked: the contact search degenerates to its current position and it shatters mid-air against the wall — the same accepted mechanism as the spawn-inside-geometry policy on Self::spawn_island.

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

Mirror the simulation into the facade: retire handles of landed bodies, spawn a model + pre-posed instance for each newborn (no axis-aligned first-frame flash), and batch-move everything alive via one set_sprite_instance_transforms. The facade tombstones removed models — a host shattering many islands should call compact_sprite_models periodically.

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

One-shot per-frame step: Self::update then Self::sync.

pub fn drain_impacts(&mut self) -> Drain<'_, DebrisImpact>

Drain the impacts accumulated by Self::update — DT.3’s shatter consumes these (each carries its island’s voxels).

pub fn debris_count(&self) -> usize

Number of bodies currently falling.

Trait Implementations

impl Default for DebrisSystem

fn default() -> Self

Returns the “default value” for a type.