# 项目长期记忆

## 工程约定

- 玩家控制器只认「运动结果」，不认识任何动画片段名；表现层在 `Body/PlayerAnimator`。
  新增动作状态改 `player_animator.gd` 的 `ANIM_CLIPS`，不要往 `player.gd` 里塞片段名。
- 组件的可调参数放在组件自己身上（如 Zipline 的速度 / 刹车 / 吸附半径），控制器只读不定义。
- 头顶 UI（血条、交互提示）是 `player.tscn` 里的 Label3D 节点，不在代码里动态创建。
- 测试用 `McpTestSuite`（`addons/godot_ai/testing`），脚本放 `res://tests/`。

## Godot MCP 踩坑

- **数值标量会被字符串化**：直接调 `node_set_property` 传 `1` / `false` 会报
  `WRONG_TYPE: Cannot write String to a int/bool property`。
  绕法：改用 `batch_execute`，把 value 放进每条 command 的 `params` 里（嵌套数字能正常保型）。
  字符串、Vector / Color 对象不受影响。
- **@tool 脚本现造的节点不会写进 .tscn**：`add_child` 后不给 `owner`，
  `PackedScene::pack()` 就会跳过它。缆绳网格因此可以纯由锚点推导，不存在「文件和锚点对不上」的脏数据。
- **新 `class_name` 要跑一次 `filesystem_manage(op="scan")`** 才进全局类表，
  否则别的脚本把它当类型引用会解析不到。
- `game_manage(op="suspend")` 期间**输入事件不送达**，`next_frame` 也拦不住物理帧；
  想抓「运行中途某一瞬间」的画面不可靠，只能靠日志 / 属性断言验证。
- 测试跑在编辑器进程里，`@tool` 节点必须真的 `add_child` 进编辑中场景才会跑 `_ready()`；
  用完在 `teardown()` 摘掉，节点名以 `_McpTest` 开头可被测试运行器兜底清理。