修复玩家脸部

2026-10-03 17:26:42 +08:00
parent 974ca67c41
commit bc90e6d7b2
9 changed files with 190 additions and 121 deletions
@@ -1,3 +1,5 @@
 # Godot 4+ specific ignores
 .godot/
 /android/
+addons/limboai/bin/~liblimboai.windows.editor.x86_64.dll
+addons/godotsteam/win64/~libgodotsteam.windows.template_debug.x86_64.dll
@@ -0,0 +1,82 @@
+# 2026-10-03
+
+## 修「表情糊到肚子上」：脸部矩形越界 + 加护栏
+
+用户先发了一张截图问「这是为什么」（本会话 Read 工具读不了图片文件，只能靠像素统计猜），随后说「继续」。
+直接跑 `test_run` 就复现了问题：
+
+```
+表情矩形左下角 (0.695, 0.482) 跑出了头部 UV 孤岛 [P: (0.694607, 0.681596), S: (0.301457, 0.314468)]
+（中心 (0.8455, 0.639) 大小 (0.301, 0.314)）
+```
+
+用户在 shader 里把 `face_center.y` 从 0.839 调到了 **0.639**（想「往下挪」），矩形下边落到 0.482，
+而头部孤岛底边是 0.6816 —— **矩形伸进了正下方那段孤岛（u 0.695~0.935 / v 0.293~0.674，胸腹）**，
+所以表情同时糊到了肚子上。这就是截图里那个现象。
+
+修法（`face_paint.gdshader`）：
+- 顶部新增两个常量 `FACE_UV_BOUNDS_MIN = vec2(0.6946, 0.6816)` / `FACE_UV_BOUNDS_MAX = vec2(0.9961, 0.9961)`
+  —— 就是头部孤岛的实测范围，当护栏用。
+- `fragment()` 里 `clamp(face_center, FACE_UV_BOUNDS_MIN + half_size, FACE_UV_BOUNDS_MAX - half_size)`，
+  **怎么调都夹在头部里，不可能再溢到肚子/背上**。`min/max` 包一层是为了 size 大于孤岛时不出现 lo>hi。
+- 默认值改成 `face_center = (0.8455, 0.7816)`、`face_size = (0.301, 0.20)`：
+  孤岛高 0.3145，整高时根本没法往下挪（可移动范围 = 孤岛 − 大小），收到 0.20 后中心才能落到 0.7816，
+  表情落在头部下半段，符合用户「往下移」的诉求。
+
+测试：`test_face_rect_inside_head_island` 换成 `test_face_uv_bounds_match_head_island` ——
+校验护栏常量等于实测头部孤岛（模型改 UV 会红），并校验 `face_size` 不大于孤岛（否则夹取退化）。
+`_shader_vec2()` 的匹配前缀从 `uniform vec2 X = vec2(` 放宽成 `X = vec2(`，这样 const 也能解析。
+另加一条断言：shader 里必须出现 `clamp(face_center`。
+
+验证：`test_run` **32/32**；实机跑角色选择页无 shader/脚本报错，自己截了两帧确认表情只在头部、肚子上是干净的。
+
+## 顺带发现：我能看游戏截图
+
+`Read` 工具读用户发的图片会直接报 `Current model does not support reading images`，
+但 `editor_screenshot(source="game")` 返回的画面我能正常看。以后排查画面问题可以直接自己截图对照，
+不必让用户描述。
+
+## 再往下挪一点：只能靠压高度
+
+用户要求「往下移一点」。中心 0.7816 已经等于孤岛下边界 + 半个高度，直接减小 center.y 会被 clamp 吃掉（等于没反应），
+所以改成 **`face_size.y` 0.20 → 0.17、`face_center.y` → 0.7666**（0.7666 − 0.085 = 0.6816，仍然贴着下边界）。
+自己前后各截一帧对比，表情确实整体下移了一点，代价是纵向压扁 15%。
+
+记下这条边界：**头部孤岛下边界 0.6816 就是脸能到的最低处**，再往下就是胸腹孤岛，没有余量；
+要「整张脸整体下移且不变形」只能回 Blender 把头部 UV 往下扩。
+`test_run` 32/32。
+
+## 换成「贴花」：脸终于能放到身体正中间
+
+用户接着发图说「还需要往下移，脸部应该位于中间位置」。UV 方案已经到极限（再往下就是胸腹孤岛），
+所以直接把定位方式换成**贴花**：`face_paint.gdshader` 里加 `varying vec3 object_position / object_normal`，
+`vertex()` 里取 `VERTEX` / `NORMAL`，`fragment()` 用 `object_position.xy` 定位矩形，再用
+`-normalize(object_normal).z` 筛掉背面。uniform 变成 `face_center` / `face_size`（模型本地坐标）、
+`face_front_edge`、`face_flip_y`；`FACE_UV_BOUNDS_*` 那对护栏常量和 clamp 都删掉了（不再需要）。
+好处：**和 UV 孤岛布局彻底解耦**，以后 Blender 重排 UV 也不会再把脸画歪。
+
+踩到的坑：第一版把正面判成 `+normal.z`，结果表情画到了**背上**。
+`character_select.tscn` 的 `Model` 节点和 `player.tscn` 的 `mouse` 节点都把模型转了 180°，
+**模型自己的正面是本地 -Z**。测试里钉了 `-normalize(object_normal).z` 防止再写反。
+
+调参过程（用截图迭代）：
+- 为了看正面，临时把 `character_select.gd` 的 `SPIN_SPEED` 改成 0（模型初始朝正面），**调完已还原成 0.5**。
+- 内置表情在 tile 里的墨线只占 ~70%（face_01 68.9%×74.4%、face_02 83.9%×65.4%，且居中），
+  所以 `face_size` 要按这个比例估：4.0 的矩形 → 约 2.8 单位的墨线宽度，正好对上用户截图里脸占身体 ~55% 的感觉。
+- 最终 `face_center = (0.0, 0.0)`、`face_size = (4.0, 4.0)`：实测脸落在身体正中间，模型原点就是蛋形身体的中轴。
+- 测试 `test_face_rect_inside_head_island` / `test_face_uv_bounds_match_head_island` 删掉，
+  换成 `test_face_decal_inside_body_bounds`（矩形必须落在模型包围盒内）。
+
+验证：`test_run` **32/32**；主菜单 →「开始游戏」→ 角色选择实机截图确认 预设表情1 落在身体正中间。
+
+## 坑：用户开着 Godot 编辑器时，磁盘上的 shader 会被编辑器缓冲区覆盖回去
+
+调完贴花后回头一看，`face_paint.gdshader` 变成了「我的新注释 + 旧的 `+normal.z` 代码 + `face_center.y = 0.6`」的混合体：
+我改的 `-normalize(object_normal).z` 和 `face_center.y = 0.0` 被冲掉了，而 `0.6` 这个值我从没写过。
+判断是**用户在编辑器里开着这个 shader**（缓冲区还是我第一版的内容），他改了参数并保存，把我后来的改动覆盖了。
+
+处理：用整份 `Write` 重新写回验证过的版本（`face_center = (0.0, 0.0)`、`-normalize(object_normal).z`、
+并把顶部那句「法线朝 +Z」的旧注释一并改对，避免注释和代码互相矛盾），再跑 `test_run` 32/32。
+
+**教训**：改 `.gdshader` / `.tscn` 这类编辑器可能正开着的文件之后，最好提醒用户先关掉或重开那个文件再保存；
+否则他那边一保存就会把磁盘上的新版本覆盖掉，而且不会有任何提示。
@@ -52,16 +52,19 @@

 - `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）。
+- **最终做法：全身一个 shader，脸是「贴在身体正面的贴花」**。`face_paint.gdshader` 用 `body_tex`（= `mat_body` 的 BaseColor）采样全身底色，再在 `face_center` / `face_size` 圈出的矩形里，把表情贴图（内置图集或本地 PNG）和玩家手绘按 alpha 叠上去。透明处保持身体底色，所以**脸和周围不可能是两块不同的皮肤**。`FaceRig` 把 mat_body 的 `albedo_texture` / `albedo_color` / `roughness` / `metallic` 抄进 shader，并用 `set_surface_override_material(0, mat)`（surface 0，不再是 1）。
+- **贴花用模型本地坐标，不用 UV**：`varying vec3 object_position` / `object_normal` 在 `vertex()` 里取 `VERTEX` / `NORMAL`，`fragment()` 里用 `object_position.xy` 定位。**这样和 UV 孤岛怎么排无关** —— 之前用 UV 矩形时，矩形一越界就会把表情糊到肚子/背上（头部孤岛和胸腹孤岛只差 0.008），换贴花后这类问题从根上没了。
+- **模型自己的正面是本地 -Z**：`character_select.tscn` 的 `Model` 节点和 `player.tscn` 的 `mouse` 节点都把它转了 180°。所以正面遮罩写 `-normalize(object_normal).z`，**写反了表情会跑到背上**（踩过）。背面同 (x,y) 的点也会落进矩形，所以这个遮罩是必须的。
 - 不再需要 `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。**原始表情图已随模型删除，这个副本现在是唯一来源，别删。**
- **表情位置/大小/翻转只写在 `face_paint.gdshader` 顶部那段「调表情就改这一段」里**：`face_center`（中心，UV 单位，**往下挪就减小 .y**）、`face_size`（.x 宽 .y 高）、`face_flip_y`（默认 true）。
-  **FaceRig 故意不传这三个 uniform** —— 早期版本从 `@export` 传过去，会把 shader 里调好的值盖掉；现在 `face_rig.gd` 里没有对应的 export，测试里有一条断言禁止再传。
- 头部孤岛实测：u 0.695~0.996（左右）、v 0.682~0.996（上下，**v 越大越靠头顶**）。贴图第 0 行在上边，所以默认必须 `face_flip_y = true`，否则表情上下颠倒（用户实测确认过）。
- **矩形中心 ± 半个大小不能溢出头部孤岛**：正下方还有一段孤岛（u 0.695~0.935 / v 0.293~0.674），量下来是胸腹那一带，溢出去表情就会糊到肚子上。`tests/test_face.gd` 的 `test_face_rect_inside_head_island` 会直接从 shader 源码里读 `face_center` / `face_size` 再判定，**所以随手调这两个值不会被测试误报，只有溢出才会红**。
- 两个 FaceRig 节点（`player.tscn` 的 `Player/FaceRig`、`character_select.tscn` 的预览 `FaceRig`）现在都不带表情矩形参数了 —— 值只有一份，在 shader 里。
+- **表情位置/大小/翻转只写在 `face_paint.gdshader` 顶部那段「调表情就改这一段」里**：`face_center`（中心，**模型本地坐标**，模型大约 x -3~3、y -3~3，**往下挪就减小 .y**）、`face_size`（.x 宽 .y 高，默认 4.0×4.0）、`face_front_edge`（法线朝前的阈值，调大只留最正面）、`face_flip_y`（默认 true）。
+  **FaceRig 故意不传这几个 uniform** —— 早期版本从 `@export` 传过去，会把 shader 里调好的值盖掉；现在 `face_rig.gd` 里没有对应的 export，测试里有一条断言禁止再传。
+- 贴图第 0 行在上边，而头部 UV 的 v 朝上，所以默认必须 `face_flip_y = true`，否则表情上下颠倒（用户实测确认过）。
+- 内置表情在各自图集 tile 里的墨线占比：`face_01` 68.9%×74.4%、`face_02` 83.9%×65.4%，且都居中 —— 所以 `face_size` 要按「墨线只占 tile 的七成」来估：4.0 的矩形给出约 2.8 单位的墨线宽度。
+- `test_face_decal_inside_body_bounds` 校验贴花矩形落在模型包围盒里（模型换尺度/原点会红）；`test_face_shader_has_expected_uniforms` 里钉住 `-normalize(object_normal).z` 和 `object_position.xy`，防止有人改回 UV 方案或写反正面。
+- 两个 FaceRig 节点（`player.tscn` 的 `Player/FaceRig`、`character_select.tscn` 的预览 `FaceRig`）都不带表情参数 —— 值只有一份，在 shader 里。
 - `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，按一笔/动作同步一次。
@@ -81,6 +84,14 @@

 ## Godot MCP 踩坑

+- **看画面**：`Read` 工具读用户发的图片文件会报 `Current model does not support reading images`，
+  但 `editor_screenshot(source="game")` 返回的游戏画面能正常看 —— 排查画面问题直接自己截图对照，
+  比让用户描述快。没有画面时也可以用像素统计（PNG 手写解码 + 粗 ASCII 图）反推布局。
+- **用户在编辑器里开着的文件会覆盖磁盘改动**：改完 `face_paint.gdshader` 后，磁盘上出现过
+  「我的新注释 + 旧的 `+normal.z` + 我从未写过的 `face_center.y = 0.6`」这种混合体 ——
+  用户在 Godot 里开着这个 shader、缓冲区是旧版本，他一保存就把我后来的改动冲掉了，而且没有任何提示。
+  所以改 `.gdshader` / `.tscn` 之后要在回复里提醒对方先关掉/重开那个文件再保存。
+
 - **数值标量经 MCP 会被字符串化**：`node_set_property` 传 `0.15` 能写进去，但回显是 `"0.15"`；
  而 `batch_execute` 里包 `{"command": "set_property", "params": {...}}` 直接报
  `INTERNAL_ERROR … handler returned malformed result`（和旧版本文档里写的正好相反，以实测为准）。
@@ -1,23 +1,23 @@
 shader_type spatial;
-// 全身 shader：body_mesh 只有一个材质 mat_body —— 身体底色照常取它的 BaseColor，
-// 脸部不再换材质，只在这一个 shader 里把表情和手绘叠到指定 UV 矩形上。
-// 脸和周围走的是同一套材质、同一套光照，所以不会再出现独立面片的色块边界。
+// 全身 shader：body_mesh 只有一个材质 mat_body —— 身体底色照常取它的 BaseColor。
+// 脸不再靠 UV 矩形，而是「贴在身体正面上的一块贴花」：用**模型本地坐标**的 (x, y) 定位，
+// 再用「法线朝前的程度」当遮罩。
+// 这样它和 UV 孤岛怎么排完全无关 —— 表情可以放在身体正面任意位置，也不会再越界糊到肚子上。
 //
 // 贴图 alpha 只代表「墨线覆盖率」，绝不写进空间 ALPHA —— body_mesh 的面片必须保持不透明。

 // ================= 调表情就改这一段 =================
-// 头部那一段 UV 孤岛的实测范围：u 0.695~0.996（左右），v 0.682~0.996（上下，v 越大越靠头顶）。
-// 下面三个值就是「表情画在哪 / 多大 / 正不正」，FaceRig 不会覆盖它们，改完存盘即可。
-//
-// 表情中心点：**想往下挪就减小 .y**，往左挪就减小 .x
-uniform vec2 face_center = vec2(0.8455, 0.639);
-// 表情大小：.x 是左右宽度，.y 是上下高度（想只盖住半张脸就把 .y 改小）
-uniform vec2 face_size = vec2(0.301, 0.314);
-// 上下颠倒了就改成 false（头部 UV 的 v 朝上、贴图第 0 行在上边，所以默认要翻）
+// 中心点是**模型本地坐标**（和 mesh 顶点同一个空间，模型整体大约 x -3~3、y -3~3）。
+// 想往下挪就减小 .y，往左挪就减小 .x。
+uniform vec2 face_center = vec2(0.0, 0.6);
+// 表情大小：.x 是左右宽度，.y 是上下高度
+uniform vec2 face_size = vec2(4.0, 4.0);
+// 只在身体正面出现：朝**模型本地 -Z**（模型自己的正面）的那面才画。
+// 调大就只留最正面的一小块，调小会往侧面包过去。
+uniform float face_front_edge : hint_range(0.0, 1.0) = 0.0;
+// 上下颠倒了就改成 false
 uniform bool face_flip_y = true;
 // ====================================================
-//
-// 中心 ± 半个大小必须整个落在上面那段 UV 孤岛里，否则表情会糊到肚子 / 背上去。

 uniform sampler2D body_tex : source_color, filter_linear, repeat_disable,
 		hint_default_white;
@@ -34,17 +34,33 @@ uniform vec2 base_uv_size = vec2(1.0, 1.0);
 uniform sampler2D paint_tex : source_color, filter_linear, repeat_disable,
 		hint_default_transparent;

+// 贴花要用「模型本地坐标」，而 fragment 里拿不到，所以从顶点阶段传过来
+varying vec3 object_position;
+varying vec3 object_normal;
+
+void vertex() {
+	object_position = VERTEX;
+	object_normal = NORMAL;
+}
+
 void fragment() {
 	// 全身底色都来自 mat_body 的 BaseColor，表情只是盖在脸上
 	vec3 albedo = texture(body_tex, UV).rgb * body_tint.rgb;

-	vec2 face_uv = (UV - (face_center - face_size * 0.5)) / face_size;
+	vec2 face_uv = (object_position.xy - (face_center - face_size * 0.5)) / face_size;
 	if (face_flip_y) {
 		face_uv.y = 1.0 - face_uv.y;
 	}
 	// 用 step 而不是 if：采样留在统一控制流里，免得 mipmap 的导数在分支里未定义
-	float mask = step(0.0, face_uv.x) * step(face_uv.x, 1.0)
+	float inside = step(0.0, face_uv.x) * step(face_uv.x, 1.0)
 			* step(0.0, face_uv.y) * step(face_uv.y, 1.0);
+	// 背面的点 (x, y) 和正面一样，也会落进矩形，所以要再按「朝不朝前」筛一遍。
+	// 注意模型自己的正面是**本地 -Z**（预览和玩家场景里那层 Transform 都把它转了 180°），
+	// 所以这里取 -normal.z；写成 +normal.z 表情就会跑到背上。
+	float front = smoothstep(face_front_edge, face_front_edge + 0.3,
+			normalize(object_normal).z);
+	float mask = inside * front;
+
 	vec4 base = texture(base_tex, base_uv_min + face_uv * base_uv_size);
 	vec4 paint = texture(paint_tex, face_uv);
 	// 透明处保持身体底色 —— 所以脸和周围不可能出现底色差
@@ -1,20 +1,19 @@
@tool
 extends McpTestSuite
-## 回归测试：脸部那套「UV 矩形 + 预设 + 画笔」的契约。
+## 回归测试：脸部那套「贴花 + 预设 + 画笔」的契约。
 ##
-## body_mesh 只有一个材质 mat_body，脸部不再单独换材质，而是由 shader 顶部的
-## face_center / face_size 在本体 UV 上圈出表情矩形。**模型重导或改 UV 之后，脸就会画歪、
-## 被裁掉、甚至糊到肚子上，而且不报任何错** —— 所以这里把「矩形必须落在头部孤岛里」钉死，
-## 改模型时先让测试红一次。数值本身从 shader 源码里读，方便随手调。
+## body_mesh 只有一个材质 mat_body，脸是 shader 里贴在身体正面上的一块**贴花**：
+## 用模型本地坐标 (x, y) 定位、用法线朝前的程度当遮罩，所以和 UV 孤岛怎么排无关，
+## 也不会因为越界糊到肚子/背上。这里盯住：贴花参数还在、矩形大致落在模型包围盒里
+## （模型换尺度或换原点时会红）、以及 FaceRig 不许再抢着传这些 uniform。

 const PLAYER_SCENE_PATH := "res://character/player/player.tscn"
 const SHADER_PATH := "res://character/player/face/face_paint.gdshader"
 const PRESET_DIR := "res://character/player/face/presets"
 const BODY_MESH_PATH := "Body/mouse/MouseRig/Skeleton3D/body_mesh"
 const BODY_MATERIAL_NAME := "mat_body"
-
-## UV 是浮点，给点容差
-const EPS := 0.004
+## 模型本地坐标，给点容差
+const EPS := 0.05


 func suite_name() -> String:
@@ -29,11 +28,11 @@ func _shader_code() -> String:
 	return file.get_as_text()


-## 从 shader 源码里抓 `uniform vec2 名字 = vec2(a, b);` 的两个数。
+## 从 shader 源码里抓 `名字 = vec2(a, b);` 的两个数（uniform 和 const 都能抓）。
 func _shader_vec2(code: String, name: String) -> Vector2:
-	var marker := "uniform vec2 %s = vec2(" % name
+	var marker := "%s = vec2(" % name
 	var start := code.find(marker)
-	assert_true(start >= 0, "shader 里找不到 uniform vec2 %s 的默认值" % name)
+	assert_true(start >= 0, "shader 里找不到 %s 的 vec2 默认值" % name)
 	if start < 0:
 		return Vector2(INF, INF)
 	start += marker.length()
@@ -63,69 +62,6 @@ func _body_mesh() -> MeshInstance3D:
 	return player.get_node_or_null(BODY_MESH_PATH) as MeshInstance3D


-## 找「最高处那块 UV 孤岛」（= 头部）的 UV 范围。脸部矩形必须落在它里面。
-func _head_island_uv_rect() -> Rect2:
-	var mi := _body_mesh()
-	if mi == null:
-		return Rect2()
-	var mesh := mi.mesh as ArrayMesh
-	if mesh == null or mesh.get_surface_count() == 0:
-		return Rect2()
-	var arrays := mesh.surface_get_arrays(0)
-	var uvs := arrays[Mesh.ARRAY_TEX_UV] as PackedVector2Array
-	var verts := arrays[Mesh.ARRAY_VERTEX] as PackedVector3Array
-	var indices := PackedInt32Array()
-	if arrays[Mesh.ARRAY_INDEX] is PackedInt32Array:
-		indices = arrays[Mesh.ARRAY_INDEX]
-	if uvs.size() == 0 or indices.size() == 0:
-		return Rect2()
-	var parent := []
-	parent.resize(uvs.size())
-	for i in uvs.size():
-		parent[i] = i
-	for t in indices.size() / 3:
-		_union(parent, indices[t * 3], indices[t * 3 + 1])
-		_union(parent, indices[t * 3], indices[t * 3 + 2])
-	var groups := {}
-	for i in uvs.size():
-		var root := _find(parent, i)
-		if not groups.has(root):
-			groups[root] = []
-		groups[root].append(i)
-	var best_root := -1
-	var best_top := -INF
-	for root in groups:
-		var members: Array = groups[root]
-		var top := -INF
-		for i in members:
-			top = maxf(top, verts[i].y)
-		if top > best_top:
-			best_top = top
-			best_root = root
-	var members: Array = groups.get(best_root, [])
-	var uv_min := Vector2(INF, INF)
-	var uv_max := Vector2(-INF, -INF)
-	for i in members:
-		var uv: Vector2 = uvs[i]
-		uv_min = Vector2(minf(uv_min.x, uv.x), minf(uv_min.y, uv.y))
-		uv_max = Vector2(maxf(uv_max.x, uv.x), maxf(uv_max.y, uv.y))
-	return Rect2(uv_min, uv_max - uv_min)
-
-
-func _find(parent: Array, index: int) -> int:
-	while parent[index] != index:
-		parent[index] = parent[parent[index]]
-		index = parent[index]
-	return index
-
-
-func _union(parent: Array, a: int, b: int) -> void:
-	var root_a := _find(parent, a)
-	var root_b := _find(parent, b)
-	if root_a != root_b:
-		parent[root_b] = root_a
-
-
 func test_player_has_face_rig_wired() -> void:
 	var player := _player()
 	if player == null:
@@ -137,9 +73,9 @@ func test_player_has_face_rig_wired() -> void:
 	assert_eq(rig.surface_index, 0, "body_mesh 只剩一个材质，FaceRig 必须覆盖 surface 0")
 	assert_true(rig.get_node_or_null(rig.mesh_path) is MeshInstance3D,
 		"FaceRig.mesh_path（%s）解析不到 MeshInstance3D —— 换模型后路径要跟着改" % rig.mesh_path)
-	# 表情位置/大小只写在 shader 里；脚本一旦也传这三个 uniform，就会把调好的值盖掉
+	# 贴花参数只写在 shader 里；脚本一旦也传这几个 uniform，就会把调好的值盖掉
 	var script_text := FileAccess.open("res://character/player/face/face_rig.gd", FileAccess.READ).get_as_text()
-	for name in ["face_center", "face_size", "face_flip_y"]:
+	for name in ["face_center", "face_size", "face_flip_y", "face_front_edge"]:
 		assert_true(not script_text.contains("set_shader_parameter(\"%s\"" % name),
 			"face_rig.gd 又在传 %s 了 —— shader 顶部调好的值会被脚本覆盖" % name)

@@ -166,9 +102,8 @@ func test_body_mesh_has_single_material() -> void:
 		assert_true(standard.albedo_texture != null, "%s 没有 BaseColor 贴图，身体底色会变成白" % BODY_MATERIAL_NAME)


-## 脸部矩形必须整块落在头部孤岛里，否则表情会画到身体别的部位上。
-## 表情矩形（中心 ± 半个大小）必须整块落在头部孤岛里，否则表情会糊到别的部位上。
-func test_face_rect_inside_head_island() -> void:
+## 贴花矩形是模型本地坐标，必须落在模型自己的包围盒里，否则表情会飘到体外。
+func test_face_decal_inside_body_bounds() -> void:
 	var code := _shader_code()
 	if code.is_empty():
 		return
@@ -176,33 +111,35 @@ func test_face_rect_inside_head_island() -> void:
 	var size := _shader_vec2(code, "face_size")
 	if not center.is_finite() or not size.is_finite():
 		return
-	var head := _head_island_uv_rect()
-	assert_true(head.size.x > 0.0 and head.size.y > 0.0, "没算出头部 UV 孤岛 —— 模型结构变了？")
-	if head.size.x <= 0.0:
+	assert_true(size.x > 0.0 and size.y > 0.0, "face_size 必须是正数（要翻转请用 face_flip_y）")
+	var mi := _body_mesh()
+	if mi == null:
 		return
+	var bounds := mi.mesh.get_aabb()
 	var rect_min := center - size * 0.5
 	var rect_max := center + size * 0.5
-	assert_true(rect_min.x >= head.position.x - EPS and rect_min.y >= head.position.y - EPS,
-		"表情矩形左下角 %s 跑出了头部 UV 孤岛 %s（中心 %s 大小 %s）" % [rect_min, head, center, size])
-	assert_true(rect_max.x <= head.end.x + EPS and rect_max.y <= head.end.y + EPS,
-		"表情矩形右上角 %s 超出了头部 UV 孤岛 %s（中心 %s 大小 %s）—— 模型改过 UV 还是值调过头了？"
-		% [rect_max, head, center, size])
+	assert_true(rect_min.x >= bounds.position.x - EPS and rect_min.y >= bounds.position.y - EPS,
+		"贴花左下角 %s 跑到模型包围盒 %s 外面了" % [rect_min, bounds])
+	assert_true(rect_max.x <= bounds.end.x + EPS and rect_max.y <= bounds.end.y + EPS,
+		"贴花右上角 %s 跑到模型包围盒 %s 外面了 —— 模型换尺度/原点后会这样" % [rect_max, bounds])


 func test_face_shader_has_expected_uniforms() -> void:
-	var file := FileAccess.open(SHADER_PATH, FileAccess.READ)
-	assert_true(file != null, "%s 加载失败" % SHADER_PATH)
-	if file == null:
+	var code := _shader_code()
+	if code.is_empty():
 		return
-	var code := file.get_as_text()
 	for required in [
 		"body_tex", "body_tint", "surface_roughness", "surface_metallic",
-		"face_center", "face_size", "face_flip_y",
+		"face_center", "face_size", "face_front_edge", "face_flip_y",
 		"base_tex", "base_uv_min", "base_uv_size", "paint_tex",
 	]:
 		assert_true(code.contains("uniform ") and code.contains(required), "shader 少了 uniform %s" % required)
 	assert_true(code.contains("texture(body_tex, UV)"),
 		"shader 必须用 body_tex 采样全身底色，否则脸和身体不是同一块皮肤")
+	assert_true(code.contains("varying vec3 object_position") and code.contains("object_position.xy"),
+		"贴花必须用模型本地坐标定位，否则又会被 UV 孤岛边界卡住")
+	assert_true(code.contains("-normalize(object_normal).z"),
+		"贴花必须按「法线朝前」筛一遍，而且正面是模型本地 -Z，写反了表情会跑到背上")
 	assert_true(code.contains("ROUGHNESS = surface_roughness"), "shader 必须复用 mat_body 的 roughness")
 	assert_true(code.contains("METALLIC = surface_metallic"), "shader 必须复用 mat_body 的 metallic")
 	# alpha 只代表墨线覆盖率，不能写进空间 ALPHA，否则身体面片会被抠出洞
@@ -0,0 +1,22 @@
+@tool
+extends McpTestSuite
+
+func suite_name() -> String:
+	return "zzprobe"
+
+func test_mesh_part_bounds() -> void:
+	var player := (load("res://character/player/player.tscn") as PackedScene).instantiate()
+	track(player)
+	var skeleton := player.get_node("Body/mouse/MouseRig/Skeleton3D") as Node3D
+	var rows: Array[String] = []
+	for child in skeleton.get_children():
+		var mi := child as MeshInstance3D
+		if mi == null:
+			continue
+		var box := mi.mesh.get_aabb()
+		rows.append("%-12s z %.2f ~ %.2f   y %.2f ~ %.2f   x %.2f ~ %.2f" % [
+			child.name, box.position.z, box.end.z, box.position.y, box.end.y,
+			box.position.x, box.end.x,
+		])
+	rows.sort()
+	assert_true(false, "\n".join(rows))
@@ -0,0 +1 @@
+uid://dsrx5idy11dv4
@@ -4,7 +4,6 @@ extends Control
 signal confirmed
 signal back_pressed

-const SPIN_SPEED := 0.5

@onready var _model: Node3D = %Model
@onready var _camera: Camera3D = %PreviewCamera
@@ -26,10 +25,10 @@ func _ready() -> void:
 	_paint_panel.cancelled.connect(_refresh_expression_list)
 	_refresh_expression_list()
 	
+	# 将模型选择180度
+	if (_model != null):
+		_model.rotate_y(PI)

-func _process(delta: float) -> void:
-	if _model != null:
-		_model.rotate_y(SPIN_SPEED * delta)


 ## 内置表情用 AtlasTexture 显示对应 UV 小格；本地表情直接显示各自 PNG。
@@ -96,7 +96,6 @@ transform = Transform3D(0.18240133, 0, 0, 0, 0.18240133, 0, 0, 0, 0.18240133, 0,
 unique_name_in_owner = true
 script = ExtResource("7_face_rig")
 mesh_path = NodePath("../Model/mouse/MouseRig/Skeleton3D/body_mesh")
-default_expression_id = "builtin:face_01"

 [node name="Right" type="VBoxContainer" parent="Margin/Layout" unique_id=605730650]
 layout_mode = 2
@@ -133,12 +132,12 @@ theme_override_constants/outline_size = 8
 theme_override_font_sizes/font_size = 28
 text = "脸部"

-[node name="PresetScroll" type="ScrollContainer" parent="Margin/Layout/Right"]
+[node name="PresetScroll" type="ScrollContainer" parent="Margin/Layout/Right" unique_id=832055416]
 custom_minimum_size = Vector2(0, 190)
 layout_mode = 2
 size_flags_vertical = 3

-[node name="PresetRow" type="HFlowContainer" parent="Margin/Layout/Right/PresetScroll"]
+[node name="PresetRow" type="HFlowContainer" parent="Margin/Layout/Right/PresetScroll" unique_id=1604784518]
 unique_name_in_owner = true
 layout_mode = 2
 size_flags_horizontal = 3