Crate roxlap_scene 

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

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 lod::select_lod;

pub use lod::Lod;

pub use lod::LodThresholds;

pub use streaming::ChunkGenerator;

pub use streaming::ChunkStore;

pub use streaming::StreamRadius;

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).

chunks

Sparse chunk storage helpers.

edit

Multi-chunk edit API on Grid.

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.

Structs

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.

RayHit

A solid-voxel hit from Scene::raycast.

Scene

Top-level scene container. Holds a flat collection of grids keyed by GridId.

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.