unity-timeline

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

触发条件

• 构建过场或序列
• 创建 Timeline 资产
• 添加轨道和片段
• 制作过场或序列、创建 Timeline 资产、添加轨道与片段

Timeline 技能

创建和修改 Unity Timeline 资产——添加类型化轨道、将片段放到轨道上、绑定对象、设置时长／循环模式，以及通过 PlayableDirector 播放／暂停／停止编辑器预览。

操作模式

• Approval：查询类 skill（timeline_list_tracks，源码标记为 SkillMode.SemiAuto）直接执行；其余变更／播放类（timeline_create / add_*_track / timeline_add_clip / timeline_set_duration / timeline_play / timeline_set_binding，标记为 SkillMode.FullAuto）需获得用户授权，授权后由服务端一步执行并返回结果。
• Auto / Bypass：未被禁用列表拦截的 skill 直接执行。
• 本模块包含 Delete 类 skill：timeline_remove_track 标记为 SkillOperation.Delete，会被 IsForbiddenInSemi 静态拦截——仅 Bypass 模式或加入 Allowlist 后才能调用。
• timeline_play 仅驱动编辑器预览（在编辑器上下文中调用 PlayableDirector.Evaluate / Play），不会进入 Play mode。

不要（常见臆测）：

• timeline_create_animation / timeline_add_track 不存在 → 请使用类型化轨道技能：timeline_add_animation_track、timeline_add_audio_track、timeline_add_activation_track、timeline_add_control_track、timeline_add_signal_track
• timeline_add_keyframe 不存在 → Timeline 使用片段，而非直接使用关键帧；请使用 timeline_add_clip
• timeline_set_duration 设置的是 Timeline 资产时长，而非单个片段的时长

路由：

• 对于 Animator 参数／状态 → 使用 animator 模块
• 对于运行时动画播放 → 使用 editor_play，或通过 script 模块编写 C#

技能

timeline_create

创建新的 Timeline 资产和 Director 实例。

参数	类型	必填	默认值	描述
name	string	是	-	Timeline／对象的名称
folder	string	否	"Assets/Timelines"	资产的保存文件夹

返回： { success, assetPath, gameObjectName, directorInstanceId }

timeline_add_audio_track

向 Timeline 添加 Audio 轨道。

参数	类型	必填	默认值	描述
name	string	否	-	包含 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
trackName	string	否	"Audio Track"	新轨道的名称

返回： { success, trackName }

timeline_add_animation_track

向 Timeline 添加 Animation 轨道，并可选择绑定对象。

参数	类型	必填	默认值	描述
name	string	否	-	包含 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
trackName	string	否	"Animation Track"	新轨道的名称
bindingObjectName	string	否	-	要绑定的 GameObject 名称（animator）

返回： { success, trackName, boundObject }

timeline_add_activation_track

添加 Activation 轨道以控制对象的可见性。

参数	类型	必填	默认值	描述
name	string	否	-	包含 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
trackName	string	否	"Activation Track"	新轨道的名称

返回： { success, trackName }

timeline_add_control_track

为嵌套 Timeline 或预制体生成添加 Control 轨道。

参数	类型	必填	默认值	描述
name	string	否	-	带有 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
trackName	string	否	"Control Track"	新轨道的名称

返回： { success, trackName }

timeline_add_signal_track

添加用于事件标记的 Signal 轨道。

参数	类型	必填	默认值	描述
name	string	否	-	带有 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
trackName	string	否	"Signal Track"	新轨道的名称

返回： { success, trackName }

timeline_remove_track

按名称从 Timeline 中移除轨道。

参数	类型	必填	默认值	描述
name	string	否	-	带有 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
trackName	string	是	-	要移除的轨道名称

返回： { success, removed }

timeline_list_tracks

列出 Timeline 中的所有轨道。

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

返回： { count, tracks: [{ name, type, muted, clipCount }] }

timeline_add_clip

按轨道名称向轨道添加片段。

参数	类型	必填	默认值	描述
name	string	否	-	带有 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
trackName	string	是	-	目标轨道的名称
start	double	否	0	片段开始时间，单位为秒
duration	double	否	1	片段时长，单位为秒

返回： { success, trackName, clipStart, clipDuration }

timeline_set_duration

设置 Timeline 时长和循环模式。

参数	类型	必填	默认值	描述
name	string	否	-	带有 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
duration	double	否	0	固定时长，单位为秒
wrapMode	string	否	-	循环模式：Hold/Loop/None

返回： { success, duration, wrapMode }

timeline_play

播放、暂停或停止 Timeline（编辑器预览）。

参数	类型	必填	默认值	描述
name	string	否	-	带有 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
action	string	否	"play"	操作：play/pause/stop

返回： { success, action, time }

timeline_set_binding

设置轨道的绑定对象。

参数	类型	必填	默认值	描述
name	string	否	-	带有 PlayableDirector 的 GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	-	GameObject 层级路径
trackName	string	是	-	轨道名称
bindingObjectName	string	是	-	要绑定的对象名称

返回： { success, trackName, boundTo }

精确签名

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