limbo hsm

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

@@ -0,0 +1,142 @@
+# 2026-10-14
+
+## shader/toon_apply.gd 自动刷新可行性咨询（未改动任何文件）
+
+- 项目 Godot 4.7 Forward+。
+- 现状：`toon_apply.gd` 是 @tool Node3D，`_apply_materials()` 对每个子 MeshInstance3D `duplicate()` 一份 ShaderMaterial 并 `material_override`。
+- 结论：
+  1. 保存/编辑 `toon_apply.gd` 本身 → 编辑器热重载 @tool 脚本会重跑 `_ready()`，已能自动刷新（4.3 有热重载失效 bug，4.4+ 已修，本项目 4.7 无此问题）。
+  2. 编辑 `shader/toon.tres` 的 shader 参数（color / uv_scale 等）→ **不会**自动刷新。原因：ShaderMaterial 的 `Resource.changed` 仅在 resource_name 变化或 shader 本身变化时发出，参数改动不发出（官方文档明确）；且每网格是 duplicate 的副本，与模板已无关联。
+  3. 若要 2 也自动刷新，需 EditorPlugin 监听 `EditorInterface.get_inspector().property_edited`（或 EditorFileSystem），回调里调用 `_apply_materials()`。
+- 备选架构：改用 `GeometryInstance3D.set_instance_shader_parameter()` 的 per-instance uniform，可不 duplicate、直接共享 toon.tres，改参数即实时生效；但限制是**不支持贴图/数组**、每 shader 上限 16 个。本项目需要 per-mesh 的 `base_texture`，因此该方案只能覆盖 color 之类的标量/向量参数，贴图仍需 duplicate 或走 Texture2DArray + index。
+
+## 追加：评估 per-instance uniform + Texture2DArray 方案（结论：不适合本项目）
+
+- 实测贴图尺寸（脚本扫 PNG 头）：全项目 289 张 PNG / 24 种尺寸。
+  - `assets` 180 张：1024×1024 ×108、512×512 ×40、4096×4096 ×25、2048×2048 ×5
+  - `assets/自建资产` 18 张：4096×4096 ×13（地板、地毯 PBR 套图）
+  - `character` 81 张：32×32 ×70、512×512 ×4、1024×1024 ×1
+  - `demo` 28 张：15 种尺寸混杂
+- 结论：Texture2DArray 要求所有层同尺寸/同格式/同 mipmap，只能统一到 4096（单层带 mipmap 约 85 MiB 无损 / 21 MiB VRAM 压缩），几百张即 GB 级显存，且需额外打包流水线 → **per-instance uniform 路线不划算**，除非贴图少且尺寸统一。
+- 推荐路线（未实施）：
+  - A：保留 duplicate，加 EditorPlugin 监听 `EditorInspector.property_edited`，命中 toon.tres 时重刷 `_apply_materials()`（可加防抖）。
+  - B：把公共外观参数（color/specular/fresnel/normal_scale/uv_scale/uv_offset）提升为 `global uniform`（项目设置 → Shader Globals 定义），调参全局实时生效、无需重刷；贴图与 per-model 覆盖仍留在 duplicate 材质上。代价：需改 cel-shader-base.gdshader / outline.gdshader 并清掉 toon.tres 里的同名参数；全局值会写入 project.godot，需团队一起提交。
+
+## 已实施：路线 A（新增 addons/toon_refresh 编辑器插件）
+
+用户选择 A。改动：
+- 新增 `addons/toon_refresh/plugin.cfg` + `plugin.gd`（EditorPlugin）。
+- `project.godot` 的 `[editor_plugins] enabled` 追加 `res://addons/toon_refresh/plugin.cfg`。
+
+实现要点：
+- 监听 `EditorInterface.get_inspector().property_edited`，命中 `res://shader/toon.tres` 或其内联子资源时，0.2s 防抖后遍历当前编辑场景，对脚本文件名为 `toon_apply.gd` 且有 `_apply_materials` 的节点调用该方法。
+- 另加 项目 > 工具 菜单项「刷新 toon 材质（当前场景）」作手动兜底。
+- 只影响当前编辑场景；不覆盖手动改过的单个材质副本。
+
+已实测确认的事实（重要，别再靠猜）：
+- **`toon.tres` 的 `next_pass` 内联子资源，`resource_path` 不是空串**，而是 `res://shader/toon.tres::ShaderMaterial_m5gih` 这种带 `::` 后缀的形式 → 匹配逻辑用 `begins_with(TARGET + "::")`。
+- `ShaderMaterial.changed` **不会**因 `set_shader_parameter()` 触发；因改 `resource_name` 触发（与官方文档一致）。
+- 编辑器路径：`D:\_yvmou\Godot\Godot_v4.7.2-stable_win64.exe\Godot_v4.7.2-stable_win64.exe`（另有 mono 版）。可用 `--headless --editor --path E:/Godot/agame --quit` 做插件加载冒烟测试；用 `--check-only --script res://xxx.gd` 做语法校验。
+- 该项目 headless 启动时 godotsteam / limboai 的 GDExtension DLL 会报加载失败（既有问题，与本次改动无关）。
+
+项目相关：`[shader_globals]` 里已有 diffuse_curve、specular_smoothness、fresnel_smoothness、outline_width、outline_color —— 描边与光照曲线本来就是全局 uniform，调参实时生效；真正需要重刷的是 toon.tres 上的材质级参数。
+
+## 修复：USE_NORMAL_MAP=1 时"平视全场景变暗、俯瞰才亮"
+
+用户报告的症状。根因是 `cel-shader-base.gdshader` 里的一行：
+`NORMAL = normal.vector;`（原第 121 行）——`normal.vector` 是**切线空间**的法线贴图值，
+而 Godot 4 的 `fragment()` 里 `NORMAL` 是**视图空间**（官方文档明确写
+"inout vec3 NORMAL ... in view space"）。把切线空间值写进视图空间的 NORMAL，
+等于让所有像素的法线都指向"视图空间 +Z"≈ 朝向相机的一个常量 →
+整个场景明暗只由相机朝向决定：平视时与光方向近乎垂直/反向 → 全黑且无明暗起伏；
+俯瞰时与向下打的光对齐 → 恢复正常。`normal_map_fragment()` 里算好的正确视图空间法线
+`ref_normal` 被算出来后就丢掉了（死代码）。
+
+连带问题：`normal_map` 这个 uniform 从来没被赋过值（toon_apply.gd 只抓 base_texture），
+采样到引擎默认纹理后算出的法线同样是垃圾。main2.tscn 里 413 个 toon_apply 节点刷出的
+434 个网格中，430 个都没有法线贴图。
+
+改动：
+- `shader/includes/normal-map.gdshaderinc`：删掉 `ref_normal` / `vector.xy*2-1` / `vector.z`
+  重建等死代码，改为返回 `NormalData(map, normal_scale)`，map 就是原始纹理值（切线空间），
+  蓝通道交给引擎重建；补上坐标空间说明。
+- `shader/cel-shader-base.gdshader`：`USE_NORMAL_MAP` 分支只写
+  `NORMAL_MAP = normal.map; NORMAL_MAP_DEPTH = normal.depth;`，不再碰 `NORMAL`。
+- `shader/toon_apply.gd`：抓 `normal_texture`（StandardMaterial3D）或 `normal_map`
+  （ShaderMaterial）→ 有就赋给副本；**没有就显式把 `normal_scale` 设为 0.0**，否则会采样默认纹理。
+
+验证（真实场景跑法，见 MEMORY.md）：
+- 对照实验确认 dummy 渲染后端仍会报 `SHADER ERROR`，所以无头运行可校验 shader 语法。
+- 加载 `world/main2.tscn` 零 shader 错误、零脚本错误。
+- 功能断言：toon_apply 子树 434 个网格全部应用成功；430 个 `normal_scale=0.0`（无贴图），
+  4 个 `normal_scale=1.0` 且 `normal_map` 已设置（源材质确实带法线贴图）。
+
+遗留待用户确认（未改动）：
+- `world/main2.tscn` 的 `model/floor1`（不归 toon_apply 管，用自建 `surface_material_override/0`）
+  上 `normal_scale = -1.7749993243124995`，在新语义下等于 `NORMAL_MAP_DEPTH = -1.775`（反向外插），
+  几乎不可能是想要的，建议改成 1.0。
+- `toon_apply.gd` 只读 `mesh.surface_get_material(0)`，忽略了 `surface_material_override`，
+  对把材质放在节点覆盖槽上的模型会抓不到贴图（本次未改，属潜在问题）。
+
+## 排查：亮色模型"像自发光"（未改动任何项目文件）
+
+用户问"没开自发光，为什么颜色较亮时有自发光感"。用 Godot 无头脚本采样截图
+（`Image.load_from_file` + 逐像素统计，临时脚本已删）：
+- 红篮区域(25988 样本)：**37.1% 的像素有通道被钉在 255**，均值 (164,57,56)
+- 抽屉顶面(7616 样本)：**63.0% 触顶，4758 个纯白像素**，均值 (212,212,205)
+- 深色柜体正面(10048 样本)：仅 **3.3% 触顶**，均值 (108,89,74)
+- 背景：66452 样本 min==max==(54,72,87) → **纯色平涂，不是天空盒**
+
+结论：是**通道削顶（clipping）**，不是自发光。shader 里 `USE_EMISSION 0`，且 toon.tres
+的 specular/fresnel 的 rgb 都是 0 → 唯一光照项就是 `ALBEDO × LIGHT_COLOR × 阶梯`。
+亮色/高饱和色在线性空间里本来就有通道接近 1.0，光照只要 >1 就把它钉死 →
+整片变成没有渐变的满色 → 观感就像发光；中等亮度色需要 3 倍以上才触顶，所以正常。
+阶梯曲线本身是平的（`new_gradient_texture_1d.tres`：u<0.127→0，0.14~0.50→0.198，
+u>0.523→1.0），削顶后连最后一点层次也没了。
+
+项目里的过曝来源候选：
+- `world/main2.tscn` 的 SpotLight3D `sconce`：`light_energy = 2.655`、`light_indirect_energy = 2.41`
+- `world/main.tscn` 的 Environment：`ambient_light_source = 3`（天空）+ 自定义天空
+  `atm_sun_intensity = 18`、`sun_disk_intensity = 30` → 环境光辐照度可远超 1
+- **矛盾点（可用来定位）**：main.tscn 的 Environment 是 `tonemap_mode = 3`(ACES) + `tonemap_white = 6.0`，
+  ACES 会把高光滚降，理论上几乎不可能出现纯 255（输入 4.0 也只到 ~253）。但截图里大面积纯 255
+  → 说明被观察的视口**没有套用那套 ACES 环境**：要么看的是 main2.tscn（自身无 WorldEnvironment、
+  无 tonemap → 硬削顶），要么编辑器 3D 视口没启用场景环境。
+- 另一个坑：toon.tres 的 `color = 0.549` 带 `source_color`，线性空间里只有 **0.26**，
+  toon 管线把反照率整体压掉约 4 倍 → 亮暗反差被拉得很大。
+- `world/main2.tscn` 里没有任何 `use_custom_color = true`，所以不存在自定义颜色覆盖。
+- `world/main.tscn` 通过 ext_resource 把 `main2.tscn` 作为子场景实例化。
+
+待用户确认：具体是哪个场景/哪个物体，以便定位"材质来源 + 光源 + 环境"这条链路。
+
+## 重要：上游 godot4-cel-shader 的法线贴图路径是"从未运行过的死代码"
+
+用户质疑"着色器源自 https://github.com/eldskald/godot4-cel-shader，理应无需修改"。
+本地有干净的上游副本 `E:/Godot/godot4-cel-shader-main/godot4-cel-shader-main/`，比对结果：
+
+- 本项目改动前的 `cel-shader-base.gdshader` / `includes/normal-map.gdshaderinc`
+  **与上游逐字一致**（包括 `NORMAL = normal.vector;` 和 `ref_normal` 算完即丢）。→ 当时不是本项目改坏的。
+- 但上游 5 个 shader 变体**全部是 `#define USE_NORMAL_MAP 0`**，全仓库没有任何一处写成 1，
+  README 里 "normal" 出现 0 次 → **这条路径上游从未启用、从未测试过**。
+- 本项目把它开成 1，才第一次走进这段代码，于是坐标空间错误暴露。
+- 结论：**只要 `USE_NORMAL_MAP 1`，那行就必须改**；想严格保持上游 1:1，唯一办法是把开关保持 0。
+- Godot 侧证据：引擎自己也会再做一次 NORMAL_MAP 合成
+  （Godot 源码 clearcoat 等价实现：`normalize(tangent*map.x + binormal*map.y + normal*map.z)`），
+  公式里的 `normal` 就是被污染过的 NORMAL → 污染会传播；且 depth=0 也无法"中和"，
+  因为 mix 的基值本身就是被写坏的 NORMAL。
+
+给用户的三个选项（待其选择）：
+A. `USE_NORMAL_MAP` 改回 0，并把两个 shader 文件完全还原成上游（代价：实测 434 个网格里那 4 个带法线贴图的会失去效果）
+B. 只保留 `cel-shader-base.gdshader` 删掉 `NORMAL = normal.vector;` 这一行的差异，include 还原上游（1 行差异）
+C. 保留当前版本（include 里的死代码也清掉，与上游差异最大但最干净）
+
+### 已实施：用户选择 A
+
+- 用 git 精确还原：`git checkout -- shader/cel-shader-base.gdshader shader/includes/normal-map.gdshaderinc shader/toon_apply.gd`
+  （先 `git diff` 逐 hunk 确认过全部改动都是本次会话产生的，没有混入用户未提交的修改）。
+- 再把 `#define USE_NORMAL_MAP 1` 改成 `0`（HEAD 里本来就是 1，是用户自己开的）。
+- 结果：`normal-map.gdshaderinc` 与上游**逐字一致**；`cel-shader-base.gdshader` 与上游的差异
+  只剩项目自己加的中文注释行（值已与上游相同）；`toon_apply.gd` 无改动。
+- 验证：`--headless res://world/main2.tscn --quit-after 60` 无 shader / 脚本 / 解析错误。
+- 注意：`toon.tres` 里仍有 `shader_parameter/normal_scale = 1.0`，宏关闭时被忽略，无副作用；
+  `world/main2.tscn` 里 `model/floor1` 那份自建材质的 `normal_scale = -1.775` 同样被忽略。

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

@@ -0,0 +1,62 @@
+# 2026-10-15
+
+## 玩家状态管理迁移到 LimboAI LimboHSM
+
+- 需求：玩家场景的状态管理完全用 LimboHSM 实现（addons/limboai v1.8.1，GDExtension 版，
+  **无需启用 editor plugin**，ClassDB 里没有 HSMPlayer —— LimboHSM/LimboState 本身就是 Node）。
+- 方案讨论：BT vs HSM 选型 → 玩家是人操作的（决策已由人完成），用 HSM 建模身体状态；
+  BT 留给将来的 NPC/autopilot。
+- 新增 `character/player/hsm/`（11 个脚本）：
+  - `player_hsm.gd`（根，转换表 Grounded⇄Airborne：`airborne`/`landed` 事件）
+  - `grounded.gd`（Grounded 子机：12 条转换 + `_enter` 按当下输入挑初始子状态）
+  - `airborne.gd`（Jump→Fall on `falling`；`_enter` 按 vy>0 挑 Jump 否则 Fall）
+  - `ground_state.gd`（地面叶子基类：统一判 try_jump/踏空 → `airborne`，再走 `_think()`）
+  - idle/walk/sprint/crouch/sneak.gd（写 motor.target_speed/crouching/sprinting + 动画）
+  - jump.gd/fall.gd（落地判定 `is_on_floor and vy<=0`，带 vy 门槛防起跳帧弹回）
+- 改动：
+  - `player.gd`：加 `class_name Player`；挂 HSM；`_ready` 末尾 `hsm.initialize(self)` +
+    `hsm.set_active(true)`（仅权威端）；管线第一位 `hsm.update(delta)`；animator 改调 `set_gait`。
+  - `player_motor.gd`：删掉从输入推断 sprint/crouch/target 的逻辑，暴露
+    `target_speed`（状态写）、`has_move_input()`、`try_jump()`（起跳在状态判定处就地执行，
+    同帧转 Jump）；crouching/sprinting 变成状态写入的事实镜像（Look/DebugPanel 继续用）。
+  - `player_animator.gd`：`set_motion` 拆成 `play_state(state)`（状态 _enter 调）+
+    `set_gait(velocity)`（每帧刷倍率）；删 `_resolve_state` 和 `idle_threshold`。
+    anim_state/anim_speed 同步属性保持不变（远端靠 Sync 复制驱动）。
+  - `player.tscn`：HSM 节点子树（LimboHSM root + Grounded{Idle,Walk,Sprint,Crouch,Sneak} +
+    Airborne{Jump,Fall}），根机器 `update_mode = 2`（MANUAL，编辑器里写入 int 失败，
+    手改 tscn 后 force_reload 场景生效）。
+- 行为变化（有意为之）：行走/站立切换改按**输入**判定（旧版按速度阈值 0.2 m/s），
+  顶墙时播 walk 而非 idle；其余（蹲伏优先于疾跑、跳跃缓冲、落地按输入挑状态）与旧版一致。
+- 验证：全部脚本 `--check-only` 通过；无头探针场景模拟输入跑完整状态链
+  （Idle→Walk→Sprint→Sneak→Crouch→Idle→Walk→Jump→落地Walk→Idle），数值与理论吻合。
+
+## 二次重写：小人国定标（同日）
+
+- 用户明确：不保旧手感、可重写；**小人国玩法，角色身高约 0.2 m**；旧代码可删。
+- 定标（全部固化进 player_motor.gd 默认值，删掉了 tscn 里的 walk/sprint 覆盖）：
+  walk 2.419（≈12 身长/s）、sprint 3.624（≈18 身长/s）、crouch 1.21（走速一半）、
+  accel 22（0.11s 到全速）、air_accel 5.9（地面 1/4）、jump 1.5 / gravity_scale 0.5
+  （跳高 0.23 m ≈ 1.15 身高、滞空 0.61 s）不变。DebugPanel body_height 0.15 → 0.2。
+- **修掉一个真 bug**：场景里 walk 被调到 2.419 后，动画器基准速度还是 0.4286，
+  walk/run 动画一直被 clamp 在 1.6× 上限。重构：删掉 animator 的 4 个 *_ref_speed 导出，
+  `play_state(state, ref_speed)` 由 HSM 状态传入基准速度（状态知道目标速度是多少），
+  `set_gait` 用存下的 `_ref_speed` 算倍率 —— 两处对表的坑没了。
+- 探针复测：三个位移动画全速倍率均 1.00，转换链不变。
+
+### 踩坑（复用注意）
+
+1. **无头 `--check-only` 对新 class_name 报「Could not find type」**：
+   全局类缓存 `.godot/global_script_class_cache.cfg` 没刷新。让编辑器跑一次
+   `EditorFileSystem.scan()`（godot_ai MCP 的 filesystem scan）即解；批量循环检查时
+   同一批里前后结果不一致也是这个原因。
+2. **godot-ai MCP `node_set_property` 写 enum int 属性失败**
+   （WRONG_TYPE: Cannot write String to a int property，value 传 JSON number 也一样）。
+   变通：MCP scene_save 后直接手改 .tscn 补属性行，再 `scene_open force_reload=true`。
+3. **MCP 场景节点路径**要含场景根：`/Player/HSM`，不是 `/HSM`。
+4. **LimboHSM 嵌套用法**：子状态机的 `_enter`（脚本 override）先于其 initial_state 激活执行，
+   所以可以在 `_enter` 里 `set_initial_state()` 动态挑入口子状态（落地按输入挑、空中按 vy 挑）。
+5. **转换触发的环境判定要放叶子状态**，不要放父机 `_update`：父机先于子状态执行，
+   在父机里 dispatch 转换后，本轮级联还可能调到已退出的旧子状态（叶子自己判、dispatch 后
+   立即 return，没有这个窗口）。
+6. 无头模拟按键：`Input.action_press` 只改动作状态、**不发输入事件**（Motor 的跳跃缓冲在
+   `_unhandled_input` 收事件，探不到）；要用 `Input.parse_input_event(InputEventAction)`。

.workbuddy/memory/MEMORY.md

@@ -0,0 +1,73 @@
+# agame 项目长期笔记
+
+Godot 4.7.2（Forward+，Jolt Physics，D3D12）。编辑器位于
+`D:\_yvmou\Godot\Godot_v4.7.2-stable_win64.exe\Godot_v4.7.2-stable_win64.exe`（另有 mono 版）。
+
+## 代码约定
+
+- **GDScript 警告被当作错误**（至少 `inference_on_variant`）。不要写成
+  `var x := some_variant_returning_call()`；要显式写类型，例如
+  `var s: Script = node.get_script() as Script`。改完脚本务必用
+  `--check-only --script res://xxx.gd` 自查。
+- 缩进用 tab，注释用中文（项目既有风格）。
+
+## 无头验证的正确姿势（踩过坑）
+
+- `--check-only --script res://x.gd`：GDScript 语法校验，有效。
+- `godot --headless --editor --path <proj> --quit`：验证编辑器插件能否加载，有效。
+- **不要**用 `extends SceneTree` 的 `--script` 脚本去测 `_ready()` 相关行为：
+  这种模式下节点不会真正进入场景树（`is_inside_tree()` 为 false），`_ready` 不执行，
+  会得出完全错误的结论。正确做法是造一个临时场景，用位置参数当主场景跑：
+  `godot --headless --path <proj> res://tools/_tmp_probe.tscn`。
+- 即使是 `--headless`（dummy 渲染后端），**shader 编译错误仍会被报告**
+  （`SHADER ERROR: ...`），所以可以用无头运行来校验 shader 语法。
+
+## 玩家 = LimboAI LimboHSM（2026-10-15 起）
+
+- LimboAI v1.8.1 是 **GDExtension 版**（addons/limboai 只有 bin/，无 plugin.cfg），
+  **不需要启用 editor plugin**；ClassDB 里没有 HSMPlayer —— `LimboHSM`/`LimboState` 本身就是 Node。
+- 玩家状态机在 `character/player/hsm/`：根 `player_hsm.gd`（Grounded⇄Airborne）+
+  Grounded{Idle,Walk,Sprint,Crouch,Sneak} + Airborne{Jump,Fall}，全是场景节点、脚本挂状态上。
+- 分工：**HSM 管「是什么状态」**（写 motor.target_speed/crouching/sprinting + 调
+  animator.play_state），**motor 只管物理**（重力/加速度/跳跃缓冲 + try_jump），
+  animator 只管「怎么播」（play_state + set_gait 刷倍率）。player.gd 管线第一位
+  `hsm.update(delta)`（MANUAL 模式，仅权威端 initialize+set_active；远端靠 Sync 复制）。
+- 走/站立转换按**输入**判定（非旧版的速度阈值）——顶墙时播 walk 不播 idle，是预期行为。
+- 用法要点：子机 `_enter` 里可 `set_initial_state()` 动态挑入口子状态；环境判定
+  （起跳/踏空/落地）放**叶子**状态的 _update，别放父机；落地判定要带 `vy<=0` 门槛。
+- 踩坑：新 class_name 后无头 `--check-only` 报「Could not find type」＝ 全局类缓存没刷新，
+  让编辑器 scan 一次即解；MCP node_set_property 写 enum int 失败 → 手改 tscn + 场景 force_reload。
+
+## toon 卡通渲染管线
+
+- `shader/cel-shader-base.gdshader`（`USE_*` 宏开关各模块）+ `shader/includes/*.gdshaderinc`，
+  上游是 godot4-cel-shader 项目。
+- `shader/toon.tres` 是材质模板；`shader/outline.gdshader` 作为 `next_pass` 描边。
+- `shader/toon_apply.gd`（@tool Node3D）给每个 MeshInstance3D 复制一份独立材质，
+  因为**每个模型有各自的贴图**，所以必须独立（不能共享一份材质）。
+- 已在项目设置里用了 **global uniform**：`diffuse_curve`、`specular_smoothness`、
+  `fresnel_smoothness`、`outline_width`、`outline_color` —— 这几项调参本来就是全局实时生效。
+- 贴图尺寸极不统一（289 张 PNG / 24 种尺寸，1024²、512²、4096²、32² 混杂），
+  因此**不适合** Texture2DArray + per-instance uniform 方案（显存会爆且要额外打包流水线）。
+- 编辑器插件 `addons/toon_refresh/`：改 toon.tres 时自动重刷 toon_apply 材质。
+
+## 坐标系陷阱 + 上游着色器的边界（重要）
+
+Godot 4 的 `fragment()` 里 `NORMAL` / `TANGENT` / `BINORMAL` 都处于**视图空间**，
+而 `NORMAL_MAP` 要的是**切线空间**值、由引擎用 TANGENT/BINORMAL 还原。
+把切线空间值直接赋给 `NORMAL` 会让整个场景的法线变成一个跟着相机转的常量 ——
+表现为平视全黑、俯瞰才亮。
+
+但**不要**因此去改上游文件：`cel-shader-base.gdshader` 与
+`includes/normal-map.gdshaderinc` 来自 <https://github.com/eldskald/godot4-cel-shader>，
+本项目的策略是**逐字跟随上游**。上游的法线贴图路径 `NORMAL = normal.vector;`
+确实有上述坐标空间错误，但上游所有变体都是 `#define USE_NORMAL_MAP 0`，
+全仓库从未启用过这条路径（README 也没提），所以是"能编译但结果错"的死代码。
+本项目保持 `USE_NORMAL_MAP 0`，与上游一致；`toon.tres` 里残留的
+`shader_parameter/normal_scale` 在宏关闭时会被忽略，无副作用。
+
+**结论：要动上游 shader 之前，先用 `E:/Godot/godot4-cel-shader-main/` 里的干净副本 diff。**
+
+正确做法（若将来真要开法线贴图）：只写 `NORMAL_MAP = 原始切线空间值` +
+`NORMAL_MAP_DEPTH`，让引擎合成；不要自己写 `NORMAL`，也不要预先做 `*2-1` 重映射
+（引擎自己做，蓝通道由引擎重建）。