Skip to main content

rayengine_voxel/
streaming.rs

1//! Bounded CPU streaming. The game keeps ownership of the world and save policy.
2use crate::{
3    BlockRegistry, Chunk, ChunkMesh, ChunkPos, ChunkStamp, MeshDependencies, MeshInput,
4    MeshingError, MeshingOptions, VoxelError, VoxelWorld,
5};
6use rayengine_core::jobs::{Cancellation, JobHandle, JobOutcome, JobPool, JobPoolError};
7use std::{
8    collections::{HashMap, VecDeque},
9    fmt,
10    sync::Arc,
11    time::{Duration, Instant},
12};
13
14/// Bounds for a cubic X/Z focus region with independent vertical extent.
15#[derive(Clone, Copy, Debug)]
16pub struct StreamConfig {
17    /// Horizontal radius in chunks; `(2*r+1)^2 * (2*y+1)` must fit max_resident.
18    pub radius: u32,
19    /// Vertical radius in chunks.
20    pub vertical_radius: u32,
21    /// Upper bound on the supplied world's capacity, including dirty pinned chunks.
22    pub max_resident: usize,
23    /// Fixed worker count; generation must cooperate with cancellation.
24    pub workers: usize,
25    /// Queued, running and unconsumed CPU jobs combined.
26    pub max_jobs: usize,
27    /// Mesh jobs, ready results and externally held results combined.
28    pub max_meshes: usize,
29    /// Retained vertex/index byte allowance per mesh; meshing limits must fit it.
30    /// Metadata and temporary quad/snapshot buffers are bounded separately by job count.
31    pub mesh_bytes: usize,
32    /// Immutable geometry policy, including missing-neighbor behavior.
33    pub meshing: MeshingOptions,
34}
35impl Default for StreamConfig {
36    fn default() -> Self {
37        Self {
38            radius: 2,
39            vertical_radius: 0,
40            max_resident: 32,
41            workers: 2,
42            max_jobs: 4,
43            max_meshes: 4,
44            mesh_bytes: 4 * 1024 * 1024,
45            meshing: MeshingOptions::default(),
46        }
47    }
48}
49/// Persistence decision for an out-of-range dirty chunk. Clean chunks evict directly.
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub enum Eviction {
52    /// Retain data and apply backpressure. Also use for an in-progress/failed save.
53    Keep,
54    /// The exact supplied stamp has been durably saved (or is reproducible terrain
55    /// explicitly exempted by the game's policy). Acknowledges it before removal.
56    Saved,
57}
58/// Invalid settings, incompatible world, or worker creation failure.
59#[derive(Debug)]
60pub enum StreamError {
61    /// Invalid region, geometry limits, or nonpositive/overflowing bounds.
62    Config,
63    /// Invalid focus coordinate.
64    Position(VoxelError),
65    /// World capacity exceeds the bound or a streamer was reused with another world.
66    World,
67    /// CPU worker creation failed.
68    Jobs(JobPoolError),
69    /// The bounded focus buffer could not be allocated.
70    Allocation,
71}
72impl fmt::Display for StreamError {
73    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
74        match self {
75            Self::Config => f.write_str("invalid chunk streaming limits"),
76            Self::Position(e) => e.fmt(f),
77            Self::World => f.write_str("incompatible streaming world"),
78            Self::Jobs(e) => e.fmt(f),
79            Self::Allocation => f.write_str("chunk focus allocation failed"),
80        }
81    }
82}
83impl std::error::Error for StreamError {}
84/// A failed request is paused until its dependencies change or retry is called.
85#[derive(Clone, Debug, PartialEq, Eq)]
86pub enum StreamFailure {
87    /// Game loader or storage admission rejected data.
88    Load(VoxelError),
89    /// Mesh generation or retained-byte admission failed.
90    Mesh(MeshingError),
91    /// The worker panicked; other jobs remain operational.
92    Panicked,
93    /// The render consumer rejected an otherwise completed result.
94    Upload,
95}
96/// Per-tick counters plus current bounded queue sizes. Timing includes callbacks.
97#[derive(Clone, Copy, Debug, Default)]
98pub struct StreamReport {
99    /// Wanted chunks in nearest-first order.
100    pub desired: usize,
101    /// Resident world chunks, including pinned dirty chunks.
102    pub resident: usize,
103    /// Queued/running/unconsumed jobs, including cancelled work not yet drained.
104    pub jobs: usize,
105    /// Completed meshes waiting to be taken.
106    pub ready: usize,
107    /// Mesh slots used by jobs, ready results and render consumers together.
108    pub mesh_slots: usize,
109    /// Actual retained ready vertex/index capacities (worker/consumer bytes excluded).
110    pub ready_bytes: usize,
111    /// Chunks admitted this tick.
112    pub loaded: usize,
113    /// Chunks removed after clean/saved admission.
114    pub evicted: usize,
115    /// Out-of-range dirty chunks whose save was deferred.
116    pub pinned: usize,
117    /// Cancelled/stale completions or ready meshes discarded this tick.
118    pub discarded: usize,
119    /// New paused failures this tick.
120    pub failed: usize,
121    /// Submitted CPU requests this tick.
122    pub submitted: usize,
123    /// Tick wall time, including save callback work.
124    pub elapsed: Duration,
125}
126type Loader = dyn Fn(ChunkPos, Arc<BlockRegistry>, Cancellation) -> Result<Chunk, VoxelError>
127    + Send
128    + Sync
129    + 'static;
130// The bounded pool holds only max_jobs entries; keeping results inline avoids
131// a separate allocation for every completed mesh.
132#[allow(clippy::large_enum_variant)]
133enum Output {
134    Load(Result<Chunk, VoxelError>),
135    Mesh(Result<ChunkMesh, MeshingError>),
136}
137struct Active {
138    position: ChunkPos,
139    handle: JobHandle,
140    dependencies: Option<MeshDependencies>,
141}
142struct Failure {
143    reason: StreamFailure,
144    dependencies: Option<MeshDependencies>,
145}
146
147/// CPU scheduler using the core bounded job pool. No native resources or implicit saves.
148///
149/// The world stays game-owned, including after shutdown/Drop. A loader must bound its
150/// own scratch/I/O and check Cancellation during lengthy work. Loaded chunks retain
151/// their dirty status: explicitly mark reproducible fresh terrain saved if desired.
152/// Mesh inputs are 11,664 cell bytes each; output is capped by mesh_bytes and geometry
153/// limits; temporary quads are bounded by max_quads. Metadata/allocator overhead is
154/// additional. Cancelled jobs occupy slots until their completions are drained.
155pub struct ChunkStreamer {
156    config: StreamConfig,
157    loader: Arc<Loader>,
158    pool: JobPool<Output>,
159    identity: Option<Arc<()>>,
160    desired: Vec<ChunkPos>,
161    focus: Option<ChunkPos>,
162    evictions: Vec<ChunkPos>,
163    active: Vec<Active>,
164    ready: VecDeque<ChunkMesh>,
165    held: HashMap<ChunkPos, MeshDependencies>,
166    installed: HashMap<ChunkPos, MeshDependencies>,
167    failures: HashMap<ChunkPos, Failure>,
168    stopped: bool,
169}
170impl ChunkStreamer {
171    /// Starts fixed workers. No world loads occur until tick is called.
172    pub fn new(
173        config: StreamConfig,
174        loader: impl Fn(ChunkPos, Arc<BlockRegistry>, Cancellation) -> Result<Chunk, VoxelError>
175        + Send
176        + Sync
177        + 'static,
178    ) -> Result<Self, StreamError> {
179        let width = usize::try_from(config.radius)
180            .ok()
181            .and_then(|r| r.checked_mul(2))
182            .and_then(|r| r.checked_add(1))
183            .ok_or(StreamError::Config)?;
184        let height = usize::try_from(config.vertical_radius)
185            .ok()
186            .and_then(|r| r.checked_mul(2))
187            .and_then(|r| r.checked_add(1))
188            .ok_or(StreamError::Config)?;
189        let count = width
190            .checked_mul(width)
191            .and_then(|v| v.checked_mul(height))
192            .ok_or(StreamError::Config)?;
193        let limits = config.meshing.limits;
194        if count > config.max_resident
195            || config.workers == 0
196            || config.max_jobs == 0
197            || config.max_meshes == 0
198            || config.radius > i32::MAX as u32
199            || config.vertical_radius > i32::MAX as u32
200            || !(1..=crate::meshing::MAX_CHUNK_FACES).contains(&limits.max_quads)
201            || !(1..=crate::meshing::MAX_CHUNK_FACES).contains(&limits.max_batches)
202            || !(4..=65532).contains(&limits.max_vertices_per_batch)
203            || !limits.max_vertices_per_batch.is_multiple_of(4)
204            || config.mesh_bytes < limits.max_quads * 156
205            || config.mesh_bytes.checked_mul(config.max_meshes).is_none()
206        {
207            return Err(StreamError::Config);
208        }
209        let mut desired = Vec::new();
210        desired
211            .try_reserve_exact(count)
212            .map_err(|_| StreamError::Allocation)?;
213        let pool = JobPool::new(config.workers, config.max_jobs).map_err(StreamError::Jobs)?;
214        Ok(Self {
215            config,
216            loader: Arc::new(loader),
217            pool,
218            identity: None,
219            desired,
220            focus: None,
221            evictions: Vec::new(),
222            active: Vec::new(),
223            ready: VecDeque::new(),
224            held: HashMap::new(),
225            installed: HashMap::new(),
226            failures: HashMap::new(),
227            stopped: false,
228        })
229    }
230    /// Current configured bounds.
231    pub fn config(&self) -> StreamConfig {
232        self.config
233    }
234    /// Current region, nearest first, deterministic ties ordered X/Y/Z.
235    pub fn desired(&self) -> &[ChunkPos] {
236        &self.desired
237    }
238    /// Whether a position belongs to the current focus region.
239    pub fn wants(&self, position: ChunkPos) -> bool {
240        !self.stopped && self.desired.contains(&position)
241    }
242    /// Paused failure for this position. The game can inspect before retrying.
243    pub fn failure(&self, position: ChunkPos) -> Option<&StreamFailure> {
244        self.failures.get(&position).map(|f| &f.reason)
245    }
246    /// Explicit retry after external repair, such as adding a missing material.
247    pub fn retry(&mut self, position: ChunkPos) {
248        self.failures.remove(&position);
249    }
250    fn mesh_slots(&self) -> usize {
251        self.active
252            .iter()
253            .filter(|a| a.dependencies.is_some())
254            .count()
255            + self.ready.len()
256            + self.held.len()
257    }
258    /// Moves one ready result to a consumer. Its mesh slot stays reserved until
259    /// finish_mesh; the consumer must eventually acknowledge success or rejection.
260    /// Rechecks receipts and chooses the nearest ready chunk at the current focus.
261    pub fn take_mesh(&mut self, world: &VoxelWorld) -> Option<ChunkMesh> {
262        self.ready.retain(|m| {
263            self.desired.contains(&m.dependencies().position())
264                && m.dependencies().is_current(world)
265        });
266        let index = self
267            .ready
268            .iter()
269            .enumerate()
270            .min_by_key(|(_, m)| {
271                self.desired
272                    .iter()
273                    .position(|p| *p == m.dependencies().position())
274                    .unwrap()
275            })
276            .map(|(i, _)| i)?;
277        let mesh = self.ready.remove(index)?;
278        self.held
279            .insert(mesh.dependencies().position(), mesh.dependencies().clone());
280        Some(mesh)
281    }
282    /// Releases a consumer's reservation. Success records the installed receipt;
283    /// failure pauses this revision, so persistent upload errors do not spin.
284    /// Old acknowledgements cannot overwrite a newer held request, including
285    /// retries with unchanged owner/neighbor stamps.
286    pub fn finish_mesh(&mut self, dependencies: &MeshDependencies, installed: bool) -> bool {
287        let position = dependencies.position();
288        if !self
289            .held
290            .get(&position)
291            .is_some_and(|d| d.same(dependencies))
292        {
293            return false;
294        }
295        self.held.remove(&position);
296        if !self.wants(position) {
297            return true;
298        }
299        if installed {
300            self.installed.insert(position, dependencies.clone());
301        } else {
302            self.failures.insert(
303                position,
304                Failure {
305                    reason: StreamFailure::Upload,
306                    dependencies: Some(dependencies.clone()),
307                },
308            );
309        }
310        true
311    }
312    /// Invalidates an installed receipt, e.g. after explicit renderer teardown.
313    pub fn forget_mesh(&mut self, position: ChunkPos) {
314        self.installed.remove(&position);
315    }
316    /// Updates focus, requests saves/evictions, drains results, then submits nearest
317    /// missing loads or stale meshes. Edits through VoxelWorld are detected without
318    /// notifications; all six neighbors participate, including missing neighbors.
319    /// Save callback runs only for out-of-range dirty chunks, on the caller thread.
320    pub fn tick(
321        &mut self,
322        world: &mut VoxelWorld,
323        focus: ChunkPos,
324        mut eviction: impl FnMut(ChunkPos, &Chunk, ChunkStamp) -> Eviction,
325    ) -> Result<StreamReport, StreamError> {
326        let start = Instant::now();
327        focus.origin().map_err(StreamError::Position)?;
328        if world.capacity() > self.config.max_resident
329            || self
330                .identity
331                .as_ref()
332                .is_some_and(|id| !Arc::ptr_eq(id, &world.identity))
333        {
334            return Err(StreamError::World);
335        }
336        self.identity.get_or_insert_with(|| world.identity.clone());
337        if self.focus != Some(focus) {
338            self.desired.clear();
339            let r = i64::from(self.config.radius);
340            let v = i64::from(self.config.vertical_radius);
341            for y in -v..=v {
342                for z in -r..=r {
343                    for x in -r..=r {
344                        let (Ok(x), Ok(y), Ok(z)) = (
345                            i32::try_from(i64::from(focus.x) + x),
346                            i32::try_from(i64::from(focus.y) + y),
347                            i32::try_from(i64::from(focus.z) + z),
348                        ) else {
349                            continue;
350                        };
351                        let position = ChunkPos::new(x, y, z);
352                        if position.origin().is_ok() {
353                            self.desired.push(position);
354                        }
355                    }
356                }
357            }
358            self.desired.sort_unstable_by_key(|p| {
359                let dx = i64::from(p.x) - i64::from(focus.x);
360                let dy = i64::from(p.y) - i64::from(focus.y);
361                let dz = i64::from(p.z) - i64::from(focus.z);
362                (dx * dx + dy * dy + dz * dz, p.x, p.y, p.z)
363            });
364            self.focus = Some(focus);
365        }
366        let mut report = StreamReport::default();
367        self.evictions.clear();
368        self.evictions.extend(
369            world
370                .chunks()
371                .map(|(p, _)| p)
372                .filter(|p| !self.desired.contains(p)),
373        );
374        for &p in &self.evictions {
375            let (chunk, stamp) = world.chunk_with_stamp(p).unwrap();
376            if chunk.is_dirty() {
377                if eviction(p, chunk, stamp) == Eviction::Keep {
378                    report.pinned += 1;
379                    continue;
380                }
381                world.mark_saved(p, stamp);
382            }
383            world.remove_chunk(p);
384            report.evicted += 1;
385        }
386        self.installed
387            .retain(|p, _| self.desired.contains(p) && world.chunk(*p).is_some());
388        self.failures.retain(|p, f| {
389            self.desired.contains(p)
390                && match &f.dependencies {
391                    Some(d) => d.is_current(world),
392                    None => world.chunk(*p).is_none(),
393                }
394        });
395        let before = self.ready.len();
396        self.ready.retain(|m| {
397            self.desired.contains(&m.dependencies().position())
398                && m.dependencies().is_current(world)
399        });
400        report.discarded += before - self.ready.len();
401        for active in &self.active {
402            if !self.desired.contains(&active.position)
403                || match &active.dependencies {
404                    Some(d) => !d.is_current(world),
405                    None => world.chunk(active.position).is_some(),
406                }
407            {
408                active.handle.cancel();
409            }
410        }
411        while let Some(completion) = self.pool.try_recv() {
412            let index = self
413                .active
414                .iter()
415                .position(|a| a.handle.id() == completion.id)
416                .unwrap();
417            let active = self.active.swap_remove(index);
418            let p = active.position;
419            let failure = match completion.outcome {
420                JobOutcome::Cancelled => {
421                    report.discarded += 1;
422                    continue;
423                }
424                JobOutcome::Panicked => Some(StreamFailure::Panicked),
425                JobOutcome::Ready(Output::Load(result)) => match result {
426                    Ok(chunk) => {
427                        if !self.wants(p) || world.chunk(p).is_some() {
428                            report.discarded += 1;
429                            continue;
430                        }
431                        match world.insert_chunk(p, chunk) {
432                            Ok(_) => {
433                                report.loaded += 1;
434                                None
435                            }
436                            Err(e) => Some(StreamFailure::Load(e.error)),
437                        }
438                    }
439                    Err(e) => Some(StreamFailure::Load(e)),
440                },
441                JobOutcome::Ready(Output::Mesh(result)) => {
442                    if !self.wants(p) || !active.dependencies.as_ref().unwrap().is_current(world) {
443                        report.discarded += 1;
444                        continue;
445                    }
446                    match result {
447                        Ok(mesh) if mesh.retained_bytes() <= self.config.mesh_bytes => {
448                            self.ready.push_back(mesh);
449                            None
450                        }
451                        Ok(_) => Some(StreamFailure::Mesh(MeshingError::LimitExceeded)),
452                        Err(e) => Some(StreamFailure::Mesh(e)),
453                    }
454                }
455            };
456            if let Some(reason) = failure {
457                self.failures.insert(
458                    p,
459                    Failure {
460                        reason,
461                        dependencies: active.dependencies,
462                    },
463                );
464                report.failed += 1;
465            }
466        }
467        if !self.stopped {
468            for &p in &self.desired {
469                if self.active.len() == self.config.max_jobs {
470                    break;
471                }
472                if self.failures.contains_key(&p)
473                    || self.active.iter().any(|a| a.position == p)
474                    || self.held.contains_key(&p)
475                    || self.ready.iter().any(|m| m.dependencies().position() == p)
476                {
477                    continue;
478                }
479                if world.chunk(p).is_none() {
480                    let loads = self
481                        .active
482                        .iter()
483                        .filter(|a| a.dependencies.is_none())
484                        .count();
485                    if world.len() + loads >= world.capacity() {
486                        continue;
487                    }
488                    let loader = self.loader.clone();
489                    let registry = world.shared_registry();
490                    if let Ok(handle) = self
491                        .pool
492                        .try_submit(move |cancel| Output::Load(loader(p, registry, cancel)))
493                    {
494                        self.active.push(Active {
495                            position: p,
496                            handle,
497                            dependencies: None,
498                        });
499                        report.submitted += 1;
500                    }
501                } else if self.mesh_slots() < self.config.max_meshes
502                    && !self.installed.get(&p).is_some_and(|d| d.is_current(world))
503                {
504                    match MeshInput::capture(world, p) {
505                        Ok(input) => {
506                            let dependencies = Some(input.dependencies().clone());
507                            let options = self.config.meshing;
508                            if let Ok(handle) = self.pool.try_submit(move |cancel| {
509                                Output::Mesh(
510                                    input.build_cancellable(options, || cancel.is_cancelled()),
511                                )
512                            }) {
513                                self.active.push(Active {
514                                    position: p,
515                                    handle,
516                                    dependencies,
517                                });
518                                report.submitted += 1;
519                            }
520                        }
521                        Err(e) => {
522                            // Capture errors are transient admission errors, reported for this tick.
523                            let _ = e;
524                            report.failed += 1;
525                        }
526                    }
527                }
528            }
529        }
530        report.desired = self.desired.len();
531        report.resident = world.len();
532        report.jobs = self.active.len();
533        report.ready = self.ready.len();
534        report.mesh_slots = self.mesh_slots();
535        report.ready_bytes = self.ready.iter().map(ChunkMesh::retained_bytes).sum();
536        report.elapsed = start.elapsed();
537        Ok(report)
538    }
539    /// Cancels and joins CPU work, drops ready results/reservations, and disables
540    /// submissions. Idempotent. World data is untouched; unload renderer separately.
541    pub fn shutdown(&mut self) {
542        self.pool.shutdown();
543        self.active.clear();
544        self.ready.clear();
545        self.held.clear();
546        self.installed.clear();
547        self.failures.clear();
548        self.stopped = true;
549    }
550}
551
552#[cfg(test)]
553mod tests;