book_controller/
book_controller.rs

1//! Companion example for the book's "The scene graph" chapter — the
2//! character-controller section pulls its snippets from here via
3//! `// ANCHOR:` markers, so everything it shows compiles and its
4//! assertions actually ran. Headless: no window, no renderer.
5//!
6//! ```sh
7//! cargo run -p roxlap-scene --example book_controller
8//! ```
9//!
10//! Keep the anchors when editing; `docs/book/check-anchors.sh` (run by
11//! the CI `book` job) goes red if one disappears.
12
13use glam::{DVec3, IVec3};
14use roxlap_scene::{
15    CharacterBody, CharacterDef, GridTransform, MoveMode, Scene, Solidity, VoxColor, WalkInput,
16};
17
18// ANCHOR: veto
19/// Colour veto for the collision probe: voxels this colour are
20/// passable (water, foliage, ladders); everything else blocks. A
21/// plain `fn`, keyed like a material map — compare `.rgb_part()`,
22/// the brightness byte belongs to the lighting bake.
23const WATER: VoxColor = VoxColor::rgb(0x30, 0x60, 0xc8);
24fn water_passes(c: VoxColor) -> bool {
25    c.rgb_part() == WATER.rgb_part()
26}
27// ANCHOR_END: veto
28
29fn build_world() -> Scene {
30    let mut scene = Scene::new();
31    let id = scene.add_grid(GridTransform::identity());
32    let g = scene.grid_mut(id).expect("grid");
33    // Ground slab: surface plane at z = 100 (+z is down, so the
34    // slab fills downward).
35    g.set_rect(
36        IVec3::new(20, 20, 100),
37        IVec3::new(140, 140, 120),
38        Some(VoxColor::rgb(0x4d, 0x8a, 0x3a)),
39    );
40    // A 1-voxel ledge to step onto, and a wall to slide along.
41    g.set_rect(
42        IVec3::new(90, 20, 99),
43        IVec3::new(140, 140, 99),
44        Some(VoxColor::rgb(0x77, 0x66, 0x55)),
45    );
46    g.set_rect(
47        IVec3::new(60, 70, 60),
48        IVec3::new(62, 140, 99),
49        Some(VoxColor::rgb(0x88, 0x44, 0x44)),
50    );
51    // A water curtain the veto lets the body wade through. Two
52    // format facts (both pinned as engine tests): pass-through
53    // geometry works up to 2 voxels thick — thicker walls grow a
54    // colourless UnexposedSolid core no veto can classify — and
55    // must sit ≥ 1 voxel inside the chunk (edge voxels lose their
56    // side colours).
57    g.set_rect(IVec3::new(40, 40, 80), IVec3::new(41, 60, 99), Some(WATER));
58    scene
59}
60
61fn main() {
62    let scene = build_world();
63
64    // ANCHOR: setup
65    // A walking body: a feet-positioned collision box, f64 world.
66    // Distances are voxels, times seconds; +z is DOWN, so gravity is
67    // positive and a jump impulse negative.
68    let mut body = CharacterBody::new(CharacterDef {
69        radius: 0.4,      // xy half-extent of the box
70        height: 1.8,      // feet → head (toward -z)
71        eye_height: 1.62, // feet → camera anchor
72        step_up: 1.05,    // auto-step ledges up to 1 voxel
73        solidity: Solidity {
74            bedrock_blocks: false, // match your renderer's policy
75            passable: Some(water_passes),
76        },
77        ..CharacterDef::default()
78    });
79    body.teleport(DVec3::new(50.0, 50.0, 95.0)); // FEET position
80                                                 // ANCHOR_END: setup
81
82    // ANCHOR: frame
83    // Per frame: build a wish direction from input (unit-length or
84    // zero — walk() clamps), call walk() EVERY frame (a zero wish is
85    // what stops the body), then anchor the camera at the eye.
86    let dt = 1.0 / 60.0;
87    for frame in 0..480 {
88        let input = WalkInput {
89            wish: DVec3::new(1.0, 0.2, 0.0), // toward the ledge
90            jump: frame == 120,              // one hop on the way
91        };
92        body.walk(&scene, dt, input);
93    }
94    let eye = body.eye_pos(); // = Camera::from_yaw_pitch(eye.into(), yaw, pitch)
95                              // ANCHOR_END: frame
96
97    // The trajectory the walk above promises, pinned:
98    assert!(body.on_ground(), "settled after the hop");
99    // It fell to the floor plane, then stepped up the 1-voxel ledge
100    // (surface z = 99) while walking +x.
101    assert!(body.pos().x > 90.0, "reached the ledge region");
102    assert!(
103        (body.pos().z - 99.0).abs() < 0.01,
104        "standing on the ledge, feet at {}",
105        body.pos().z
106    );
107    assert!(eye.z < body.pos().z, "the eye is above the feet (-z is up)");
108
109    // Fly mode is the demos' free camera: no gravity, full-3D wish,
110    // instant start/stop, still sliding along walls.
111    body.set_mode(MoveMode::Fly);
112    body.walk(&scene, dt, WalkInput::default());
113    assert_eq!(body.vel(), DVec3::ZERO, "fly idles in place");
114
115    // The water curtain from `build_world` is passable: probe the
116    // veto directly (the same query walk() uses).
117    let wading = roxlap_scene::box_overlaps_solid(
118        &scene,
119        DVec3::new(40.2, 50.0, 90.0),
120        DVec3::new(40.8, 50.6, 91.8),
121        body.def().solidity,
122    );
123    assert!(!wading, "water is passable under the veto");
124
125    println!("book_controller: all controller assertions hold");
126}
book_controller/book_controller.rs

book_controller/
book_controller.rs
