跳到主要内容

模块介绍

重要 注意 提醒

Coding Style wiki​

基本说明​

各种 DeltaTimer, RealTimer, DTUpdater, RTUpdater, IntervalTimer, IntervalSetter, NtpTime (clock sync with NTP server) 关于时间的控制器，涵盖游戏时间与真实时间的计时器、独立于 MonoBehaviour 的更新循环、类 JavaScript setInterval 的间隔触发器，以及与 NTP 服务器进行时钟同步的授时工具。

  • 版本：v1.1.3 (com.michaelo.oxgkit.timesystem)
  • 命名空间：OxGKit.TimeSystem

注意 本模块依赖 UniTask 与 OxGKit.LoggingSystem (作为日志输出)，需先安装依赖库。

应用说明​

模块选型 (依时间基准区分)​

重要 选择计时器或更新器前，先确认使用场景是否需要忽略 Time.timeScale 与游戏暂停 (真实时间)，或是跟随游戏时间，由此决定 Real 系列或 Delta (DT) 系列。

类别时间基准驱动方式适用场景
DeltaTimer外部喂入的 deltaTime 累加 (游戏时间)拥有者于 Update 调用 UpdateTimer(dt)跟随游戏暂停与变速的冷却、倒计时
RealTimer系统时钟 (真实时间)自驱动 (查询式)不受暂停与 Time.timeScale 影响的冷却、倒计时
DTUpdaterUniTask 更新循环 (乘算 Unity Time.timeScale)Start()受 Time.timeScale 影响的独立更新循环
RTUpdaterUniTask 更新循环 (真实时间)Start() / StartOnThread()不受 Time.timeScale 影响的独立更新循环 (如网络心跳)
IntervalTimer / IntervalSetter毫秒间隔SetInterval每 N 毫秒触发 Action (类 JavaScript setInterval)
RealTime系统时钟主程序调用 InitStartupTime()记录应用程序启动时间
NtpTimeNTP 服务器 / HTTP 时间 APISynchronize()服务器授时 (防作弊、每日重置等需要可信时间的场景)

Timer / Tick / Mark 计时模式​

DeltaTimer 与 RealTimer 皆提供三种计时模式，可于同一实例上同时使用：

  • Timer (单次计时)：通过 SetTimer(秒数) 设置单次倒计时，以 IsTimerTimeout() 检查是否到时。
  • Tick (循环计时)：通过 SetTick(秒数) 设置循环间隔，IsTickTimeout() 返回 true 时会自动重新装填，持续循环触发。
  • Mark (时间标记)：通过 SetMark() 标记当前时间，以 GetElapsedMarkTime() 获取自标记以来的经过时间 (秒表用途)。

更新循环与间隔触发​

  • DTUpdater 与 RTUpdater 为 UniTask 驱动的独立更新循环，提供 onUpdate、onFixedUpdate、onLateUpdate 回调，可自定义 targetFrameRate (更新频率) 与 timeScale (自身时间尺度，0 ~ 64)，适合驱动非 MonoBehaviour 的系统 (例如搭配 ActionSystem 的 Runner)。
  • IntervalSetter 为静态管理器，统一创建与管理 IntervalTimer，支持 int id / string id / 匿名 handle 三种键值管理方式。

重要 Updater 与 IntervalTimer 皆为 UniTask 循环，功能或场景结束时务必调用 Stop() / StopInterval() / TryClearInterval() 停止，否则循环会持续运转。

模块日志​

  • 本模块的日志通过 OxGKit.LoggingSystem 输出，日志器名称为 OxGKit.TimeSystem.Logger，可在 LoggingLauncher 进行开关与级别配置。

简单使用​

RealTimer vs DeltaTimer 计时​

using OxGKit.TimeSystem;
using UnityEngine;

public class TimerExample : MonoBehaviour
{
    private RealTimer _realTimer;
    private DeltaTimer _deltaTimer;

    private void Start()
    {
        // RealTimer (真实时间，不受 Time.timeScale 与暂停影响)
        this._realTimer = new RealTimer();
        this._realTimer.SetTimer(3f);
        this._realTimer.Play();

        // DeltaTimer (游戏时间，由 UpdateTimer 喂入 dt 驱动)
        this._deltaTimer = new DeltaTimer();
        this._deltaTimer.SetTimer(3f);
        this._deltaTimer.Play();
    }

    private void Update()
    {
        // DeltaTimer 必须持续喂入 deltaTime
        this._deltaTimer.UpdateTimer(Time.deltaTime);

        // 检查 RealTimer
        if (this._realTimer.IsPlaying() &&
            this._realTimer.IsTimerTimeout())
        {
            this._realTimer.Stop();
            Debug.Log("[RealTimer] Time's up!");
        }

        // 检查 DeltaTimer
        if (this._deltaTimer.IsPlaying() &&
            this._deltaTimer.IsTimerTimeout())
        {
            this._deltaTimer.Stop();
            Debug.Log("[DeltaTimer] Time's up!");
        }
    }
}

Updater 更新循环​

using OxGKit.TimeSystem;

// 独立于 MonoBehaviour 的更新循环 (UniTask 驱动)
var rtUpdater = new RTUpdater();
rtUpdater.onUpdate += (dt) => { /* 每次更新 */ };
rtUpdater.timeScale = 1f;        // 自身时间尺度 (0 ~ 64)
rtUpdater.targetFrameRate = 60f; // 更新频率 (默认 60)
rtUpdater.Start();

// 功能结束时务必停止
rtUpdater.Stop();

IntervalSetter 间隔触发​

using OxGKit.TimeSystem;

// 每 1000 毫秒触发一次 (以 string id 管理)
IntervalSetter.SetInterval("poll", () => { /* 周期性工作 */ }, 1000);

// 停止并移除
IntervalSetter.TryClearInterval("poll");

NtpTime 时钟同步​

using OxGKit.TimeSystem;

// 与 NTP 服务器同步 (默认 time.google.com)
NtpTime.Synchronize();

// 同步完成后获取校正时间
if (NtpTime.IsSynchronized())
{
    var now = NtpTime.GetNow();
    var utcNow = NtpTime.GetUtcNow();
}

[参考 Example]

Installation​

Install via git URL
Add https://github.com/michael811125/OxGKit.git?path=Assets/OxGKit/TimeSystem/Scripts to Package Manager

第三方库 (需自行安装)

Samples (Package Manager -> Samples)

模块 API​

Demo​

TimeSystem Demo