修复摄像机穿模

.workbuddy/memory/2026-10-09.md

@@ -136,3 +136,44 @@
 - 选 C 不选 A（只提 jump_velocity、保持 g=9.8）的理由：同样 0.23 m 的高度，A 只有 0.43 s 滞空，落地仍嫌仓促；C 多出 0.18 s。而且 C 让 jump 片段能播完约六成（A 只有四成）。
 - 没选等比方案（`gravity_scale = 0.0857`）：那比月球（1.62）还飘。
 - 代码注释已整理：`jump_velocity` 与 `gravity_scale` 标注为**配对参数**，并写入反解公式 `g = 8h/T²`、`v = 4h/T`；`player_animator.gd` 里那句引用旧值的上升时间注释也改准了（1.5 / 4.9 ≈ 0.31 s）。
+
+### 贴墙时摄像机穿模（已修）
+- **根因（纯几何，差 8 毫米）**：
+  | 项 | 值 | 来源 |
+  |---|---|---|
+  | 摄像机 `near` | **0.05 m** | Godot 默认，`player.tscn` 未覆盖 |
+  | 摄像机前移量 | **0.01074 m** | `Camera` 本地 Z = −0.1118 × Player 缩放 0.096096 |
+  | 贴墙时身体离墙 | **0.05241 m** | 胶囊局部半径 0.5454 × 0.096096 |
+  | **摄像机到墙** | **0.04167 m** | 0.05241 − 0.01074 |
+  → `0.0417 < 0.05`，墙面落在近裁剪面**内部**被整个裁掉，于是看到墙的背面/内部。
+- **修复 1**：`player.tscn` 的 `Camera` 加 `near = 0.01`（留 4 倍余量）。项目是 Forward+（反向 Z 深度），near 缩小对深度精度影响很小。`far` 保持默认未动。
+- **修复 2**：`player.gd` 新增 `@onready var model: Node3D = get_node_or_null("Body/mouse") as Node3D`，在权威分支里 `model.visible = false` —— 原来正是靠 near=0.05 把自己的身体裁掉才看不见，near 调小后身体会露出来。只影响本地玩家，远端玩家各自的模型实例不受影响。
+  - 代价：自己也看不到自己的影子（`visible=false` 会关掉阴影）。想保留影子可改用「本地玩家的 MeshInstance3D 放到独立视觉层 + 本地摄像机 cull_mask 排除该层」，但要注意该层不能和远端玩家共用，否则本地相机也看不到别人。
+- **备选方案（未采用）**：把胶囊半径加大到 > 0.06 m 让摄像机永远离墙更远 —— 会改变玩法（体型变胖）；或把 `Camera` 的前移量改小 —— 会动视角位置。
+
+### 附带发现的 bug：复制配置里的节点路径过期（已修）
+- 用户此前把 `AnimationPlayer` 从 `Body/AnimationPlayer` 移到 Player 根节点（`$AnimationPlayer`），但 `player_sync.tres` 里两条路径仍写着 `Body/AnimationPlayer:anim_state` / `Body/AnimationPlayer:anim_speed` → 这两个属性根本没被复制，**远端玩家的动画状态不会同步**。
+- 已改为 `AnimationPlayer:anim_state` / `AnimationPlayer:anim_speed`。
+
+## ⚠ 项目约定（用户明确要求）
+**改 Godot 的 .tscn / .tres / .gd，一律走 godot-ai MCP，不要直接写文件。** 原因见下：外部直接写 .tscn 会和编辑器的文件监视重载（`_reload_modified_scenes`）竞态，导致编辑器读到中间状态、报出**假的解析错误**。
+- 可用工具：`scene_open` / `scene_save` / `node_set_property` / `node_get_properties` / `node_create` / `node_manage` / `script_manage(find_symbols 可当解析校验)` / `script_create`(带诊断) / `filesystem_manage(read_text/write_text/scan/reimport)` / `resource_manage` / `logs_read` / `editor_manage(state)` / `project_run`。
+- 调用形式：多数工具是「扁平参数」（如 `scene_open {path}`），管理类工具是 `{op, params}` 双层（如 `editor_manage {op:"state"}`）。`node_*` 的 path 是**相对当前编辑场景根**（如 `/Player/CameraRig/Camera`），不是 `/root/...`。
+
+## player.tscn 解析错误事件（已解决）
+- 现象：`Parse Error ... player.tscn:38` in `_parse_node_tag`，场景彻底打不开。
+- **真实原因：不是文件语法错误。** 我用 MCP `node_set_property` 设 `Camera.near = 0.01` 后 `scene_save`，编辑器写出的内容与我手写的**字节完全一致**（同为 5106 字节），且 `scene_open(force_reload=true)` 立即 `reloaded_from_disk: true` 加载成功。
+  → 根因是**外部直接写 .tscn 与编辑器文件监视及重载的竞态**。
+- 诊断过程中的有效手段（可复用）：
+  1. `editor_manage(op="state")` 看当前场景与就绪状态
+  2. `scene_open` 做**对照实验**（打开一个已知正常场景，若 `switched:true` 则说明工具可靠、目标文件真的坏了）
+  3. `logs_read(source="editor", include_details=true)` 拿准确报错函数与行号
+  4. 用 `node_create` 在**内存里**加临时节点 + `node_get_properties` 探测属性真名（**不保存、不落盘**，随后 `node_manage(op="delete")` 清掉）—— 这次用它确认了 `Camera3D.near` 是合法 float 属性（默认 0.05，`far` 默认 4000）
+  5. `script_manage(op="find_symbols")` 可当脚本**解析校验**器；`filesystem_manage(op="scan")` 重建 `class_name` 全局表
+- 修复结果：`player.tscn` 的 `Camera` 现有 `near = 0.01`（MCP 设置并保存），场景可正常加载。
+
+### 日志里发现的其它线索（多为历史记录，非当前问题）
+- `Could not find type "PlayerLook/PlayerMotor/PlayerPickup/Crosshair"`、`Identifier "animator" not declared` —— 都是**旧状态的历史日志**；`find_symbols` 证明 player.gd 现已正常，且 `filesystem_manage(scan)` 返回 `global_classes_registered_delta: 0`（类名表本是全的，共 75 个）。
+- `crosshair.gd:133 _draw 里 texture_for_state 收到 Nil` —— `@tool` 脚本热重载时旧实例被新代码调用的一次性产物，非当前 bug。
+- `player.tscn` 的 **Crosshair 纹理疑似接反**：`hover_texture = grab_hover.png`、`hold_texture = grab.png`。按我的语义（hover=指着可拖拽物 / hold=正抓着）应互换；但若按光标包命名（`_hover` 后缀表示悬停态）则现状正确。**未擅自改动，已向用户指出。**
+- 遗留警告（非本次引入）：`face_painter.gd:153` 整数除法、`face_rig.gd:190` 局部变量 `name` 遮蔽 Node.name、`paint_panel.gd:69` 局部变量 `scale` 遮蔽 Control.scale、`Cannot load shader: res://shader/stylized.gdshader`。