Skip to content

Developer Guide

Jump to bottom
Liparakis edited this page Jul 12, 2026 · 5 revisions

Developer Guide

Repository map

Area Start with Responsibility
data model common/.../core/ChunkDelta.java chunk payload shape and codec contracts
format constants common/.../core/model/CisConstants.java CIS version and encoding constants
storage storage/.../io/CisStorage.java encode, compress, read, write, clear
region layout storage/.../io/region/RegionFile.java 32×32 region allocation and compaction
migration migration/.../migrator/CisStorageMigrator.java versioned storage rewrite
tracking fabric/.../world/tracking/state/GlobalChunkTracker.java live owned dirty deltas
save safety fabric/.../world/tracking/ownership/DeltaPersistenceGuard.java reject unreconstructable payloads
load/restore fabric/.../world/restoration/core/ChunkRestorer.java apply saved state to WorldChunk
vanilla bridge fabric/.../mixin/storage/ThreadedAnvilChunkStorageMixin.java load source resolution and synthetic NBT
MCA import fabric/.../integration/migration/offline/PreLaunchMigrationCoordinator.java pre-launch authority takeover

Change rules

Changing ChunkDelta or its codec

Ask whether the change alters stored bytes or their interpretation. If yes, bump the CIS version, add an explicit migration edge, preserve old decode support where applicable, and add a focused codec/migration test. Do not rely on Java field order or an undocumented palette layout.

Changing save ownership

Trace every caller of the ownership predicate. A new field must not accidentally cause vanilla writes to be suppressed. Keep ChunkDeltaOwnership and DeltaPersistenceGuard aligned: a payload that establishes ownership also needs a safe restoration baseline.

Changing restore behavior

Keep Fabric mixins thin and move decision logic into normal classes when possible. Restore runs on the server thread; do not introduce asynchronous chunk-section, block-entity, or entity mutation. After direct section writes, section counts must represent final palette state.

Changing network behavior

Full restored chunks use vanilla ChunkDataS2CPacket. Do not add another full-delta client channel unless vanilla demonstrably cannot synchronize one narrowly defined state; document that missing state and test it against a remote client.

Validation

# Windows
gradlew.bat fabric:test
gradlew.bat fabric:build

# Linux/macOS
./gradlew fabric:test
./gradlew fabric:build

Run fabric:runGameTest when the world test server is not already using the shared test world. For runtime changes, test a real persisted world through: first load, edit, save, restart, reload, and remote-client visibility.

Review checklist

  • Does the change preserve unknown/auxiliary metadata or explicitly state what is dropped?
  • Can a sparse payload reconstruct terrain without relying on current world generation?
  • Does an error include chunk coordinates, dimension/path, and operation context?
  • Are writes/cancellations still gated by explicit ownership?
  • Are docs and migration tests updated when the persistence contract changes?

Clone this wiki locally