ChunkAPI

[!INFO] Git Commit: d7b4afe | Updated: 2026-05-17

ChunkAPI（modid chunkapi）不是一个内容 mod，而是一个区块数据序列化库 + core mod。它不注册任何方块、物品、实体、维度、群系或结构，玩家在游戏里看不到它。它的全部作用是：

1. 提供一套 API，让其他 mod 把自己的一小段数据挂进区块（存盘、读盘、区块克隆、网络同步四件事统一由它分发）；
2. 用 core mod + 10 个 mixin + 4 条 Access Transformer 把原版区块读写与封包代码的挂钩点接管掉；
3. 把原版自己的区块字段（Biomes、Blocks、Add、Data、SkyLight、BlockLight、HeightMap、LightPopulated）重新实现成 6 个内建数据管理器，从而对区块数据做统一的分片打包。

mcmod.info 里唯一的描述是仓库 README 的第一句：“Chunk data, simplified.”

⚠️ 这个 mod 不是什么（对任务简报的核实）

任务简报把它描述为"被许多世界生成 mod 使用的区块/世界操作库"，并预设了"世界生成钩子、人口生成事件、方块替换/扫描、结构/特征放置、群系、配置项、事件类型"等维度。源码核实后，这些绝大部分不存在：

• 本 mod 不做任何世界生成或人口生成。IWorldGenerator、WorldGen、populate(、PopulateChunk、addGenerator、MapGenStructure、Feature、BiomeProvider、WorldProvider、registerDimension 在 src/ 下全部零命中。它是读写已有区块，不是生成区块。
• BiomeManager 不是群系。它只是把原版 Chunk.getBiomeArray() 的 256 字节搬进打包框架，不定义任何群系。因此本 wiki 没有 biome/ 目录。
• 没有方块、物品、实体、TileEntity、多方块结构、附魔、Buff/Debuff、成就、维度、热键、指令、事件。
• 不写任何配置文件。
• 不调用矿词典、不注册配方、无任何液体/能量接口。

完整的 grep 证据见页面底部"本 mod 没有的东西"。

基本信息

⚠️ @Mod 注解类在 internal 包里：com.falsepattern.chunk.internal.ChunkAPI。类名与 mod 名同名，但从源码树位置看不出 modid——modid 实际定义在 build.gradle.kts 的 mod { modid = "chunkapi" }，@Mod 里引用的是构建期生成的 Tags.MOD_ID。

⚠️ gradle.properties 里没有 coreModClass / usesMixins / accessTransformersFile / mixinPlugin——这些键全部在 build.gradle.kts 的 minecraft_fp { } 块内，用 Kotlin DSL 写法（core { coreModClass = ...; accessTransformerFile = ... }、mixin { pkg = ... }）。gradle.properties 全文只有两行：

org.gradle.caching=true
org.gradle.configuration-cache=true

全部 9 个条目

机制与设定（9 个）

API 表面总览

对外 API 只有 4 个类型，全部在 com.falsepattern.chunk.api 包：

DataManager 的 6 个嵌套接口构成"一个类可以同时是多种身份"的设计，注册表用 instanceof 逐个分流：

⚠️ PacketDataManager 的 5 个内建实现者中有 4 个是"隐式"的——MetadataManager / BlocklightManager / SkylightManager 的源码里没写 implements PacketDataManager，它们从 NibbleManager 父类继承了这个身份。LightingManager 则是唯一不参与任何网络同步的内建 manager。

6 条序列化路径

全部靠 mixin 挂载，没有任何 Forge 事件。 每条路径的详细顺序见 序列化流水线。

数据包格式

区块包体（DataRegistryImpl.writeToBuffer / readFromBuffer，小端序）：

putInt(manager 数量)
for each manager（按 ordering 升序）:
    putInt(id 的 UTF-8 字节长度) + id 字节
    putInt(该段实际长度)            ← 预留 4 字节槽后回填
    manager.writeToBuffer(chunk, subChunkMask, forceUpdate, slice)

单方块包体（writeBlockPacketToBuffer）没有长度前缀，靠注册键精确查找：

writeInt(blockPacketManagers 数量)
for each manager（按 ordering 升序）:
    writeStringToBuffer(ord.id)
    manager.writeBlockPacketToBuffer(packet, buffer)

⚠️ 两条路径的容错性不同：区块包遇到未注册的 manager 会打 error 并跳过该段（可降级），单方块包遇到未注册的 manager 直接 NPE。

核心机制速览

包体积预算

S21PacketChunkData.func_149275_c() 被 @Overwrite 成 DataRegistryImpl.maxPacketSize()，原版返回固定 12288，ChunkAPI 换成按注册表累加的动态值：

maxPacketSize 初值 4
每注册一个 PacketDataManager: maxPacketSize += 4 + id.length + 4 + maxPacketSize()

⚠️ BlockIDManager 一家就占了预算的一半（2 + 16 × (4096 LSB + 2048 MSB)），且这 5 个 manager 全部 ordering 传 0（ChunkAPI.init），实际遍历序退化成按 id 字典序。全部累加后 maxPacketSize = 197018（按公式推算）。

读档兼容闸门

这是本 mod 唯一有用户可见行为的部分。level.dat 里记录每个第三方 manager 的 version 与 uninstallMessage（跳过所有 minecraft: 前缀）。读档时 DataRegistryImpl.verifyManagerCompatibility 比对三类差异：

任一命中 → 拼风险警告 → StartupQuery.confirm(...)（用户不确认就 abort()） → ZipperUtil.backupWorld()（备份失败也 abort()）。

⚠️ 内建 6 个 manager 继承 VanillaManager 的默认实现（version() 返回 ""、三个提示方法分别返回 null/""/null），因此永远不会触发任何一类警告。

Mixin 分组与加载时机

Mixin 枚举 5 个分组，4 个 EARLY + 1 个 LATE：

⚠️ 只有 Core_NoSpool 带 avoid(Spool)——Spool 存在时被跳过的只有 AnvilChunkLoaderMixin 与 ChunkMixin，CommonCore 的 5 个 mixin 照常应用。 ⚠️ hasThermos() 的实现是 Class.forName("thermos.Thermos")。 ⚠️ 两份 mixin JSON 都没有 "mixins" 数组，类清单运行时注入。

Access Transformer（4 条）

public-f net.minecraft.world.chunk.NibbleArray field_76585_a # data
public-f net.minecraft.world.chunk.NibbleArray field_76583_b # depthBits
public-f net.minecraft.world.chunk.NibbleArray field_76584_c # depthBitsPlusFour
public net.minecraft.server.management.PlayerManager$PlayerInstance

⚠️ CoreLoadingPlugin.getAccessTransformerClass() 返回 null——AT 走 build.gradle.kts 的 accessTransformerFile，不经 IFMLLoadingPlugin。 ⚠️ 前 3 条用 -f 保留 final，但 ArrayUtil.copyArray(NibbleArray, NibbleArray) 里确实对这两个字段做了赋值（源码与 AT 不一致）。

源码中的不一致（均为原文，未修正）

本 mod 没有的东西（grep 证据）

以下断言均已在 /Users/evlos/a/mirror/ChunkAPI/src/main/java/ 下全量检索核实：

⚠️ 关于"实体"的唯一两处 net.minecraft.entity import 都与实体内容无关：AnvilChunkLoaderMixin:35 的 net.minecraft.entity.Entity（用于写盘时遍历实体列表）与 PacketChunkInfoMixin:35 的 net.minecraft.entity.player.EntityPlayer（LookingGlass 封包的接收者参数）。

因此只建了 setting/ 一个目录；block、item、entity、multiblock、enchantment、dimension、keybinding、potioneffect、biome、structure、achievement、item-effect 共 12 个维度无内容，未建目录、未在正文里留占位。

相关条目

• API 接口 — 从这里开始读
• 序列化流水线 — 6 条路径的详细顺序
• 核心 mod 与读档闸门 — 唯一有用户可见行为的部分
• Mixin 清单 — 10 个 mixin 与 verbatim SRG 别名