Skip to content

Architecture

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

Architecture

Chunkis is organized as a layered persistence system. Minecraft integration lives in the fabric module, while storage and migration logic remain independent from Fabric wherever possible.

Module Structure

Module Responsibility
common Shared data models, codecs, compression, constants, and debug structures
storage CIS storage engine, region files, mappings, allocation metadata, and inspection
migration CIS version upgrades and storage-backed migrations
fabric Minecraft entrypoints, mixins, tracking, restoration, networking, and MCA migration

Runtime Flow

flowchart TD
    Minecraft["Minecraft runtime"] --> Fabric["fabric module"]
    Fabric --> Tracking["Mutation tracking"]
    Fabric --> Save["Save pipeline"]
    Fabric --> Load["Load and restore pipeline"]
    Fabric --> Sync["Client synchronization"]
    Save --> Storage["storage module"]
    Load --> Storage
    Storage --> Common["common module"]
    Migration["migration module"] --> Storage
Loading

Persistence Pipeline

  1. Minecraft mutates a loaded chunk.
  2. Chunkis tracking records relevant changes in a ChunkDelta.
  3. The save pipeline determines whether the delta is Chunkis-owned.
  4. The delta is encoded and written to CIS region storage.
  5. During loading, Chunkis resolves the appropriate delta from memory, cache, prefetch, or disk.
  6. Vanilla deserialization creates the initial chunk structure.
  7. Chunkis restores blocks, block entities, entities, and metadata into the live chunk.
  8. Derived Minecraft state is refreshed after restoration.

Ownership Model

Not every ChunkDelta attached to a chunk is automatically authoritative. Chunkis distinguishes between attached state, Chunkis-owned state, restorable state, dirty state, and persisted-base state.

This prevents weaker or stale data from overwriting authoritative data and allows vanilla reads to remain available while selectively suppressing vanilla writes.

See Delta and Ownership Model.

Storage

CIS storage uses dimension-specific region directories and provides region file management, chunk payload allocation, compression, mappings, allocation metadata, region inspection, corruption handling, and storage format versioning.

See Storage Format.

Save and Load

The save path captures authoritative chunk state and writes it through CisStorage.

The load path resolves the best available Chunkis state, builds the NBT required by vanilla deserialization, attaches the decoded ChunkDelta, restores Chunkis-owned data, suppresses mutation tracking during replay, and refreshes derived chunk state.

See Load and Restore Pipeline.

Migration

Chunkis supports CIS-to-CIS version upgrades and vanilla MCA-to-CIS migration. MCA migration produces authoritative CIS snapshots before normal world runtime begins.

See Migration and Versioning.

Architecture Principles

  • CIS is authoritative only when ownership has been explicitly established.
  • Storage mechanics should remain independent from Minecraft integration.
  • Vanilla serialization is reused where practical.
  • Restore replay must not be mistaken for fresh gameplay mutation.
  • Format changes require migration support and documentation.
  • Persistence behavior must be validated with unit tests and game tests.

Clone this wiki locally