Struct GridTransform 

pub struct GridTransform {
    pub origin: DVec3,
    pub rotation: DQuat,
    pub voxel_world_size: f64,
}

f64 world placement of one grid: position + orientation.

origin is the grid’s local-space origin in world coords — a grid-local point p (in voxel units) maps to origin + rotation * (p * voxel_world_size).

SC — voxel_world_size is the grid’s world units per voxel (1.0 = the classic 1:1). A coarse planet grid might use 4.0 (big voxels) and a finely detailed ship 0.25, so they coexist at the right relative sizes in one scene. The scale enters ONLY at the world↔grid-local boundary (crate::world_to_grid_local / crate::grid_local_to_world, Scene::raycast, shadows); the per-grid voxel storage, marchers and bakes are scale-agnostic. Only a uniform scalar is supported (anisotropic scale would break the ray-length invariant the raycast/shadow t conversion relies on).

Fields

origin: DVec3

The grid’s local-space origin, in world coordinates.

rotation: DQuat

The grid’s orientation about origin.

voxel_world_size: f64

SC — world units per voxel (1.0 = 1:1). See the type docs. #[serde(skip)]: this field is NOT part of GridTransform’s wire form (which stays frozen for snapshot back-compat). The snapshot persists it as a trailing field on crate::snapshot::GridSnapshot instead, so old saves — which predate it — still load (defaulting to 1.0). A standalone GridTransform deserialize also defaults it to 1.0.

Implementations

impl GridTransform

pub fn identity() -> Self

Identity transform at world origin, 1 world unit per voxel. Useful as a default for the first grid added to an otherwise empty scene.

Examples found in repository

examples/book_controller.rs (line 31)

fn build_world() -> Scene {
    let mut scene = Scene::new();
    let id = scene.add_grid(GridTransform::identity());
    let g = scene.grid_mut(id).expect("grid");
    // Ground slab: surface plane at z = 100 (+z is down, so the
    // slab fills downward).
    g.set_rect(
        IVec3::new(20, 20, 100),
        IVec3::new(140, 140, 120),
        Some(VoxColor::rgb(0x4d, 0x8a, 0x3a)),
    );
    // A 1-voxel ledge to step onto, and a wall to slide along.
    g.set_rect(
        IVec3::new(90, 20, 99),
        IVec3::new(140, 140, 99),
        Some(VoxColor::rgb(0x77, 0x66, 0x55)),
    );
    g.set_rect(
        IVec3::new(60, 70, 60),
        IVec3::new(62, 140, 99),
        Some(VoxColor::rgb(0x88, 0x44, 0x44)),
    );
    // A water curtain the veto lets the body wade through. Two
    // format facts (both pinned as engine tests): pass-through
    // geometry works up to 2 voxels thick — thicker walls grow a
    // colourless UnexposedSolid core no veto can classify — and
    // must sit ≥ 1 voxel inside the chunk (edge voxels lose their
    // side colours).
    g.set_rect(IVec3::new(40, 40, 80), IVec3::new(41, 60, 99), Some(WATER));
    scene
}

fn main() {
    let scene = build_world();

    // ANCHOR: setup
    // A walking body: a feet-positioned collision box, f64 world.
    // Distances are voxels, times seconds; +z is DOWN, so gravity is
    // positive and a jump impulse negative.
    let mut body = CharacterBody::new(CharacterDef {
        radius: 0.4,      // xy half-extent of the box
        height: 1.8,      // feet → head (toward -z)
        eye_height: 1.62, // feet → camera anchor
        step_up: 1.05,    // auto-step ledges up to 1 voxel
        solidity: Solidity {
            bedrock_blocks: false, // match your renderer's policy
            passable: Some(water_passes),
        },
        ..CharacterDef::default()
    });
    body.teleport(DVec3::new(50.0, 50.0, 95.0)); // FEET position
                                                 // ANCHOR_END: setup

    // ANCHOR: frame
    // Per frame: build a wish direction from input (unit-length or
    // zero — walk() clamps), call walk() EVERY frame (a zero wish is
    // what stops the body), then anchor the camera at the eye.
    let dt = 1.0 / 60.0;
    for frame in 0..480 {
        let input = WalkInput {
            wish: DVec3::new(1.0, 0.2, 0.0), // toward the ledge
            jump: frame == 120,              // one hop on the way
            ..WalkInput::default()           // sink (WT.1) + future fields
        };
        body.walk(&scene, dt, input);
    }
    let eye = body.eye_pos(); // = Camera::from_yaw_pitch(eye.into(), yaw, pitch)
                              // ANCHOR_END: frame

    // The trajectory the walk above promises, pinned:
    assert!(body.on_ground(), "settled after the hop");
    // It fell to the floor plane, then stepped up the 1-voxel ledge
    // (surface z = 99) while walking +x.
    assert!(body.pos().x > 90.0, "reached the ledge region");
    assert!(
        (body.pos().z - 99.0).abs() < 0.01,
        "standing on the ledge, feet at {}",
        body.pos().z
    );
    assert!(eye.z < body.pos().z, "the eye is above the feet (-z is up)");

    // Fly mode is the demos' free camera: no gravity, full-3D wish,
    // instant start/stop, still sliding along walls.
    body.set_mode(MoveMode::Fly);
    body.walk(&scene, dt, WalkInput::default());
    assert_eq!(body.vel(), DVec3::ZERO, "fly idles in place");

    // The water curtain from `build_world` is passable: probe the
    // veto directly (the same query walk() uses).
    let wading = roxlap_scene::box_overlaps_solid(
        &scene,
        DVec3::new(40.2, 50.0, 90.0),
        DVec3::new(40.8, 50.6, 91.8),
        body.def().solidity,
    );
    assert!(!wading, "water is passable under the veto");

    swim_demo();

    println!("book_controller: all controller assertions hold");
}

/// WT — the water + swimming section's snippets: a deep pool the body
/// falls into, floats in, dives through and breaches out of.
fn swim_demo() {
    // ANCHOR: water
    // Physics water is a WaterVolume on the grid — a grid-local voxel
    // AABB whose TOP face (min z — +z is down) is the surface. It is
    // independent of the voxels: fill the same region with a
    // volumetric-material shell for the visuals, or don't.
    let mut scene = Scene::new();
    let id = scene.add_grid(GridTransform::identity());
    let g = scene.grid_mut(id).expect("grid");
    // Basin floor, then 20 voxels of water above it (surface z = 100).
    g.set_rect(
        IVec3::new(20, 20, 120),
        IVec3::new(140, 140, 130),
        Some(VoxColor::rgb(0x50, 0x90, 0x50)),
    );
    g.add_water_volume(IVec3::new(20, 20, 100), IVec3::new(140, 140, 119));

    // A Walk-mode body dropped in swims AUTOMATICALLY once submerged
    // past `swim_enter_frac` of its height: buoyancy floats it to a
    // bob at the surface, `jump` strokes up, `sink` strokes down, and
    // a jump with the head above water breaches.
    let mut body = CharacterBody::new(CharacterDef::default());
    body.teleport(DVec3::new(80.0, 80.0, 115.0)); // deep in the pool
    for _ in 0..600 {
        body.walk(&scene, 1.0 / 60.0, WalkInput::default());
    }
    assert!(body.is_swimming(), "floated to the surface bob");
    assert!(!body.eye_in_water(&scene), "bobbing: the camera is dry");

    // Dive: hold `sink`. The submerged EYE is the hook for the
    // underwater feel — drive the WT.2 frame tint and the WT.3
    // listener lowpass from this one flag.
    for _ in 0..90 {
        body.walk(
            &scene,
            1.0 / 60.0,
            WalkInput {
                sink: true,
                ..WalkInput::default()
            },
        );
    }
    assert!(body.eye_in_water(&scene), "diving: tint + muffle now");
    // ANCHOR_END: water
}

pub fn at(origin: DVec3) -> Self

Axis-aligned grid placed at origin with no rotation, 1 world unit per voxel.

Examples found in repository

examples/book_scene_graph.rs (line 87)

fn main() {
    // ANCHOR: scene_grids
    let mut scene = Scene::new();
    // A static "world" grid at the origin…
    let ground_id = scene.add_grid(GridTransform::at(DVec3::ZERO));
    // …and a second grid placed and rotated independently — its own
    // f64 world position + quaternion, same chunked voxel payload.
    let ship_id = scene.add_grid(GridTransform {
        origin: DVec3::new(300.0, -80.0, -40.0),
        rotation: DQuat::from_rotation_z(0.5),
        voxel_world_size: 1.0,
    });
    // Object grids should not paint their own (grid-local, rotating)
    // sky — leave the sky to the world grid.
    scene.grid_mut(ship_id).expect("just added").render_sky = false;
    // ANCHOR_END: scene_grids

    // ANCHOR: edits
    let ground = scene.grid_mut(ground_id).expect("just added");
    // Solid slab: grid-local voxel coords, inclusive on both ends,
    // decomposed across as many chunks as it spans (here 4×4).
    ground.set_rect(
        IVec3::new(-200, -200, 200),
        IVec3::new(199, 199, 254),
        Some(GRASS),
    );
    // `Some(colour)` inserts, `None` carves back to air.
    ground.set_sphere(IVec3::new(0, 0, 195), 12, Some(STONE));
    ground.set_rect(IVec3::new(-3, -200, 190), IVec3::new(3, 199, 196), None);
    // ANCHOR_END: edits

    // ANCHOR: queries
    // Solid tests: inside the slab, then inside the carved tunnel.
    assert!(ground.voxel_solid(IVec3::new(0, 0, 210)));
    assert!(!ground.voxel_solid(IVec3::new(0, 100, 193)));
    // Colour queries answer on surface voxels; deep interior cells
    // are untextured in the slab format and read as `None`.
    assert_eq!(ground.voxel_color(IVec3::new(50, 50, 200)), Some(GRASS));
    // ANCHOR_END: queries

    // ANCHOR: recolour
    // GOTCHA: inserting over already-solid voxels does NOT repaint
    // them — span insertion only fills air. Recolour = carve, then
    // insert.
    let (lo, hi) = (IVec3::new(20, 20, 200), IVec3::new(24, 24, 204));
    ground.set_rect(lo, hi, Some(RED));
    assert_eq!(ground.voxel_color(IVec3::new(22, 22, 200)), Some(GRASS)); // unchanged!
    ground.set_rect(lo, hi, None); // carve…
    ground.set_rect(lo, hi, Some(RED)); // …then insert
    assert_eq!(ground.voxel_color(IVec3::new(22, 22, 200)), Some(RED));
    // ANCHOR_END: recolour

    // ANCHOR: colfunc
    // A carve exposes fresh interior walls; the plain edits paint
    // them colour 0 (black). The `_with_colfunc` variants ask a
    // closure instead — it sees grid-local coordinates, so gradients
    // stay continuous across chunk seams. Here: a crater whose walls
    // darken with depth.
    ground.set_sphere_with_colfunc(IVec3::new(60, 60, 200), 8, SpanOp::Carve, |_x, _y, z| {
        let depth = (z - 192).clamp(0, 15) as u8;
        VoxColor::rgb(0x6b, 0x40 + depth * 3, 0x2f)
    });
    // ANCHOR_END: colfunc

    // ANCHOR: snapshot
    // Name grids before saving: ids survive the round-trip, but the
    // generator / store hooks are host code and cannot be serialised
    // — the name is your key for rebinding them after a load.
    scene.grid_mut(ground_id).expect("ground exists").name = Some("ground".into());
    let bytes = scene.save_snapshot(); // versioned envelope
    let restored = Scene::load_snapshot(&bytes).expect("self-authored snapshot");
    assert_eq!(restored.grid_count(), 2);
    let (_, ground2) = restored
        .grids()
        .find(|(_, g)| g.name.as_deref() == Some("ground"))
        .expect("rebind by name");
    assert_eq!(ground2.voxel_color(IVec3::new(22, 22, 200)), Some(RED));
    // ANCHOR_END: snapshot

    // ANCHOR: streaming
    // Streaming: attach a generator + radii to a grid, then pump once
    // per frame with the camera's world position. Chunks within
    // `r_active` stream in; chunks beyond `r_evict` drop out; the band
    // between is hysteresis so a camera hovering on a boundary
    // doesn't thrash.
    let stream_id = scene.add_grid(GridTransform::at(DVec3::new(0.0, 4096.0, 0.0)));
    let store = Arc::new(MemoryStore::default());
    let grid = scene.grid_mut(stream_id).expect("just added");
    grid.set_generator(Some(Arc::new(FloorGenerator)));
    grid.set_chunk_store(Some(store));
    grid.stream_radius = StreamRadius::new(256.0, 384.0);

    let camera_near = DVec3::new(0.0, 4096.0, 100.0);
    scene.pump_streaming_sync(camera_near); // real games: `pump_streaming`
    let grid = scene.grid(stream_id).expect("still there");
    assert!(grid.chunk_count() > 0); // floor streamed in around the camera
    assert!(grid.voxel_solid(IVec3::new(5, 5, 240)));
    // ANCHOR_END: streaming

    // ANCHOR: streaming_edit
    // Edit the streamed floor, walk far away, come back. The active
    // set follows the camera: the old region evicts (edited chunks
    // are handed to the ChunkStore first) while a fresh set streams
    // in around the new position. On return the store wins over the
    // generator, so the edit survives; without a store, eviction
    // would silently revert the chunk to generator output.
    scene
        .grid_mut(stream_id)
        .expect("still there")
        .set_voxel(IVec3::new(5, 5, 240), None); // dig a hole
    scene.pump_streaming_sync(camera_near + DVec3::new(0.0, 100_000.0, 0.0));
    let grid = scene.grid(stream_id).expect("still there");
    assert!(grid.chunk(IVec3::ZERO).is_none()); // home chunk evicted…
    assert!(grid.chunk_count() > 0); // …but the far region streamed in
    scene.pump_streaming_sync(camera_near);
    let grid = scene.grid(stream_id).expect("re-streamed");
    // The hole survived evict + re-stream.
    assert!(!grid.voxel_solid(IVec3::new(5, 5, 240)));
    // ANCHOR_END: streaming_edit

    // ANCHOR: grid_scale
    // Per-grid scale: `voxel_world_size` is world units per voxel. A grid
    // built with `at_scale(origin, 2.0)` has voxels twice world size — a
    // coarse "planet" — while `0.25` gives a fine detail grid; both coexist
    // at their true relative sizes. Only the world↔grid boundary scales:
    // edits + queries stay in voxels, unchanged.
    let mut scaled = Scene::new();
    let planet = scaled.add_grid(GridTransform::at_scale(DVec3::ZERO, 2.0));
    scaled
        .grid_mut(planet)
        .expect("just added")
        // Same voxel edit API — grid-local coordinates.
        .set_voxel(IVec3::new(5, 5, 10), Some(STONE));
    // Grid-local voxel z=10 sits at WORLD z = 20 (10 voxels × 2.0). A world
    // raycast down that column reports the grid-local voxel it hit AND a
    // WORLD-space `t` — so hits across grids of different scale compare
    // correctly (the raycaster marches voxels but returns world distance).
    let hit = scaled
        .raycast(DVec3::new(11.0, 11.0, 0.0), DVec3::new(0.0, 0.0, 1.0), 64.0)
        .expect("ray hits the scaled voxel");
    assert_eq!(hit.voxel, IVec3::new(5, 5, 10)); // grid-local, unscaled
    assert!((hit.t - 20.0).abs() < 1e-4); // WORLD distance: 10 voxels × 2.0
                                          // ANCHOR_END: grid_scale

    println!("book_scene_graph: all scene-graph assertions hold");
}

pub fn at_scale(origin: DVec3, voxel_world_size: f64) -> Self

SC — axis-aligned grid at origin with voxel_world_size world units per voxel (no rotation). 1.0 = the classic 1:1.

voxel_world_size must be finite and > 0: it scales every world↔grid boundary, and a 0 collapses the GPU marcher’s chunk_dim to zero → floor(origin / 0) = NaN (garbage geometry), worse than the CPU’s divide. Debug-asserted here; release builds trust the caller.

Examples found in repository

examples/book_scene_graph.rs (line 210)

fn main() {
    // ANCHOR: scene_grids
    let mut scene = Scene::new();
    // A static "world" grid at the origin…
    let ground_id = scene.add_grid(GridTransform::at(DVec3::ZERO));
    // …and a second grid placed and rotated independently — its own
    // f64 world position + quaternion, same chunked voxel payload.
    let ship_id = scene.add_grid(GridTransform {
        origin: DVec3::new(300.0, -80.0, -40.0),
        rotation: DQuat::from_rotation_z(0.5),
        voxel_world_size: 1.0,
    });
    // Object grids should not paint their own (grid-local, rotating)
    // sky — leave the sky to the world grid.
    scene.grid_mut(ship_id).expect("just added").render_sky = false;
    // ANCHOR_END: scene_grids

    // ANCHOR: edits
    let ground = scene.grid_mut(ground_id).expect("just added");
    // Solid slab: grid-local voxel coords, inclusive on both ends,
    // decomposed across as many chunks as it spans (here 4×4).
    ground.set_rect(
        IVec3::new(-200, -200, 200),
        IVec3::new(199, 199, 254),
        Some(GRASS),
    );
    // `Some(colour)` inserts, `None` carves back to air.
    ground.set_sphere(IVec3::new(0, 0, 195), 12, Some(STONE));
    ground.set_rect(IVec3::new(-3, -200, 190), IVec3::new(3, 199, 196), None);
    // ANCHOR_END: edits

    // ANCHOR: queries
    // Solid tests: inside the slab, then inside the carved tunnel.
    assert!(ground.voxel_solid(IVec3::new(0, 0, 210)));
    assert!(!ground.voxel_solid(IVec3::new(0, 100, 193)));
    // Colour queries answer on surface voxels; deep interior cells
    // are untextured in the slab format and read as `None`.
    assert_eq!(ground.voxel_color(IVec3::new(50, 50, 200)), Some(GRASS));
    // ANCHOR_END: queries

    // ANCHOR: recolour
    // GOTCHA: inserting over already-solid voxels does NOT repaint
    // them — span insertion only fills air. Recolour = carve, then
    // insert.
    let (lo, hi) = (IVec3::new(20, 20, 200), IVec3::new(24, 24, 204));
    ground.set_rect(lo, hi, Some(RED));
    assert_eq!(ground.voxel_color(IVec3::new(22, 22, 200)), Some(GRASS)); // unchanged!
    ground.set_rect(lo, hi, None); // carve…
    ground.set_rect(lo, hi, Some(RED)); // …then insert
    assert_eq!(ground.voxel_color(IVec3::new(22, 22, 200)), Some(RED));
    // ANCHOR_END: recolour

    // ANCHOR: colfunc
    // A carve exposes fresh interior walls; the plain edits paint
    // them colour 0 (black). The `_with_colfunc` variants ask a
    // closure instead — it sees grid-local coordinates, so gradients
    // stay continuous across chunk seams. Here: a crater whose walls
    // darken with depth.
    ground.set_sphere_with_colfunc(IVec3::new(60, 60, 200), 8, SpanOp::Carve, |_x, _y, z| {
        let depth = (z - 192).clamp(0, 15) as u8;
        VoxColor::rgb(0x6b, 0x40 + depth * 3, 0x2f)
    });
    // ANCHOR_END: colfunc

    // ANCHOR: snapshot
    // Name grids before saving: ids survive the round-trip, but the
    // generator / store hooks are host code and cannot be serialised
    // — the name is your key for rebinding them after a load.
    scene.grid_mut(ground_id).expect("ground exists").name = Some("ground".into());
    let bytes = scene.save_snapshot(); // versioned envelope
    let restored = Scene::load_snapshot(&bytes).expect("self-authored snapshot");
    assert_eq!(restored.grid_count(), 2);
    let (_, ground2) = restored
        .grids()
        .find(|(_, g)| g.name.as_deref() == Some("ground"))
        .expect("rebind by name");
    assert_eq!(ground2.voxel_color(IVec3::new(22, 22, 200)), Some(RED));
    // ANCHOR_END: snapshot

    // ANCHOR: streaming
    // Streaming: attach a generator + radii to a grid, then pump once
    // per frame with the camera's world position. Chunks within
    // `r_active` stream in; chunks beyond `r_evict` drop out; the band
    // between is hysteresis so a camera hovering on a boundary
    // doesn't thrash.
    let stream_id = scene.add_grid(GridTransform::at(DVec3::new(0.0, 4096.0, 0.0)));
    let store = Arc::new(MemoryStore::default());
    let grid = scene.grid_mut(stream_id).expect("just added");
    grid.set_generator(Some(Arc::new(FloorGenerator)));
    grid.set_chunk_store(Some(store));
    grid.stream_radius = StreamRadius::new(256.0, 384.0);

    let camera_near = DVec3::new(0.0, 4096.0, 100.0);
    scene.pump_streaming_sync(camera_near); // real games: `pump_streaming`
    let grid = scene.grid(stream_id).expect("still there");
    assert!(grid.chunk_count() > 0); // floor streamed in around the camera
    assert!(grid.voxel_solid(IVec3::new(5, 5, 240)));
    // ANCHOR_END: streaming

    // ANCHOR: streaming_edit
    // Edit the streamed floor, walk far away, come back. The active
    // set follows the camera: the old region evicts (edited chunks
    // are handed to the ChunkStore first) while a fresh set streams
    // in around the new position. On return the store wins over the
    // generator, so the edit survives; without a store, eviction
    // would silently revert the chunk to generator output.
    scene
        .grid_mut(stream_id)
        .expect("still there")
        .set_voxel(IVec3::new(5, 5, 240), None); // dig a hole
    scene.pump_streaming_sync(camera_near + DVec3::new(0.0, 100_000.0, 0.0));
    let grid = scene.grid(stream_id).expect("still there");
    assert!(grid.chunk(IVec3::ZERO).is_none()); // home chunk evicted…
    assert!(grid.chunk_count() > 0); // …but the far region streamed in
    scene.pump_streaming_sync(camera_near);
    let grid = scene.grid(stream_id).expect("re-streamed");
    // The hole survived evict + re-stream.
    assert!(!grid.voxel_solid(IVec3::new(5, 5, 240)));
    // ANCHOR_END: streaming_edit

    // ANCHOR: grid_scale
    // Per-grid scale: `voxel_world_size` is world units per voxel. A grid
    // built with `at_scale(origin, 2.0)` has voxels twice world size — a
    // coarse "planet" — while `0.25` gives a fine detail grid; both coexist
    // at their true relative sizes. Only the world↔grid boundary scales:
    // edits + queries stay in voxels, unchanged.
    let mut scaled = Scene::new();
    let planet = scaled.add_grid(GridTransform::at_scale(DVec3::ZERO, 2.0));
    scaled
        .grid_mut(planet)
        .expect("just added")
        // Same voxel edit API — grid-local coordinates.
        .set_voxel(IVec3::new(5, 5, 10), Some(STONE));
    // Grid-local voxel z=10 sits at WORLD z = 20 (10 voxels × 2.0). A world
    // raycast down that column reports the grid-local voxel it hit AND a
    // WORLD-space `t` — so hits across grids of different scale compare
    // correctly (the raycaster marches voxels but returns world distance).
    let hit = scaled
        .raycast(DVec3::new(11.0, 11.0, 0.0), DVec3::new(0.0, 0.0, 1.0), 64.0)
        .expect("ray hits the scaled voxel");
    assert_eq!(hit.voxel, IVec3::new(5, 5, 10)); // grid-local, unscaled
    assert!((hit.t - 20.0).abs() < 1e-4); // WORLD distance: 10 voxels × 2.0
                                          // ANCHOR_END: grid_scale

    println!("book_scene_graph: all scene-graph assertions hold");
}

Trait Implementations

impl Clone for GridTransform

fn clone(&self) -> GridTransform

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for GridTransform

impl Debug for GridTransform

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GridTransform

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for GridTransform

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for GridTransform

fn eq(&self, other: &GridTransform) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for GridTransform

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for GridTransform