Developer Guide

Repository Navigation

• common/: shared model, codecs, compression, debug model, and adapter SPI
• storage/: storage engine, region files, mapping persistence, and inspection helpers
• migration/: CIS version graph and storage-backed rewrite logic
• fabric/: entrypoint, mixins, runtime tracking, restore, commands, vanilla client delivery, and offline migration

Build and Test

./gradlew build
./gradlew test
./gradlew runGameTest

Good Entry Files

• fabric/src/main/java/io/liparakis/chunkis/mixin/storage/ThreadedAnvilChunkStorageMixin.java
• fabric/src/main/java/io/liparakis/chunkis/mixin/storage/ChunkSerializerMixin.java
• fabric/src/main/java/io/liparakis/chunkis/world/restoration/core/ChunkRestorer.java
• fabric/src/main/java/io/liparakis/chunkis/world/tracking/state/GlobalChunkTracker.java
• storage/src/main/java/io/liparakis/chunkis/storage/io/CisStorage.java
• storage/src/main/java/io/liparakis/chunkis/storage/io/region/RegionFile.java
• migration/src/main/java/io/liparakis/chunkis/migrator/CisStorageMigrator.java

Editing Rules

• Persistence format and codec changes belong in common and storage, not Fabric mixins.
• Fabric mixins and world lifecycle behavior belong in fabric.
• CIS version changes should update migration support when old data must still load.
• Do not re-enable vanilla writes as an undocumented fallback.
• When persistence semantics change, update the matching Wiki pages.

Before Changing Persistence

• The save path is snapshot-based, not merely sparse-delta persistence.
• Ownership and restore suppression are correctness requirements.
• Normal runtime load expects current CIS semantics; old formats require migration support.

Test Surface

• Unit tests exist across all four modules.
• Fabric game tests cover reload, migration, metadata extraction, and asynchronous-save loss cases.