ChunkAPI: гибкое хранение данных чанков без взлома кода

ChunkAPI: гибкое управление данными чанков в Minecraft без взлома ванильного кода

Каждый разработчик модов для Minecraft рано или поздно сталкивается с необходимостью хранить собственные данные внутри чанков. Будь то информация о температуре биома, состоянии руды или прогрессе магического алтаря — стандартный мир хранит лишь базовые блоки и сущности. Раньше для этого приходилось вручную патчить сетевые пакеты, переопределять загрузчик Anvil и писать десятки строк низкоуровневого кода. ChunkAPI переворачивает этот подход, предлагая чистый API для добавления кастомных данных без вмешательства в ванильные классы.

Зачем нужен ChunkAPI

Основная мотивация проекта — избавить моддеров от рутины. Модификация пакетов S21PacketChunkData и S26PacketMapChunkBulk требовала несовместимых изменений, которые ломались при каждом обновлении игры. ChunkAPI берёт на себя сериализацию, сетевую синхронизацию и сохранение в NBT, оставляя вам только логику самой информации. Лицензия LGPLv3 позволяет свободно использовать библиотеку в любых проектах, а оригинальная разработка FalsePattern гарантирует стабильность.

Ключевые возможности API

Библиотека построена вокруг менеджера данных чанка — ChunkDataManager. Он не реализует функциональность сам, а предоставляет три интерфейса для разных сценариев:

• PacketData — синхронизация данных с сервера на клиент. Если ваша информация нужна только на серверной стороне, этот интерфейс можно смело пропустить.
• ChunkNBTData — сохранение и загрузка из корневого NBT чанка. Обязателен для постоянных данных, которые должны пережить перезагрузку мира.
• SectionNBTData — аналог предыдущего, но ориентированный на хранение информации по блокам внутри секции 16x16x16. Вызывается для каждого ExtendedBlockStorage отдельно, что гораздо эффективнее при работе с плотными структурами.

Разработчику остаётся лишь реализовать нужные интерфейсы и зарегистрировать их через ChunkDataRegistry на фазе init. При необходимости можно отключить отдельные менеджеры вызовом disableDataManager в postInit, но это рекомендуется только опытным авторам, понимающим внутренние механизмы.

Кстати, если вы хотите быстро собрать тестовую среду с ChunkAPI, обратите внимание на лаунчер foxygame.net — он позволяет загружать моды прямо из меню и автоматически подтягивает все зависимости, что особенно удобно для экспериментов с новыми API без ручной возни с файлами.

Как данные попадают в сеть

ChunkAPI аккуратно перезаписывает форматы двух ключевых пакетов, сохраняя обратную совместимость на уровне протокола. Новый формат S21PacketChunkData включает:

• 4 байта — X-координата чанка
• 4 байта — Z-координата
• 1 байт — флаг принудительного обновления
• 2 байта — маска ExtendedBlockStorage
• 4 байта — длина несжатых данных
• 4 байта — длина сжатых данных
• n байт — сжатый блок данных

Для пакета S26PacketMapChunkBulk структура немного сложнее: сначала идёт количество чанков (2 байта), затем массив длин несжатых данных, общая длина сжатого потока и сами сжатые данные, после чего следуют заголовки чанков с координатами и маской. Внутри сжатого блока все менеджеры упаковываются последовательно: сначала их количество, а затем для каждого — длина имени в UTF-8, само имя и массив байтов с данными менеджера.

Такая схема позволяет передавать десятки независимых наборов данных в одном чанке, не создавая коллизий между модами. Вам не нужно думать о порядке байтов или версионировании — ChunkAPI делает всё сам.

Хранение на диске и совместимость

Для долговременного хранения используется стандартный NBT-формат чанка. Интерфейс ChunkNBTData получает на вход корневой тег, а SectionNBTData — тег конкретной секции. Это полностью повторяет внутреннюю структуру региона, поэтому данные не теряются при обновлении мира или переносе сохранения.

Отдельно стоит отметить, что API не навязывает собственную систему хранения. Типичный паттерн — добавить поле в класс чанка через миксин и использовать его как контейнер. Такой подход сохраняет производительность и не заставляет переписывать существующую архитектуру мода.

Зависимости и начало работы

Для работы ChunkAPI необходимы две библиотеки: FalsePatternLib и UniMixins. Первая предоставляет общие утилиты, а вторая — прослойку для корректной работы миксинов на разных версиях Minecraft. Обе зависимости автоматически подгружаются большинством современных лаунчеров, поэтому ручная установка обычно не требуется.

Регистрация менеджеров выполняется на этапе инициализации мода. Достаточно вызвать ChunkDataRegistry.registerManager(new MyDataManager()), и все чанки начнут автоматически обрабатывать ваши данные при загрузке и сохранении. Никаких дополнительных хуков или событий подписывать не нужно.

Почему это важно для экосистемы модов

ChunkAPI решает давнюю проблему совместимости. Раньше два мода, расширяющих чанки, могли конфликтовать из-за перезаписи одних и тех же классов. Теперь каждый мод регистрирует свой независимый канал данных, а библиотека заботится о корректной упаковке. Это особенно критично для крупных модпаков, где одновременно работают десятки модификаций, изменяющих мир.

Разработчики получают чистый, документированный контракт: реализуйте интерфейс, опишите сериализацию — и ваши данные будут бесшовно путешествовать между сервером и клиентом, сохраняться в регионах и не мешать соседям по чанку.

Заключение

ChunkAPI — это именно тот инструмент, которого не хватало сообществу моддеров. Он убирает рутинную обвязку вокруг чанков и позволяет сосредоточиться на творческой части разработки. Чёткое разделение на интерфейсы, продуманный сетевой протокол и поддержка секционного хранения делают библиотеку универсальным фундаментом для любых проектов, от небольших утилит до глобальных изменений генерации мира. Если вы всё ещё пишете свои пакеты вручную — попробуйте ChunkAPI и почувствуйте разницу.

--- **Обновление 21.09.2026:** Добавлено 1 файл для версии 1.7.10 (Forge).