Struct ChunkHolder 

pub struct ChunkHolder {

    data: OnceLock<Chunk>,
    published_status: AtomicU8,
    status_changed: Notify,
    generation_task: SyncMutex<Option<Arc<ChunkGenerationTask>>>,
    generation_task_target: AtomicU8,
    pos: ChunkPos,
    load_level: AtomicU8,
    simulation_level: AtomicU8,
    started_work: AtomicUsize,
    active_save_dependencies: AtomicUsize,
    save_lifecycle: AtomicU8,
    highest_allowed_status: AtomicU8,
    min_y: i32,
    height: i32,
    has_changed_sections: AtomicBool,
    queued_for_broadcast: AtomicBool,
    packet_content_revision: AtomicU64,
    ticking_readiness: AtomicU64,
    full_status_initialized: AtomicBool,
    full_publications: Weak<FullPublicationQueue>,
    changed_blocks_per_section: Box<[SyncMutex<FxHashSet<PackedSectionBlockPos>>]>,
    changed_light_sections: SyncMutex<ChangedLightSectionSets>,
}

Holds chunk data and coordinates asynchronous generation work.

published_status is released only after the corresponding data and Full tick containers are installed. Synchronous readers acquire it before reading data; status_changed wakes async waiters so they can re-check the atomic state.

Fields

data: OnceLock<Chunk>

published_status: AtomicU8

status_changed: Notify

generation_task: SyncMutex<Option<Arc<ChunkGenerationTask>>>

generation_task_target: AtomicU8

pos: ChunkPos

load_level: AtomicU8

The current loading ticket level of the chunk.

simulation_level: AtomicU8

The current simulation ticket level of the chunk.

started_work: AtomicUsize

The highest status that has started work.

active_save_dependencies: AtomicUsize

Number of save dependencies that have not completed yet.

save_lifecycle: AtomicU8

Coordinates unloading revival with the short immutable save-preparation phase.

highest_allowed_status: AtomicU8

The highest status that generation is allowed to reach.

min_y: i32

The minimum Y coordinate of the world.

height: i32

The total height of the world.

has_changed_sections: AtomicBool

Whether any sections have pending block changes.

queued_for_broadcast: AtomicBool

Whether this holder is already queued for the next broadcast flush.

packet_content_revision: AtomicU64

Monotonic revision for client-visible chunk packet content.

ticking_readiness: AtomicU64

Packed ticking readiness generation. The low two bits store TickingReadiness.

full_status_initialized: AtomicBool

Whether Full post-load initialization completed and was published for readiness.

full_publications: Weak<FullPublicationQueue>

Weak sink for Full status publication notifications.

changed_blocks_per_section: Box<[SyncMutex<FxHashSet<PackedSectionBlockPos>>]>

Per-section sets of changed block positions. Index is (block_y - min_y) / 16.

changed_light_sections: SyncMutex<ChangedLightSectionSets>

Changed light sections grouped by light layer.

Implementations

impl ChunkHolder

pub const fn get_pos(&self) -> ChunkPos

Gets the chunk position.

pub const fn min_y(&self) -> i32

Gets the minimum Y coordinate of the world.

pub const fn height(&self) -> i32

Gets the total height of the world.

pub fn new( pos: ChunkPos, load_level: ChunkTicketLevel, simulation_level: Option<ChunkTicketLevel>, min_y: i32, height: i32, ) -> Self

Creates a new chunk holder.

pub(crate) fn new_with_full_publications( pos: ChunkPos, load_level: ChunkTicketLevel, simulation_level: Option<ChunkTicketLevel>, min_y: i32, height: i32, full_publications: Weak<FullPublicationQueue>, ) -> Self

pub fn load_level(&self) -> Option<ChunkTicketLevel>

Returns the current load ticket level.

pub(crate) fn swap_load_level( &self, level: ChunkTicketLevel, ) -> Option<ChunkTicketLevel>

Stores the current load ticket level and returns the previous level.

pub(crate) fn clear_load_level(&self)

Clears the current load ticket level.

pub fn simulation_level(&self) -> Option<ChunkTicketLevel>

Returns the current simulation ticket level.

pub(crate) fn set_simulation_level(&self, level: Option<ChunkTicketLevel>)

Stores the current simulation ticket level.

pub(crate) fn entity_visibility(&self) -> EntityVisibility

pub fn update_highest_allowed_status( &self, ticket_level: Option<ChunkTicketLevel>, )

Updates the highest allowed generation status based on the ticket level.

pub fn block_changed(&self, pos: BlockPos) -> bool

Records a block change at the given position. Returns true if this is the first change (chunk should be added to broadcast list).

pub fn light_changed(&self, layer: LightLayer, section_pos: SectionPos) -> bool

Records a light-section change for a full chunk and marks saved light data dirty.

Returns true if this is the first pending broadcast change for the chunk holder.

pub fn mark_light_section_dirty(&self, section_pos: SectionPos) -> bool

Marks saved light data dirty without queuing client-visible changes.

fn mark_valid_light_section_dirty( &self, section_pos: SectionPos, ) -> Option<bool>

pub fn has_changes_to_broadcast(&self) -> bool

Returns whether there are pending changes to broadcast.

pub fn clear_broadcast_queued(&self)

Allows later changes to enqueue this holder for a future broadcast.

pub fn take_changed_blocks( &self, ) -> Vec<(usize, FxHashSet<PackedSectionBlockPos>)>

Takes all pending block changes, grouped by section index. Returns a vec of (section_index, set of packed positions).

pub fn take_changed_light_sections(&self) -> ChangedLightSections

Takes all pending light-section changes.

pub fn mark_packet_content_changed(&self)

Marks the holder’s client-visible chunk packet content as changed.

pub fn packet_content_revision(&self) -> u64

Returns the current client-visible content revision.

pub(crate) fn ticking_readiness_snapshot(&self) -> TickingReadinessSnapshot

pub(crate) fn is_full_status_initialized(&self) -> bool

pub(crate) fn transition_ticking_readiness( &self, target: TickingReadiness, ) -> Option<TickingReadiness>

pub fn section_count(&self) -> usize

Returns the number of sections in this chunk.

pub fn is_status_disallowed(&self, status: ChunkStatus) -> bool

Checks if the given status is disallowed.

pub(crate) fn schedule_chunk_generation_task_b( &self, status: ChunkStatus, chunk_map: &Arc<ChunkMap>, ) -> bool

Schedules a generation task for this chunk if needed.

Returns true if a new task was actually scheduled, false if the chunk already has a suitable task or is already at the target status.

pub(crate) fn reschedule_chunk_task_b( &self, status: ChunkStatus, chunk_map: &Arc<ChunkMap>, )

Reschedules the chunk task to the given status.

pub fn try_chunk(&self, status: ChunkStatus) -> Option<&Chunk>

Gets access to the chunk if it has reached the given status.

pub fn try_full_chunk(&self) -> Option<FullChunkRef<'_>>

Gets the Full-only capability after Full status is published.

pub async fn await_chunk(&self, status: ChunkStatus) -> Option<&Chunk>

Waits until the chunk has reached the given status.

pub async fn await_chunk_status( &self, status: ChunkStatus, ) -> Option<ChunkStatus>

Waits until the chunk has reached the given status without reading chunk data.

async fn await_claimed_chunk_status( &self, status: ChunkStatus, ) -> Option<ChunkStatus>

pub fn published_status(&self) -> Option<ChunkStatus>

Gets the published status of the chunk.

pub fn is_ready_for_saving(&self) -> bool

Returns whether vanilla timed tickets may age for this chunk.

pub(crate) fn add_save_dependency(self: &Arc<Self>) -> ChunkSaveDependency

pub(crate) fn begin_unloading(&self)

Moves an active holder into the unloading lifecycle.

pub(crate) fn try_begin_save_preparation( self: &Arc<Self>, ) -> Option<ChunkSavePreparationGuard>

Reserves the unloading holder while its immutable save input is assembled.

pub(crate) fn try_revive_from_unloading(&self) -> bool

Attempts to reactivate an unloading holder without waiting for save preparation.

pub fn apply_step( self: &Arc<Self>, step: &'static ChunkStep, chunk_map: &Arc<ChunkMap>, cache: &Arc<StaticCache2D<Arc<ChunkHolder>>>, thread_pool: Arc<ThreadPool>, ) -> Option<NeighborReady>

Applies a step to the chunk.

Cancellation is handled structurally by the owning generation task: its run loop races the whole join_all of dependency-wait futures against its cancel token and drops them on cancellation, so the returned futures don’t each re-check it. A failed dependency surfaces as await_chunk_status returning None.

Panics

Panics if the target status is not Empty and has no parent, or if the chunk status is invalid during generation.

fn await_light_work_window_and_apply_step( holder: Arc<Self>, step: &'static ChunkStep, chunk_map: Arc<ChunkMap>, cache: Arc<StaticCache2D<Arc<ChunkHolder>>>, thread_pool: Arc<ThreadPool>, light_work_window_gate: Arc<LightWorkWindowGate>, ) -> NeighborReady

fn apply_step_with_light_work_window_reservation( self: &Arc<Self>, step: &'static ChunkStep, chunk_map: &Arc<ChunkMap>, cache: &Arc<StaticCache2D<Arc<ChunkHolder>>>, thread_pool: Arc<ThreadPool>, light_work_window_reservation: Option<LightWorkWindowReservation>, ) -> Option<NeighborReady>

async fn apply_empty_step( holder: Arc<Self>, step: &'static ChunkStep, context: Arc<WorldGenContext>, cache: Arc<StaticCache2D<Arc<ChunkHolder>>>, storage: Arc<ChunkStorage>, thread_pool: Arc<ThreadPool>, ) -> Option<()>

async fn apply_existing_empty_step( holder: &Arc<Self>, target_status: ChunkStatus, context: &Arc<WorldGenContext>, storage: &Arc<ChunkStorage>, thread_pool: &ThreadPool, ) -> Option<bool>

async fn apply_generated_step( holder: Arc<Self>, step: &'static ChunkStep, context: Arc<WorldGenContext>, cache: Arc<StaticCache2D<Arc<ChunkHolder>>>, thread_pool: Arc<ThreadPool>, light_work_window_reservation: Option<LightWorkWindowReservation>, ) -> Option<()>

async fn run_step_task( thread_pool: Arc<ThreadPool>, step: &'static ChunkStep, context: Arc<WorldGenContext>, cache: Arc<StaticCache2D<Arc<ChunkHolder>>>, holder: Arc<Self>, )

fn claim_status_work( self: &Arc<Self>, status: ChunkStatus, ) -> Option<StatusWorkClaim>

fn release_status_work_claim(&self, status: ChunkStatus)

fn mark_status_work_published(&self, status: ChunkStatus)

fn status_work_covers(&self, status: ChunkStatus) -> bool

pub(crate) fn upgrade_to_full(&self)

Upgrades the chunk to a full chunk.

If the chunk is already Full (e.g., loaded from disk), this is a no-op.

Panics

Panics if no chunk has been installed or Full runtime initialization repeats.

pub(crate) fn post_process_generation( &self, ) -> Result<usize, PostProcessGenerationError>

Runs Full-load post-processing and returns the number of packed positions attempted.

fn finish_generation_status(self: &Arc<Self>, status: ChunkStatus)

Finishes a generated status on the async scheduler after the Rayon task returns.

pub fn insert_chunk(self: &Arc<Self>, chunk: Chunk, status: ChunkStatus)

Inserts a chunk into the holder with a specific status. This notifies watchers - use insert_chunk_no_notify + separate notification if calling from a rayon thread to avoid contention.

Panics

Panics if status claims Full without initialized Full runtime state, or if initialized Full runtime state is paired with a lower status.

fn store_and_publish_chunk_status(&self, chunk: Chunk, status: ChunkStatus)

fn publish_generated_status(&self, status: ChunkStatus)

fn register_full_chunk_ticks(&self)

Registers tick queues before Full status becomes observable to watchers.

fn publish_full(self: &Arc<Self>)

pub(crate) fn insert_chunk_no_notify(&self, chunk: Chunk)

Inserts a chunk into the holder without notifying watchers. The caller is responsible for notifying via the completion channel.

pub fn wake_all_watchers(&self)

Wakes all await_chunk watchers without changing the chunk result. This allows waiting futures to re-check is_status_disallowed and bail out during chunk unload.

pub fn cancel_generation_task(&self)

Cancels the current generation task.

pub(crate) fn clear_generation_task_if_current( &self, task: &Arc<ChunkGenerationTask>, )

Clears the current generation task if it is still the supplied task.