-
Notifications
You must be signed in to change notification settings - Fork 0
Migration and Versioning
Chunkis has two separate migration systems. They share CIS storage, but they solve different problems and run at different times.
The migration module owns the explicit version graph. Current CIS version is 11.
| Edge | Meaning |
|---|---|
| 7 → 8 | dense-section palette width changed from 8 to 12 bits |
| 8 → 9 | chunk metadata for structure starts/references was added |
| 9 → 10 | NBT changed from individually compressed blobs to raw length-prefixed data inside outer compression |
| 10 → 11 | payloads became authoritative compact snapshots and the v11 section codec was finalized |
CisVersionMap.plan(...) accepts only ascending, contiguous paths. Downgrades and missing paths fail explicitly.
CisStorageMigrator scans canonical r.<x>.<z>.cis files, visits every one of the 1024 slots in each region, loads old payloads without clearing them, and re-saves only chunks below the target version. A clean completed scan writes .chunkis-cis-version; the marker is trusted only when it exactly matches the requested target version.
One corrupt chunk does not stop the scan, but it is counted as a failure and prevents writing the success marker.
MCA import belongs to fabric because it needs Minecraft registries, dimension definitions, and vanilla NBT. PreLaunchMigrationCoordinator runs it before integrated-server startup.
For every configured dimension it inspects both:
- vanilla chunk regions:
region/r.<x>.<z>.mca; - vanilla external entity regions:
entities/r.<x>.<z>.mca.
The importer builds an authoritative CIS snapshot for each present chunk, validates the written result, and only then allows CIS to become authoritative for that dimension.
Real source MCA files are never simply overwritten. OfflineMcaCisTranslator.retireRegionFile(...):
- ignores/deletes only a 0-byte placeholder;
- refuses to overwrite an existing
.backup; - copies the source to
<name>.mca.backup; - verifies backup size matches the source;
- deletes the source only after verification succeeds.
If CIS is already present at pre-launch, the coordinator treats it as authoritative and removes stale live vanilla region/entity files. That is a takeover rule: do not place partially imported CIS data next to vanilla data and expect both to remain active.
Migration failure is a startup failure, not a warning. Continuing into a world after an incomplete import would make authority ambiguous and risks data loss.