文档	主题
设计.md	总体设计规范、素材库位置、Mod 加载、无限世界、易遗漏功能检查表
架构.md	分层架构、模块依赖、并发模型、核心数据流
开发规范.md	Go 编码规范、Git 工作流、评审清单、ADR

数据层

文档	主题
区块管理.md	Chunk 数据结构、生命周期状态机、异步生成流水线、锁与并发
世界生成.md	噪声选型、确定性地形、生成管线、跨区块安全
世界生态.md	生物群系、树/植被/矿物后处理、随机刻、液体流动

表现层

文档	主题
渲染.md	GL 线程亲和、mesh 策略（face culling / greedy）、纹理图集、透明排序、默认光影系统与光影包替换
光照.md	天空光+方块光、BFS 传播、光源移除 relight、火把跨区块
音频.md	3D 音效衰减、声源上限、分类音量、音频库线程

交互层

文档	主题
物理与碰撞.md	AABB 逐轴解算、移动模式、非立方体碰撞、实体推挤
方块交互与动画.md	DDA 射线拾取、破坏进度、方块耐久、crack 动画、放置、方块状态
红石与方块更新.md	延迟更新队列、迭代上限、红石信号、活塞推动

玩法层

文档	主题
实体系统.md	实体生命周期、AI 与限频寻路、自然生成、掉落物
物品与背包.md	物品栈、背包规则表、配方索引、工具耐久、容器方块实体
UI与输入.md	UI 渲染架构、拖拽/Shift 状态机、多语言、键位与鼠标
UI还原.md	客户端 UI 一比一还原原版：界面清单、像素级布局规格、字体/纹理、截图验收
村民系统.md	村庄生成、职业村民日程 AI、程序化建造房子（特色）、交易
工作台与合成表.md	3×3 合成网格、配方索引匹配、tag 展开、批量合成、防刷
挖矿与矿物.md	矿物深度分布、工具门槛、速度公式、掉落/烧炼/附魔、矿洞照明
动物体系.md	动物行为 AI、繁殖与数量控制、剪羊毛/牛奶/蛋、驯服骑乘
僵尸与敌对生物.md	敌对生物样板：AI 状态机、攻击模型、白天燃烧、村庄围攻

网络层 / 稳定层

文档	主题
多人同步.md	服务器权威、实体插值、区块流限流、防作弊细化
存档与持久化.md	保存时机、diff-only、异步保存池、原子写入、迁移
性能与内存.md	Go GC 坑、对象池、锁粒度、channel 边界、pprof 流程
热更新.md	Mod/素材/光影不重启热更新：分层矩阵、generation 版本化、原子切换与回滚

文档	主题
网络协议.md	帧格式、消息目录、序列化规则、同步与防作弊
存档格式.md	level.dat、region、chunk 序列化、压缩、迁移
Mod开发指南.md	Mod 结构、manifest、Lua API、权限沙箱

新增或修改文档后，必须同步更新 文档/索引.md。

AI 助手规则

仓库根目录提供面向 AI 编码助手的规则文件，统一引导助手先查文档索引、遵循开发规范再动手：

目录规划

遵循设计.md 第 1 节：cmd/、internal/、assets/、mods/、resourcepacks/、worlds/、config/、logs/ 等。

素材包、光影包与功能 Mod 共用同一套内容包格式（manifest + type，见设计.md §1.3），统一投放到 mods/：

素材包（type: "resource"）覆盖默认材质；支持原生 Minecraft 格式（pack.mcmeta + assets/…）直接放置；默认素材包已在 resourcepacks/texture-pack-default1.20.5-26.2/。
光影包（type: "shader"）覆盖着色管线；不下载光影包也没关系——未安装时使用系统默认光影（内置，见渲染.md §9）。
初版材质：随客户端 go:embed 嵌入，无素材包时生效。

Languages

C 65.7%

C++ 16%

Zig 15.3%

NSIS 1.2%

HTML 0.8%

Other 0.9%