Struct CharacterBody 

pub struct CharacterBody { /* private fields */ }

A walking body: feet-positioned collision box + velocity + contact flags. Construct with CharacterBody::new, place with teleport, then call walk once per frame.

Implementations

impl CharacterBody

pub fn new(def: CharacterDef) -> Self

A body at the world origin with zero velocity — call teleport before the first walk.

Examples found in repository

examples/book_controller.rs (lines 68-78)

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 mode(&self) -> MoveMode

Current movement mode.

pub fn set_mode(&mut self, mode: MoveMode)

Switch movement mode. Velocity is kept — dropping out of Fly mid-air falls with whatever speed you had.

Examples found in repository

examples/book_controller.rs (line 112)

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");
}

pub fn def(&self) -> &CharacterDef

The construction parameters.

Examples found in repository

examples/book_controller.rs (line 122)

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");
}

pub fn def_mut(&mut self) -> &mut CharacterDef

Tune parameters at runtime — sprint (walk_speed / fly_speed), variable jump height, etc. Growing radius / height while standing in a tight spot can leave the body overlapping solid; the stuck-escape rule makes that recoverable rather than a jam.

pub fn pos(&self) -> DVec3

Feet position, world space.

Examples found in repository

examples/book_controller.rs (line 102)

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");
}

pub fn eye_pos(&self) -> DVec3

Eye position — the camera anchor: eye_height above the feet, i.e. toward −z.

Examples found in repository

examples/book_controller.rs (line 95)

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");
}

pub fn vel(&self) -> DVec3

Current velocity, world units per second.

Examples found in repository

examples/book_controller.rs (line 114)

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");
}

pub fn set_vel(&mut self, vel: DVec3)

Overwrite the velocity — knockback, launch pads, spawn state.

pub fn on_ground(&self) -> bool

true while the feet rest on solid ground (skin probe below the feet, updated by walk).

Examples found in repository

examples/book_controller.rs (line 99)

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");
}

pub fn hit_head(&self) -> bool

true if the head hit a ceiling during the last walk.

pub fn is_swimming(&self) -> bool

WT.1 — true while the body is in the swim state (submerged past CharacterDef::swim_enter_frac, held until it falls below CharacterDef::swim_exit_frac). Updated by walk; always false in the fly modes.

Examples found in repository

examples/book_controller.rs (line 159)

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 submerged_fraction(&self, scene: &Scene) -> f64

WT.1 — fraction of the body height below a water surface, 0.0..=1.0: the Scene::water_depth_at point depth at the FEET over CharacterDef::height (exact for the world-horizontal surfaces water is authored with — PORTING-WATER.md decision 1: there is deliberately no box-overlap query). This is the BODY-STATE number (it drives the swim state) — do NOT wire underwater tint/audio to it: at the default bobbing equilibrium it reads 0.75 while the head (and camera) are in the air. Use Self::eye_in_water for those.

Continuity guard: feet just below an authored volume’s BOTTOM face (a pool volume that stops short of the floor) read as fully submerged while the head is still in water — without this, the fraction would snap 0.55+ → 0.0 mid-dive and strobe the swim state faster than hysteresis can absorb. (Author volumes down to the floor anyway.)

pub fn eye_in_water(&self, scene: &Scene) -> bool

WT.1 — true while the EYE (the camera anchor, Self::eye_pos) is under a water surface. THE hook for the underwater feel — WT.2 tint, WT.3 listener lowpass: it flips exactly when the player’s view goes under, unlike Self::submerged_fraction (feet-depth, 0.75 at the surface bob with a dry camera).

Examples found in repository

examples/book_controller.rs (line 160)

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 set_pos(&mut self, pos: DVec3)

Reposition the feet, KEEPING velocity and contact state — for world-bounds clamps and moving-platform style corrections. For spawns and respawns use teleport.

pub fn teleport(&mut self, pos: DVec3)

Hard-place the feet at pos, zeroing velocity and contact flags. No collision check — placing inside solid is allowed (the stuck-escape rule below makes it recoverable).

Examples found in repository

examples/book_controller.rs (line 79)

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 walk(&mut self, scene: &Scene, dt: f64, input: WalkInput)

Advance the body by dt seconds against scene. Behaviour follows the current MoveMode; everything below describes MoveMode::Walk.

Integration order: horizontal velocity approaches wish · walk_speed at the ground/air accel rate; gravity; jump if grounded; then the displacement is applied in substeps of at most radius per axis (the no-tunnel guarantee), each substep moving x, then y, then z, clamping flush against the blocking cell plane and zeroing that velocity component on contact — unless a grounded horizontal block steps up a ledge (CharacterDef::step_up). +z contact grounds the body; −z contact is a head bump.

Stuck escape (kept verbatim from the demos): if the body starts the frame overlapping solid — an edit carved under the player, a bake reclassified a column — the whole frame moves without collision so the player can escape rather than jam.

Examples found in repository

examples/book_controller.rs (line 93)

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
}

Trait Implementations

impl Clone for CharacterBody

fn clone(&self) -> CharacterBody

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for CharacterBody

impl Debug for CharacterBody

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

Formats the value using the given formatter.