pub struct Chunk<V: VoxelType> {
pub states: Box<[u8; 4096]>,
/* private fields */
}Expand description
A 16×16×16 block of voxels — the fundamental unit of world storage.
Chunk<V> is a Bevy Component that holds all voxel data for one
16-voxel-per-axis region of the world. It is generic over any type
implementing VoxelType, so it works with crate::voxel::DefaultVoxel
out of the box and with custom palettes without any changes to the framework.
§Memory layout
Voxels are stored in a single heap-allocated array of length
CHUNK_VOLUME (4 096), indexed in X-major order:
flat_index = x * CHUNK_SIZE² + y * CHUNK_SIZE + zThis means a full row of Z-adjacent voxels is contiguous in memory —
the layout the greedy meshing algorithm iterates most frequently.
The array is wrapped in a Box to keep the struct’s stack size to a single
pointer (8 bytes) regardless of V’s size.
§Block states
Each voxel has a companion u8 state byte stored in a parallel
states array. The state byte is set automatically by the placement system
to record which face the block was placed against (bits 0-2, see
face_to_state):
| Bits | Meaning |
|---|---|
| 0–2 | Placement face (0=+X, 1=−X, 2=+Y, 3=−Y, 4=+Z, 5=−Z, 6=unknown) |
| 3–7 | Reserved for game-specific use |
Games may read and write state bytes freely via Chunk::get_state /
Chunk::set_state for door open/close flags, liquid level, growth stage,
or any other per-voxel metadata.
§Coordinate bounds
Every method that takes (x, y, z) expects each coordinate in
[0, CHUNK_SIZE) (i.e. 0..16). Out-of-bounds access panics in debug
builds via debug_assert inside Chunk::get_index. In release builds,
out-of-bounds indices silently alias other voxels — callers must ensure
correct inputs.
Use crate::chunk::world_to_local_coord to convert a world-space
position to a valid (x, y, z) triple before calling get or set.
§See also
crate::chunk— coordinate systems and conversion helpers.crate::voxel::VoxelType— the traitVmust implement.
Fields§
§states: Box<[u8; 4096]>Per-voxel state bytes — parallel array to voxels.
Bits 0–2 encode the placement face; bits 3–7 are reserved for games.
All states are initialised to 0 (face = +X, conventional default).
Implementations§
Source§impl<V: VoxelType> Chunk<V>
impl<V: VoxelType> Chunk<V>
Sourcepub fn new() -> Self
pub fn new() -> Self
Creates a new chunk with every voxel initialized to VoxelType::air
and every state byte set to 0.
Allocates two CHUNK_VOLUME-element arrays on the heap.
Sourcepub fn get_index(x: usize, y: usize, z: usize) -> usize
pub fn get_index(x: usize, y: usize, z: usize) -> usize
Computes the flat array index for the voxel at local coordinate (x, y, z).
The formula is x * CHUNK_SIZE² + y * CHUNK_SIZE + z, giving X-major
(row-major with X as the outermost dimension) storage order.
Prefer calling Chunk::get or Chunk::set directly; this method is
public for use by the meshing and persistence systems that need to
iterate the flat array efficiently.
§Panics
Panics in debug builds if any coordinate is >= CHUNK_SIZE. In
release builds, the assertion is omitted for performance.
Sourcepub fn get(&self, x: usize, y: usize, z: usize) -> V
pub fn get(&self, x: usize, y: usize, z: usize) -> V
Returns a copy of the voxel at local coordinate (x, y, z).
Each coordinate must be in [0, CHUNK_SIZE). The value is returned by
copy because VoxelType requires Copy.
§Panics
Panics in debug builds if any coordinate is out of bounds (see
Chunk::get_index).
Sourcepub fn set(&mut self, x: usize, y: usize, z: usize, voxel: V)
pub fn set(&mut self, x: usize, y: usize, z: usize, voxel: V)
Overwrites the voxel at local coordinate (x, y, z) with voxel.
Each coordinate must be in [0, CHUNK_SIZE). Use
VoxelType::air to clear a voxel back to empty.
After calling this method on an already-spawned chunk entity, emit a
crate::world::ChunkModified event so that the mesh system
regenerates the chunk’s geometry.
§Panics
Panics in debug builds if any coordinate is out of bounds (see
Chunk::get_index).
Sourcepub fn get_state(&self, x: usize, y: usize, z: usize) -> u8
pub fn get_state(&self, x: usize, y: usize, z: usize) -> u8
Returns the state byte for the voxel at local coordinate (x, y, z).
Bits 0–2 hold the placement face (see face_to_state); bits 3–7 are
available for game-specific use. Returns 0 for voxels that have never
been explicitly placed (e.g. generator-filled voxels).
§Panics
Panics in debug builds if any coordinate is out of bounds.
Sourcepub fn set_state(&mut self, x: usize, y: usize, z: usize, state: u8)
pub fn set_state(&mut self, x: usize, y: usize, z: usize, state: u8)
Overwrites the state byte for the voxel at local coordinate (x, y, z).
Games may set bits 3–7 freely. Bits 0–2 are normally written by the
placement system via face_to_state.
§Panics
Panics in debug builds if any coordinate is out of bounds.
Sourcepub fn is_solid_at(&self, x: usize, y: usize, z: usize) -> bool
pub fn is_solid_at(&self, x: usize, y: usize, z: usize) -> bool
Returns true if the voxel at local coordinate (x, y, z) is solid.
Equivalent to self.get(x, y, z).is_solid(). Used by the meshing and
occlusion systems to test individual voxels without materializing the
full voxel value.
§Panics
Panics in debug builds if any coordinate is out of bounds.
Sourcepub fn is_fully_solid(&self) -> bool
pub fn is_fully_solid(&self) -> bool
Returns true if every voxel in the chunk is solid.
A fully solid chunk is opaque from all six faces and requires no interior face geometry. The occlusion system uses this to skip mesh generation for completely buried chunks.
Runs in O(CHUNK_VOLUME) time by scanning the flat array.
Sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true if every voxel in the chunk is air (non-solid).
An empty chunk produces no geometry. The streaming system uses this to avoid spawning mesh entities for chunks that contain only air, such as the open space above a terrain surface or inside a cave ceiling.
Runs in O(CHUNK_VOLUME) time by scanning the flat array.
Sourcepub fn border_slice(&self, face: usize) -> [V; 256]
pub fn border_slice(&self, face: usize) -> [V; 256]
Extracts a 16x16 border slice for one of the six chunk faces.
The returned array contains the voxels on the outermost layer in the
direction indicated by face:
| Face | Direction | Fixed axis value |
|---|---|---|
| 0 | +Y | y = 15 |
| 1 | -Y | y = 0 |
| 2 | +X | x = 15 |
| 3 | -X | x = 0 |
| 4 | +Z | z = 15 |
| 5 | -Z | z = 0 |
The slice is packed in row-major order for the two varying axes.
§Panics
Panics if face >= 6.
Trait Implementations§
Source§impl<V: VoxelType> Component for Chunk<V>
impl<V: VoxelType> Component for Chunk<V>
Source§const STORAGE_TYPE: StorageType = ::bevy::ecs::component::StorageType::Table
const STORAGE_TYPE: StorageType = ::bevy::ecs::component::StorageType::Table
Source§type Mutability = Mutable
type Mutability = Mutable
Component<Mutability = Mutable>,
while immutable components will instead have Component<Mutability = Immutable>. Read moreSource§fn register_required_components(
_requiree: ComponentId,
required_components: &mut RequiredComponentsRegistrator<'_, '_>,
)
fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )
Source§fn clone_behavior() -> ComponentCloneBehavior
fn clone_behavior() -> ComponentCloneBehavior
Source§fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>
fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>
ComponentRelationshipAccessor required for working with relationships in dynamic contexts. Read moreSource§fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn on_replace() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_replace() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn map_entities<E>(_this: &mut Self, _mapper: &mut E)where
E: EntityMapper,
fn map_entities<E>(_this: &mut Self, _mapper: &mut E)where
E: EntityMapper,
EntityMapper. This is used to remap entities in contexts like scenes and entity cloning.
When deriving Component, this is populated by annotating fields containing entities with #[entities] Read moreAuto Trait Implementations§
impl<V> Forget for Chunk<V>
impl<V> Freeze for Chunk<V>
impl<V> Move for Chunk<V>
impl<V> RefUnwindSafe for Chunk<V>
impl<V> Send for Chunk<V>
impl<V> Sync for Chunk<V>
impl<V> Unpin for Chunk<V>
impl<V> UnsafeUnpin for Chunk<V>
impl<V> UnwindSafe for Chunk<V>
Blanket Implementations§
Source§impl<T, U> AsBindGroupShaderType<U> for T
impl<T, U> AsBindGroupShaderType<U> for T
Source§fn as_bind_group_shader_type(&self, _images: &RenderAssets<GpuImage>) -> U
fn as_bind_group_shader_type(&self, _images: &RenderAssets<GpuImage>) -> U
T ShaderType for self. When used in AsBindGroup
derives, it is safe to assume that all images in self exist.Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<C> Bundle for Cwhere
C: Component,
impl<C> Bundle for Cwhere
C: Component,
fn component_ids( components: &mut ComponentsRegistrator<'_>, ) -> impl Iterator<Item = ComponentId> + use<C>
Source§fn get_component_ids(
components: &Components,
) -> impl Iterator<Item = Option<ComponentId>>
fn get_component_ids( components: &Components, ) -> impl Iterator<Item = Option<ComponentId>>
Source§impl<C> BundleFromComponents for Cwhere
C: Component,
impl<C> BundleFromComponents for Cwhere
C: Component,
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> ConditionalSend for Twhere
T: Send,
Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>, which can then be
downcast into Box<dyn ConcreteType> where ConcreteType implements Trait.Source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait> (where Trait: Downcast) to Rc<Any>, which can then be further
downcast into Rc<ConcreteType> where ConcreteType implements Trait.Source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &Any’s vtable from &Trait’s.Source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.Source§impl<T> DowncastSend for T
impl<T> DowncastSend for T
impl<S, T> Duplex<S> for Twhere
T: FromSample<S> + ToSample<S>,
Source§impl<C> DynamicBundle for Cwhere
C: Component,
impl<C> DynamicBundle for Cwhere
C: Component,
Source§unsafe fn get_components(
ptr: MovingPtr<'_, C>,
func: &mut impl FnMut(StorageType, OwningPtr<'_>),
) -> <C as DynamicBundle>::Effect
unsafe fn get_components( ptr: MovingPtr<'_, C>, func: &mut impl FnMut(StorageType, OwningPtr<'_>), ) -> <C as DynamicBundle>::Effect
Source§unsafe fn apply_effect(
_ptr: MovingPtr<'_, MaybeUninit<C>>,
_entity: &mut EntityWorldMut<'_>,
)
unsafe fn apply_effect( _ptr: MovingPtr<'_, MaybeUninit<C>>, _entity: &mut EntityWorldMut<'_>, )
Source§impl<S> FromSample<S> for S
impl<S> FromSample<S> for S
fn from_sample_(s: S) -> S
Source§impl<T> FromWorld for Twhere
T: Default,
impl<T> FromWorld for Twhere
T: Default,
Source§fn from_world(_world: &mut World) -> T
fn from_world(_world: &mut World) -> T
Creates Self using default().
Source§impl<T, W> HasTypeWitness<W> for Twhere
W: MakeTypeWitness<Arg = T>,
T: ?Sized,
impl<T, W> HasTypeWitness<W> for Twhere
W: MakeTypeWitness<Arg = T>,
T: ?Sized,
Source§impl<T> Identity for Twhere
T: ?Sized,
impl<T> Identity for Twhere
T: ?Sized,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more