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
//! Bevy systems that implement the chunk streaming loop.
//!
//! # Systems in this module
//!
//! | System | Schedule | Reads | Writes / Emits |
//! |---|---|---|---|
//! | [`streaming_system`] | [`Update`] | [`ViewerPosition`], [`ChunkManager`] | [`ChunkLoadRequest`], [`ChunkUnloadRequest`], `ChunkManager` pending set |
//!
//! # Execution order
//!
//! [`streaming_system`] has no explicit ordering constraints relative to other
//! `Update` systems. It should run **after** your camera/player system has
//! updated [`ViewerPosition`] for the current frame. If you need a hard
//! ordering guarantee, use `.after(YourMovementSystem)` when adding the plugin
//! or configure a system set.
//!
//! # Authoring note
//!
//! [`ViewerPosition`] is defined here (alongside the system that consumes it)
//! because both share the same module-level concern: mapping a world-space
//! position to chunk-grid decisions. It is re-exported from the crate root via
//! [`super`].
use *;
use crate;
use ;
// ─── ViewerPosition ───────────────────────────────────────────────────────────
/// World-space position of the primary viewer (player or camera).
///
/// This resource is read by [`streaming_system`] every frame to decide which
/// chunk coordinates lie within the load sphere and which loaded chunks have
/// drifted beyond the unload sphere. It **must be updated every frame** by
/// your player or camera system — if it is stale, the streaming system will
/// not respond to player movement and chunks near the new position will never
/// be requested.
///
/// The resource defaults to the origin (`Vec3::ZERO`). [`WorldPlugin`](crate::world::WorldPlugin)
/// registers it via `init_resource`, so it is always present when the plugin
/// is active.
///
/// # What happens if it is not updated?
///
/// The streaming system will continue to evaluate distances against the last
/// written position. No new [`ChunkLoadRequest`] events will be emitted for
/// the region around the player's actual position, and no
/// [`ChunkUnloadRequest`] events will fire for chunks the player has left
/// behind. The world will appear frozen at the last known viewer position.
///
/// # Example
///
/// ```rust,no_run
/// use bevy::prelude::*;
/// use voxel_framework::world::ViewerPosition;
///
/// fn sync_viewer_to_camera(
/// mut viewer: ResMut<ViewerPosition>,
/// camera: Query<&Transform, With<Camera3d>>,
/// ) {
/// if let Ok(transform) = camera.single() {
/// viewer.position = transform.translation;
/// }
/// }
/// ```
///
/// Register your sync system in [`Update`] before the streaming system runs:
///
/// ```rust,no_run
/// use bevy::prelude::*;
/// use voxel_framework::world::ViewerPosition;
///
/// # fn sync_viewer_to_camera() {}
/// # fn main() {
/// App::new()
/// .add_systems(Update, sync_viewer_to_camera)
/// .run();
/// # }
/// ```
// ─── streaming_system ────────────────────────────────────────────────────────
/// Drives chunk load and unload decisions based on [`ViewerPosition`].
///
/// Scheduled in [`Update`] by [`super::WorldPlugin`]. Each frame this system:
///
/// 1. Reads [`ViewerPosition`] and converts it to fractional chunk-grid space
/// by dividing by `CHUNK_SIZE`.
/// 2. Computes `load_radius_chunks = ceil(load_distance / CHUNK_SIZE)` and
/// iterates every integer coordinate in the `[-r, r]³` bounding cube.
/// 3. For each coordinate whose world-space center is within `load_distance`
/// and that is neither already loaded nor pending in [`ChunkManager`]:
/// - calls [`ChunkManager::mark_pending`] to prevent duplicate requests,
/// - writes a [`ChunkLoadRequest`] for the generation system to consume.
/// 4. Collects all currently loaded chunk coordinates whose world-space center
/// distance exceeds `unload_distance`, then writes one
/// [`ChunkUnloadRequest`] per coordinate.
///
/// The unload pass uses a separate `Vec` to avoid holding a shared borrow on
/// [`ChunkManager`] while emitting messages that may mutate it in the same
/// frame.