# animation

> 查询、控制和编辑动画。查询: list_players, get_info, get_details, get_keyframes。播放: play, stop, seek, blend。编辑: create, delete, update_props, add_track, remove_track, add_keyframe, remove_keyframe, update_keyframe。运行时操作，仅影响当前执行上下文。如需持久化，请编辑 .tscn 文件。

| 属性 | 值 |
|------|-----|
| 所属层 | headless |
| 安全级别 | guarded |
| 需要 Godot | 是 |
| 需要编辑器 | 否 |
| 只读 | 否 |
| 长耗时 | 否 |

## Actions

- `list_players`
- `get_info`
- `get_details`
- `get_keyframes`
- `play`
- `stop`
- `seek`
- `blend`
- `create`
- `delete`
- `update_props`
- `add_track`
- `remove_track`
- `add_keyframe`
- `remove_keyframe`
- `update_keyframe`
- `ik_modifier_create`
- `ik_modifier_get`
- `ik_modifier_set`
- `ik_list_bones`

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | enum (20 项) | ✓ | 操作类型 |
| `project_path` | string |  | Godot 项目目录路径（可选，默认使用 GODOT_PROJECT_PATH 环境变量或当前目录） |
| `root_path` | string |  | 搜索起始节点路径（list_players） |
| `node_path` | string |  | AnimationPlayer 节点路径（除 list_players 外必填） |
| `animation_name` | string |  | 动画名称 |
| `library_name` | string |  | 动画库名称（create/delete） |
| `track_index` | number |  | 轨道索引 |
| `track_type` | enum (9 项) |  | 轨道类型（add_track） |
| `track_path` | string |  | 轨道路径，如 "Sprite2D:frame"（add_track） |
| `insert_at` | number |  | 轨道插入位置，-1 为末尾（add_track） |
| `keyframe_index` | number |  | 关键帧索引 |
| `time` | number |  | 关键帧时间（秒） |
| `value` | any |  | 关键帧值 |
| `transition` | number |  | 过渡曲线，1.0=线性 |
| `method_name` | string |  | 方法名（method 轨道） |
| `args` | array |  | 方法参数 |
| `length` | number |  | 动画长度（秒） |
| `loop_mode` | enum: none | linear | pingpong |  | 循环模式 |
| `step` | number |  | 关键帧对齐步进值 |
| `custom_blend` | number |  | 自定义混合时间，-1 为默认（play） |
| `custom_speed` | number |  | 播放速度，默认 1.0（play） |
| `from_end` | boolean |  | 从末尾开始播放（play） |
| `keep_state` | boolean |  | 停止时保持状态（stop） |
| `seconds` | number |  | 跳转位置（秒）（seek） |
| `update` | boolean |  | 跳转后立即更新节点（seek） |
| `blend_time` | number |  | 混合过渡时间（秒）（blend） |
| `speed` | number |  | 播放速度，默认 1.0（blend） |
| `load_autoloads` | boolean |  | 是否加载 Autoload 上下文（默认 true） |
| `type` | enum (5 项) |  | IK：IK 类型 |
| `bone_name` | string |  | IK：骨骼名 |
| `target_nodepath` | string |  | IK：目标节点路径 |
| `parent` | string |  | IK：父节点路径 |
| `properties` | object |  | IK：属性键值对 |
| `limit` | number |  | IK：最大返回数量 |

## 风险分布

读 10 / 写 7 / 破坏性 3

---
<!-- AUTO-GENERATED by scripts/gen-tool-docs.mjs from capability-matrix.json v0.32.21. DO NOT edit manually; re-run npm run gen:tool-docs after tool changes. -->