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

一个用 Go 实现的可扩展、可 Mod 的类 Minecraft 体素沙盒游戏。
游戏名 / 窗口标题 / 安装包统一使用中文名 **年糕历险记**（Windows 安装包为 NSIS 中文安装，见 [构建与发布.md](文档/构建与发布.md) §8）。

## 状态

项目处于**实现阶段**：M0–M3、M5 里程碑已完成（世界/渲染/交互/Mod/热更新），
M3.5/M4/M6 进行中（见 [路线图.md](文档/路线图.md)）。
客户端/服务器可构建运行（客户端需 C 工具链：`tools/` 放 zig 或 MinGW，用 `scripts/build.ps1` 构建）。

## 文档中心

所有开发文档统一存放于 [`文档/`](文档/) 目录，**入口为 [`文档/索引.md`](文档/索引.md)**（书签式目录，含决策树，AI 助手先读它）。

### 第一层：总纲

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

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

**数据层**

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

**表现层**

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

**交互层**

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

**玩法层**

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

**网络层 / 稳定层**

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

### 第三层：协议与格式

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

### 第四层：流程与治理

| 文档 | 主题 |
| --- | --- |
| [测试与质量.md](文档/测试与质量.md) | 单测/集成/基准、race/fuzz、CI、质量门禁 |
| [构建与发布.md](文档/构建与发布.md) | 构建、go:embed、交叉编译、版本、发布清单 |
| [路线图.md](文档/路线图.md) | 里程碑 M0–M6、验收标准 |

> 新增或修改文档后，必须同步更新 [`文档/索引.md`](文档/索引.md)。

## AI 助手规则

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

- [`CLAUDE.md`](CLAUDE.md) — Claude Code
- [`.cursorrules`](.cursorrules) — Cursor
- [`.github/copilot-instructions.md`](.github/copilot-instructions.md) — GitHub Copilot

## 目录规划

遵循 [设计.md](文档/设计.md) 第 1 节：`cmd/`、`internal/`、`assets/`、`mods/`、`resourcepacks/`、`worlds/`、`config/`、`logs/` 等。

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

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

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