Migration and Versioning

Chunkis has two separate migration concerns:

1. CIS-to-CIS version upgrades.
2. Vanilla MCA-to-CIS world import.

CIS-to-CIS Migration

The migration module owns the CIS version graph and storage-backed rewrites.

Current runtime CIS version: 11.

Supported version edges currently include:

• 7 → 8
• 8 → 9
• 9 → 10
• 10 → 11

Migration is forward-only. Downgrades are not supported.

A clean full-directory migration writes .chunkis-cis-version.

MCA-to-CIS Migration

The fabric module owns the pre-runtime MCA import flow through integration/migration/offline.

The process:

• Runs before integrated-server startup.
• Reads vanilla region/ and entities/ directories.
• Parallelizes independent region files with bounded worker counts.
• Produces one authoritative CIS snapshot per present chunk.
• Validates the migrated payload shape after writing.
• Retires a source .mca file as .backup only when all present chunks were handled successfully.

Important Caveats

• Normal runtime load expects current CIS semantics.
• Old CIS formats must be migrated before normal runtime use.
• MCA import is a forward takeover process, not a reversible conversion.
• If CIS data already exists, prelaunch logic may mark it authoritative and delete stale vanilla source files.

Key Classes

• migration/src/main/java/io/liparakis/chunkis/migrator/CisVersionMap.java
• migration/src/main/java/io/liparakis/chunkis/migrator/CisStorageMigrator.java
• fabric/src/main/java/io/liparakis/chunkis/integration/migration/offline/PreLaunchMigrationCoordinator.java
• fabric/src/main/java/io/liparakis/chunkis/integration/migration/offline/OfflineMcaCisTranslator.java