Crate roxlap_scene

Expand description

roxlap scene-graph layer — many independent chunked voxel grids in a single 3D scene.

New to roxlap? The roxlap book is the guide — its scene-graph chapter walks this crate end to end; this page is the API reference.

This crate is the layer above the per-chunk renderer (roxlap-core): a Scene holds a sparse set of Grids, each with its own f64 world position + arbitrary 3D rotation (GridTransform). Around that core sit:

addr — world ↔ grid-local ↔ chunk + voxel-in-chunk decomposition, the canonical f64↔i32 boundary helpers;
chunks — sparse chunk storage with on-demand materialisation, plus the Grid edit API (Grid::set_voxel, Grid::set_rect, Grid::set_sphere, …) which decomposes multi-chunk operations and delegates to roxlap_formats::edit;
render — multi-grid raycast composition for the CPU renderer;
snapshot — save/load: the versioned wire format (Scene::save_snapshot / Scene::load_snapshot, QE.5b) plus the underlying serde-friendly snapshot::SceneSnapshot value (chunks encode via roxlap_formats::vxl::serialize / parse);
streaming — chunk streaming + procedural generation (streaming::ChunkGenerator, radius-driven install/evict, async generation on a rayon pool) and persistence for edited chunks (streaming::ChunkStore, QE.5a);
lod / billboard / occluder — far-LOD billboards and render culling helpers;
world queries — Scene::raycast, Scene::resolve_voxel, Grid::voxel_solid / Grid::voxel_color.

docs/porting/PORTING-SCENE.md in the repository records the original substage roadmap (S1..S7, all landed).

Re-exports§

pub use addr::grid_local_to_world;
pub use addr::voxel_global;
pub use addr::voxel_split;
pub use addr::world_to_grid_local;
pub use addr::GridLocalPos;
pub use billboard::canonical_viewpoints;
pub use billboard::BillboardCache;
pub use billboard::BillboardSnapshot;
pub use character::CharacterBody;
pub use character::CharacterDef;
pub use character::MoveMode;
pub use character::WalkInput;
pub use chunks::BakeLight;
pub use chunks::BakeMode;
pub use collide::box_overlaps_solid;
pub use collide::grid_box_overlaps_solid;
pub use collide::point_overlaps_solid;
pub use collide::Solidity;
pub use islands::detect_islands;
pub use islands::FracturePattern;
pub use islands::Island;
pub use islands::DEFAULT_ISLAND_BUDGET;
pub use lod::select_lod;
pub use lod::Lod;
pub use lod::LodThresholds;
pub use streaming::ChunkGenerator;
pub use streaming::ChunkStore;
pub use streaming::StreamRadius;
pub use water::WaterVolume;

Modules§

addr: Address math for the world ↔ grid-local ↔ chunk + voxel coordinate spaces.
billboard: Billboard impostor cache — S6.2 of PORTING-SCENE.md § S6.
cavegen: Adapter wrapping roxlap-cavegen’s Generator presets as a crate::ChunkGenerator (S7.5).
character: Character controller (stage CC) — a walking body over the scene; see docs/porting/PORTING-CONTROLLER.md. Character controller (stage CC.1 — see docs/porting/PORTING-CONTROLLER.md).
chunks: Sparse chunk storage helpers.
collide: Collision query layer (stage CC) — box-vs-voxel overlap over a scene; see docs/porting/PORTING-CONTROLLER.md. Collision query layer (stage CC.0 — see docs/porting/PORTING-CONTROLLER.md).
edit: Multi-chunk edit API on Grid.
islands: DT.0 — floating-island detection, the destruction stage’s core (see docs/porting/PORTING-DESTRUCTION.md).
lod: Per-grid LOD tier selection — S6.0 of PORTING-SCENE.md § S6.
occluder: XS.1 — a world-space scene occlusion oracle for cross-grid (and, in XS.2, cross-sprite) hard shadows.
render: Scene-level rendering — drives roxlap_core::opticast::opticast across the grids of a Scene.
snapshot: Serde-friendly snapshot of a Scene.
streaming: Streaming + procedural-generation hooks.
water: Water volumes (stage WT) — the physics representation of water; see docs/porting/PORTING-WATER.md. WT.0 — water volumes (PORTING-WATER.md): the physics representation of water.

Structs§

AoParams: AO.2 — tunable ambient-occlusion bake parameters (the lightmode == 3 knobs). Default matches the AO.0/AO.1 constants.
Grid: One independent voxel grid in a scene. Holds its world placement and a sparse map of populated chunks. Empty chunk slots are implicit air and skipped during rendering / raycasts.
GridAddr: Address of one voxel inside a scene: which grid it belongs to, which chunk within that grid, and the voxel’s offset inside that chunk.
GridId: Stable identifier for a grid registered in a Scene. Issued by Scene::add_grid; persists across edits but a removed grid’s id is not reissued.
GridTransform: f64 world placement of one grid: position + orientation.
OverlayColor: An overlay colour with real alpha: 0xAA_RR_GG_BB (0xFF = opaque). Used by the overlay-line API (Line3) — the one place in the engine where the high byte genuinely is opacity.
RayHit: A solid-voxel hit from Scene::raycast.
Rgb: A plain 0x00_RR_GG_BB colour: sprite/actor/particle tints, the sky / fog / clear colours, and the colour keys of colour→material maps. No packing surprises — the high byte is unused and must stay zero.
Scene: Top-level scene container. Holds a flat collection of grids keyed by GridId.
VoxColor: A voxel colour in voxlap’s packing: RGB in the low 24 bits, the baked brightness/AO byte on top — 0x80 is neutral (“unlit”), and lighting bakes rewrite it per voxel. NOT alpha: translucency is a material property (see the material palette), never a colour channel.

Enums§

DirtyExtent: PF.12 — how much of a chunk changed since a consumer last synced it.
SpanOp: Re-export of roxlap_formats::edit::SpanOp so scene callers can name the add-vs-carve flag without depending on roxlap-formats directly. Used by Grid::set_sphere_with_colfunc / Grid::set_rect_with_colfunc. Operation for span-style edits.

Constants§

CHUNK_SIZE_XY: XY size of one chunk in voxels. The plan locks 128 — keeps chunks compact (~2 MB worst-case dense-slab footprint inside each Vxl) and divides cleanly into voxlap’s 2048 reference world size.
CHUNK_SIZE_Z: Z size of one chunk in voxels. Locked at 256 to preserve voxlap’s existing slab byte format unchanged inside each chunk — the per-chunk renderer doesn’t need to know it’s living inside a scene-graph.