# TimerModule 接入说明

基于 UnityGameFramework 的通用定时器组件插件，支持延迟执行、循环执行、按归属对象批量取消等功能。

## 导入步骤

1. 将 `Assets/Plugins/TimerModule/` 整个目录导入目标项目
2. 导入后通过 asmref 自动并入 `SepCore.Runtime` 程序集，基座项目仍可正常编译
3. 移除 TimerModule 时只需删除整个目录，不会留下残留引用

## 程序集结构

```
SepCore.Runtime.Timer.asmref  →  引用 SepCore.Runtime，使 TimerComponent 与其他基座 Component 平级
```

- 依赖：`UnityGameFramework.Runtime`（框架自带）
- 无第三方依赖，纯 C# 实现
- 命名空间：`SepCore.Timer`

## 场景挂载要求

在 GameFramework 框架的组件挂载对象上（通常是场景中的 `GameEntry` 对象）：

1. 添加 `TimerComponent` 组件
2. 组件会通过 `Update()` 自动驱动，无需额外初始化
3. AddComponentMenu 路径：`Game Main/Timer`

## API 使用方式

```csharp
using SepCore.Timer;

// 获取组件引用
var timer = GameEntry.GetComponent<TimerComponent>();

// 1. 一次性延迟执行
timer.ScheduleOnce(2f, () =>
{
    Debug.Log("2秒后执行");
});

// 2. 无限循环（默认）
timer.ScheduleRepeat(1f, () =>
{
    Debug.Log("每秒执行一次");
});

// 3. 指定次数循环（首次延迟 = 循环间隔）
timer.ScheduleRepeat(0.5f, () =>
{
    Debug.Log("每0.5秒执行，共执行10次");
}, repeatCount: 10);

// 4. 自定义首次延迟 + 循环间隔
timer.ScheduleRepeat(delay: 3f, interval: 1f, () =>
{
    Debug.Log("3秒后开始，然后每秒执行一次");
});

// 5. 使用 unscaledTime（不受 Time.timeScale 影响）
timer.ScheduleRepeat(1f, () =>
{
    Debug.Log("暂停时也会执行");
}, timeMode: TimerTimeMode.Unscaled);

// 6. 取消单个任务
TimerHandle handle = timer.ScheduleOnce(5f, Callback);
timer.Cancel(handle);  // 提前取消

// 7. 按归属对象批量取消（适合 MonoBehaviour 销毁时清理）
private void OnDestroy()
{
    timer.CancelByOwner(this);  // 取消所有归属于当前对象的定时器
}

// 8. 全局暂停/恢复
timer.Pause();   // 暂停所有定时器
timer.Resume();  // 恢复所有定时器

// 9. 清理所有
timer.ClearAll();
```

## TimerHandle 说明

- 值类型，可安全作为成员变量存储
- `handle.IsValid` - 检查句柄是否有效
- `TimerHandle.Invalid` - 无效句柄常量
- 实现 `IEquatable<TimerHandle>`，可用于字典键或比较

## 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `delay` | float | - | 首次触发前的延迟时间（秒） |
| `interval` | float | - | 循环触发间隔（秒），一次性任务忽略 |
| `repeatCount` | int | -1 | 触发次数：1=一次性，负数=无限循环，0=不创建 |
| `owner` | object | null | 任务归属对象，用于 `CancelByOwner` 批量取消 |
| `timeMode` | TimerTimeMode | Scaled | 时间源：Scaled 受 timeScale 影响，Unscaled 不受影响 |

## 最佳实践

1. **MonoBehaviour 中使用时务必设置 owner**，并在 `OnDestroy` 中调用 `CancelByOwner(this)` 避免回调执行在已销毁对象上

2. **在回调中取消自身是安全的**：回调执行时标记取消，当前帧更新结束后统一清理

3. **精度说明**：定时器基于帧更新，精度受帧率影响，适合游戏逻辑计时，不适合高精度物理模拟

4. **推荐使用便捷方法**：`ScheduleOnce` 和 `ScheduleRepeat` 比直接 `Schedule(TimerTask)` 更清晰

## 编辑器调试功能

TimerModule 内置了完整的 Editor 调试扩展，选中挂载 `TimerComponent` 的对象即可看到：

### 统计信息面板
- **活跃任务总数** - 当前正在运行的任务数量
- **Scaled/Unscaled 分布** - 受时间缩放影响的任务 vs 不受影响的任务
- **无限循环数** - `repeatCount < 0` 的永久任务数量
- **异常任务数** - 回调曾抛出异常的任务（红色高亮）
- **全局运行状态** - 绿色=运行中，橙色=已暂停

### 任务列表可视化
- **ID + 时间模式标签** - 快速识别任务，青色=Scaled，黄色=Unscaled
- **进度条** - 显示剩余时间和当前周期完成进度
  - 一次性任务：显示延迟完成度
  - 循环任务：显示当前周期进度
- **回调方法名** - `Class.Method` 格式，定位来源
- **归属对象** - 点击可直接 Ping 到场景中的 Owner 对象
- **异常标记** - 曾抛异常的任务会有红色背景警告

### 调试控制
- **暂停/恢复全部** - 一键控制全局定时器
- **单任务取消** - 每个任务右侧的取消按钮，可随时终止
- **清理全部** - 一键清除所有任务（含确认对话框）

## 性能特性

- 回调异常自动捕获并 LogError，不会中断其他任务或游戏
- 帧更新时遍历取消采用反向遍历，避免索引错乱
- 更新期间的删除操作延迟到帧末执行，避免并发问题
- O(n) 线性遍历，适合千级以内任务规模
- Editor 调试面板每帧自动刷新，不影响 Build 性能