ChunkAPI

作者：FalsePattern

轻松管理区块中的自定义数据。

模组 Forge 前置库

介绍

介绍由机器翻译自 CurseForge 原页面，仅供参考。

一个用于向区块添加自定义数据的模组，无需费心编写自定义数据包、事件处理、加载钩子等内容。

采用 LGPLv3 许可证

最初由 FalsePattern 开发

模组徽标由 Houstonruss 制作

目标

本项目旨在提供一种向区块添加自定义数据的方法，同时无需修改任何原版类。该 API 还将提供一种简单的方法，用于实现数据的自定义序列化和反序列化，涵盖网络传输和 NBT 格式。另一个可选目标是提供一种为自定义数据注册 DFU 的方法，但这并非优先事项。

非目标

本项目不打算为保存/加载和网络代码之外的任何内容提供回调/钩子系统；任何额外行为都应在使用 ChunkAPI 的模组中实现。

该 API 不提供存储功能，用户需要自行实现存储系统。一个不错的示例是使用 mixin 在区块类中添加字段，并用该字段存储数据。

开发动机

修改区块数据包需要以不兼容的方式修改网络数据包、区块类和 Anvil 区块加载器，对于一个简单功能来说，这要做的工作太多了。该模组提供了一种向区块添加自定义数据的方法，无需你自行修改任何原版类。

API 与规范

该 API 提供了向区块添加自定义数据的方法，以及为这些数据注册自定义序列化器的方法。

ChunkDataManager

ChunkDataManager 本身是用于管理注册的主要类，但它本身不实现功能。要实现这些功能，需要使用 ChunkDataManager 类中包含的 PacketDataManager、ChunkNBTDataManager 和 SectionNBTDataManager 接口。

ChunkDataManager.PacketData

此接口用于将数据从服务器同步到客户端。如果你的数据只需在服务器端使用，可以不实现此接口。

ChunkDataManager.ChunkNBTData

此接口用于从区块 NBT 中保存/加载数据。如果你希望数据在世界重新加载后仍然保留，就必须实现此接口。注意，如果你在区块中按方块存储数据，应改用 SectionNBTData，因为它是针对区块内部格式设计的。

ChunkDataManager.SectionNBTData

此接口与 ChunkNBTData 基本相同，但专为在区块中按方块存储数据而设计。它不是每个区块调用一次，而是每个区块分区调用一次（16x16x16 个方块，ExtendedBlockStage 类）。

ChunkDataRegistry

你需要在此处实际注册管理器。所有注册操作都必须在 init 阶段完成。你也可以调用 disableDataManager 禁用特定的管理器 ID，但不建议这样做；只有在明确了解操作后果时才应使用。所有禁用操作都必须在 postInit 阶段完成。

数据包规范

ChunkAPI 会修改原版数据包 S21PacketChunkData 和 S26PacketMapChunkBulk，并覆盖它们的默认格式。

下表中的所有大小均以字节为单位。

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	1	是否包含天光数据
m	byte[m]	压缩数据
n * 10	(int, int, short)[n]	区块头 (x、z、ebs 掩码)