Architecture

Chunkis separates Minecraft integration from persistent-format mechanics. fabric decides when Minecraft events become Chunkis work; common, storage, and migration keep the data model, on-disk format, and upgrade path independent of Fabric lifecycle hooks.

Module boundaries

Module	Owns	Must not own
common	ChunkDelta, CIS codecs, compression contracts, format constants, debug model	Fabric or Minecraft runtime calls
storage	CIS region I/O, mappings, compression, region allocation, compaction	world lifecycle or mixins
migration	explicit CIS version graph and storage-backed rewrites	Minecraft world mutation
fabric	entrypoint, mixins, snapshot capture, tracking, restore, commands, MCA import	a second persistence format

Runtime flow

flowchart TD
    M["Minecraft mutation"] --> T["Fabric tracking mixins"]
    T --> D["ChunkDelta on WorldChunk"]
    D --> O{"Chunkis-owned?"}
    O -- no --> V["Vanilla save remains available"]
    O -- yes --> S["Capture + async CIS save"]
    S --> R["r.x.z.cis + global_ids.json"]
    R --> L["Load source resolution"]
    L --> N["Vanilla NBT deserialization"]
    N --> X["ChunkRestorer on server thread"]
    X --> P["Vanilla ChunkDataS2CPacket"]

Loading

The authoritative-data rule

ChunkDelta is a carrier, not proof of ownership. A delta becomes Chunkis-owned only after it has an ownership claim. ChunkDeltaOwnership.hasChunkisOwnedState(...) is the common predicate for mirroring dirty state and entering the save path.

Restorable state is deliberately broader: replay payloads or a persistence anchor can make a delta worth loading. A persistence anchor is either persisted base-chunk NBT or a full block baseline. This distinction prevents an empty placeholder attached to a live chunk from suppressing vanilla persistence.

Save-side architecture

• World and block mixins record mutations in the attached delta.
• GlobalChunkTracker keys dirty state by dimension plus chunk coordinates and refuses weaker replacements when an authoritative tracked delta already exists.
• CisSnapshotCapture creates the save-time snapshot; AsyncCisSaveManager prepares and flushes CIS writes.
• PendingVanillaSaveDecision carries the ownership decision through lower vanilla storage hooks on the same thread.
• Vanilla write cancellation is conditional. If a delta is not Chunkis-owned, Chunkis does not claim the write.

The hard safety gate is DeltaPersistenceGuard: sparse blocks, block entities, or entities without a persisted base/full baseline are rejected. Version-11 authoritative snapshots are accepted as their own baseline source.

Load-side architecture

1. ThreadedAnvilChunkStorageMixin resolves candidate state from tracker memory, unload cache, completed prefetch, or CisStorage.
2. CisNbtUtil selects persisted-base-backed NBT or builds the minimal synthetic root that vanilla can deserialize.
3. ChunkSerializerMixin carries the decoded delta through proto-chunk conversion.
4. ChunkRestorer applies the authoritative snapshot to the live WorldChunk on the server thread.
5. ChunkHolderMixin ensures pending entities are replayed before the full vanilla chunk packet is sent.

Client delivery

Chunkis does not send a second full-delta payload. The restored server chunk is serialized by vanilla into ChunkDataS2CPacket, which works for integrated and remote clients. This avoids retaining or decoding a duplicate client-side chunk representation.

Migration boundary

CIS upgrades are a migration concern: existing payloads are decoded and re-saved through the configured CisStorage. Vanilla MCA import is a pre-launch Fabric concern because it needs Minecraft registries and dimension layouts. The two paths share storage, but neither silently treats old or partial data as current authoritative data.