Interchange MVP: Java 26.2 и Sponge v3

shacraft-compat — отдельная Rust-библиотека и автономная CLI. Она действительно переносит состояния блоков в WorldStore: браузер, Control API и MCP редактируют импортированные данные, а экспорт читает текущие секции. Исходный мир хранится отдельно на диске с SHA-256. Возврат оригинала без изменений является отдельным проверенным режимом.

Целевая версия: Minecraft Java 26.2, DataVersion 4903. Библиотека не запускает JVM. Java 25 нужна только воспроизводимой проверке и генератору собственных тестовых сохранений.

Команды

Команды выполняются из корня репозитория. Все выходные пути должны отсутствовать. Каждый экспорт публикует каталог, даже экспорт одной постройки: в нём находятся world.schem и conversion-report.json. Если исходный мир уже содержит файл с этим именем, новый отчёт получает числовой суффикс; исходный файл сохраняется.

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

# Импорт остановленной копии Java-мира в новый native store.
target/release/shacraft-compat import-anvil /path/to/java-world data/imported

# Открыть импорт в браузере через сервер; в списке миров выбрать main.
target/release/shacraft-server --data data/imported --listen 127.0.0.1:4000

# После остановки сервера: все импортированные измерения вместе.
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

# Новый мир Shacraft: полноценный каталог сохранения Java 26.2.
target/release/shacraft-compat export-anvil data artifacts/new-java-world --world lobby --mode best-effort

# Sponge v3; Offset переносится в координаты native мира.
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

# Экспорт ограниченного объёма нового native мира; границы включительные.
target/release/shacraft-compat export-schem data artifacts/build --world lobby --min=-16,-1,-16 --max=16,15,16

CLI печатает отчёт JSON в stdout, ошибки — JSON в stderr и ненулевой exit code. Конвертация выполняется offline: WorldStore удерживает ту же блокировку единственного писателя, что сервер, поэтому параллельное редактирование не смешивает ревизии в одном экспорте. Сам исходный Java-мир должен быть остановленной копией: изменения размера/времени файла во время копирования обнаруживаются, но это не заменяет согласованный backup работающего Minecraft.

Что реализовано

Big-endian NBT: все 12 payload-типов, числовые разрядности, float/double bit patterns, signed arrays, Java modified UTF-8/CESU-8, Unicode, тип элемента пустого списка и неизвестные compound-поля. Duplicate compound keys, невозможные длины, превышение глубины и лишние распакованные байты отклоняются.
Anvil: level.dat, обычные измерения, dimensions/<namespace>/<path>, секционные палитры Name/Properties, современные непересекающие 64-битную границу индексы, отрицательные координаты, единообразные секции, биомы. Чтение gzip, zlib, raw и LZ4Block с checksum, включая внешние c.x.z.mcc. Запись zlib и внешний payload для chunk более 255 секторов.
Исходные entities, block_entities, POI, биомы, inventories, playerdata, datapacks, неизвестные поля и произвольные обычные файлы сохраняются на диске. Отдельные entity region-файлы действительно читаются для серверного представления, а не только копируются.
Sponge v3: Blocks, sparse palette indices и varints, block entities, сущности, полный 3D-контейнер биомов, размеры, Offset, Metadata и неизвестные теги. Контейнер Schematic вложен в корневой NBT compound согласно спецификации.
Новый Anvil-мир использует собственный маленький шаблон сохранения, созданный public API Java 26.2. В 26.2 параметры генерации и game rules находятся в data/minecraft/world_gen_settings.dat и game_rules.dat; экспорт включает эти файлы. Генератор — пустой flat overworld, creative, три стандартных измерения, биом plains в новых секциях, высота редактируемого экспорта −64…319.

Сущности между MCP и файлами мира

Импорт создаёт совместимый server.sqlite3, таблица metadata(id,json). До 4 096 сущностей становятся доступны через сервер и MCP с исходными UUID, типом, координатами и поворотом. Остальные сущности, неподходящие координаты и неподдерживаемые записи остаются в оригинале и отмечаются preserved; они не превращаются в пропавшие данные.

Исходный типизированный NBT каждой редактируемой сущности находится в compat/entities/<uuid>.nbt; его хеш закреплён в provenance. compat/native-entities.json содержит исходное серверное представление. Экспорт отдельно сравнивает fingerprint сущностей и ревизии блоков, поэтому перемещение сущности без правки блоков также отклоняет exact.

best-effort применяет создание, удаление и перемещение сущностей между chunks/regions и измерениями, а также yaw в радианах из серверного API. Явно поддерживаются свойства Health, CustomName, NoGravity, Invisible, Invulnerable, Glowing, Silent, CustomNameVisible с соответствующими числовыми/строковыми/логическими типами. Прочие свойства JSON сохраняются в shacraft-native-entities*.json и получают entity_property_unmapped; они не выдаются за vanilla NBT. Оригинальный NBT сохраняет остальные поля. AI, passengers, leash и связанные UUID не симулируются и не получают обещания точной семантики после перемещения.

Exact и best-effort

exact использует DataVersion 4903 и тот же формат, что источник. Пока любая новая ревизия блоков или изменённое серверное представление сущностей консервативно запрещает точный возврат исходного мира/постройки. Это касается даже отменённой правки, восстановившей те же блоки: ревизия не возвращается назад. Без правок все исходные файлы побайтно идентичны после проверки SHA-256.

Для нового native мира exact поддерживает представимый Sponge v3. Создание нового Anvil-окружения и межформатное преобразование требуют best-effort, поскольку свет и производные данные нуждаются в восстановлении Minecraft. Режим не содержит скрытых замен блоков. Неизвестный namespace остаётся в палитре и получает unsupported: целевому Minecraft нужен соответствующий мод, иначе он может заменить неизвестный блок воздухом.

В изменённых Anvil chunks экспорт обновляет палитры/блоки, удаляет сохранённые light arrays и heightmaps, устанавливает isLightOn=false, удаляет устаревшие block entities и scheduled ticks непосредственно в изменённых координатах, инвалидирует POI record изменённого chunk. Все эти действия перечислены в отчёте, оригиналы находятся в shacraft-source-sidecar*. Это проверенный профиль сериализации и инвалидации; прохождение полной игровой симуляции света/POI не заявляется.

При экспорте между .schem и Anvil переносится блоковая модель и явный entity bridge. Биомная сетка, block entities и произвольные metadata разных форматов пока архивируются без преобразования и получают cross_format_opaque_data. Оригинал находится рядом с результатом. Неподдерживаемые версии не мигрируют через DataFixer: exact отказывает, а best-effort сохраняет исходный DataVersion и диагностирует непроверенную схему.

Ограничения ресурсов и публикация

Не более 16 MiB распакованного NBT на chunk/постройку, глубина 64, до 1 000 000 NBT nodes. Это лимиты входных данных, не обещание 16 MiB RSS: Rust-структуры и строки занимают дополнительную память.
Sponge: максимум 262 144 вокселя; Anvil обрабатывается по одному chunk, экспортная очередь координат находится на диске, страницы секций — не более 4 096 ключей. Кэш ядра конвертера — 32 секции плюс ограниченный SQLite cache.
Entity bridge: 4 096 записей, до 16 KiB properties на сущность, ограничение сериализованного metadata 8 MiB (импортируемый entity subset ограничен 6 MiB с запасом для настроек сервера). Избыточные исходные сущности сохраняются без загрузки всех записей в серверную RAM.
До 1 000 подробных issue в отчёте; omitted_issues явно считает оставшиеся события. До 256 импортированных измерений, 1 000 000 файлов, 8 GiB на исходный файл и 1 TiB суммарного источника. Symlinks, специальные файлы, выход из каталога, вложенный в исходный мир destination и повреждённые region headers отклоняются.
Импорт строит весь новый native store, metadata и provenance в соседнем временном каталоге. Экспорт тоже использует staging. Файлы и каталоги синхронизируются, публикация — Linux renameat2(RENAME_NOREPLACE) и fsync родителя. Конвертер никогда не перезаписывает существующий destination и не меняет исходный Java-мир.
При штатной ошибке staging удаляется; после SIGKILL может остаться непубликованный .shacraft-convert-*. Повторный импорт безопасно начинается заново. Возобновление с последнего chunk после аварии ещё не реализовано. Нужен запас диска: исходный архив плюс native DB, а изменённый экспорт сохраняет ещё одну полную копию исходника.

.schem v2, legacy .schematic, vanilla structure .nbt, произвольные повороты/миграции версий и полная ванильная симуляция не включены в этот профиль. Они не распознаются как v3 по расширению файла.

Воспроизводимая проверка

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

Для последней команды нужен pinned JAR/JDK из scripts/catalog_generate.py; альтернативный JDK передаётся --java-bin /path/to/jdk25/bin. Скрипт проверяет SHA-1 JAR, компилирует compat_java.java, проверяет оригинальный, изменённый и новый Rust-экспорт через официальные NbtIo, RegionFile, SerializableChunkData, PrimaryLevelData, WorldGenSettings. Независимый nbtlib 2.0.4 сравнивает типизированные Sponge-теги. Результат и Java logs сохраняются в artifacts/compat-verification-*/verification.json.

Проверка 14 сентября 2026: 17 Rust-тестов и clippy прошли; Java прочитал exact 1 chunk / 3 блока, edited 2 chunks / 3 блока, new 2 chunks / 2 блока. Плюс тесты всех четырёх compression modes, внешнего большого chunk, границ палитр, отрицательных координат, entities move/create/remove, отказа exact после entity edits, checksum и no-overwrite. Java-проверка использует codecs, не запускает сервер, не принимает EULA и не является игровым плейтестом.

Первичные источники: Sponge v3 specification, WorldEdit AnvilChunk18, lz4-java block stream. Runtime реализация написана самостоятельно; код Minecraft и оригинальные игровые ресурсы не включены.

16 KiB Raw Blame History Unescape Escape