Struct Chunk 

pub struct Chunk {

    pub sections: Sections,
    pub pos: ChunkPos,
    pub dirty: AtomicBool,
    pub(crate) heightmaps: SyncRwLock<ChunkHeightmaps>,
    min_y: i32,
    height: i32,
    level: Weak<World>,
    pub(crate) block_entities: BlockEntityStorage,
    pub(crate) entities: EntityStorage,
    pub structure_starts: SyncRwLock<StructureStartMap>,
    pub structure_references: SyncRwLock<StructureReferenceMap>,
    pub carving_mask: SyncRwLock<Option<CarvingMask>>,
    pub postprocessing: SyncMutex<Box<[Vec<u16>]>>,
    pub(crate) scheduled_ticks: Arc<ChunkTickContainer>,
    pub sky_light_sources: SyncRwLock<ChunkSkyLightSources>,
    pub light: SyncRwLock<ChunkLightData>,
    full_runtime: OnceLock<Box<FullChunkRuntime>>,
    transient_generation_state: SyncMutex<TransientGenerationState>,
}

Canonical chunk storage retained across generation and Full runtime phases.

Fields

sections: Sections

The sections of the chunk.

pos: ChunkPos

The position of the chunk.

dirty: AtomicBool

Whether the chunk has been modified since last save. Newly generated chunks start dirty.

heightmaps: SyncRwLock<ChunkHeightmaps>

Heightmaps retained across every generation phase.

min_y: i32

The minimum Y coordinate of the world this chunk belongs to.

height: i32

The total height of the world.

level: Weak<World>

Weak reference to the owning world.

block_entities: BlockEntityStorage

Stable block-entity storage retained through Full promotion.

entities: EntityStorage

Entity staging storage closed and drained at Full promotion.

structure_starts: SyncRwLock<StructureStartMap>

Structure starts originating in this chunk.

structure_references: SyncRwLock<StructureReferenceMap>

References to structures from nearby origin chunks.

carving_mask: SyncRwLock<Option<CarvingMask>>

Bitset of positions visited by carvers (lazily initialized).

postprocessing: SyncMutex<Box<[Vec<u16>]>>

Section-indexed packed offsets that need vanilla postprocessing after promotion.

scheduled_ticks: Arc<ChunkTickContainer>

Stable block and fluid scheduled-tick storage retained through Full promotion.

sky_light_sources: SyncRwLock<ChunkSkyLightSources>

Vanilla skylight source edge cache for this chunk.

light: SyncRwLock<ChunkLightData>

Chunk-owned light sections and section emptiness maps.

full_runtime: OnceLock<Box<FullChunkRuntime>>

Full-only runtime state, installed once before Full publication.

transient_generation_state: SyncMutex<TransientGenerationState>

Generator-owned state retained only between generation stages.

Implementations

impl Chunk

pub fn new( sections: Sections, pos: ChunkPos, min_y: i32, height: i32, level: Weak<World>, ) -> Self

Creates a new proto chunk at the given position with empty sections.

pub(crate) fn from_disk( sections: Sections, pos: ChunkPos, status: ChunkStatus, min_y: i32, height: i32, heightmaps: ChunkHeightmaps, structure_starts: StructureStartMap, structure_references: StructureReferenceMap, carving_mask: Option<CarvingMask>, postprocessing: Vec<Vec<u16>>, block_ticks: BlockTickList, fluid_ticks: FluidTickList, level: Weak<World>, light: ChunkLightData, ) -> Self

Creates a chunk that was loaded from disk.

Panics

Panics when persisted light data does not match the loaded section range.

pub const fn min_y(&self) -> i32

Returns the minimum Y coordinate of the world.

pub const fn height(&self) -> i32

Returns the total height of the world.

pub const fn pos(&self) -> ChunkPos

Returns the chunk position.

pub const fn sections(&self) -> &Sections

Returns the stable section storage.

pub fn is_dirty(&self) -> bool

Returns whether this chunk has unsaved changes.

pub fn mark_dirty(&self)

Marks this chunk as needing persistence.

pub fn take_dirty(&self) -> bool

Clears the dirty flag and returns its previous value.

pub fn clear_dirty(&self)

Clears the dirty flag.

pub fn get_relative_block( &self, relative_x: usize, relative_y: usize, relative_z: usize, ) -> Option<BlockStateId>

Reads a block using coordinates relative to the chunk’s minimum Y.

pub(crate) fn set_relative_block_for_generation( &self, status: ChunkStatus, relative_x: usize, relative_y: usize, relative_z: usize, value: BlockStateId, )

Writes one generation block while preserving the current stage’s side effects.

pub(crate) fn write_block_batch_for_generation( &self, status: ChunkStatus, blocks: &[(usize, usize, usize, BlockStateId)], )

Writes a batch of generation blocks.

pub(crate) fn write_column_blocks_for_generation( &self, status: ChunkStatus, x: usize, z: usize, blocks: &[(usize, BlockStateId)], )

Writes one column of generation blocks.

pub(crate) fn prime_heightmaps(&self, heightmap_types: &[HeightmapType])

Ensures the requested generation heightmaps exist.

pub fn prime_final_heightmaps(&self)

Ensures every final heightmap exists before feature generation or promotion.

pub(crate) fn generation_height_at( &self, heightmap_type: HeightmapType, local_x: usize, local_z: usize, ) -> i32

Reads a generation heightmap, priming it lazily when needed.

pub(crate) fn generation_heightmaps( &self, ) -> RwLockReadGuard<'_, ChunkHeightmaps>

Returns the generation heightmaps retained by this chunk.

pub(crate) fn update_heightmaps_after_direct_column_writes( &self, status: ChunkStatus, local_x: usize, local_z: usize, relative_writes: &[(usize, BlockStateId)], )

Applies generation heightmap maintenance after direct writes in one column.

pub fn sky_light_sources(&self) -> RwLockReadGuard<'_, ChunkSkyLightSources>

Returns a read guard for the skylight-source cache.

pub fn block_light_sources(&self) -> Vec<BlockPos>

Returns every block position that emits light in this chunk.

pub fn light(&self) -> RwLockReadGuard<'_, ChunkLightData>

Returns committed chunk light data.

pub(crate) fn light_mut(&self) -> RwLockWriteGuard<'_, ChunkLightData>

Returns mutable committed chunk light data.

pub fn structure_starts(&self) -> RwLockReadGuard<'_, StructureStartMap>

Returns structure starts originating in this chunk.

pub fn structure_starts_mut(&self) -> RwLockWriteGuard<'_, StructureStartMap>

Returns mutable structure starts originating in this chunk.

pub fn structure_references(&self) -> RwLockReadGuard<'_, StructureReferenceMap>

Returns references to nearby structures.

pub fn structure_references_mut( &self, ) -> RwLockWriteGuard<'_, StructureReferenceMap>

Returns mutable references to nearby structures.

pub(crate) fn initialize_full_runtime( &self, runtime: FullChunkRuntime, ) -> Result<(), FullChunkRuntime>

Installs Full-only runtime state before this chunk is published as Full.

pub(crate) fn full_runtime(&self) -> Option<&FullChunkRuntime>

Returns the Full-only runtime state after promotion or Full disk construction.

pub(crate) fn install_transient_generation_state<T>(&self, state: T)

where T: DowncastType + Send + Sync,

Installs generator-owned state for reuse by later generation stages.

Panics

Panics if the current generator has already installed transient state.

pub(crate) fn with_transient_generation_state_mut<T, R>( &self, f: impl FnOnce(&mut T) -> R, ) -> Option<R>

where T: DowncastType + Send + Sync,

Borrows generator-owned state without extending its lifetime beyond the callback.

Returns None when no state was installed, such as after reloading a partially generated chunk from disk.

Panics

Panics if another generator’s state occupies this chunk.

pub(crate) fn consume_transient_generation_state<T, R>( &self, f: impl FnOnce(Option<&mut T>) -> R, ) -> R

where T: DowncastType + Send + Sync,

Removes generator-owned state and passes it to f before dropping it.

The erased allocation is moved out before the callback, so it is also dropped if the callback unwinds. None represents a cold continuation loaded from disk.

Panics

Panics if another generator’s state occupies this chunk.

pub(crate) fn clear_transient_generation_state(&self)

Drops any generator-owned state that is no longer needed by the pipeline.

pub(crate) fn get_or_create_carving_mask( &self, ) -> MappedRwLockWriteGuard<'_, CarvingMask>

Returns a write guard to this chunk’s carving mask, initializing it on first access. Mirrors vanilla’s ProtoChunk.getOrCreateCarvingMask.

Panics

Never — the mask is populated immediately before projecting the guard.

pub const fn pack_postprocessing_offset(pos: BlockPos) -> u16

Vanilla ProtoChunk.packOffsetCoordinates for postprocessing offsets.

pub fn unpack_postprocessing_offset( packed: u16, section_y: i32, chunk_pos: ChunkPos, ) -> BlockPos

Vanilla ProtoChunk.unpackOffsetCoordinates for postprocessing offsets.

pub(crate) fn mark_pos_for_postprocessing(&self, pos: BlockPos)

Marks a block position for postprocessing after proto-to-full promotion.

const fn get_section_index(&self, y: i32) -> usize

Gets the section index for a given Y coordinate.

fn mark_unsaved(&self)

Marks the chunk as unsaved.

pub(crate) fn level_weak(&self) -> Weak<World>

Returns the weak reference to the world.

pub(crate) fn get_level(&self) -> Option<Arc<World>>

Returns a reference to the world if it is still alive.

pub(crate) const fn block_entity_storage(&self) -> &BlockEntityStorage

Returns this chunk’s block-entity storage.

pub(crate) const fn scheduled_tick_container(&self) -> &Arc<ChunkTickContainer>

Returns this chunk’s stable scheduled-tick container.

pub fn initialize_light_sources(&self)

Fills the vanilla skylight-source cache from current section contents.

pub(crate) fn get_block_entity( &self, pos: BlockPos, ) -> Option<SharedBlockEntity>

Gets a block entity at the given position.

pub(crate) fn set_block_entity(&self, block_entity: SharedBlockEntity) -> bool

Stores a concrete proto block entity if its type accepts the live block state.

pub(crate) fn set_pending_block_entity(&self, pos: BlockPos)

Stores Vanilla’s pending DUMMY marker for a worldgen-placed entity block.

pub(crate) fn set_pending_block_entity_if_state( &self, pos: BlockPos, expected_state: BlockStateId, ) -> bool

Stores a pending marker only while expected_state is still live.

pub fn pending_block_entity_positions(&self) -> Vec<BlockPos>

Returns pending DUMMY positions for promotion or serialization.

pub(crate) fn promote_pending_block_entity( &self, pos: BlockPos, ) -> Option<SharedBlockEntity>

Promotes a pending worldgen DUMMY on explicit region access without ticking it.

fn commit_pending_creation( &self, pos: BlockPos, expected_state: BlockStateId, creation: BlockEntityCreation, ) -> PendingPromotionCommit

pub(crate) fn remove_block_entity(&self, pos: BlockPos)

Removes a block entity at the given position.

pub(crate) fn remove_block_entity_if_state( &self, pos: BlockPos, expected_state: BlockStateId, ) -> bool

Removes an entity or marker only while expected_state is still live.

pub(crate) fn clear_all_block_entities(&self)

Drops every block entity without Full-chunk lifecycle callbacks or dirtying.

pub fn get_block_entities(&self) -> Vec<SharedBlockEntity>

Returns all block entities in this proto chunk.

pub(crate) fn add_entity(&self, entity: SharedEntity) -> bool

Adds an entity to proto storage.

pub fn get_entities(&self) -> Vec<SharedEntity>

Returns all entities in this proto chunk.

pub(crate) fn get_saveable_entities(&self) -> Vec<SharedEntity>

Returns entities that should be persisted from this proto chunk.

pub(crate) fn schedule_block_tick( &self, pos: BlockPos, block: BlockRef, priority: TickPriority, )

Schedules a block tick in proto storage.

Vanilla ProtoChunkTicks.schedule(ScheduledTick) stores a saved tick with delay 0, so worldgen-scheduled proto ticks run after promotion instead of preserving the requested delay from generation time.

pub(crate) fn schedule_fluid_tick( &self, pos: BlockPos, fluid: FluidRef, priority: TickPriority, )

Schedules a fluid tick in proto storage.

See Self::schedule_block_tick for why proto ticks use delay 0.

pub(crate) fn set_block_state_for_generation( &self, status: ChunkStatus, pos: BlockPos, state: BlockStateId, _flags: UpdateFlags, ) -> Option<BlockStateId>

Sets a block state at the given position.

Returns the old block state at the position, or VOID_AIR if out of bounds.

fn update_light_section_emptiness(&self, y: i32, is_empty: bool)

fn update_sky_light_sources(&self, local_x: usize, y: i32, local_z: usize)

pub(crate) fn refresh_light_emptiness_maps(&self)

pub(crate) fn update_status_heightmaps_after_block_change( &self, status: ChunkStatus, local_x: usize, y: i32, local_z: usize, state: BlockStateId, )

Applies the heightmap side effect for an optimized direct section write.

Use this only for generation paths that intentionally bypass [Self::set_block_state] but still need vanilla heightmap maintenance.

pub(crate) fn update_status_heightmaps_after_column_block_changes( &self, status: ChunkStatus, local_x: usize, local_z: usize, relative_writes: &[(usize, BlockStateId)], )

fn update_heightmaps_after_block_change( &self, heightmap_types: &[HeightmapType], local_x: usize, y: i32, local_z: usize, state: BlockStateId, )

fn update_heightmaps_after_column_block_changes( &self, heightmap_types: &[HeightmapType], local_x: usize, local_z: usize, relative_writes: &[(usize, BlockStateId)], )

pub fn get_block_state(&self, pos: BlockPos) -> BlockStateId

Gets a block state at the given position.

fn with_locked_block_state<R>( &self, pos: BlockPos, f: impl FnOnce(BlockStateId) -> R, ) -> R

impl Chunk

fn initialize_full_runtime_state( &self, listener_count: Arc<GameEventListenerCount>, )

pub(crate) fn promote_to_full(&self) -> FullChunkPromotion<'_>

Promotes this chunk to Full status and initializes its runtime state.

Transfers the chunk’s heightmaps after ensuring every final map is primed. Recalculates section block counts for random tick optimization.

Panics

Panics if this chunk’s light-section count does not match its world height.

pub(crate) fn from_full_disk( sections: Sections, pos: ChunkPos, min_y: i32, height: i32, level: Weak<World>, block_ticks: BlockTickList, fluid_ticks: FluidTickList, heightmaps: ChunkHeightmaps, postprocessing: Vec<Vec<u16>>, structure_starts: StructureStartMap, structure_references: StructureReferenceMap, light: ChunkLightData, ) -> Chunk

Creates an owning Full chunk loaded from disk (not dirty).

Recalculates section block counts for random tick optimization.

Arguments

• sections - The chunk sections
• pos - The chunk position
• min_y - The minimum Y coordinate of the world
• height - The total height of the world
• level - Weak reference to the world (mirrors Java’s LevelChunk.level)
• block_ticks - Scheduled block ticks loaded from disk
• fluid_ticks - Scheduled fluid ticks loaded from disk
• heightmaps - Heightmaps loaded from disk
• postprocessing - Pending postprocessing offsets loaded from disk
• light - Chunk-owned light data loaded from disk

Panics

Panics if the loaded light-section count does not match the chunk’s world height.

Trait Implementations

impl Debug for Chunk

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.