# TimelineKit 使用文档

TimelineKit 是 AIBIS Dream 项目中用于统一管理 Unity Timeline 播放的中心化系统。它基于 `PlayableDirector`，提供播放控制、Addressables 动态加载、Yarn 对话集成等功能。

---

## 目录

1. [系统架构](#系统架构)
2. [快速开始](#快速开始)
3. [配置 DirectorHandler](#配置-directorhandler)
4. [TimelineCenter API](#timelinecenter-api)
5. [Timeline 名称格式](#timeline-名称格式)
6. [Yarn 对话集成](#yarn-对话集成)
7. [代码调用示例](#代码调用示例)
8. [资源组织](#资源组织)
9. [Addressables 配置](#addressables-配置)
10. [常见问题](#常见问题)

---

## 系统架构

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  TimelineCenter │────▶│  DirectorHandler │────▶│ PlayableDirector│
│    (单例中心)    │     │ (场景中的组件)    │     │  (Unity 原生)   │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │
        ├── 注册/注销 Director
        ├── 播放控制 (播放/暂停/停止/重置)
        ├── 状态查询 (时间/时长)
        └── 批量操作
```

- **TimelineCenter**：单例管理器，负责注册所有 Director 并统一调度
- **DirectorHandler**：挂载在带 `PlayableDirector` 的 GameObject 上，自动向 TimelineCenter 注册
- **TimelineYarnCommand**：提供 Yarn Spinner 命令，可在对话脚本中直接播放 Timeline

---

## 快速开始

### 1. 场景设置

1. 在场景中创建或选中一个 GameObject
2. 添加 **PlayableDirector** 组件，并分配默认的 Playable Asset
3. **将 PlayableDirector 的 Play On Awake 设为 false**，否则 Timeline 会在场景加载时立刻播放
4. 添加 **DirectorHandler** 组件
5. 在 DirectorHandler 中填写 **Timeline Name**（唯一标识，用于 PlayTimeline 时指定）

### 2. 播放 Timeline

```csharp
// 播放该 Director 自带的 Playable Asset
TimelineCenter.Instance.PlayTimeline("维修面板");

// 从 Addressables 加载并播放
TimelineCenter.Instance.PlayTimeline("卡扣/卡扣解锁");
```

---

## 配置 DirectorHandler

| 字段 | 说明 |
|------|------|
| **timelineName** | Director 的全局唯一名称，供 PlayTimeline 等 API 使用 |
| **director** | 关联的 PlayableDirector（通常与组件同一 GameObject，可自动查找） |

DirectorHandler 会在 `Start` 时自动向 TimelineCenter 注册，在 `OnDestroy` 时注销。

---

## TimelineCenter API

### 播放控制

| 方法 | 说明 |
|------|------|
| `PlayTimeline(string timelineName)` | 播放 Timeline（同步，不等待结束） |
| `PlayTimelineAsync(string name)` | 协程版本，播放完成后 yield 返回 |
| `StopTimeline(string timelineName)` | 停止播放 |
| `PauseTimeline(string timelineName)` | 暂停 |
| `ResumeTimeline(string timelineName)` | 恢复播放 |
| `ResetTimeline(string timelineName)` | 重置到开头 |
| `HideTimeline(string timelineName)` | 隐藏该 Director 的 GameObject（SetActive(false)） |

### 状态查询

| 方法 | 说明 |
|------|------|
| `GetPlaybackTime(string name)` | 获取当前播放时间（秒） |
| `GetDuration(string name)` | 获取 Timeline 总时长（秒） |

### 扩展操作

| 方法 | 说明 |
|------|------|
| `SetPlaybackSpeed(string name, float speed)` | 设置播放速度 |
| `SeekToTime(string name, double time)` | 跳转到指定时间点 |

### 批量操作

| 方法 | 说明 |
|------|------|
| `PauseAll()` | 暂停所有已注册的 Timeline |
| `StopAll()` | 停止所有 |
| `ResetAll()` | 重置所有 |

---

## Timeline 名称格式

`timelineName` 支持两种格式：

| 格式 | 示例 | 说明 |
|------|------|------|
| **仅 Director 名** | `"维修面板"` | 播放该 Director 自带的 `playableAsset` |
| **Director 名/AddressableKey** | `"卡扣/卡扣解锁"` | 从 Addressables 加载 `Timeline/{AddressableKey}` 并播放 |

解析规则：若包含 `/`，则前半部分为 directorName，后半部分为 addressableKey；否则整个字符串为 directorName。

---

## Yarn 对话集成

TimelineYarnCommand 提供以下 Yarn 命令，可在 `.yarn` 文件中直接使用：

### play_timeline

播放 Timeline，**会等待播放完成**后再继续对话。

```yarn
// 播放自带 Timeline
<<play_timeline 维修面板>>

// 播放 Addressable Timeline
<<play_timeline 卡扣/卡扣解锁>>
```

### reset_timeline

重置 Timeline 到开头。

```yarn
<<reset_timeline 维修面板>>
```

### hide_timeline

隐藏 Timeline 所在的 GameObject。

```yarn
<<hide_timeline 维修面板>>
```

### start_timeline / wait_timeline

`start_timeline` 起播但**不等待**；`wait_timeline` 等待**已经在播**的 Timeline 结束（不重头播）。叙事切场景时常用：黑屏下 `start` → 短 wait 稳住首帧 → `fade_out` → `wait_timeline`。完整约定见项目 Skill [`.cursor/skills/narrative-timeline-flow/SKILL.md`](../../../../.cursor/skills/narrative-timeline-flow/SKILL.md)。

```yarn
<<start_timeline 英里初登场>>
<<wait 0.2>>
<<fade_out>>
<<wait_timeline 英里初登场>>
<<hide_timeline 英里初登场>>
```

---

## 代码调用示例

### 直接播放（不等待）

```csharp
TimelineCenter.Instance.PlayTimeline("维修面板");
```

### 协程中等待播放完成

```csharp
IEnumerator PlayAndDoSomething()
{
    yield return TimelineCenter.Instance.PlayTimelineAsync("卡扣/卡扣解锁");
    // 播放完成后执行
    Debug.Log("Timeline 播放完毕");
}
```

### 配合 ActionKit 使用

```csharp
ActionKit.Sequence()
    .Coroutine(() => TimelineCenter.Instance.PlayTimelineAsync("卡扣/卡扣解锁"))
    .Callback(() => BlockPuzzleYarnCommand.UnlockSystem())
    .Start(this);
```

### 带完成回调的 DirectorHandler 播放

若直接持有 DirectorHandler 引用，可传入 `onComplete`：

```csharp
// 仅适用于 Director 自带的 Asset，非 Addressable
directorHandler.Play(() => Debug.Log("播放完成"));
```

---

## 资源组织

- **Timeline 文件建议放在 `Assets/Animation` 文件夹下**，便于统一管理。

## Addressables 配置

对于需要动态加载的 Timeline 文件，**Addressable 的 Address 格式为 `Timeline/xxx`**。使用 `DirectorName/AddressableKey` 格式调用时，DirectorHandler 会加载：

```
Timeline/{AddressableKey}
```

因此需在 Addressables 中：

1. 创建或使用已有 Group（如「石头维修相关资源」）
2. 将 Timeline 资源加入 Group
3. **设置 Address 为 `Timeline/xxx` 格式**（如 `Timeline/卡扣解锁`）

示例（`石头维修相关资源.asset` 中已有）：

- `Timeline/卡扣解锁`
- `Timeline/卡扣锁定`

代码中调用时，`DirectorName/AddressableKey` 的 addressableKey 部分填 `卡扣解锁` 即可，DirectorHandler 会自动补全 `Timeline/` 前缀。

---

## 常见问题

### Q: Timeline 一进场景就自动播放？

将 PlayableDirector 组件的 **Play On Awake** 设为 **false**。否则 Unity 会在 Awake 时自动播放，与 TimelineCenter 的播放控制冲突。

### Q: Timeline 找不到？

确保场景中对应 GameObject 上有 DirectorHandler，且 `timelineName` 与调用时一致。DirectorHandler 在 `Start` 时注册，若场景未完全加载可能尚未注册。

### Q: Addressable 加载失败？

检查：

1. Addressable 的 Address 是否包含 `Timeline/` 前缀，或与 DirectorHandler 拼出的 key 一致
2. 资源已正确加入 Addressables Group
3. 控制台是否有 `Failed to load PlayableAsset` 等错误

### Q: 播放完成回调不触发？

- `PlayTimeline` / `PlayTimelineAsync` 不直接支持回调，需用协程或 ActionKit 在播放完成后再执行逻辑
- 直接调用 `directorHandler.Play(onComplete)` 时可使用回调，但仅适用于自带 Asset

### Q: 多个 Director 重名？

`timelineName` 必须全局唯一，否则后注册的会覆盖先前的。

---

## 相关文件

- `TimelineCenter.cs` - 中心管理器
- `DirectorHandler.cs` - Director 组件
- `TimelineYarnCommand.cs` - Yarn 命令注册