跳至主要内容

模塊介紹

重要 注意 提醒

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