1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
//! Chunk data model, coordinate utilities, and persistence for the voxel world.
//!
//! ## Overview
//!
//! This module defines the core data structures that represent a piece of the
//! voxel world at rest. The runtime lifecycle (request, generate, mesh, render)
//! lives in [`crate::world`], [`crate::generator`], and [`crate::mesh`]. This
//! module is purely about *what a chunk is* and *where it lives in space*.
//!
//! ## The `Chunk<V>` data model
//!
//! A [`Chunk<V>`] is a 16×16×16 block of voxels stored in a single,
//! heap-allocated flat array of length [`CHUNK_VOLUME`] (4 096 elements).
//! Voxels are indexed in X-major order:
//!
//! ```text
//! flat_index = x * CHUNK_SIZE² + y * CHUNK_SIZE + z
//! ```
//!
//! This layout keeps a full Z-row of voxels contiguous in memory, which is
//! cache-friendly for the greedy meshing algorithm's inner loop. The array is
//! wrapped in a `Box` to keep the chunk's stack footprint to a single pointer
//! regardless of voxel size.
//!
//! Because [`Chunk<V>`] derives [`bevy::prelude::Component`], it can be
//! attached directly to a Bevy entity, making it queryable alongside
//! [`ChunkCoordComp`] and [`ChunkLod`] without any indirection.
//!
//! ## Coordinate systems
//!
//! The framework uses three distinct coordinate spaces:
//!
//! | Space | Type | Unit |
//! |-------|------|------|
//! | **World space** | `Vec3` | One unit = one voxel = [`VOXEL_SIZE`] meters |
//! | **Chunk space** | [`ChunkCoord`] (`IVec3`) | One unit = `CHUNK_SIZE` world units |
//! | **Local space** | `(usize, usize, usize)` | Voxel index within a chunk, each in `[0, CHUNK_SIZE)` |
//!
//! ### Conversion helpers
//!
//! | Function | Input → Output |
//! |----------|----------------|
//! | [`world_to_chunk_coord`] | `Vec3` → [`ChunkCoord`] |
//! | [`world_to_local_coord`] | `Vec3` → `(x, y, z)` local |
//! | [`chunk_origin`] | [`ChunkCoord`] → `Vec3` (min corner) |
//! | [`chunk_center`] | [`ChunkCoord`] → `Vec3` (center) |
//!
//! All conversions use Euclidean division, so negative world coordinates map
//! correctly to negative chunk coordinates without off-by-one errors.
//!
//! ## Constants
//!
//! | Constant | Value | Meaning |
//! |----------|-------|---------|
//! | [`CHUNK_SIZE`] | `16` | Voxels per axis |
//! | [`CHUNK_VOLUME`] | `4 096` | Total voxels per chunk |
//! | [`VOXEL_SIZE`] | `1.0` | World-space size of one voxel |
//!
//! ## Persistence
//!
//! Raw chunk data can be written to and read from disk via the
//! [`persistence`] sub-module, which serializes each voxel with
//! [`crate::voxel::VoxelType::to_byte`] / [`crate::voxel::VoxelType::from_byte`].
pub use ;
use *;
/// Number of voxels along each axis of a chunk.
///
/// A chunk is a cube with `CHUNK_SIZE` voxels per edge. The value `16` is
/// chosen to balance memory footprint (4 096 voxels per chunk), generation
/// granularity, and cache locality during meshing. Increasing this value
/// reduces chunk boundary overhead but raises per-chunk allocation size and
/// generation latency.
pub const CHUNK_SIZE: usize = 16;
/// Total number of voxels in a single chunk (`CHUNK_SIZE³ = 4 096`).
///
/// This is the length of the flat array inside every [`Chunk<V>`].
/// At one byte per voxel (the minimum for `DefaultVoxel`), a fully populated
/// chunk occupies 4 KiB of heap memory before any component overhead.
pub const CHUNK_VOLUME: usize = CHUNK_SIZE * CHUNK_SIZE * CHUNK_SIZE;
/// World-space size of a single voxel, in Bevy world units.
///
/// Currently `1.0`, meaning one voxel corresponds to one world unit. All
/// coordinate conversion functions in this module factor `VOXEL_SIZE` in so
/// that changing this constant is sufficient to rescale the entire world.
pub const VOXEL_SIZE: f32 = 1.0;
/// Integer coordinate identifying a chunk in the world grid.
///
/// `ChunkCoord` is a type alias for [`bevy::math::IVec3`]. Each component
/// is a signed integer where one unit equals `CHUNK_SIZE * VOXEL_SIZE`
/// world-space units. The minimum corner of the chunk in world space is:
///
/// ```text
/// chunk_origin = coord.as_vec3() * (CHUNK_SIZE as f32 * VOXEL_SIZE)
/// ```
///
/// Chunk `(0, 0, 0)` covers world positions `[0, 16)³`.
/// Chunk `(-1, 0, 0)` covers world positions `[-16, 0)` on the X axis.
///
/// Use [`world_to_chunk_coord`] to convert a world-space position to the
/// chunk that contains it, and [`chunk_origin`] / [`chunk_center`] to go
/// back the other way.
pub type ChunkCoord = IVec3;
/// Bevy [`Component`] that tags a chunk entity with its [`ChunkCoord`].
///
/// Every chunk entity receives this component when generation completes.
/// Having the coordinate on the entity lets systems query
/// `&ChunkCoordComp` directly — without going through
/// [`crate::world::ChunkManager`] — and avoids the lock contention that
/// would arise if all per-chunk logic had to look up coordinates in the
/// manager's `HashMap`.
///
/// The inner [`IVec3`] is the same value as the corresponding entry in
/// [`crate::world::ChunkManager`] and can be passed to any function
/// expecting a [`ChunkCoord`].
;
/// Bevy [`Component`] that stores the current Level of Detail for a chunk entity.
///
/// The LOD level controls the voxel sampling step used during greedy mesh
/// generation — a higher step skips more voxels, producing a lower-resolution
/// mesh that is cheaper to render.
///
/// | `ChunkLod` | Distance from viewer | Sampling step | Effective resolution |
/// |------------|---------------------|---------------|----------------------|
/// | `0` | < 200 units | 1 (every voxel) | Full 16³ |
/// | `1` | >= 200 units | 2 (every 2nd) | Effective 8³ |
///
/// The value is updated every frame by `lod_update_system` based on the
/// distance between the chunk center and [`crate::world::systems::ViewerPosition`].
/// When the level changes, a [`crate::world::ChunkModified`] event is emitted
/// so that [`crate::mesh::MeshPlugin`] regenerates the geometry at the new
/// detail level on the next frame.
///
/// `Default` produces `ChunkLod(0)` (full detail).
;
// ─── Coordinate utilities ─────────────────────────────────────────────────────
/// Converts a world-space position to the [`ChunkCoord`] of the chunk that contains it.
///
/// Each chunk spans `CHUNK_SIZE * VOXEL_SIZE` (`16.0`) world units per axis.
/// Euclidean division is used so that negative positions round toward negative
/// infinity and map to the correct chunk rather than toward zero.
///
/// # Examples
///
/// ```rust,no_run
/// use bevy::math::Vec3;
/// use voxel_framework::chunk::world_to_chunk_coord;
///
/// // Origin is in chunk (0, 0, 0).
/// assert_eq!(world_to_chunk_coord(Vec3::ZERO), bevy::math::IVec3::ZERO);
///
/// // Position (16.0, 0.0, 0.0) is the first voxel of chunk (1, 0, 0).
/// assert_eq!(world_to_chunk_coord(Vec3::new(16.0, 0.0, 0.0)).x, 1);
///
/// // Negative positions map to negative chunks.
/// assert_eq!(world_to_chunk_coord(Vec3::new(-1.0, 0.0, 0.0)).x, -1);
/// ```
/// Converts a world-space position to the local voxel coordinate within its chunk.
///
/// Returns `(x, y, z)` where each component is in `[0, CHUNK_SIZE)`.
/// The result can be passed directly to [`Chunk::get`] or [`Chunk::set`].
///
/// Use [`world_to_chunk_coord`] to find which chunk the position belongs to,
/// then this function to get the offset within that chunk.
///
/// # Examples
///
/// ```rust,no_run
/// use bevy::math::Vec3;
/// use voxel_framework::chunk::world_to_local_coord;
///
/// // Position (0.5, 0.5, 0.5) → local voxel (0, 0, 0).
/// assert_eq!(world_to_local_coord(Vec3::splat(0.5)), (0, 0, 0));
///
/// // Position (15.5, 0.0, 0.0) is in local voxel (15, 0, 0).
/// assert_eq!(world_to_local_coord(Vec3::new(15.5, 0.0, 0.0)).0, 15);
/// ```
/// Returns the world-space position of the minimum corner (origin) of a chunk.
///
/// The origin is the corner with the smallest X, Y, and Z values. It equals
/// `coord.as_vec3() * (CHUNK_SIZE as f32 * VOXEL_SIZE)`.
/// Returns the world-space position of the center of a chunk.
///
/// Equivalent to `chunk_origin(coord) + Vec3::splat(CHUNK_SIZE as f32 * VOXEL_SIZE * 0.5)`.
/// Used by the LOD and occlusion systems to measure the distance from a chunk
/// to the viewer or camera.
// ─── Tests ────────────────────────────────────────────────────────────────────