unity-animator

**调用本模块中的任何技能前：**如果你准备根据技能名称或描述猜测参数后调用技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其 schema）。如果你已从 recommend/schema 获取参数定义，则可直接进行 dryRun。

触发条件

• 设置或连接 Animator
• 调整动画状态机
• 在运行时驱动动画参数
• 搭建或连接 Animator、调整动画状态机、运行时驱动动画参数

Unity Animator 技能

控制 Unity 的 Mecanim 系统——创建 Animator Controller、添加层的状态 / 转换 / 参数、将控制器分配给 GameObject、在运行时设置参数，以及播放状态。

操作模式

• Approval：查询类技能（animator_get_parameters / animator_get_info / animator_list_states，源码标记为 SkillMode.SemiAuto）直接执行；其余变更类（create_controller / add_parameter / set_parameter / play / assign_controller / add_state / add_transition，标记为 SkillMode.FullAuto）需要用户授权，授权后由服务端一步执行并返回结果。
• Auto / Bypass：所有技能均直接执行；Auto 由 AI 自行评估，Bypass 则全部放行。
• 本模块不包含 Delete / PlayMode / Reload / 高危技能，也没有仅 Bypass 可拦截的项目。
• animator_set_parameter / animator_play 作用于场景中已挂载 Animator 的 GameObject；如果当前不在 Play mode，状态机只会在 Editor 预览模式下推进，效果与 runtime 并不完全相同。

切勿（常见幻觉）：

• animator_create_clip / animator_add_clip 不存在 → AnimationClips 通过 Unity Editor 或资源导入创建
• animator_set_speed 不存在 → 对 Animator 组件使用 component_set_property，并将 propertyName="speed"

路由：

• 对于 Timeline 动画 → 使用 timeline 模块
• 对于 Animator 上的组件属性 → 使用 component 模块
• 对于动画导入设置 → 使用 importer 模块

技能概览

技能	描述
animator_create_controller	创建新的 Animator Controller
animator_add_parameter	向控制器添加参数
animator_get_parameters	列出所有参数
animator_set_parameter	在运行时设置参数值
animator_play	播放动画状态
animator_get_info	获取 Animator 组件信息
animator_assign_controller	将控制器分配给 GameObject
animator_list_states	列出控制器中的状态
animator_add_state	向控制器层添加状态
animator_add_transition	在两个状态之间添加转换

---

参数类型

类型	描述	示例用途
float	小数值	速度、混合权重
int	整数值	状态索引
bool	真 / 假	IsGrounded、IsRunning
trigger	单次触发信号	Jump、Attack

---

技能

animator_create_controller

创建新的 Animator Controller。

参数	类型	必填	默认值	描述
name	string	是	-	控制器名称
folder	string	否	"Assets/Animations"	保存文件夹

返回值：{success, name, path}

animator_add_parameter

向控制器添加参数。

参数	类型	必填	默认值	描述
controllerPath	string	是	-	控制器资源路径
paramName	string	是	-	参数名称
paramType	string	否	float	float/int/bool/trigger
defaultFloat	float	否	0	初始 float 值
defaultInt	int	否	0	初始 int 值
defaultBool	bool	否	false	初始 bool 值

animator_get_parameters

获取控制器中的所有参数。

参数	类型	必填	描述
controllerPath	string	是	控制器资源路径

返回值：{controller, parameters: [{name, type, defaultFloat, defaultInt, defaultBool}]}

animator_set_parameter

在运行时设置参数值（支持 name/instanceId/path）。

参数	类型	必填	描述
name	string	否*	GameObject 名称
instanceId	int	否*	GameObject 实例 ID
path	string	否*	GameObject 层级路径
paramName	string	是	参数名称
paramType	string	否	float/int/bool/trigger（默认值：float）
floatValue	float	否*	浮点值
intValue	int	否*	整数值
boolValue	bool	否*	布尔值

*至少需要一个标识符。请根据 paramType 使用相应的值（trigger 不需要值）。

animator_play

播放指定的动画状态（支持 name/instanceId/path）。

参数	类型	必填	默认值	描述
name	string	否*	-	GameObject 名称
instanceId	int	否*	0	GameObject 实例 ID
path	string	否*	null	GameObject 层级路径
stateName	string	是	-	动画状态名称
layer	int	否	0	Animator 层
normalizedTime	float	否	0	起始时间（0-1）

*至少需要一个标识符。

animator_get_info

获取 Animator 组件信息（支持 name/instanceId/path）。

参数	类型	必填	默认值	描述
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径

返回：{gameObject, instanceId, hasController, controllerPath, speed, applyRootMotion, updateMode, cullingMode, layerCount, parameterCount}

animator_assign_controller

为 GameObject 指定控制器（支持 name/instanceId/path）。

参数	类型	必填	描述
name	string	否*	GameObject 名称
instanceId	int	否*	GameObject 实例 ID
path	string	否*	GameObject 层级路径
controllerPath	string	是	控制器资源路径

*至少需要一个标识符。

animator_list_states

列出控制器层中的所有状态。

参数	类型	必填	默认值	描述
controllerPath	string	是	-	控制器资源路径
layer	int	否	0	层索引

返回：{controller, layer, layerName, stateCount, states: [{name, tag, speed, hasMotion}]}

animator_add_state

向 Animator Controller 层添加状态。

参数	类型	必填	默认值	描述
controllerPath	string	是	-	控制器资源路径
stateName	string	是	-	新状态的名称
clipPath	string	否	null	要指定的动画剪辑资源路径；如果路径指向的不是 AnimationClip，则会在添加状态前拒绝调用
layer	int	否	0	层索引

返回：{success, controller, stateName, layer}

animator_add_transition

在 Animator Controller 的两个状态之间添加过渡。

参数	类型	必填	默认值	描述
controllerPath	string	是	-	控制器资源路径
fromState	string	是	-	源状态名称
toState	string	是	-	目标状态名称
layer	int	否	0	层索引
hasExitTime	bool	否	true	过渡是否等待退出时间
duration	float	否	0.25	过渡时长（秒）

返回：{success, from, to, layer, hasExitTime, duration}

---

示例：完整动画设置

import unity_skills

# 1. Create controller
unity_skills.call_skill("animator_create_controller",
    name="PlayerController",
    folder="Assets/Animations"
)

# 2. Add parameters
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="Speed", paramType="float", defaultFloat=0
)
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="IsGrounded", paramType="bool", defaultBool=True
)
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="Jump", paramType="trigger"
)

# 3. Assign to character
unity_skills.call_skill("animator_assign_controller",
    name="Player",
    controllerPath="Assets/Animations/PlayerController.controller"
)

# 4. Control at runtime
unity_skills.call_skill("animator_set_parameter",
    name="Player", paramName="Speed", paramType="float", floatValue=5.0
)

# Trigger jump
unity_skills.call_skill("animator_set_parameter",
    name="Player", paramName="Jump", paramType="trigger"
)

# Play specific state
unity_skills.call_skill("animator_play", name="Player", stateName="Idle")

最佳实践

1. 添加参数前先创建控制器
2. 使用有意义的参数名称
3. 触发后，触发器会自动重置
4. 播放状态前设置参数
5. 使用图层播放独立动画（身体 + 面部）
6. 播放状态前，控制器中必须存在这些状态

---

精确签名

确切的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。