Skip to content

Load and Restore Pipeline

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

The load path converts a stored ChunkDelta into a live server WorldChunk without recording the replay as new gameplay mutation.

Source selection

ThreadedAnvilChunkStorageMixin resolves state in this order of availability:

  1. currently tracked runtime state;
  2. the unload cache;
  3. a completed CIS prefetch;
  4. synchronous CisStorage load.

The first three reduce disk work but do not weaken ownership rules. A clean cached delta is invalidated before it can override stronger persistent state.

Vanilla deserialization bridge

Minecraft still constructs the initial chunk through its normal NBT deserializer. CisNbtUtil.buildLoadChunkNbt(...) chooses one of two baselines:

  • Persisted-base-backed NBT when the delta carries a preserved vanilla base.
  • Synthetic empty-shell NBT when a full CIS baseline can supply the chunk contents itself.

ChunkSerializerMixin attaches the decoded delta to the proto chunk and carries restoration suppression through the conversion to WorldChunk.

Live restoration

ChunkRestorer.restore(...) runs on the server thread. For an authoritative CIS snapshot it:

  1. clears the target chunk block grid to air;
  2. removes stale block-entity state;
  3. applies saved block states directly to chunk sections;
  4. restores block entities only when their type identifier is valid;
  5. recalculates counts for touched ChunkSections;
  6. refreshes lighting and heightmaps;
  7. copies validated state into the runtime delta without marking it dirty.

The block clear is deliberate. For v11, an omitted block entry is air; leaving generated terrain behind would corrupt the snapshot contract.

Entity handling

Entity payloads are removed from synthetic vanilla load NBT. EntityReplayCoordinator is the sole server-side materializer for CIS-owned entities, avoiding duplicate loads from vanilla and Chunkis.

Pending entities are replayed once per restore operation. ChunkHolderMixin repeats the guard immediately before a vanilla full-chunk send, covering chunks that became visible before the normal promotion-path replay.

Client delivery

After restore, vanilla serializes the live server chunk as ChunkDataS2CPacket. There is no Chunkis custom full-chunk client payload. This keeps trial spawners, entities, and registry-sensitive vanilla state on the vanilla synchronization path.

Failure behavior

  • A block-entity-only sparse payload without a persisted base/full baseline is rejected before restore.
  • An invalid persisted block-entity id is skipped with context rather than fed into Minecraft's NBT deserializer.
  • Missing prefetch data falls back to synchronous storage load.
  • Restore code does not prune saved blocks merely because current world generation happens to match; world generation is not a stable persistence baseline.

Clone this wiki locally