ChunkAPI

ChunkAPI - технический API-мод для Minecraft Java Edition 1.7.10. Он позволяет разработчикам добавлять собственные данные в чанки без ручной переделки ванильных классов, сетевых пакетов, событий сохранения и загрузчиков мира. Обычному игроку ChunkAPI не добавит блоки, предметы или новые механики, зато может быть обязательной зависимостью другого мода или большой сборки модов.

Библиотека особенно полезна в сложных технических проектах, где к каждому чанку нужно привязать дополнительное состояние. Это могут быть параметры механизмов, сведения о генерации, служебные метки или данные отдельных блоков. API берет на себя их сериализацию, сохранение в NBT и передачу с сервера на клиент. ChunkAPI, или Чанк АПИ, встречается в старых сборках вроде GT New Horizons и Photon Optimization.

Совместимость и назначение

Параметр	Значение
Тип проекта	Библиотечный мод и API
Версия игры	Minecraft 1.7.10
Загрузчик	Forge
Установка	На клиент и сервер
Актуальная версия проекта	0.8.3
Дата выпуска версии 0.8.3	21 мая 2026 года
Лицензия	LGPL-3.0-only
Разработчик оригинальной версии	FalsePattern

Поддержка Fabric, Quilt, NeoForge и новых версий Minecraft не заявлена. ChunkAPI создавался именно для Forge 1.7.10 и продолжает развиваться внутри экосистемы старого моддинга. В 2026 году последовательно вышли версии 0.8.0, 0.8.1, 0.8.2 и 0.8.3.

Если лаунчер сообщает, что ChunkAPI отсутствует, обычно это означает, что библиотека требуется одному из установленных модов. Самостоятельно добавлять ее в случайную сборку смысла нет. Сначала стоит проверить зависимости конкретного проекта и совпадение версий на клиенте и сервере.

Лицензия LGPLv3

ChunkAPI распространяется по лицензии LGPL-3.0-only.

Зачем нужен ChunkAPI

В Minecraft 1.7.10 добавление собственных данных в чанки связано сразу с несколькими внутренними системами. Разработчику приходится учитывать формат сетевых пакетов, класс чанка, загрузчик Anvil, сохранение NBT и синхронизацию состояния между сторонами. Для одной небольшой функции это довольно большой объем низкоуровневого кода.

ChunkAPI закрывает эту задачу единым интерфейсом. Мод регистрирует менеджер данных, определяет правила чтения и записи, а библиотека подключает его к нужным этапам сохранения и сетевого обмена. При этом разработчику не требуется самостоятельно изменять ванильные классы Minecraft.

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

Цели проекта

Основная цель - дать модам способ добавлять пользовательские данные в чанки без прямого изменения ванильных классов. API также упрощает собственную сериализацию и десериализацию данных:

• при отправке информации по сети;
• при сохранении данных в формате NBT;
• при загрузке чанков после повторного открытия мира;
• при работе с данными всего чанка;
• при хранении информации для отдельных секций и блоков.

Дополнительная, но не приоритетная цель проекта - регистрация DFU для пользовательских данных.

Что ChunkAPI не делает

ChunkAPI не является универсальной системой событий. Обратные вызовы и хуки относятся только к сохранению, загрузке и сетевому коду. Любое дополнительное поведение должен реализовать сам мод, который использует библиотеку.

Готового хранилища API тоже не предоставляет. Разработчик самостоятельно решает, где держать сведения во время работы игры. Например, через mixin можно добавить поле в класс чанка и хранить данные в этом поле, а ChunkAPI использовать для записи, чтения и синхронизации.

Это важное разделение ответственности. Библиотека управляет форматом и моментом обмена данными, но не определяет внутреннюю модель конкретного мода.

API и структура данных

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

ChunkDataManager

ChunkDataManager - основной класс для управления регистрациями. Сам по себе он не реализует хранение или синхронизацию. Нужное поведение подключается через интерфейсы PacketDataManager, ChunkNBTDataManager и SectionNBTDataManager, находящиеся внутри класса ChunkDataManager.

Такое разделение позволяет не реализовывать ненужные части API. Серверные данные не обязательно отправлять клиенту, а временную информацию не обязательно сохранять в мир.

ChunkDataManager.PacketData

Интерфейс PacketData используется для синхронизации пользовательских данных с сервера на клиент. Если сведения нужны только серверной логике, этот интерфейс можно не реализовывать.

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

ChunkDataManager.ChunkNBTData

Интерфейс ChunkNBTData отвечает за сохранение и загрузку данных через NBT чанка. Он нужен для постоянных значений, которые должны переживать закрытие мира, перезапуск сервера или выгрузку чанка из памяти.

Если информация хранится отдельно для каждого блока, вместо ChunkNBTData следует использовать SectionNBTData. Этот вариант лучше соответствует внутренней структуре чанков Minecraft и не заставляет обрабатывать весь чанк одним большим набором.

ChunkDataManager.SectionNBTData

SectionNBTData похож на ChunkNBTData, но рассчитан на данные отдельных блоков. Метод вызывается не один раз для целого чанка, а отдельно для каждой секции размером 16x16x16 блоков, представленной классом ExtendedBlockStorage.

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

ChunkDataRegistry

В ChunkDataRegistry регистрируются созданные менеджеры. Все регистрации должны выполняться во время фазы init.

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

Спецификация пакетов

ChunkAPI изменяет ванильные пакеты S21PacketChunkData и S26PacketMapChunkBulk, полностью заменяя их стандартный формат. Поэтому библиотека должна присутствовать на обеих сторонах соединения. Клиент без ChunkAPI не сможет корректно разобрать пакет сервера, использующего измененный формат.

Все размеры в таблицах указаны в байтах.

Новый формат S21PacketChunkData

Размер	Тип данных	Поле
4	int	Координата X
4	int	Координата Z
1	bool	Принудительное обновление
2	short	Маска ExtendedBlockStorage
4	int	Длина несжатых данных
4	int	Длина сжатых данных (n)
n	byte[n]	Сжатые данные

Новый формат S26PacketMapChunkBulk

Размер	Тип данных	Поле
2	short	Количество чанков в пакете (n)
n * 4	int[n]	Длины несжатых данных чанков
4	int	Длина сжатых данных (m)
1	bool	Наличие данных освещения неба
m	byte[m]	Сжатые данные
n * 10	(int, int, short)[n]	Заголовки чанков: X, Z и маска EBS

В обоих пакетах сжатый блок заполняется методом ChunkDataRegistryImpl.writeToBuffer. Сначала записывается число зарегистрированных менеджеров, затем идут данные каждого менеджера.

Содержимое общего блока данных

Размер	Тип данных	Поле
4	int	Количество менеджеров (n)
Зависит от данных	MGRData	Данные менеджеров

Данные одного менеджера

Размер	Тип данных	Поле
4	int	Длина имени менеджера (n)
n	Строка UTF-8	Имя менеджера
4	int	Длина блока данных (m)
m	byte[m]	Данные менеджера

Имя менеджера фактически служит идентификатором блока. Поэтому разработчикам зависимых модов нельзя без миграции менять такие идентификаторы между версиями: старые сохранения могут содержать данные под прежним именем.

Установка в сборку Minecraft 1.7.10

ChunkAPI устанавливается как обычный Forge-мод: файл библиотеки помещается в папку mods вместе с обязательными зависимостями. Версии файлов должны подходить для Minecraft 1.7.10.

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

После добавления библиотеки лучше проверить существующий мир на копии. Особенно это касается больших технических сборок, где несколько модов вмешиваются в загрузку чанков, сетевой код или формат сохранений.

Совместимость и возможные конфликты

ChunkAPI нельзя использовать вместе с NotEnoughIDs. Для сборок, которым требуется расширение пространства идентификаторов, рекомендуется EndlessIDs. Одновременная установка несовместимых модов может привести не только к сбою запуска, но и к проблемам при чтении мира, поэтому подменять такую зависимость без резервной копии сохранения рискованно.

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

При диагностике проблем стоит проверить:

• используется ли Minecraft 1.7.10, а не соседняя версия;
• установлен ли Forge на клиенте и сервере;
• совпадает ли версия ChunkAPI на обеих сторонах;
• присутствуют ли FalsePatternLib и UniMixins;
• отсутствует ли NotEnoughIDs;
• требует ли установленный контентный мод именно эту ветку API.

Если ошибка появляется при входе в мир или при перемещении между чанками, первым делом стоит смотреть не графические настройки, а журнал Forge. Проблемы ChunkAPI обычно связаны с зависимостями, несовпадением сборок или другим модом, который вмешивается в те же сетевые и загрузочные классы.

Зависимости

• FalsePatternLib
• UniMixins

Обе зависимости должны соответствовать Minecraft 1.7.10 и используемой версии ChunkAPI. Без них Forge может остановить запуск еще на этапе загрузки модов.

Что изменится после установки

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

Для разработчика разница существеннее: меньше прямых изменений ванильного кода, единый механизм сетевой передачи и понятное разделение данных по уровню чанка или секции. Для игрока это означает, что нужный технический мод сможет корректно сохранять состояние мира и передавать его клиенту. В старых Forge-сборках Minecraft 1.7.10 именно такие библиотеки часто удерживают вместе большой набор взаимосвязанных механик.