Цели
Целью является предоставление способа добавления пользовательских данных к чанкам без необходимости модификации каких-либо ванильных классов. API также предоставит простой способ реализации пользовательской сериализации/десериализации данных как для сетевого взаимодействия, так и для формата NBT. Опциональной целью является предоставление способа регистрации DFU (Data Fixer Units) для пользовательских данных, но это не является приоритетом.
Нецели
Не является целью предоставление какой-либо системы колбэков/хуков для чего-либо, кроме сохранения/загрузки и сетевого кода. Любое дополнительное поведение должно быть реализовано в моде, использующем ChunkAPI.
API не предоставляет хранилище. Пользователь должен реализовать свою собственную систему хранения. Хорошим примером является использование mixin для добавления поля в класс чанка и использование этого поля для хранения данных.
Мотивация
Изменение данных пакетов чанков требовало несовместимых модификаций сетевых пакетов, класса чанка и загрузчика чанков Anvil, что является значительной работой для простой функции. Данный мод предоставляет способ добавления пользовательских данных к чанкам без необходимости самостоятельного изменения каких-либо ванильных классов.
API и спецификация
API предоставляет способ добавления пользовательских данных к чанкам и способ регистрации пользовательских сериализаторов для этих данных.
ChunkDataManager
Сам класс ChunkDataManager является основным классом, используемым для управления регистрациями, но не реализует функциональность самостоятельно. Для этого необходимо использовать интерфейсы PacketDataManager, ChunkNBTDataManager и SectionNBTDataManager, включенные в класс ChunkDataManager.
ChunkDataManager.PacketData
Данный интерфейс используется для синхронизации данных с сервера на клиент. Если ваши данные требуются только на сервере, вы можете не реализовывать этот интерфейс.
ChunkDataManager.ChunkNBTData
Данный интерфейс используется для сохранения/загрузки данных из NBT чанка. Это требуется, если вы хотите сохранять постоянные данные между перезагрузками мира. Примечание: если вы храните данные на уровне блоков в чанке, вам следует использовать SectionNBTData, так как он разработан с учетом внутреннего формата чанка.
ChunkDataManager.SectionNBTData
Данный интерфейс в основном идентичен ChunkNBTData, но предназначен для хранения данных на уровне блоков в чанке. Вместо вызова один раз на чанк, он вызывается один раз на секцию чанка (16x16x16 блоков, класс ExtendedBlockStorage).
ChunkDataRegistry
Это место, где вы фактически регистрируете свой менеджер. Все регистрации должны выполняться внутри фазы init. Вы также можете отключить определенные ID менеджеров, вызвав disableDataManager, но это не рекомендуется и должно использоваться только при полном понимании последствий. Все отключения должны выполняться внутри фазы postInit.
Спецификация пакетов
ChunkAPI модифицирует ванильные пакеты S21PacketChunkData и S26PacketMapChunkBulk, переопределяя их стандартные форматы.
Все размеры в таблицах ниже указаны в байтах.
Новый формат S21PacketChunkData:
| Размер (байты) | Тип данных | Название |
|---|---|---|
| 4 | int | Позиция X |
| 4 | int | Позиция Z |
| 1 | bool | Force Update |
| 2 | short | Маска ExtendedBlockStorage |
| 4 | int | Длина несжатых данных |
| 4 | int | (n) Длина сжатых данных |
| n | byte[n] | Сжатые данные |
Новый формат S26PacketMapChunkBulk:
| Размер (байты) | Тип данных | Название |
|---|---|---|
| 2 | short | (n) Количество чанков в пакете |
| n * 4 | int[n] | Длины несжатых данных чанков |
| 4 | int | (m) Длина сжатых данных |
| 1 | bool | Содержит данные skylight |
| m | byte[m] | Сжатые данные |
| n * 10 | (int, int, short)[n] | Заголовки чанков (x, z, маска ebs) |
В обоих случаях сжатые данные заполняются через метод ChunkDataRegistryImpl.writeToBuffer. Структура этих данных следующая:
| Размер (байты) | Тип данных | Название |
|---|---|---|
| 4 | int | (n) Количество менеджеров |
| n * varying | MGRData | Данные менеджера |
Данные менеджера (MGRData):
| Размер (байты) | Тип данных | Название |
|---|---|---|
| 4 | int | (n) Длина имени менеджера |
| n | UTF-8 строка | Имя менеджера |
| 4 | int | (m) Длина данных менеджера |
| m | byte[m] | Данные менеджера |
