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

第二层：场景专篇（核心开发手册，共 20 篇）

数据层

文档	主题
区块管理.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	单测/集成/基准、race/fuzz、CI、质量门禁
构建与发布.md	构建、go:embed、交叉编译、版本、发布清单
路线图.md	里程碑 M0–M6、验收标准

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

AI 助手规则

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

CLAUDE.md — Claude Code
.cursorrules — Cursor
.github/copilot-instructions.md — GitHub Copilot

目录规划

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

打包发布（NSIS 中文安装器）

正式发布用 NSIS 3 生成简体中文安装器，产品名统一为「年糕历险记」（见构建与发布.md §8）。

根目录一键脚本（双击即可；需 tools/ 下 zig 或 MinGW；安装包另需 tools/nsis/）：

脚本	作用	产物
`打包-dev.bat`	开发构建（`gl` + `dev`）	`bin/mc-client.exe`
`打包-安装包.bat`	Release + NSIS 安装器	`dist/年糕历险记-Setup-v<版本>.exe`

打包-dev.bat
打包-安装包.bat
打包-安装包.bat 1.0.0

等价 PowerShell：scripts/build.ps1、scripts/make_nsis.ps1 -Version 1.0.0。

产物：dist/年糕历险记-Setup-v1.0.0.exe

手动步骤（不依赖一键脚本）：

构建发布版可执行文件：
```
pwsh -File scripts/build.ps1 -Release
```
用 NSIS 3 编译安装脚本（scripts/installer.nsi，NSIS 可放 tools/nsis/ 或加入 PATH）：
```
makensis /DVERSION=1.0.0 scripts/installer.nsi
```

安装器特性（全中文向导界面）：

安装器 exe / 卸载器使用游戏 logo 图标（与游戏本体一致，素材包 pack.png 经 scripts/make_icon.ps1 生成 cmd/client/icon.ico，规范见构建与发布.md §8「安装器图标」）；
组件页可选快捷方式：「创建桌面快捷方式」「创建开始菜单快捷方式」（默认勾选，可取消）；
完成页可选安装完成后立即运行（默认勾选，可取消）；
开始菜单含「年糕历险记」与「卸载年糕历险记」入口；
卸载时保留 worlds/ 存档与 logs/ 日志目录。

备选：便携 zip 安装包（无 NSIS 环境时）：pwsh -File scripts/make_installer.ps1 -Version 1.0.0，解压后运行 安装.bat（同样支持可选桌面快捷方式、可选立即运行）。

素材包 / 光影包怎么放（内容包统一格式）

素材包、光影包与功能 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%

README.md Unescape Escape

年糕历险记（NianGao Adventure）— Go 体素沙盒（类 Minecraft）

状态

文档中心

第一层：总纲