LitematicaFolia - серверная Litematica для Paper и Folia

LitematicaFolia - это плагин для серверов Майнкрафт на Paper и Folia, который добавляет полноценную поддержку формата .litematic на стороне сервера. Если ты админ сервера и твои игроки используют Litematica для строительства, ты знаешь проблему: на Paper этот мод работает через /setblock фолбэк, который тупо дропает NBT тайл-энтити, сущности и отложенные тики блоков. А еще лимит чата в 20 блоков в секунду и кик после 30 команд. LitematicaFolia решает это раз и навсегда.

Какую проблему решает плагин

Litematica - это клиентский мод на Fabric. Его серверные компаньоны (Servux, Syncmatica) тоже только под Fabric. На Paper единственное, что получают игроки - это /setblock фолбэк, который:

• теряет NBT тайл-энтити (сундуки, печки, таблички остаются пустыми)
• не сохраняет сущности (рамки, вагонетки)
• не переносит отложенные тики блоков (редстоун-механика ломается)
• упирается в лимит чата - макс 20 блоков в секунду
• после ~30 команд в секунду Paper кикает игрока

LitematicaFolia - это недостающая серверная половина для Paper. Он:

• читает и пишет .litematic v6 и v7 через встроенный NBT-парсер, без лишних зависимостей
• вставляет схемы через Folia's RegionScheduler, по одному чанку за раз, сохраняя TileEntity, Entity, PendingBlockTick и PendingFluidTick
• прогоняет старые файлы через DataFixerUpper при вставке
• поддерживает протокол Servux, так что обычный клиент Litematica может вставлять схемы напрямую на сервер, как если бы он работал с Fabric + Servux

Детали вставки, которые стоит знать

Наблюдатели и поршни отрабатывают во втором проходе, физика отложена. Есть лимит на размер сплиттера (128 MiB по умолчанию), так что схемы под 40+ MiB не падают. Самое тяжелое, что я тестировал - 4.2 миллиона блоков за 9.5 секунд. Прямая вставка (Direct Paste) выдала 870k блоков с 6,500 тайл-энтити за 5.6 секунд. Никаких повреждений файлов регионов.

Команды на Brigadier, весь плагин под MIT лицензией.

Что нового в 0.5.1 (MC 26.2)

Первый релиз под 26.2. Главный фикс: Direct Paste теперь работает на ядрах линейки Leaves (Lophine, Leaves и т.д.). Эти серверные ядра сами обрабатывают протокол Servux и молча глотали каналы servux:* плагина - загрузка просто зависала без ошибок. Теперь плагин перехватывает свои каналы при старте. На обычном Paper или Folia это ничего не меняет.

Протестировано на Paper 26.2 (build 62), собранном из исходников Folia 26.2 с полным end-to-end Direct Paste, и Lophine 26.2 в продакшене.

Установка плагина LitematicaFolia

1. Скачай LitematicaFolia-<version>-all.jar
2. Кинь в папку plugins/
3. Перезапусти сервер (или сделай hot-reload)
4. Если хочешь Direct Paste, включи protocol.enableServuxBridge: true в plugins/LitematicaFolia/config.yml

Требуется Paper или Folia 26.2 (форки вроде Luminol, Lophine, Purpur тоже подходят) и Java 25. На 26.1.x используй версии 0.4.x.

Настройка клиента для Direct Paste

Игрокам понадобятся Fabric Loader 0.16+, Fabric API, MaLiLib и Litematica - все под версию Minecraft.

В Litematica: Configs -> Generic tab выставь:

Настройка	Значение
ENTITY_DATA_SYNC	true
PASTE_USING_SERVUX	true
PASTE_USE_FILL_COMMAND	false
PASTE_ALWAYS_USE_FILL	false
ENTITY_DATA_SYNC_BACKUP	true

ENTITY_DATA_SYNC - та самая настройка, о которую спотыкаются новички. Если она выключена, Litematica молча отклоняет наш пакет S2C_METADATA, падает обратно на /setblock спам, и игрока кикает. В интерфейсе ничего не говорит об этом.

Также нужно назначить клавишу для executeOperation в Configs -> Hotkeys - по умолчанию она не назначена.

Рабочий процесс:

1. Открой меню Litematica (M)
2. Load Schematics -> выбери файл
3. Loaded Schematics -> Create Placement -> позиционируй схему
4. Возьми инструмент Litematica (палка)
5. Переключи Tool Mode на "Paste Schematic in world"
6. Посмотри на размещение и нажми клавишу executeOperation

Проверено на litematica-fabric-1.21.11-0.27.6.

Если используешь Velocity

Прямая вставка (Direct Paste) упирается в лимит пакетов по умолчанию (5 MiB/s) на схемах больше ~10 MiB. В velocity.toml:

[packet-limiter]
decompressed-bytes-per-second = -1

compression-threshold оставь как есть (256).

Для старых файлов, где DataVersion сильно отстает от текущей, дай клиентам больше времени на DataFixer + загрузку:

-Dpaper.playerconnection.keepalive=120

Команды плагина LitematicaFolia

Команда	Разрешение
/litematica paste <file> [x y z] [yaw] [--no-entities] [--no-physics]	litematica.paste
/litematica save <name> <x1 y1 z1> <x2 y2 z2>	litematica.save
/litematica materials <file>	litematica.materials
/litematica list [--filter <glob>]	litematica.use
/litematica info <file>	litematica.use
/litematica cancel [ticket]	litematica.paste
/litematica reload	litematica.admin

Конфигурация плагина LitematicaFolia

paste:
  maxBlocksPerChunkTask: 8192
  allowEntities: true
  allowTileEntities: true
  allowPendingTicks: true
  deferredPhysics: true
  observersLast: true
  runDataFixer: true
  minDataVersion: 2586

protocol:
  enableServuxBridge: false        # выключено по умолчанию
  enableEasyPlace: false
  maxDirectPasteSize: 134217728    # 128 MiB, увеличь для схем под 32M+ блоков

Сравнение с альтернативами для Майнкрафт сервера

	LitematicaFolia	Litematica /fill фолбэк	FAWE
Поддержка .litematic	нативная	нет (только клиент)	не нативная
Серверная вставка	да	нет	да, для .schem
Прямая вставка с клиента	да, через Servux	нет	нет
Сохранение TileEntity	полный NBT	никакое	частичное
Сохранение сущностей	полный NBT	никакое	частичное
Отложенные тики блоков	да	нет	нет
Поддержка Folia	нативная	зависит от сервера	частичная
Риск кика по лимиту чата	нет	высокий	нет

FAWE все еще лучше для общего редактирования мира; этот плагин заточен только под .litematic. Если тебе нужно именно строить по схемам с сохранением всех NBT-данных - LitematicaFolia твой выбор.

Лицензия и благодарности (техническая часть)

MIT лицензия, LGPL-clean: никакой код из апстрима не копировался. Парсинг формата основан на публичной спецификации Litematica, с litemapy и Lite2Edit как референсами. Проводной формат Servux совпадает байт-в-байт с sakura-ryoko/servux, перепроверен как неизменный на 26.2-0.11.1.

Сделано exo для сети ekaii, с заимствованием паттернов из AxiomPaperPlugin и PaperMC. Litematica - работа maruohon, протокол Servux - sakura-ryoko.