Skip to content

Storage Format

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

CIS is the durable Chunkis format. The runtime currently writes CIS version 11 with magic 0x43495334 (CIS4). Codec decoding accepts versions 7 through 11; normal runtime use expects current semantics after migration.

Dimension paths

Chunkis keeps its files under a dimension-local chunkis directory:

Dimension CIS region directory
minecraft:overworld <save>/chunkis/regions/
every other dimension <save>/dimensions/<namespace>/<path>/chunkis/regions/

The same chunkis directory contains global_ids.json (block/state mapping) and portal_chunks.nbt. Cross-dimension portal links live at <save>/chunkis/portal_links.nbt.

Vanilla paths are intentionally resolved separately: Nether MCA uses DIM-1, End MCA uses DIM1, and custom dimensions use dimensions/<namespace>/<path>. This distinction matters during MCA import.

Region file layout

Each r.<regionX>.<regionZ>.cis file stores a 32 × 32 chunk region (1024 slots):

0 .. 8191          1024 header entries: (offset:int, length:int)
8192 .. dataEnd    compressed chunk payloads; allocator may reuse gaps
dataEnd .. EOF     optional allocation metadata and footer

The header is always 8192 bytes. The optional footer records reusable free blocks and reuse counters. If a process stops after truncating the footer but before writing its replacement, the next open reconstructs allocation state from the header instead of trusting incomplete metadata.

Chunk payloads

CisStorage.prepareSave(...) encodes the delta and flushes mapping changes. writePrepared(...) then either:

  • clears the region entry for an empty delta; or
  • compresses the encoded bytes with Zstd level 3 and writes them to the owning RegionFile.

global_ids.json is part of the format contract: state IDs in payloads require its persisted mapping to decode consistently.

v11 semantics

Version 11 stores authoritative chunk snapshots in the block payload. A missing block entry means air during restore. It also uses a 12-bit palette width, supports sparse and dense section encodings, and has explicit sentinels for uniform/default-sparse sections.

Changing this interpretation is a format change, not a local optimization. It requires a new CIS version, an explicit CisVersionMap edge, migration coverage, and documentation.

Corruption and maintenance

  • Normal load may clear a corrupt stored entry after decode failure so it cannot repeatedly poison runtime loads.
  • Migration uses loadWithoutClearing(...) so a bad source payload is preserved for diagnosis instead of erased during an upgrade attempt.
  • Region compaction rewrites live entries and validates the replacement before swapping it in.
  • At paranoid debug level, writes are read back and compared against the compressed bytes just written.

Clone this wiki locally