Skip to content

System Overview

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

System Overview

This page describes the live system, not an idealized pipeline. Chunkis manages persistence only for Chunkis-owned chunk state; vanilla remains available for data that Chunkis has not explicitly claimed.

Startup

ChunkisMod.onInitialize() installs the API, registers commands, and registers server/world lifecycle hooks. For integrated worlds, MinecraftClientMixin invokes PreLaunchMigrationCoordinator before the server starts.

For each dimension, pre-launch migration checks for vanilla region/*.mca, external entities/*.mca, and existing CIS data:

  • a new world starts under Chunkis authority;
  • existing CIS data makes CIS authoritative and stale vanilla sources are removed;
  • otherwise vanilla MCA is imported before normal loading begins;
  • any failed migrated chunk aborts startup instead of continuing with a partially migrated world.

During play

WorldChunk carries a ChunkDelta through ChunkisDeltaDuck. Mutation hooks update that delta; GlobalChunkTracker retains dirty, owned deltas by (dimension, chunkX, chunkZ) and keeps a bounded unload cache for relevant state.

The tracker protects an existing authoritative delta from a weaker incoming replacement. It is a runtime cache, not the durable source of truth after a successful CIS save.

Save

The save path captures a snapshot while the chunk is authoritative, prepares encoded bytes, then writes compressed data to the owning CIS region. CisStorage.prepareSave(...) turns an empty delta into a clear operation; writePrepared(...) removes that entry or compresses and writes its payload.

After a successful write, the delta is marked saved at the current CIS version. At server shutdown, ChunkisMod performs a final synchronous dirty-delta sweep, flushes async saves, then closes portal indexes before static runtime state is cleared.

Load and restore

Load resolves the strongest available Chunkis state, builds load NBT for vanilla, and attaches the decoded delta. ChunkRestorer then clears the target block grid, applies saved block state, restores compatible block entities, recalculates touched section counts, and refreshes lighting/heightmaps.

Restoration runs with mutation suppression. Replaying a snapshot must not create a new dirty delta. Invalid block-entity type identifiers are skipped before NBT deserialization; they are logged as bad persisted data rather than crashing the whole chunk restore.

Entities and clients

Entity replay is server-side and coordinated by EntityReplayCoordinator. Pending entities are replayed once per restore operation, including the packet-send path when needed.

The client receives the result through vanilla ChunkDataS2CPacket. ChunkHolderMixin does not mirror full chunks through a custom payload; it replays pending entities before vanilla sends the full chunk.

Primary entry points

  • fabric/.../ChunkisMod.java — common/server initialization and shutdown ordering.
  • fabric/.../ThreadedAnvilChunkStorageMixin.java — load source resolution and synthetic NBT.
  • fabric/.../ChunkSerializerMixin.java — delta transport across vanilla chunk conversion.
  • fabric/.../world/restoration/core/ChunkRestorer.java — live chunk restoration.
  • fabric/.../world/tracking/state/GlobalChunkTracker.java — live owned-delta tracking.
  • storage/.../CisStorage.java — encode, compress, region I/O, and decode.

Clone this wiki locally