1

.workbuddy-ai/memory/MEMORY.md

@@ -38,31 +38,32 @@
 
 ## 模型：mouse.glb
 
-- `body_mesh` 有**两个 surface**：`s0 "lambert1"`（身体，UV 几乎占满 0~1，贴
-  `mouse_mouse_lambert1_BaseColor.png`）、`s1 "face"`（面部，独立 UV 孤岛
-  u[0.142,0.356] v[0.038,0.238]，贴 `mouse_表情测试.png`）。
-  **面部是独立材质槽 → 换脸不用动 Blender**，`set_surface_override_material(1, mat)` 即可。
-- `mouse_表情测试.png` 是 1024² **RGBA 但 alpha 全 255**（实心蓝 #89B3FF 底 + 黑线脸），
-  不是透明覆盖层，只能当底图，不能当笔画层。
-- 面部孤岛只占 1024² 的 21%×20%，实际脸分辨率约 219×205 —— 要用 shader 把孤岛重映射到 0~1
-  再用方形小贴图，有效分辨率能翻一倍多。
+- **2026-10-02 用户重建过模型**：原来 `body_mesh` 的「`lambert1` 身体 + `face` 面部」两个材质槽已合并成
+  **一个材质 `mat_body`**，贴 `mouse_body_basecolor.png`（纯色底）。耳朵单独 `ear_l_mesh`/`ear_r_mesh`
+  用 `mat_ear` + `mouse_ear_basecolor.png`；手臂、腿、尾巴是另外的 mesh 节点（`mat_arm`/`mat_leg`/`mat_body`）。
+  旧的两张贴图 `mouse_mouse_lambert1_BaseColor.png`、`mouse_表情测试.png` **已被删除**，别在代码或测试里再引用。
+- `body_mesh` 现在 **1 个 surface、484 顶点、6 段 UV 孤岛**，UV 整体落在 u[0.004,0.996] v[0.259,0.996]。
+  最高处那段孤岛（= 头部）的 UV 是 u[0.695,0.996] v[0.682,0.996]；**没有任何一段专门的「脸」孤岛**，
+  头部是一整块连续展开。脸部矩形必须整块落在头部孤岛里，见 `tests/test_face.gd` 的 `test_face_uv_rect_inside_head_island`。
+- 量 UV 孤岛的办法：临时写一个 `@tool extends McpTestSuite` 的探针脚本，用并查集把 index buffer 连成
+  连通分量，再打印每段的 3D AABB + UV bbox；也可以把 UV 画成 64×32 的 `#`/`.` 占据图。跑完记得删掉脚本。
 
 ## 面部系统（character/player/face/ + ui/）
 
-- `face_paint.gdshader`：把孤岛 UV 重映射到 0~1，`ALBEDO = mix(base_tex, paint_tex, paint.a)`。
-  **两层必须分开**：`base_tex` = 预设脸（切换就换它），`paint_tex` = 玩家笔画层。
-  这样橡皮擦掉笔画露出来的是预设脸，而且换预设不会丢手绘。
-- `FaceRig`（挂在 Player 下）：建一张 512² 的笔画 Image + ImageTexture，`set_surface_override_material(1, mat)`。
-  存 `user://face_preset.json`（选了哪张预设）+ `user://face_paint.png`（透明底笔画层），
-  玩家出生时 `apply_saved()` 读回来。预览和玩家是**两套 FaceRig、共用一份存档**。
-- `FacePainter`：**不用 `Control._draw()`，直接改 RGBA8 字节缓冲**。画 = source-over alpha 混合，
-  擦 = 把目标 alpha 乘掉；一笔画完 `_sync()` 一次（512² 一次 1MB，别每盖一个印章就同步）。
-- 界面链路：`ui/main_menu.tscn` →「开始游戏」→ `ui/character_select.tscn`（3D 预览 + 预设缩略图 + 自己画）
-  → `ui/paint_panel.tscn`。**画布要「预设 TextureRect + 笔画 TextureRect」叠着显示** ——
-  笔画层是透明底的，只显示它等于让玩家对着空气画。
-- **「自己画」= 从空白脸起手**（`presets/face_00_blank.png`，纯色底），不是在预设上补笔。
-  空白由面板来落（`open(rig, blank_face)`）—— 它必须**先拍快照再改**，否则点「取消」还原回来的
-  是已经清空的状态。取消要同时还原**底图和笔画**，只还原笔画会留下一张白脸。
+- `face_paint.gdshader`：将 face surface 的 UV remap 到 0~1，再映射到内置图集 rect 或本地 PNG；贴图 alpha 只代表墨线覆盖率，混到 `skin_color` 上，**不写空间 `ALPHA`**（否则脸片变洞）。
+- `mouse_mouse_lambert1_BaseColor.png` 和 `mouse_表情测试.png` 的背景都精确为 RGB(137,179,255) / `#89B3FF`；表情图源 alpha 全 255，不能直接当透明度。
+- **最终做法：全身一个 shader，脸部靠 UV 矩形圈出来**。`face_paint.gdshader` 用 `body_tex`（= `mat_body` 的 BaseColor）采样全身底色，再在 `face_uv_min` / `face_uv_size` 圈出的矩形里，把表情贴图（内置图集或本地 PNG）和玩家手绘按 alpha 叠上去。透明处保持身体底色，所以**脸和周围不可能是两块不同的皮肤**。`FaceRig` 把 mat_body 的 `albedo_texture` / `albedo_color` / `roughness` / `metallic` 抄进 shader，并用 `set_surface_override_material(0, mat)`（surface 0，不再是 1）。
+- 不再需要 `skin_color` 当 shader 输入：`FaceRig` 反过来从身体贴图左上角取色写进 `skin_color`，只给画布和缩略图垫底用（导入贴图是压缩的，`get_pixel` 前要先 `decompress()`，否则报 "Can't get_pixel() on compressed image"）。
+- 表情遮罩用 `step()` 相乘而不是 `if`：采样留在统一控制流里，免得 mipmap 导数在分支里未定义。
+- **仍然不能写空间 `ALPHA`**：alpha 只代表墨线覆盖率，写进 ALPHA 会让面片变洞。
+- `face_atlas_transparent.png` 是我们自己的素材（从已删除的 `mouse_表情测试.png` 去蓝底、反混合出来的 1024² 副本），保留原图坐标排布；内置 ID `builtin:face_01/02` 对应各自的图集 rect。**原始表情图已随模型删除，这个副本现在是唯一来源，别删。**
+- **脸部矩形 = 整块头部 UV 孤岛 (0.695, 0.682) 尺寸 (0.301, 0.314)** —— 用户确认「就是整块头部」。**头部 UV 的 v 越大越靠上，而贴图第 0 行在上边，所以必须开 `face_uv_flip_y`（默认 true），否则表情上下颠倒**（用户实测确认过）。想往下挪：把 `face_uv_min.y` 钉在孤岛底边 0.682、改小 `face_uv_size.y`；**min.y 不能低于 0.682**，否则矩形会伸进下方那段孤岛（u 0.695~0.935 / v 0.293~0.674，是胸腹），表情会同时画到肚子和前胸上。
+- `face_uv_min` / `face_uv_size` / `face_uv_flip_y` 在 `player.tscn` 和 `character_select.tscn` 里**各有一份**（两个 FaceRig 节点），检视器里改只影响当前那个；要两边一致就改 `face_rig.gd` 里的默认值。`face_uv_size` 是 `Vector2`。测试 `test_face_uv_rect_inside_head_island` 会按 min/max 归一化后再判定，允许负边长当翻转用。
+- `FaceRig` 保存 `user://face_preset.json` 中的 expression ID 和 `user://face_paint.png` 暂存笔画；已保存的自绘表情用 `user://face_library/index.json` + 各自透明 PNG 持久化，角色选择页动态显示内置 atlas 表情和本地表情。
+- 联机当前表情同步：内置表情发送 ID；`user:` 本地表情发送当前 PNG 字节；笔画层另外发送。**不广播整份本地表情库**。
+- `FacePainter`：直接改 RGBA8 字节缓冲。画 = source-over alpha 混合，擦 = 把目标 alpha 乘掉；512² 一次 1MB，按一笔/动作同步一次。
+- 「自己画」= 空白底起手；保存到本地表情库成为独立项目，再次选择可加载。取消会恢复旧 expression ID 与笔画。
+- 界面链路：`ui/main_menu.tscn` →「开始游戏」→ `ui/character_select.tscn`（3D 预览 + 动态表情列表 + 自己画）→ `ui/paint_panel.tscn`（透明笔画层叠在肤色底上）。本地列表用 HFlow + ScrollContainer 显示。
 
 ## Godot 4 踩坑