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
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
//! Initial world loading lifecycle — progress tracking and the ready signal.
//!
//! # Overview
//!
//! When a world first starts, the streaming system begins requesting chunks
//! around the viewer. This module tracks how many of those chunks have been
//! fully generated and meshed, and fires a one-shot signal when the world is
//! ready to display.
//!
//! # What "loaded" means
//!
//! A chunk is considered **loaded** when it is registered in [`ChunkManager`]
//! via [`ChunkManager::register`] — meaning voxel data has been generated
//! **and** the renderable mesh entity has been spawned. The total number of
//! chunks expected in the initial load sphere is computed once from
//! `load_distance` using `count_chunks_in_sphere`.
//!
//! # Event flow
//!
//! ```text
//! WorldPlugin starts
//! │
//! ▼
//! loading_progress_system runs each frame (after GeneratorSystems)
//! │
//! ├─ emits LoadingProgress { loaded, total, progress } every frame
//! │
//! └─ when progress >= 1.0:
//! emits WorldReady (once)
//! sets WorldLoadingState::ready = true → system becomes a no-op
//! ```
//!
//! # Usage
//!
//! Add [`LoadingPlugin`] to your [`App`] alongside [`super::WorldPlugin`].
//! Subscribe to [`LoadingProgress`] to drive a loading screen, and to
//! [`WorldReady`] to transition out of it:
//!
//! ```rust,no_run
//! use bevy::prelude::*;
//! use voxel_framework::world::{WorldPlugin, LoadingPlugin, LoadingProgress, WorldReady};
//!
//! fn on_world_ready(mut reader: MessageReader<WorldReady>) {
//! for _ in reader.read() {
//! println!("world is ready!");
//! }
//! }
//!
//! App::new()
//! .add_plugins((WorldPlugin, LoadingPlugin))
//! .add_systems(Update, on_world_ready)
//! .run();
//! ```
use *;
use crate;
use crateGeneratorSystems;
use ChunkManager;
// ─── Messages ────────────────────────────────────────────────────────────────
/// Emitted every frame while the initial chunk sphere is still loading.
///
/// [`loading_progress_system`] writes this message once per frame from the
/// moment the world starts until [`WorldReady`] fires. Once [`WorldReady`] has
/// been emitted, this message is no longer written.
///
/// - `loaded` — number of chunks currently registered in [`ChunkManager`].
/// - `total` — expected chunk count for the full load sphere (computed once
/// from `load_distance` on the first frame).
/// - `progress` — `loaded / total`, clamped to `[0.0, 1.0]`.
///
/// # Example
///
/// ```rust,no_run
/// use bevy::prelude::*;
/// use voxel_framework::world::LoadingProgress;
///
/// fn show_progress(mut reader: MessageReader<LoadingProgress>) {
/// for msg in reader.read() {
/// println!("loading: {:.0}%", msg.progress * 100.0);
/// }
/// }
/// ```
/// One-shot signal emitted when the initial chunk sphere is fully loaded.
///
/// [`loading_progress_system`] emits this message exactly once, on the first
/// frame that [`LoadingProgress::progress`] reaches `1.0`. After it fires,
/// [`WorldLoadingState::ready`] is set to `true` and the progress system
/// becomes a no-op — no further [`LoadingProgress`] or `WorldReady` messages
/// are written.
///
/// Use this event to transition your app out of a loading screen, enable
/// gameplay input, or trigger any one-time "world is ready" logic.
///
/// # Example
///
/// ```rust,no_run
/// use bevy::prelude::*;
/// use voxel_framework::world::WorldReady;
///
/// fn on_world_ready(mut reader: MessageReader<WorldReady>) {
/// for _ in reader.read() {
/// println!("all chunks generated — entering gameplay");
/// }
/// }
///
/// # fn main() {
/// App::new()
/// .add_message::<WorldReady>()
/// .add_systems(Update, on_world_ready)
/// .run();
/// # }
/// ```
;
// ─── Resource ─────────────────────────────────────────────────────────────────
/// Internal resource that guards the one-shot [`WorldReady`] emission.
///
/// Inserted by [`LoadingPlugin`] via `init_resource`. [`loading_progress_system`]
/// reads and mutates this resource each frame:
///
/// - `expected` is computed once on the first frame from [`ChunkManager::load_distance`]
/// and cached here to avoid recomputing it every tick.
/// - `ready` is set to `true` after [`WorldReady`] fires, turning the system
/// into a no-op for the remainder of the session.
///
/// This resource is not intended to be mutated by user code. To check whether
/// the world has finished loading, subscribe to [`WorldReady`] instead.
// ─── Helpers (pure, testable) ─────────────────────────────────────────────────
/// Returns the number of chunk coords within a cubic grid of `[-r, r]^3` that
/// also fall inside the sphere of radius `r` (measured in chunk units).
pub
/// Computes the loading progress fraction given `loaded` and `expected` counts.
/// Returns 0.0 when `expected` is 0 to avoid division by zero.
pub
// ─── System ───────────────────────────────────────────────────────────────────
/// Tracks initial chunk loading and emits [`LoadingProgress`] and [`WorldReady`].
///
/// Scheduled in [`Update`], ordered after [`GeneratorSystems`] so that any
/// chunks completed in the current frame are already counted before progress
/// is computed.
///
/// On the first invocation, the expected chunk count is derived from
/// [`ChunkManager::load_distance`] and cached in [`WorldLoadingState::expected`].
/// Subsequent frames skip this computation and go straight to the progress
/// check.
///
/// Once [`WorldLoadingState::ready`] is `true` (set after [`WorldReady`]
/// fires), the system returns immediately without writing any messages.
// ─── Plugin ───────────────────────────────────────────────────────────────────
/// Plugin that tracks initial world loading and emits [`LoadingProgress`] and [`WorldReady`].
///
/// Registers the following on the Bevy [`App`]:
///
/// - [`WorldLoadingState`] resource (via `init_resource`).
/// - [`LoadingProgress`] and [`WorldReady`] messages.
/// - [`loading_progress_system`] scheduled in [`Update`] after [`GeneratorSystems`].
///
/// Must be used together with [`super::WorldPlugin`], which provides the
/// [`ChunkManager`] resource this plugin reads.
///
/// # Example
///
/// ```rust,no_run
/// use bevy::prelude::*;
/// use voxel_framework::world::{WorldPlugin, LoadingPlugin, WorldReady};
///
/// fn on_ready(mut reader: MessageReader<WorldReady>) {
/// for _ in reader.read() {
/// println!("world ready — starting gameplay");
/// }
/// }
///
/// App::new()
/// .add_plugins((WorldPlugin, LoadingPlugin))
/// .add_systems(Update, on_ready)
/// .run();
/// ```
;
// ─── Tests ────────────────────────────────────────────────────────────────────