shacraft-core/docs/interop.md

Interchange MVP: Java 26.2 and Sponge v3

shacraft-compat is a separate Rust library and standalone CLI. It transfers block states into WorldStore: the browser, Control API, and MCP edit the imported data, and export reads the current sections. The source world is preserved separately on disk with SHA-256 hashes. Returning the unchanged original is a separate, verified mode.

Target version: Minecraft Java 26.2, DataVersion 4903. The library does not launch a JVM. Java 25 is needed only for reproducible verification and the generator of original test saves.

Commands

Run these commands from the repository root. All output paths must be absent. Every export publishes a directory, including exports of a single build: it contains world.schem and conversion-report.json. If the source world already contains a file with that report name, the new report receives a numeric suffix; the original file is preserved.

cargo build --release -p shacraft-compat -p shacraft-server

# Import a copy of a stopped Java world into a new native store.
target/release/shacraft-compat import-anvil /path/to/java-world data/imported

# Large playable maps: load compressed section baselines instead of block edit history.
target/release/shacraft-compat import-anvil /path/to/java-world data/imported-large --baseline

# Open the import in the browser through the server; select main in the world list.
target/release/shacraft-server --data data/imported --listen 127.0.0.1:4000

# After stopping the server: export all imported dimensions together.
target/release/shacraft-compat export-anvil data/imported artifacts/return-exact
target/release/shacraft-compat export-anvil data/imported artifacts/return-edited --mode best-effort

# New Shacraft world: a complete Java 26.2 save directory.
target/release/shacraft-compat export-anvil data artifacts/new-java-world --world lobby --mode best-effort

# Sponge v3; Offset is applied to native world coordinates.
target/release/shacraft-compat import-schem /path/to/build.schem data/build --world main
target/release/shacraft-compat export-schem data/build artifacts/build-edited --mode best-effort

# Export a bounded volume from a new native world; bounds are inclusive.
target/release/shacraft-compat export-schem data artifacts/build --world lobby --min=-16,-1,-16 --max=16,15,16

The CLI prints a JSON report to stdout; errors produce JSON on stderr and a nonzero exit code. Conversion runs offline: WorldStore holds the same single-writer lock as the server, preventing concurrent edits from mixing revisions within one export. The source Java world must itself be a copy of a stopped world: changes to file size/timestamps during copying are detected, but this does not replace a consistent backup of a running Minecraft instance.

import-anvil --baseline keeps the original source and conversion checks, but stores each nonempty section directly as the immutable world baseline. It avoids creating an undo record for every imported block. Imported revisions start at zero; later edits use the normal journal, and reset restores the imported map. Snapshots include the baseline. Unchanged exact exports and edited best-effort exports remain supported. Without this flag, the existing import behavior is unchanged.

Implemented features

• Big-endian NBT: all 12 payload types, numeric widths, float/double bit patterns, signed arrays, Java modified UTF-8/CESU-8, Unicode, the element type of an empty list, and unknown compound fields. Duplicate compound keys, impossible lengths, excessive depth, and trailing decompressed bytes are rejected.
• Anvil: level.dat, standard dimensions, dimensions/<namespace>/<path>, section palettes using Name/Properties, modern indices that do not cross 64-bit boundaries, negative coordinates, uniform sections, and biomes. Reads gzip, zlib, raw, and LZ4Block with checksum, including external c.x.z.mcc files. Writes zlib and an external payload for chunks larger than 255 sectors.
• Original entities, block_entities, POI, biomes, inventories, playerdata, datapacks, unknown fields, and arbitrary regular files are preserved on disk. Separate entity region files are parsed for the server representation, not merely copied.
• Sponge v3: Blocks, sparse palette indices and varints, block entities, entities, the full 3D biome container, dimensions, Offset, Metadata, and unknown tags. The Schematic container is nested in the root NBT compound as specified.
• New Anvil worlds use a small original save template created through the public Java 26.2 API. In 26.2, generation settings and game rules reside in data/minecraft/world_gen_settings.dat and game_rules.dat; export includes these files. Generation uses an empty flat overworld, creative mode, three standard dimensions, the plains biome in new sections, and an editable export height of −64…319.

Entities between MCP and world files

Import creates a compatible server.sqlite3 with the table metadata(id,json). Up to 4,096 entities become available through the server and MCP with their original UUIDs, types, coordinates, and rotations. Remaining entities, unsuitable coordinates, and unsupported records stay in the original and are marked preserved; the data is not discarded.

Each editable entity's original typed NBT is stored in compat/entities/<uuid>.nbt; its hash is pinned in the provenance record. compat/native-entities.json contains the original server representation. Export compares entity fingerprints and block revisions separately, so moving an entity without editing blocks also causes exact to refuse the export.

best-effort applies entity creation, deletion, and movement between chunks/regions and dimensions, as well as yaw in radians from the server API. The properties Health, CustomName, NoGravity, Invisible, Invulnerable, Glowing, Silent, and CustomNameVisible are explicitly supported with their corresponding numeric/string/boolean types. Other JSON properties are preserved in shacraft-native-entities*.json and reported as entity_property_unmapped; they are not presented as vanilla NBT. The original NBT retains its other fields. AI, passengers, leashes, and linked UUIDs are not simulated, and their exact semantics after movement are not guaranteed.

Exact and best-effort

exact uses DataVersion 4903 and the same format as the source. Currently, any new block revision or changed server entity representation conservatively prevents an exact return of the original world/build. This includes an undone edit that restored the same blocks: revisions do not go backward. With no edits, all source files remain byte-identical after SHA-256 verification.

For a new native world, exact supports representable Sponge v3 data. Creating a new Anvil environment and converting between formats require best-effort, because lighting and derived data need rebuilding by Minecraft. This mode makes no hidden block substitutions. Unknown namespaces remain in the palette and are marked unsupported: the target Minecraft installation needs the corresponding mod, or it may replace an unknown block with air.

In edited Anvil chunks, export updates palettes/blocks, removes saved light arrays and heightmaps, sets isLightOn=false, removes stale block entities and scheduled ticks at the edited coordinates, and invalidates the edited chunk's POI record. The report lists all these actions, and originals remain in shacraft-source-sidecar*. This is a verified serialization and invalidation profile; a complete in-game lighting/POI simulation pass is not claimed.

Conversion between .schem and Anvil transfers the block model and uses the explicit entity bridge. Biome grids, block entities, and arbitrary metadata from different formats are currently archived without translation and reported as cross_format_opaque_data. The original is retained alongside the result. Unsupported versions are not migrated through DataFixer: exact refuses them, while best-effort preserves the source DataVersion and reports the unverified schema.

Resource limits and publication

• At most 16 MiB of decompressed NBT per chunk/build, depth 64, and up to 1,000,000 NBT nodes. These are input limits, not a promise of 16 MiB RSS: Rust structures and strings require additional memory.
• Sponge: at most 262,144 voxels. Anvil processes one chunk at a time, keeps the export coordinate queue on disk, and pages section keys in batches of at most 4,096. The converter's core cache holds 32 sections, plus a bounded SQLite cache.
• Entity bridge: 4,096 records, up to 16 KiB of properties per entity, and an 8 MiB serialized metadata limit. The imported entity subset is limited to 6 MiB to leave room for server settings. Excess source entities are preserved without loading all records into server RAM.
• At most 1,000 detailed issues in the report; omitted_issues explicitly counts the remaining events. Limits: 256 imported dimensions, 1,000,000 files, 8 GiB per source file, and 1 TiB for the complete source. Symlinks, special files, directory escapes, a destination nested inside the source world, and corrupt region headers are rejected.
• Import builds the complete new native store, metadata, and provenance in an adjacent temporary directory. Export also uses staging. Files and directories are synchronized; publication uses Linux renameat2(RENAME_NOREPLACE) and fsync of the parent directory. The converter never overwrites an existing destination or changes the source Java world.
• On an ordinary error, staging is removed; SIGKILL can leave an unpublished .shacraft-convert-* directory. Retrying an import safely starts over. Resuming from the last chunk after a crash is not yet implemented. Allow enough disk space for the source archive plus the native DB; an edited export retains another complete copy of the source.

.schem v2, legacy .schematic, vanilla structure .nbt, arbitrary rotations/version migrations, and complete vanilla simulation are outside this profile. They are not treated as v3 based on the filename extension.

Reproducible verification

cargo test -p shacraft-compat
cargo clippy -p shacraft-compat --all-targets -- -D warnings
python3 -m venv artifacts/compat-venv
artifacts/compat-venv/bin/pip install nbtlib==2.0.4
artifacts/compat-venv/bin/python scripts/compat_verify.py

The last command needs the pinned JAR/JDK from scripts/catalog_generate.py; pass an alternative JDK with --java-bin /path/to/jdk25/bin. The script checks the JAR's SHA-1, compiles compat_java.java, and validates original, edited, and new Rust exports through the official NbtIo, RegionFile, SerializableChunkData, PrimaryLevelData, and WorldGenSettings. Independent nbtlib 2.0.4 checks compare typed Sponge tags. Results and Java logs are saved under artifacts/compat-verification-*/verification.json.

Verification on September 14, 2026: 17 Rust tests and clippy passed; Java read exact 1 chunk / 3 blocks, edited 2 chunks / 3 blocks, and new 2 chunks / 2 blocks. Checks also cover all four compression modes, a large external chunk, palette boundaries, negative coordinates, entity move/create/remove, refusal of exact after entity edits, checksum validation, and no-overwrite behavior. Java verification uses codecs without launching the Minecraft game/server or accepting its server startup prompt; it is not an in-game playtest.

Primary sources: Sponge v3 specification, WorldEdit AnvilChunk18, lz4-java block stream. The runtime implementation is original; Minecraft code and original game assets are not included.