Struct ChunkMap 

pub struct ChunkMap {

    pub(crate) chunks: HashMap<ChunkPos, Arc<ChunkHolder>, FxBuildHasher>,
    pub(crate) unloading_chunks: HashMap<ChunkPos, Arc<ChunkHolder>, FxBuildHasher>,
    deferred_revivals: SyncMutex<FxHashMap<ChunkPos, DeferredChunkRevival>>,
    pub pending_generation_tasks: SyncMutex<Vec<Arc<ChunkGenerationTask>>>,
    pub task_tracker: TaskTracker,
    scheduling: ChunkSchedulingCoordinator,
    full_publications: Arc<FullPublicationQueue>,
    full_neighborhood: SyncMutex<FullNeighborhoodIndex>,
    ticking_chunks: ArcSwap<TickingChunkSnapshot>,
    finalized_block_entity_unloads: SyncMutex<Vec<FinalizedBlockEntityUnload>>,
    timed_chunk_tickets: SyncMutex<TimedChunkTickets>,
    pub world_gen_context: Arc<WorldGenContext>,
    pub generation_pool: Arc<ThreadPool>,
    chunk_encoding_pool: Arc<ThreadPool>,
    pub chunk_runtime: Arc<Runtime>,
    pub storage: Arc<ChunkStorage>,
    pub chunks_to_broadcast: SyncMutex<Vec<Arc<ChunkHolder>>>,
    light_updates: SyncMutex<LightUpdateState>,
    light_updates_progress_notify: Notify,
    light_work_window_gate: Arc<LightWorkWindowGate>,
    running_generation_tasks: AtomicUsize,
    generation_refill_notify: Notify,
    generation_refill_cancel_token: CancellationToken,
    generation_refill_stopped: AtomicBool,
    generation_refill_started: AtomicBool,
    pub cancel_token: CancellationToken,
}

A map of chunks managing their state, loading, and generation.

Fields

chunks: HashMap<ChunkPos, Arc<ChunkHolder>, FxBuildHasher>

Map of active chunks.

unloading_chunks: HashMap<ChunkPos, Arc<ChunkHolder>, FxBuildHasher>

Map of chunks currently being unloaded.

deferred_revivals: SyncMutex<FxHashMap<ChunkPos, DeferredChunkRevival>>

Ticket states waiting for an unloading holder’s save preparation to finish.

pending_generation_tasks: SyncMutex<Vec<Arc<ChunkGenerationTask>>>

Queue of pending generation tasks.

task_tracker: TaskTracker

Tracker for background scheduling, generation, save, and unload tasks.

scheduling: ChunkSchedulingCoordinator

Ordered ticket ingress and background scheduling epoch handoff.

full_publications: Arc<FullPublicationQueue>

Full status completions awaiting lifecycle-boundary reconciliation.

full_neighborhood: SyncMutex<FullNeighborhoodIndex>

Incremental radius-1/radius-2 Full-neighborhood state.

ticking_chunks: ArcSwap<TickingChunkSnapshot>

Readiness-driven chunk views published at lifecycle boundaries.

finalized_block_entity_unloads: SyncMutex<Vec<FinalizedBlockEntityUnload>>

Final-unload callbacks waiting for the serialized lifecycle boundary.

timed_chunk_tickets: SyncMutex<TimedChunkTickets>

Timed gameplay ticket owners that expire through the game tick.

world_gen_context: Arc<WorldGenContext>

The world generation context.

generation_pool: Arc<ThreadPool>

The thread pool to use for chunk generation (throughput-oriented).

chunk_encoding_pool: Arc<ThreadPool>

The thread pool to use for CPU-heavy chunk persistence work.

chunk_runtime: Arc<Runtime>

The thread pool to use for chunk ticking (latency-oriented). The runtime to use for chunk tasks.

storage: Arc<ChunkStorage>

Storage backend for chunk saving and loading.

chunks_to_broadcast: SyncMutex<Vec<Arc<ChunkHolder>>>

Chunk holders with pending block changes to broadcast.

light_updates: SyncMutex<LightUpdateState>

Coalesced light changes and drained-but-not-yet-applied light work.

light_updates_progress_notify: Notify

Notifies save barriers when in-flight light propagation state changes.

light_work_window_gate: Arc<LightWorkWindowGate>

Radius-2 work-window gate for light-engine worksets.

running_generation_tasks: AtomicUsize

Number of top-level generation tasks currently running.

generation_refill_notify: Notify

Wakes the generation refill loop when pending/running task state changes.

generation_refill_cancel_token: CancellationToken

Cancels the generation refill loop without cancelling active generation tasks.

generation_refill_stopped: AtomicBool

Fast shutdown flag for the generation refill loop.

generation_refill_started: AtomicBool

Whether the notify-driven refill loop has been started for this map.

cancel_token: CancellationToken

Parent cancellation token for all generation tasks. Child tokens are created per-task; cancelling this cancels everything.

Implementations

impl ChunkMap

pub(crate) fn schedule_generation_task_b( self: &Arc<Self>, target_status: ChunkStatus, pos: ChunkPos, ) -> Arc<ChunkGenerationTask>

Schedules a new generation task.

pub fn run_generation_tasks_b(&self)

Runs queued generation tasks.

pub(super) fn max_running_generation_tasks(&self) -> usize

pub(super) fn generation_task_priority( task: &ChunkGenerationTask, ) -> GenerationTaskPriority

pub(super) fn update_chunk_level( self: &Arc<Self>, pos: ChunkPos, new_level: Option<ChunkTicketLevel>, new_simulation_level: Option<ChunkTicketLevel>, ) -> Option<Arc<ChunkHolder>>

Updates scheduling for a chunk based on its new level. Returns the chunk holder if it is active.

pub(super) fn merge_deferred_revivals(&self, changes: &mut Vec<LevelChange>)

pub(super) fn prepare_ticking_readiness_demotions( &self, changes: &[LevelChange], ) -> Result<bool, FullNeighborhoodError>

pub(super) fn reconcile_ticking_readiness_measured( &self, changed_positions: &[ChunkPos], ) -> Result<ReadinessReconcileResult, FullNeighborhoodError>

pub(crate) fn rebuild_ticking_chunk_snapshot(&self) -> usize

Rebuilds every gameplay ticking view from one optimized SCC traversal.

This runs only after lifecycle/readiness changes, never as fixed per-tick bookkeeping. The published snapshot owns holders but never component guards, so callbacks cannot retain section or chunk-component locks.

pub(super) fn ticking_snapshot_membership( readiness: TickingReadiness, simulation_level: Option<ChunkTicketLevel>, ) -> (bool, bool, bool)

pub(super) fn simulation_changes_ticking_snapshot( &self, changes: &[LevelChange], ) -> bool

pub(super) fn current_full_contributor( &self, pos: ChunkPos, ) -> Option<Arc<ChunkHolder>>

pub(super) fn validate_full_publication( &self, publication: &FullPublication, ) -> Option<Arc<ChunkHolder>>

pub(super) fn readiness_candidates( &self, dirty: &[(ChunkPos, FullNeighborhoodCounts)], new_levels: Option<&FxHashMap<ChunkPos, Option<ChunkTicketLevel>>>, ) -> Vec<TickingReadinessCandidate>

const fn desired_ticking_readiness( level: Option<ChunkTicketLevel>, ) -> TickingReadiness

pub(super) fn target_ticking_readiness( holder: &ChunkHolder, level: Option<ChunkTicketLevel>, counts: FullNeighborhoodCounts, ) -> TickingReadiness

pub(super) fn apply_readiness_demotions( &self, candidates: &[TickingReadinessCandidate], ) -> bool

pub(super) fn apply_final_readiness( &self, dirty: Vec<(ChunkPos, FullNeighborhoodCounts)>, ) -> ReadinessReconcileResult

pub(super) fn update_pending_readiness( &self, candidates: &[TickingReadinessCandidate], )

pub(super) fn log_postprocessing_failure( candidate: &TickingReadinessCandidate, error: PostProcessGenerationError, )

pub(super) fn clear_all_ticking_readiness(&self)

pub(super) fn rebuild_ticking_readiness( &self, ) -> Result<ReadinessReconcileResult, FullNeighborhoodError>

pub(super) fn recover_ticking_readiness_index( &self, error: FullNeighborhoodError, ) -> ReadinessReconcileResult

impl ChunkMap

pub fn block_changed(&self, pos: BlockPos)

Records a block change at the given position. This marks the chunk as having pending changes to broadcast.

pub fn packet_content_changed(&self, chunk_pos: ChunkPos)

Marks client-visible chunk packet content as changed.

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

Records a light-section change at the given position.

pub fn queue_light_change( &self, pos: BlockPos, check_block: bool, empty_section_change: Option<LightSectionEmptinessChange>, )

Queues a block or section light change for the next light propagation drain.

pub fn propagate_queued_light_changes(&self)

Drains all queued light updates and runs one scoped propagation per changed chunk.

pub(super) async fn flush_queued_light_changes_for_save(&self)

pub(super) fn drain_pending_light_updates( &self, ) -> Option<(Vec<(ChunkPos, PendingChunkLightUpdates)>, InFlightLightUpdates<'_>)>

pub(super) fn next_pending_light_update_center(&self) -> Option<ChunkPos>

pub(super) fn next_pending_light_update_center_touching_chunk( &self, chunk_pos: ChunkPos, ) -> Option<ChunkPos>

pub(super) fn drain_pending_light_update_for_center( &self, center: ChunkPos, ) -> Option<(PendingChunkLightUpdates, InFlightLightUpdates<'_>)>

pub(super) fn track_in_flight_light_updates( &self, light_updates: &mut LightUpdateState, centers: Vec<ChunkPos>, ) -> InFlightLightUpdates<'_>

pub(super) fn has_in_flight_light_updates(&self) -> bool

pub(super) fn has_in_flight_light_update_touching_chunk( &self, chunk_pos: ChunkPos, ) -> bool

pub(super) async fn wait_for_in_flight_light_updates(&self)

pub(super) async fn wait_for_in_flight_light_update_touching_chunk( &self, chunk_pos: ChunkPos, )

pub(super) async fn flush_queued_light_changes_touching_chunk_for_save( &self, chunk_pos: ChunkPos, )

pub(super) fn light_update_center_is_available(&self, center: ChunkPos) -> bool

pub(super) fn light_update_holder( &self, chunk_pos: ChunkPos, ) -> Option<Arc<ChunkHolder>>

pub(super) fn propagate_queued_light_change( &self, center: ChunkPos, task: PendingChunkLightUpdates, )

pub(super) fn light_workset_for_change( &self, center: ChunkPos, ) -> Option<LightWorkset>

impl ChunkMap

async fn prepare_chunk_save_on_pool( self: &Arc<Self>, chunk_holder: &Arc<ChunkHolder>, ) -> Option<PreparedChunkSave>

pub(super) async fn save_chunk( self: &Arc<Self>, chunk_holder: &Arc<ChunkHolder>, _save_dependency: ChunkSaveDependency, )

Saves a chunk to disk. Does not remove from unloading_chunks.

pub(super) fn mark_chunk_dirty_for_save_retry(chunk_holder: &ChunkHolder)

pub(super) fn process_unloads( self: &Arc<Self>, staged_revivals: &FxHashSet<ChunkPos>, )

Processes chunks that are pending unload.

Iterates over unloading_chunks. For each chunk with strong_count == 1:

• If staged to revive at the next lifecycle boundary: keep
• If dirty: spawn save task (keep until saved and clean)
• If not dirty: release region handle and remove

pub async fn save_all_chunks(self: &Arc<Self>) -> Result<usize>

Saves all dirty chunks to disk.

This method should be called during graceful shutdown to ensure all modified chunks are persisted. It saves:

1. All dirty chunks in the active chunks map
2. All chunks pending unload in the unloading_chunks map
3. Closes all region file handles (flushing headers)

Returns the number of chunks saved.

impl ChunkMap

pub fn update_player_status(&self, player: &Player)

Updates the player’s status in the chunk map.

pub fn remove_player(&self, player: &Player)

Removes a player from the chunk map.

impl ChunkMap

pub(super) fn collect_scheduled_block_ticks( world: &World, tickable_chunks: &TickingChunkSnapshot, current_tick: i64, ) -> Vec<BlockTick>

Collects this tick’s block batch from sparse live-container heads.

pub(super) fn collect_scheduled_fluid_ticks( world: &World, tickable_chunks: &TickingChunkSnapshot, current_tick: i64, ) -> Vec<FluidTick>

Collects this tick’s fluid batch after block callbacks have run.

pub(super) fn execute_scheduled_block_ticks( world: &Arc<World>, ready_block_ticks: Vec<BlockTick>, )

Executes ready scheduled block ticks in their collected order.

pub(super) fn execute_scheduled_fluid_ticks( world: &Arc<World>, ready_fluid_ticks: Vec<FluidTick>, )

Executes ready scheduled fluid ticks in their collected order.

impl ChunkMap

pub fn new_with_storage( chunk_runtime: Arc<Runtime>, world: Weak<World>, dimension_type: DimensionTypeRef, sea_level: i32, storage: Arc<ChunkStorage>, generator: Arc<ChunkGeneratorType>, generation_pool: Arc<ThreadPool>, ) -> Self

Creates a new chunk map with a custom storage backend.

This allows using different storage implementations (disk, RAM, etc.).

pub(crate) fn new_with_storage_and_timed_tickets( chunk_runtime: Arc<Runtime>, world: Weak<World>, dimension_type: DimensionTypeRef, sea_level: i32, storage: Arc<ChunkStorage>, generator: Arc<ChunkGeneratorType>, generation_pool: Arc<ThreadPool>, chunk_encoding_pool: Arc<ThreadPool>, timed_chunk_tickets: TimedChunkTickets, ) -> Self

pub(crate) fn light_work_window_gate(&self) -> Arc<LightWorkWindowGate>

pub fn start_generation_refill_loop(self: &Arc<Self>)

Starts the notify-driven generation refill loop for this chunk map.

pub fn stop_generation_refill_loop(&self)

Stops the generation refill loop. Active generation tasks are left alone.

pub(crate) fn notify_generation_refill(&self)

fn run_or_notify_generation_refill(&self)

pub fn with_full_chunk<F, R>(&self, pos: ChunkPos, f: F) -> Option<R>

where F: FnOnce(FullChunkRef<'_>) -> R,

Executes a function with access to a fully loaded chunk. Returns None if the chunk is not loaded or not at Full status.

pub(crate) fn active_full_chunk_holder( &self, pos: ChunkPos, ) -> Option<Arc<ChunkHolder>>

Returns the active holder for a fully loaded chunk.

fn lookup_active_holder(&self, pos: ChunkPos) -> Option<Arc<ChunkHolder>>

pub(crate) fn is_block_ticking_full_chunk_loaded(&self, pos: ChunkPos) -> bool

Returns whether an active full chunk is currently block ticking.

pub(crate) fn is_block_ticking_full_chunk_simulated( &self, pos: ChunkPos, ) -> bool

Returns whether the chunk is in block simulation range with confirmed r1 readiness.

pub(crate) fn with_chunk_at_status<F, R>( &self, pos: ChunkPos, status: ChunkStatus, f: F, ) -> Option<R>

where F: FnOnce(&Chunk) -> R,

Executes a function with access to a chunk at the requested generation status or later. Returns None if the chunk is not loaded or has not reached the requested status.

pub(crate) fn add_chunk_ticket( &self, pos: ChunkPos, ticket: ChunkTicket, ) -> ChunkTicketRevision

pub(crate) fn add_chunk_tickets( &self, positions: &[ChunkPos], ticket: ChunkTicket, ) -> Option<ChunkTicketRevision>

pub(crate) fn remove_chunk_ticket( &self, pos: ChunkPos, ticket: ChunkTicket, ) -> ChunkTicketRevision

pub(crate) fn remove_chunk_tickets( &self, positions: &[ChunkPos], ticket: ChunkTicket, ) -> Option<ChunkTicketRevision>

fn replace_chunk_ticket( &self, old_pos: ChunkPos, old_ticket: ChunkTicket, new_pos: ChunkPos, new_ticket: ChunkTicket, )

pub(crate) fn is_ticket_revision_committed( &self, revision: ChunkTicketRevision, ) -> bool

pub(crate) async fn with_full_chunks_in_radius<F, R>( self: &Arc<Self>, center: ChunkPos, radius: u8, f: F, ) -> Option<R>

where F: FnOnce() -> R,

Drives startup scheduling until a full square is ready, runs f, then removes the temporary ticket.

pub(crate) fn place_portal_ticket(&self, ticket_position: BlockPos)

Adds or refreshes vanilla’s post-portal chunk ticket.

pub(crate) fn tick_timed_tickets(&self)

Advances gameplay-owned timed chunk tickets by one server tick.

pub(crate) fn persistent_chunk_tickets(&self) -> PersistentChunkTickets

fn can_timed_ticket_expire(&self, pos: ChunkPos) -> bool

fn full_square_is_ready(&self, center: ChunkPos, radius: i32) -> bool

pub fn broadcast_changed_chunks(&self)

Broadcasts pending block changes and completed light changes to nearby players.

pub fn tick_game( self: &Arc<Self>, world: &Arc<World>, tick_count: u64, random_tick_speed: u32, runs_normally: bool, ) -> ChunkMapGameTickTimings

Processes chunk updates, ticks chunks, and executes ready scheduled ticks.

Arguments

• world - The world reference (needed for executing scheduled tick callbacks) Game tick: broadcasts block changes, ticks chunks (random + scheduled ticks).

Runs on the main game tick loop. Does NOT handle chunk generation or unloading.

pub(crate) fn advance_scheduling(self: &Arc<Self>) -> ChunkMapSchedulingTimings

Ticks block entities in tickable full chunks. Commits a ready scheduling epoch and forks the next background epoch.

This must run at a gameplay lifecycle boundary or during startup before gameplay begins. It never waits for a running epoch; the previously committed chunk state remains authoritative until that epoch is ready at a later boundary.

fn commit_scheduling_epoch( self: &Arc<Self>, epoch: PreparedChunkSchedulingEpoch, ) -> ChunkMapSchedulingTimings

fn spawn_scheduling_epoch( self: &Arc<Self>, ticket_manager: ChunkTicketManager, applied_revision: ChunkTicketRevision, holders_to_schedule: Vec<(Arc<ChunkHolder>, ChunkTicketLevel)>, )

fn prepare_scheduling_epoch( self: &Arc<Self>, ticket_manager: ChunkTicketManager, applied_revision: ChunkTicketRevision, holders_to_schedule: Vec<(Arc<ChunkHolder>, ChunkTicketLevel)>, ) -> PreparedChunkSchedulingEpoch

pub fn tickable_full_chunk_positions(&self) -> Vec<ChunkPos>

Returns full chunks whose simulation level currently allows entity ticks.

pub(crate) fn is_entity_ticking_full_chunk_loaded(&self, pos: ChunkPos) -> bool

Returns whether the chunk is full and currently allows entity ticks.

pub(crate) fn block_entity_tick_state_if_owned( &self, holder: &Arc<ChunkHolder>, pos: BlockPos, expected: &SharedBlockEntity, ) -> Option<BlockStateId>

Captures the live state for an exact block-entity owner in an eligible holder.

Holder data remains the outermost guard; the Full chunk view then acquires section and storage reads in the same order as block-state writers.

pub(crate) fn reconcile_block_entity_ticker( &self, holder: &Arc<ChunkHolder>, pos: BlockPos, )

Re-selects one ticker from the live state without retaining a component lock across behavior selection or manager registration.

pub(crate) fn activate_block_entities<'a>( &self, holders: impl IntoIterator<Item = &'a Arc<ChunkHolder>>, )

fn finish_block_entity_unloads(&self)

pub fn place_ender_pearl_ticket(&self, chunk: ChunkPos)

Places (or refreshes) the timeout ticket that keeps a thrown ender pearl’s chunk loaded and ticking while it flies.

Mirrors vanilla ServerPlayer.placeEnderPearlTicket → chunkSource.addTicketWithRadius(ENDER_PEARL, chunk, 2). Re-placing the same ticket resets its countdown rather than stacking duplicates.

impl ChunkMap

pub fn request_chunks( self: &Arc<Self>, request: ChunkRequest, ) -> ChunkRequestHandle

Adds tickets for a chunk request and returns a pollable handle.

The returned handle owns the tickets. Holder creation and generation scheduling are handled by chunk scheduling epochs.

pub fn request_chunk( self: &Arc<Self>, pos: ChunkPos, status: ChunkStatus, ticket_kind: ChunkTicketKind, ) -> ChunkRequestHandle

Requests one chunk at status.

pub fn request_square( self: &Arc<Self>, center: ChunkPos, radius: u8, status: ChunkStatus, ticket_kind: ChunkTicketKind, ) -> ChunkRequestHandle

Requests a square of chunks centered on center.