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
//! Procedural chunk generation trait, async pipeline, and Bevy plugin.
//!
//! # Architecture
//!
//! World generation is split across two systems that run every frame inside
//! [`GeneratorSystems`]:
//!
//! 1. **[`chunk_request_system`]** — receives [`crate::world::ChunkLoadRequest`]
//! messages. It first tries to restore the chunk from disk (when
//! [`crate::world::PersistenceConfig`] is present); on a cache miss it
//! clones the [`Arc`]-wrapped generator and offloads work to Bevy's
//! [`bevy::tasks::AsyncComputeTaskPool`], storing the returned [`Task`] as a
//! [`ChunkTask<V>`] component on a new entity.
//!
//! 2. **[`chunk_task_poll_system`]** — polls every in-flight [`ChunkTask<V>`]
//! with a single non-blocking `poll_once`. When a task resolves it removes
//! the task component, inserts the completed [`crate::chunk::Chunk<V>`], and
//! emits [`crate::world::ChunkModified`] so that the mesh system in
//! [`crate::mesh`] can build geometry on the same frame.
//!
//! # The `ChunkGenerator` contract
//!
//! Every implementation of [`ChunkGenerator<V>`] runs on a worker thread from
//! `AsyncComputeTaskPool`. It **must not** access the Bevy [`bevy::ecs::world::World`]
//! or any `Res<T>` — the generator `Arc` is the only shared state it may touch.
//! The trait bounds `Send + Sync + 'static` enforce this at compile time.
//!
//! # Wiring into a Bevy app
//!
//! ```rust,no_run
//! use std::sync::Arc;
//! use bevy::prelude::*;
//! use voxel_framework::{
//! generator::{GeneratorPlugin, GeneratorResource},
//! mesh::MeshPlugin,
//! voxel::DefaultVoxel,
//! VoxelPlugin,
//! };
//! use voxel_framework::generator::asteroid::{AsteroidConfig, AsteroidGenerator};
//!
//! App::new()
//! .add_plugins(DefaultPlugins)
//! .add_plugins(VoxelPlugin::<DefaultVoxel>::new())
//! .insert_resource(GeneratorResource::<DefaultVoxel> {
//! generator: Arc::new(AsteroidGenerator::new(AsteroidConfig::default())),
//! })
//! .add_plugins(GeneratorPlugin::<DefaultVoxel>::new())
//! .add_plugins(MeshPlugin::<DefaultVoxel>::new())
//! .run();
//! ```
//!
//! [`Arc`]: std::sync::Arc
//! [`Task`]: bevy::tasks::Task
pub use ;
pub use ;
use Arc;
use *;
use crateChunk;
use crateVoxelType;
/// System set label for the generator pipeline.
///
/// `chunk_mesh_system` uses `.after(GeneratorSystems)` to guarantee it reads
/// `ChunkModified` messages emitted in the same frame by `chunk_task_poll_system`.
;
/// Contract for procedural chunk generation strategies.
///
/// An implementation receives an empty [`Chunk<V>`] and a chunk-grid coordinate,
/// and fills the chunk with whatever voxel data the strategy produces. The
/// framework stores implementations behind an [`std::sync::Arc`] and calls
/// [`ChunkGenerator::generate`] on worker threads from Bevy's
/// [`bevy::tasks::AsyncComputeTaskPool`].
///
/// # Thread safety contract
///
/// `generate` is called from a **background thread** — never from the Bevy main
/// thread. Implementations **must not**:
///
/// - access any [`bevy::ecs::world::World`] data (queries, resources, etc.),
/// - hold non-`Send` types, or
/// - perform blocking I/O on the calling thread.
///
/// The `Send + Sync + 'static` bounds on the trait enforce these constraints at
/// compile time. Internal state may be freely read (shared references via
/// `Arc`), but must not be mutated without interior synchronization.
///
/// # Coordinate space
///
/// `coord` is in **chunk-grid space**: each axis unit corresponds to
/// `CHUNK_SIZE` world units. Convert to world space with
/// `coord.as_vec3() * CHUNK_SIZE as f32`.
///
/// # Examples
///
/// ```rust,no_run
/// use bevy::math::IVec3;
/// use voxel_framework::{
/// chunk::Chunk,
/// generator::ChunkGenerator,
/// voxel::DefaultVoxel,
/// };
///
/// struct FlatWorldGenerator {
/// ground_level: i32,
/// }
///
/// impl ChunkGenerator<DefaultVoxel> for FlatWorldGenerator {
/// fn generate(&self, coord: IVec3, chunk: &mut Chunk<DefaultVoxel>) {
/// // Fill voxels below ground_level with rock, leave the rest as air.
/// if coord.y < self.ground_level {
/// for x in 0..voxel_framework::chunk::CHUNK_SIZE {
/// for y in 0..voxel_framework::chunk::CHUNK_SIZE {
/// for z in 0..voxel_framework::chunk::CHUNK_SIZE {
/// chunk.set(x, y, z, DefaultVoxel::Rock);
/// }
/// }
/// }
/// }
/// }
/// }
/// ```
/// Bevy [`Resource`] that holds the active [`ChunkGenerator<V>`].
///
/// Insert this resource before adding [`GeneratorPlugin<V>`] to provide the
/// generation strategy. The inner [`std::sync::Arc`] is cloned cheaply into
/// each async task so that the generator is shared without blocking or copying.
///
/// ```rust,no_run
/// use std::sync::Arc;
/// use bevy::prelude::*;
/// use voxel_framework::{
/// generator::GeneratorResource,
/// voxel::DefaultVoxel,
/// };
/// use voxel_framework::generator::asteroid::{AsteroidConfig, AsteroidGenerator};
///
/// fn main() {
/// App::new()
/// .insert_resource(GeneratorResource::<DefaultVoxel> {
/// generator: Arc::new(AsteroidGenerator::new(AsteroidConfig::default())),
/// })
/// // ... add other plugins ...
/// .run();
/// }
/// ```
/// Bevy [`Plugin`] that registers the async chunk generation pipeline for
/// voxel type `V`.
///
/// Adds two systems to the [`Update`] schedule inside [`GeneratorSystems`],
/// chained so that poll results are available to downstream systems in the same
/// frame:
///
/// 1. [`chunk_request_system`] — converts [`crate::world::ChunkLoadRequest`]
/// messages into async tasks (or immediate disk loads).
/// 2. [`chunk_task_poll_system`] — harvests completed tasks and attaches
/// [`crate::chunk::Chunk<V>`] components.
///
/// [`GeneratorResource<V>`] must be inserted separately; the plugin does not
/// require it at registration time (the system accepts it as `Option<Res<_>>`).