处理器注册表

基本信息

行为

HandlerRegistry 持有两个静态列表与一个静态字节计数，全部在 Mixin 清单 列出的 mixin 里被回调。它是 Foundation 真正对外的「扩展点」：其他 mod 实现 api 包里的接口并调用 registerChunkPacketHandler / registerBlockPacketHandler， 其数据就会自动被编进 S21 / S22 / S23 封包，无需自己写 mixin。

静态状态

注册方法

静态回调（供 mixin 调用）

注意 S23 的读写都先建 BlockPacketInfo 再回写（syncBlockPacketInfo）， handler 在读路径上拿到的是已经填好 x/y/z、block/metadata 仍为默认的 info， 因此 handler 必须负责把 block 与 metadata 写回去；S22 的读写则直接用 mixin 自己的 blockPackets 数组元素。

chunk 封包的「长度前缀分片」协议

writeChunkPackets 的核心是给每个 handler 分配一个定长切片，并在切片前 4 字节回填 真实写入长度：

1. buffer.putInt(chunkPacketHandlers.size()) —— 先写 handler 数量。
2. 对每个 handler：sliceStart = position + 4（给长度前缀留位）→ 临时把 limit 设为 sliceStart + handler.maxBytesPerChunk() → buffer.slice() 得到该 handler 的独立 ByteBuffer → 恢复原 limit/position → 调用 handler.writeChunkPacket(chunk, sendUpdates, flagSubChunks, slice) → 取 slice.position() 作为 sliceLength → buffer.putInt(sliceLength) → position(sliceStart + sliceLength)。
3. 返回 buffer.position() 作为整个缓冲区的最终大小，交给 S21PacketChunkData 做 inflate/deflate（源码注释即说明这一点）。

源码注释解释了为什么不能直接复用 ByteBuffer：ByteBuffer.slice(int, int) 需要 Java 13，而本项目目标是 JVM 8。

readChunkPackets 是完全对称的逆过程：先读 count，然后对 i 从 0 到 count-1 按注册顺序索引 chunkPacketHandlers.get(i)，读该分片的 sliceLength，切出 ByteBuffer 交给 handler.readChunkPacket。

关键约束

注册顺序必须在客户端与服务端完全一致

readChunkPackets 的索引来源是网络上的 count 与顺序，不是某个 handler 的标识符。 这意味着：

• 客户端与服务端注册 handler 的顺序与数量必须逐项一致，否则数据被错配到别的 handler 上解析（不报错，但区块数据损坏）。
• 只在单侧注册 handler 会直接导致协议错位。

handler == null 分支实际不可达

readChunkPackets 里的防御检查：

ChunkPacketHandler handler = chunkPacketHandlers.get(i);
if (handler == null) {
    Foundation.LOG.error("Received unregistered chunk packet data");
    continue;
}

chunkPacketHandlers 是 ArrayList，元素只会是 registerChunkPacketHandler 传入的非 null 处理器；而当线上 count 大于本地列表长度时，get(i) 抛的是 IndexOutOfBoundsException 而非返回 null。因此该 error 日志分支在当前实现下 不会触发，实际故障会以未捕获异常形式出现。

BlockPacketInfo 位于根包而非 api 包

api.BlockPacketHandler 的方法签名使用 com.gtnewhorizons.foundation.BlockPacketInfo， 而该类位于根包 com.gtnewhorizons.foundation（BlockPacketInfo.java），不在 com.gtnewhorizons.foundation.api 内。实现该接口的外部 mod 必须 import 根包。

数值

相关条目

• 内置区块处理器 - 6 个内置 handler 及其字节预算
• 封包数据流 - 注册表在 S21/S22/S23 链路上的调用位置
• Mixin 清单 - 调用本注册表的具体 mixin 方法
• 兼容性与门控 - 外部 mod 接入本注册表的前提条件