Storage Format

Ownership

• CisConstants defines format constants.
• CisStorage implements the storage engine.
• RegionFile implements region layout and allocation.
• CisMapping persists mappings.
• ChunkisStoragePaths resolves storage paths.

Current Layout

• Each dimension uses one chunkis/regions/ directory.
• Region filenames use the format r.<regionX>.<regionZ>.cis.
• global_ids.json stores the block/state mapping beside the region directory.
• Each RegionFile contains a fixed 8192-byte header with 1024 (offset,length) entries.
• Live chunk payload bytes follow the header.
• An optional allocation metadata footer stores reusable holes and reuse counters.

Versioning

• CisConstants.MAGIC is 0x43495334.
• CisConstants.VERSION is 11.
• Region compaction is supported and validated before replacement.
• Older files without allocation metadata fall back to header-based reconstruction.

Runtime Behavior

Save paths eventually call CisStorage.prepareSave(...) and writePrepared(...). Load paths decode the bytes back into ChunkDelta objects.

Migration uses the same storage engine instead of a separate file parser.

Important Behaviors

• Empty deltas delete stored entries instead of writing placeholder payloads.
• Normal load clears corrupt stored entries after decode failure.
• Migration can bypass that clearing path when preserving the source is required.
• Storage format changes must document their migration impact, not only codec changes.

Key Classes

• common/src/main/java/io/liparakis/chunkis/core/model/CisConstants.java
• storage/src/main/java/io/liparakis/chunkis/storage/io/CisStorage.java
• storage/src/main/java/io/liparakis/chunkis/storage/io/region/RegionFile.java
• storage/src/main/java/io/liparakis/chunkis/storage/io/region/CisRegionInspector.java