vampire-like/Assets/Plugins/TimerModule/接入说明.md

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 使用方式

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 性能