Skip to content

Load and Restore Pipeline

Jump to bottom
Panayiotis Stylianopoulos edited this page Jul 12, 2026 · 4 revisions

The load path resolves Chunkis-owned chunk state during loading, builds temporary NBT for vanilla deserialization, attaches the decoded delta, and restores chunk contents into live WorldChunk instances.

Responsibilities

  • ThreadedAnvilChunkStorageMixin resolves sources and coordinates synthetic NBT.
  • CisNbtUtil creates the NBT carrier used by vanilla deserialization.
  • ChunkSerializerMixin attaches the delta to the proto chunk.
  • ChunkRestorer replays Chunkis-owned data into the live chunk.
  • PendingChunkMutationSuppression and ChunkMutationTrackingScope prevent replay from being recorded as new gameplay mutation.

Flow

  1. Load resolves a delta from tracker memory, unload cache, completed CIS prefetch, or CIS storage.
  2. CisNbtUtil.buildLoadChunkNbt(...) chooses persisted-base-backed NBT or a synthetic empty-shell root.
  3. Vanilla converts the NBT into SerializedChunk and then ProtoChunk.
  4. ChunkSerializerMixin attaches the ChunkDelta and configures restore suppression.
  5. When the chunk becomes live, ChunkRestorer.restore(...) replays blocks, block entities, and pending entities.
  6. Touched section block occupancy counts are recalculated.
  7. Lighting, heightmaps, and follow-up networking are refreshed.

Entity payloads are removed from synthetic vanilla chunk NBT before deserialization. EntityReplayCoordinator is the sole server-side materializer for CIS-owned entities, preventing duplicate entity loading.

Important Cases

  • Block-entity-only sparse payloads without a persisted base are rejected.
  • Full-baseline snapshots and persisted-base-backed sparse payloads use different load baselines.
  • Restore may occur through a wrapped full-chunk path or the normal promotion path.
  • Confirmed CIS entries may be decoded by a prefetch worker before normal load consumes them.
  • Misses retain the synchronous fallback path.
  • Clean loaded chunks may retain one bounded server-thread base snapshot until their first mutation.
  • Player join can queue a bounded 5×5 CIS-data prefetch without force-loading world chunks.

Clone this wiki locally