数据驱动注册专题¶
陷阱：旧布局与当前实现不符。 上游早期文档描述的布局是
data/<modid>/kasugalib/*.json（平铺文件、sources字段），已废弃。现行契约是索引目录data/<modid>/kasuga_lib/data_driven/加内容目录data/<modid>/kasuga_lib_content/。
参考页（本目录）：
| 文档 | 类型 | 内容 |
|---|---|---|
| schema.md | Reference | 索引清单与内容文件的字段、类型、D1–D6 规则、错误分类 |
| api-registration.md | Reference | 注册期入口 JsonTreeBuilder、索引 API、内容分派与冲突解决 |
| api-extension.md | Reference | TypeHandler 体系、BuildContext、FactoryRegistry、属性解析器 |
| api-diagnostics.md | Reference | Diagnostics 门面、/kasuga_data 命令与错误分类 |
| api-reload.md | Reference | reload API、可断言的纯函数面与调用示例 |
章节编号对照：本目录四篇
api-*.md曾是同一页api.md，按读者任务拆开后保留了原章节号， 以免全树已经写好的§N交叉引用失效 —— 因此各页内部编号不连续：
页 原章节号 api-registration.md §1 模块与包结构、§2 JsonTreeBuilder、§3 索引 API、§4 内容分派与 apply、§5 冲突解决 api-extension.md §8 TypeHandler 体系、§9 BuildContext / RegBuildContext、§10 FactoryRegistry、§11 属性解析器 api-diagnostics.md §6 Diagnostics 门面、§7 /kasuga_data errors命令、§12 错误分类api-reload.md §13 重载 API、§14 测试可断言的纯函数面、§15 调用示例
入门与教程（guides/ 节）：
| 文档 | 类型 | 内容 |
|---|---|---|
| intro.md | Tutorial | 从空目录到方块动起来的入门路径 |
| guide-content.md | How-to | 内容组织、分组继承、last-wins、验证与排查 |
| guide-extension.md | How-to | 自定义 TypeHandler / 工厂 / 属性编译器 / ReloadHandler |
原理概览见 数据驱动注册原理。
上游旧页中仍然有效的少数限制条目（模型/纹理与翻译键不自动生成、内置物品属性解析器的覆盖面、 内嵌 BE 的
data_type不能从 JSON 配置）已并入 guide-content.md 第 7 节与 guide-extension.md 第 10 节。