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
//! High-level world-space voxel accessors.
//!
//! This module provides the two primary entry points for **reading and writing
//! individual voxels by world-space position**. It sits above the chunk-local
//! getter/setter API (e.g. `Chunk::get`, `Chunk::set`) and above the
//! chunk-coordinate helpers (`world_to_chunk_coord`, `world_to_local_coord`),
//! combining them into a single ergonomic call.
//!
//! # Relationship to chunk-local API
//!
//! When you know the exact chunk coordinate and local voxel index (e.g. inside
//! mining or placement logic that received a [`crate::world::raycast::RaycastHit`]),
//! prefer the chunk-local API — it avoids the coordinate conversion overhead.
//! Use this module when you only have a world-space `Vec3` and do not want to
//! manage chunk boundaries manually.
//!
//! # Examples
//!
//! ```no_run
//! # use bevy::prelude::*;
//! # use voxel_framework::world::{ChunkManager, ChunkModified};
//! # use voxel_framework::world::voxel_ops::{get_voxel_at, set_voxel_at};
//! # use voxel_framework::chunk::Chunk;
//! # use voxel_framework::voxel::DefaultVoxel;
//! # fn example(
//! # manager: &ChunkManager,
//! # chunks: &Query<&Chunk<DefaultVoxel>>,
//! # mut_chunks: &mut Query<&mut Chunk<DefaultVoxel>>,
//! # modified: &mut MessageWriter<ChunkModified>,
//! # ) {
//! let pos = Vec3::new(12.0, 64.0, 8.0);
//!
//! // Read
//! if let Some(voxel) = get_voxel_at(pos, manager, chunks) {
//! println!("voxel at {pos}: {voxel:?}");
//! }
//!
//! // Write
//! let written = set_voxel_at(pos, DefaultVoxel::Rock, manager, mut_chunks, modified);
//! assert!(written, "chunk must be loaded for the write to succeed");
//! # }
//! ```
use *;
use crate;
use crateVoxelType;
use crateChunkModified;
use ChunkManager;
/// Read the voxel at a world-space position.
///
/// Converts `world_pos` to a chunk coordinate and a local voxel index, looks
/// up the chunk entity in `manager`, and returns the voxel stored at that
/// position.
///
/// # Parameters
///
/// - `world_pos` — World-space position anywhere inside the target voxel.
/// The function uses the **floor** of each component to determine the voxel
/// cell, so any point inside the voxel's unit cube maps to the same result.
/// - `manager` — Chunk registry used to find the entity for the enclosing chunk.
/// - `chunks` — Read query for chunk voxel data.
///
/// # Return value
///
/// `Some(V)` containing the voxel value at `world_pos`, or `None` when the
/// enclosing chunk is not currently loaded.
///
/// # Examples
///
/// ```no_run
/// # use bevy::prelude::*;
/// # use voxel_framework::world::{ChunkManager, voxel_ops::get_voxel_at};
/// # use voxel_framework::chunk::Chunk;
/// # use voxel_framework::voxel::DefaultVoxel;
/// # fn example(manager: &ChunkManager, chunks: &Query<&Chunk<DefaultVoxel>>) {
/// let pos = Vec3::new(8.0, 64.5, 4.0);
/// match get_voxel_at(pos, manager, chunks) {
/// Some(v) => println!("voxel: {v:?}"),
/// None => println!("chunk not loaded"),
/// }
/// # }
/// ```
/// Write a voxel at a world-space position.
///
/// Converts `world_pos` to a chunk coordinate and a local voxel index, then
/// writes `voxel` into the chunk. As a side effect, emits a
/// [`crate::world::ChunkModified`] message for the containing chunk so that
/// the meshing and occlusion systems know to rebuild it.
///
/// # Parameters
///
/// - `world_pos` — World-space position inside the target voxel cell.
/// - `voxel` — The voxel value to write.
/// - `manager` — Chunk registry used to find the entity for the enclosing chunk.
/// - `chunks` — Mutable query for chunk voxel data.
/// - `modified` — Message writer; receives a [`crate::world::ChunkModified`]
/// event for the affected chunk on success.
///
/// # Return value
///
/// `true` if the write succeeded, `false` if the enclosing chunk is not loaded.
///
/// # Side effects
///
/// On success, writes one [`crate::world::ChunkModified`] message. Downstream
/// systems (mesher, occlusion, persistence) react to this event — it must not
/// be suppressed.
///
/// # Examples
///
/// ```no_run
/// # use bevy::prelude::*;
/// # use voxel_framework::world::{ChunkManager, ChunkModified, voxel_ops::set_voxel_at};
/// # use voxel_framework::chunk::Chunk;
/// # use voxel_framework::voxel::DefaultVoxel;
/// # fn example(
/// # manager: &ChunkManager,
/// # mut chunks: &mut Query<&mut Chunk<DefaultVoxel>>,
/// # mut modified: &mut MessageWriter<ChunkModified>,
/// # ) {
/// let pos = Vec3::new(8.0, 64.0, 4.0);
/// let ok = set_voxel_at(pos, DefaultVoxel::Rock, manager, &mut chunks, &mut modified);
/// if !ok { eprintln!("chunk at {pos} is not loaded"); }
/// # }
/// ```
/// Read the state byte of the voxel at a world-space position.
///
/// Returns `None` if the enclosing chunk is not loaded. Returns `0` for voxels
/// whose state has never been explicitly set (generator-filled voxels).
///
/// See [`crate::chunk::Chunk::get_state`] for the state-byte encoding.
/// Write the state byte of the voxel at a world-space position.
///
/// Does NOT emit a `ChunkModified` event — state changes do not affect
/// geometry, so remeshing is not triggered. Returns `true` on success, `false`
/// if the enclosing chunk is not loaded.
///
/// See [`crate::chunk::Chunk::set_state`] for the state-byte encoding.