Struct Scene 

pub struct Scene { /* private fields */ }

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

S2.0 only exposes registration / removal / lookup. Address math helpers (S2.x), edit API (S2.x), and rendering composition (S3) land in later sub-substages.

Implementations

impl Scene

pub fn to_snapshot(&self) -> SceneSnapshot

Capture the scene’s full state as a serde-friendly value. Each chunk is encoded via roxlap_formats::vxl::serialize; the rest is plain field data.

Grid iteration order in the produced snapshot is sorted by GridId so two snapshots of the same scene produce byte-identical output (the live HashMap iteration order would be non-deterministic).

pub fn from_snapshot(snap: &SceneSnapshot) -> Result<Self, FromSnapshotError>

Restore a Scene from a snapshot. Each chunk’s bytes are re-parsed via roxlap_formats::vxl::parse and re-armed for edits via roxlap_formats::vxl::Vxl::reserve_edit_capacity.

Errors

Returns FromSnapshotError::ChunkParse tagged with the owning grid + chunk index if any chunk’s bytes fail to parse. The partial scene is dropped — restoration is all-or-nothing.

impl Scene

pub fn new() -> Self

New empty scene — no grids.

pub fn grid_count(&self) -> usize

Number of grids currently registered.

pub fn add_grid(&mut self, transform: GridTransform) -> GridId

Register a new grid. Returns its fresh, unique GridId.

pub fn remove_grid(&mut self, id: GridId) -> Option<Grid>

Remove a grid by id. Returns the removed Grid (so the caller can reclaim its chunks) or None if the id wasn’t registered. Removed ids are not reissued.

pub fn grid(&self, id: GridId) -> Option<&Grid>

Borrow a registered grid.

pub fn grid_mut(&mut self, id: GridId) -> Option<&mut Grid>

Mutably borrow a registered grid.

pub fn grids(&self) -> impl Iterator<Item = (GridId, &Grid)>

Iterator over all (id, grid) pairs in registration order is not guaranteed — the underlying map is a HashMap. Callers that need a stable order must sort by GridId.

pub fn grids_mut(&mut self) -> impl Iterator<Item = (GridId, &mut Grid)>

Mutable iterator over all (id, grid) pairs. Yield order is not guaranteed (HashMap-backed).

pub fn resolve_voxel( &self, world: DVec3, ray_dir: DVec3, ) -> Option<(GridId, IVec3)>

Resolve a world-space surface hit to the owning grid + its grid-local voxel — the picking back half. ray_dir is the view direction the hit was found along (need not be normalised); the point is nudged half a voxel along it, past the surface and into the solid cell, before each grid’s Grid::voxel_solid test. Returns the first grid that is solid there (transform-correct for rotated/translated grids), or None if none claims it.

Backend-agnostic: pair with a renderer depth read to turn a click into a voxel — world = cam.pos + t · normalize(ray_dir), then resolve_voxel(world, ray_dir). roxlap-render’s SceneRenderer::pick wires exactly that.

pub fn raycast( &self, origin: DVec3, dir: DVec3, max_dist: f64, ) -> Option<RayHit>

Cast a world-space ray and return the nearest solid voxel hit across all grids, or None if nothing solid lies within max_dist. Renderer-independent (no depth buffer, no camera) — the primitive for line-of-sight, projectiles, AI probing, and off-screen / backend-agnostic picking.

dir need not be normalised. Each grid’s ray is transformed into the grid’s local frame (so rotated / translated grids are handled exactly) and marched with a voxel DDA against Grid::voxel_solid; the closest hit by world distance t wins. The step budget is bounded by max_dist, so empty space is safe but not free — a chunk-level skip is a future optimisation if hot.

pub fn set_streaming_threads(&mut self, n: usize)

Configure the number of worker threads in the dedicated streaming pool (S7.3).

Lazily applied — the pool itself is constructed on the first Self::pump_streaming call. If the pool was already built (i.e. a previous pump_streaming already dispatched at least one task), it gets dropped and rebuilt. Dropping the old pool blocks until all of its in-flight tasks finish (rayon’s contract); any results those tasks sent are still drained by the next pump_streaming because the channel survives the rebuild.

The streaming pool is separate from rayon’s global pool (which R12 multicore rendering uses), so chunk generation doesn’t compete with render threads. Sensible values are 1 to ~4 — generation work is CPU-bound but should leave most of the box for everything else.

On wasm32 this is a no-op (no rayon pool available); pump_streaming runs synchronously there.

Panics

Panics on native if n == 0 (zero-thread pools are not supported; the scene crate’s S7.1 helper already disallows the equivalent for StreamRadius::r_active < 0).

pub fn pump_streaming(&mut self, camera_world_pos: DVec3)

Asynchronous streaming pump (S7.3).

On native, dispatches missing-chunk generations onto a dedicated rayon pool, drains any results that arrived since the last pump, runs the eviction pass, and tracks in-flight tasks in each grid’s Grid::pending_gen set. The drain uses the per-chunk version counter from S7.2 to discard results whose chunk was edited mid-generation.

On wasm32 this short-circuits to Self::pump_streaming_sync — no thread pool is available there, but the same per-grid stream-in / evict semantics apply.

Call once per frame from the render thread. Cheap when nothing changed (early-exit on disabled grids, try_recv loops empty fast).

pub fn pump_streaming_sync(&mut self, camera_world_pos: DVec3)

Synchronous streaming pump (S7.1).

For each grid with a non-StreamRadius::DISABLED policy:

1. Project the world-space camera into grid-local coords (inverse rotation + origin subtract).
2. Stream in any chunk whose AABB-to-camera distance is <= r_active, calling Grid::ensure_chunk_generated. No-ops gracefully if the grid has no generator attached (so callers can use the eviction half of streaming on a purely-edited grid).
3. Evict any chunk whose AABB-to-camera distance exceeds r_evict from the grid’s chunk map. Eviction also clears the cached BillboardCache (the bounding sphere may shrink, invalidating impostor projections; the next Far-tier render rebuilds lazily).

Both passes use the f64 grid-local position so rotation + non-axis-aligned grids stream and evict correctly. The generate path is blocking — S7.3 will move it to a background rayon pool with pump_streaming (non-blocking). Callers that want the async variant in S7.0/S7.1 stages should keep r_active small.

Trait Implementations

impl Debug for Scene

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

Formats the value using the given formatter.

impl Default for Scene

fn default() -> Scene

Returns the “default value” for a type.