fc151e7c07
- 相机视图矩阵按 R_cam^T·T(-pos) 正确推导（旧布局非正交，非零视角下场景塌缩为灰屏） - UI 片元着色器改为纹理×颜色（旧实现丢弃纹理 RGB，彩色纹理全白） - UI 纹理与图集 mipmap：图集补齐 2 次幂、UI 上传不生成 mipmap（NPOT 不完整纹理采样纯白） - 网格构建持一次读锁（旧实现每格邻居查询各加锁约 40 万次/区块，出生区块迟迟无网格， 玩家透过脚下的洞看到地下横截面——进游戏黑屏主因）；脏区块按距离排序优先构建 - 开启背面剔除（CW 正面）：区块边界面向未加载邻居的内侧面不再以暗色出现在视野里 - 出生逻辑：等区块加载后定位地表出生，相机略微俯视 - dev 截图测试：-shot 等待玩家所在 5×5 区块网格就绪再拍（48s 兜底），先测试后打包 - 安装器改为按用户安装到 LOCALAPPDATA（Program Files 无写权限导致启动即崩） - dev 截图工具独立成 devshot_gl.go
年糕历险记（NianGao Adventure）— Go 体素沙盒（类 Minecraft）
一个用 Go 实现的可扩展、可 Mod 的类 Minecraft 体素沙盒游戏。 游戏名 / 窗口标题 / 安装包统一使用中文名 年糕历险记（Windows 安装包为 NSIS 中文安装，见 构建与发布.md §8）。
状态
项目处于实现阶段：M0–M3、M5 里程碑已完成（世界/渲染/交互/Mod/热更新），
M3.5/M4/M6 进行中（见 路线图.md）。
客户端/服务器可构建运行（客户端需 C 工具链：tools/ 放 zig 或 MinGW，用 scripts/build.ps1 构建）。
文档中心
所有开发文档统一存放于 文档/ 目录，入口为 文档/索引.md（书签式目录，含决策树，AI 助手先读它）。
第一层：总纲
| 文档 | 主题 |
|---|---|
| 设计.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/ 等。
素材包 / 光影包怎么放（内容包统一格式）
素材包、光影包与功能 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嵌入，无素材包时生效。