docs(render): 植被染色/覆盖层渲染/实体广告牌规格；路线图与索引回写

- 渲染.md 新增 §4.1 植被染色、§5.2 覆盖层渲染（裂纹/手持）、§5.3 实体广告牌，
  踩坑清单补视图矩阵正向旋转与灰度纹理两条
- 路线图.md：M3 破坏动画/手持渲染补齐、M3.5 实体渲染完成、M6 UI 精灵完成
- 索引.md 变更记录登记

文档/场景/渲染.md

@@ -46,20 +46,41 @@ func main() {
 - 防渗色：UV 取格子中心 inset（如 0.5px），或图集加 padding 并 clamp；mipmap 时渗色更明显。
 - 开启 mipmap + 各向异性过滤（设计.md §5.4），否则远处闪烁。
 
+### 4.1 植被染色（原版材质包兼容）
+
+- 原版材质包的 `grass_block_top`、`oak_leaves` 等是**灰度图**，绿色来自生物群系染色表 `textures/colormap/grass.png`、`foliage.png`；直接采样会得到一片灰世界。
+- 数据驱动：`blocks.json` 中带 `"tint": "grass" | "foliage"` 的方块，其全部纹理键在**图集构建后**乘以染色表颜色（注册表 `TintTextureKeys()` 提供「染色表 → 纹理键」映射）。
+- MVP 实现：取染色表**中心色**（平原绿）整图集统一乘色；**按群系逐顶点着色（温度+湿度采样染色表）后置**，届时改为顶点色/片元 uniform，不再 bake 进图集。
+- 顺序要求：染色必须在 `SetAtlas`（mipmap 生成）**之前**完成，否则 mip 链还是灰色。
+
 ## 5. 顶点格式与光照数据
 
 ```go
 type Vertex struct {
-    X, Y, Z      float32
-    U, V         float32
-    R, G, B, A   uint8
-    Sky, Block   uint8   // 各 4-bit（0–15），见 光照.md
+    X, Y, Z    float32
+    U, V       float32
+    Sky, Block uint8   // 各 4-bit（0–15），见 光照.md
 }
 ```
 
 - **光照不要写死在顶点色里然后永远不更新**：火把/太阳变化要重算（见 光照.md §5 增量重算）。
 - 两种方案：顶点色（简单）或独立 lightmap 纹理（合并 mesh 更自由，推荐后期）。
 
+### 5.2 覆盖层渲染（破坏裂纹与手持方块）
+
+- **破坏裂纹**（方块交互与动画.md §4）：对破坏目标方块叠加一个**略外扩**（≈1.004）的单位立方体，六面贴 `block/destroy_stage_N.png`（N = 进度×10，0–9），满亮无光照；`gl.PolygonOffset` 防 z-fighting。裂纹图集独立打包上传（10 阶段）。
+- **第一人称手持方块**：视图空间固定位置/尺度的单位立方体（六面 UV 取自选中槽放置方块的 top/down/side），顶点直接以视图坐标构造，绘制时只乘投影矩阵。
+- 二者与区块网格共用顶点格式与着色器，通过 `uOffset`（裂纹盒世界坐标平移）与「视图空间烘焙」（手持）区分。
+- GL 铁律沿用 §2：裂纹/手持的 VBO 上传只发生在渲染线程（tick 只算 UV）。
+
+### 5.3 实体广告牌（MVP）
+
+- 实体（僵尸/村民/动物）以**相机朝向的四边形**渲染：脚底锚点 + 高×宽，贴 `entity/*.png`（图集打包，64px tile）。
+- 顶点着色器按 `uCamRight/uCamUp` 展开单位四边形（x∈[-0.5,0.5]、y∈[0,1]，脚底为原点），`uUVMin/uUVMax` 把 UV 重映射到图集内对应实体格子；满亮不受光照影响。
+- 实体图集与方块图集分离（尺寸/采样不同）；广告牌绘制时关闭背面剔除（始终面向相机）。
+- 动物按实体 ID 轮换 cow/pig/sheep/chicken 外观（物种系统后置时改为数据驱动）。
+- 掉落物渲染后置接入。
+
 ## 6. 透明与半透明排序
 
 - **opaque pass**：不透明方块，深度写入，无排序。
@@ -118,6 +139,8 @@ type Vertex struct {
 - [ ] **远处闪烁**：没 mipmap 或各向异性。
 - [ ] **Greedy 合并含光照面**：合并后光照错误。
 - [ ] **光影包与内置输入约定不符**：黑屏/花屏 → 必须校验输入约定并回退默认。
+- [ ] **视图矩阵用正向旋转**：俯仰符号被翻转（低头渲染成抬头）——视图矩阵必须是 Rᵀ（`RotX(-pitch)·RotY(-yaw)`），正向 R 只用于模型变换。
+- [ ] **原版材质包灰度纹理不染色**：草顶/树叶全灰——见 §4.1 植被染色。
 - [ ] **光影包全局生效误伤 UI**：UI 阶段不受光影包影响（光影只作用于 3D 世界 pass）。
 
 ## 12. 验证与测试

文档/索引.md

@@ -205,3 +205,4 @@
 | （UI 还原） | 新增 场景/UI还原.md：客户端 UI 一比一还原原版（界面清单、像素布局、截图验收） | — |
 | （原生素材包+命名） | 素材包原生 pack.mcmeta 格式直接支持（设计.md §1.2/§1.3）；资源路径对齐原版命名；项目名「年糕历险记」+ NSIS 中文安装（构建与发布.md §8） | — |
 | （实现里程碑） | M0–M3、M5 完成，M3.5/M4/M6 进行中：GL 客户端构建运行、Mod 热更新、多人同步 MVP、中文 UI（详见 路线图.md 状态） | — |
+| （客户端渲染修复） | 渲染.md 新增 §4.1 植被染色（原版灰度草/叶图集染色）、§5.2 覆盖层渲染（破坏裂纹/手持方块）、§5.3 实体广告牌；修复相机视图矩阵俯仰符号翻转（视角不跟随鼠标根因）；HUD 换原版心/鸡腿/热键栏精灵 | — |

文档/路线图.md

@@ -10,11 +10,11 @@
 | M0 骨架 | 目录、模块接口、配置、日志、主循环 | 已完成 |
 | M1 世界 | 区块、确定性生成、光照、存档 | 已完成 |
 | M2 渲染 | 网格、图集、透明排序、视锥剔除 | 已完成 |
-| M3 游戏性 | 方块交互、物理、背包、配方、实体 | 已完成 |
-| M3.5 生态与文明 | 动物、村民（会建造）、僵尸敌对 | 进行中（实体/僵尸/蓝图/红石/工作台数据已完成；村民交易与动物繁殖后置） |
+| M3 游戏性 | 方块交互、物理、背包、配方、实体 | 已完成（破坏裂纹叠加与手持方块渲染已补齐；合成台/熔炉 GUI 后置） |
+| M3.5 生态与文明 | 动物、村民（会建造）、僵尸敌对 | 进行中（实体 AI/僵尸/村民/工作台数据/客户端实体渲染已完成；村民交易与动物繁殖后置） |
 | M4 多人 | 网络协议、同步、防作弊 | 进行中（协议/服务器/客户端网络层/区块流/方块广播/实体位置广播/心跳已完成；插值渲染与完整防作弊后置） |
 | M5 Mod | 加载器、Lua API、沙箱、资源合并 | 已完成 |
-| M6 打磨 | 音频、UI、性能、崩溃恢复、发布 | 进行中（音频/UI/光影包/存档/安装脚本已完成；性能池化与安装包构建后置） |
+| M6 打磨 | 音频、UI、性能、崩溃恢复、发布 | 进行中（音频/UI 精灵与主菜单/光影包/存档/安装脚本已完成；合成台与背包界面、性能池化与安装包构建后置） |
 
 ## M0 骨架
 
@@ -132,3 +132,4 @@
 | 日期 | 变更 | 作者 |
 | --- | --- | --- |
 | （初始建立） | 初版：M0–M6 里程碑与验收标准；补充快速原型路径 | — |
+| （客户端打磨） | 客户端渲染修复与还原：相机视图矩阵（俯仰符号）、植被染色（草/树叶）、原版 HUD 精灵（心/鸡腿/热键栏/准星）、破坏裂纹 3D 叠加、第一人称手持方块、实体广告牌渲染（僵尸/村民/动物）、主菜单字号修复；M3 破坏动画与实体渲染相关条目更新 | — |