Skip to main content

rayengine_voxel/
lib.rs

1#![doc = include_str!("../README.md")]
2
3pub use rayengine_core::glam;
4
5pub mod block;
6pub mod collision;
7pub mod coords;
8pub use collision::{
9    ColliderError, ColliderReport, MissingColliders, block_bounds, controller_bounds,
10};
11pub mod generation;
12pub use generation::{ChunkGenerator, GenerationContext, GeneratorInfo, generate_chunk};
13pub mod meshing;
14pub mod ray;
15#[cfg(feature = "render")]
16pub mod render;
17pub mod storage;
18pub mod streaming;
19pub use streaming::{
20    ChunkStreamer, Eviction, StreamConfig, StreamError, StreamFailure, StreamReport,
21};
22
23pub use meshing::{
24    ChunkMesh, FaceShading, MeshBatch, MeshDependencies, MeshInput, MeshLayer, MeshLimits,
25    MeshStats, MeshingError, MeshingMode, MeshingOptions, MissingFaces, SurfaceKey,
26};
27
28pub use block::{BlockDef, BlockId, BlockRegistry, CollisionKind, RenderKind, TileId};
29pub use coords::{BlockPos, CHUNK_SIZE, CHUNK_VOLUME, ChunkPos, Face, LocalPos};
30pub use ray::{GridRay, MissingPolicy, RayCell, Raycast, RaycastOptions, RaycastOutcome, VoxelHit};
31pub use storage::{BlockEdit, Chunk, ChunkInsertError, ChunkStamp, DirtyChunks, VoxelWorld};
32
33/// Rejected input, capacity exhaustion, or mutation admission failure.
34#[derive(Clone, Debug, PartialEq, Eq)]
35pub enum VoxelError {
36    /// Cooperative voxel generation was cancelled.
37    Cancelled,
38    /// Invalid block name, hardness, or other definition properties.
39    InvalidDefinition,
40    /// A block with the same name is already registered.
41    DuplicateName,
42    /// All 65,536 block IDs (including air) are in use.
43    RegistryFull,
44    /// The ID is absent from the chunk's registry.
45    UnknownBlock(BlockId),
46    /// A local coordinate is outside 0..16.
47    InvalidLocalPosition,
48    /// A chunk origin or extent is outside the i32 block grid.
49    InvalidChunkPosition,
50    /// Imported block data has a length other than 4096.
51    InvalidChunkLength,
52    /// Chunk and world must share the same registry allocation.
53    RegistryMismatch,
54    /// The configured resident chunk limit would be exceeded.
55    WorldFull,
56    /// An edit or metadata operation requires a resident chunk.
57    MissingChunk(ChunkPos),
58    /// An allocation could not be admitted.
59    Allocation,
60    /// A revision/generation would overflow; no state was changed.
61    RevisionExhausted,
62    /// Ray origin/direction is nonfinite, zero, loses a moving axis during
63    /// normalization, or starts outside the grid.
64    InvalidRay,
65    /// Distance must be finite/nonnegative and cell budget must be supported.
66    InvalidRayOptions,
67}
68impl std::fmt::Display for VoxelError {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        match self {
71            Self::Cancelled => f.write_str("voxel generation cancelled"),
72            Self::InvalidDefinition => f.write_str("block name or hardness is invalid"),
73            Self::DuplicateName => f.write_str("block name is already registered"),
74            Self::RegistryFull => f.write_str("block registry has exhausted its 16-bit IDs"),
75            Self::UnknownBlock(id) => write!(f, "unknown block ID {}", id.raw()),
76            Self::InvalidLocalPosition => {
77                f.write_str("local position must be in 0..16 on each axis")
78            }
79            Self::InvalidChunkPosition => f.write_str("chunk must fit inside the i32 block grid"),
80            Self::InvalidChunkLength => f.write_str("chunk data must have exactly 4096 cells"),
81            Self::RegistryMismatch => f.write_str("chunk and world must share the same registry"),
82            Self::WorldFull => f.write_str("resident chunk limit reached"),
83            Self::MissingChunk(pos) => write!(f, "chunk {pos:?} is not resident"),
84            Self::Allocation => f.write_str("voxel allocation failed"),
85            Self::RevisionExhausted => f.write_str("voxel revision or generation exhausted"),
86            Self::InvalidRay => f.write_str(
87                "ray must be finite, nonzero, preserve moving axes, and start inside the grid",
88            ),
89            Self::InvalidRayOptions => f.write_str("ray distance or cell budget is invalid"),
90        }
91    }
92}
93impl std::error::Error for VoxelError {}
94
95/// Common voxel imports; gameplay content and survival rules remain game-owned.
96pub mod prelude {
97    pub use crate::collision::{
98        ColliderError, ColliderReport, MissingColliders, block_bounds, controller_bounds,
99    };
100    pub use crate::generation::{ChunkGenerator, GenerationContext, GeneratorInfo, generate_chunk};
101    pub use crate::meshing::{
102        ChunkMesh, FaceShading, MeshBatch, MeshDependencies, MeshInput, MeshLayer, MeshLimits,
103        MeshStats, MeshingError, MeshingMode, MeshingOptions, MissingFaces, SurfaceKey,
104    };
105    #[cfg(feature = "render")]
106    pub use crate::render::{
107        ChunkDraw, RenderedChunk, StreamRenderConfig, StreamRenderReport, StreamRenderer,
108        StreamResources, TileTexture, VoxelMaterials,
109    };
110    pub use crate::streaming::{
111        ChunkStreamer, Eviction, StreamConfig, StreamError, StreamFailure, StreamReport,
112    };
113    pub use crate::{
114        BlockDef, BlockEdit, BlockId, BlockPos, BlockRegistry, CHUNK_SIZE, CHUNK_VOLUME, Chunk,
115        ChunkInsertError, ChunkPos, ChunkStamp, CollisionKind, DirtyChunks, Face, GridRay,
116        LocalPos, MissingPolicy, RayCell, Raycast, RaycastOptions, RaycastOutcome, RenderKind,
117        TileId, VoxelError, VoxelHit, VoxelWorld,
118    };
119}