跳至主要内容

RealTimer

重要 注意 提醒

Coding Style wiki​

RealTimer 是以系統時鐘 (DateTime.Now) 計算的真實時間計時器，實例建立當下即為時間基準點，查詢式自驅動 (不需外部 Update 餵入)；不受 Time.timeScale、遊戲暫停與幀率卡頓影響。支持 Timer (單次計時)、Tick (循環計時)、Mark (時間標記) 三種模式與時間速度調整。

命名空間OxGKit.TimeSystem
類型public class RealTimer
原始碼RealTimer.cs
using OxGKit.TimeSystem;

快速上手​

using OxGKit.TimeSystem;
using UnityEngine;

public class RealCooldown : MonoBehaviour
{
    private RealTimer _cooldown;

    private void Start()
    {
        // 建立並自動播放 (autoPlay: true)
        this._cooldown = new RealTimer(true);
        // 設置 10 秒冷卻 (真實時間)
        this._cooldown.SetTimer(10f);
    }

    private void Update()
    {
        // 查詢式檢查，不需餵入 deltaTime
        if (this._cooldown.IsTimerTimeout())
        {
            // 冷卻結束 (即使期間 Time.timeScale = 0 仍照常倒數)
        }
    }
}

通用規則​

RealTimer vs DeltaTimer​

注意 RealTimer 以系統時鐘為基準，即使遊戲暫停 (Time.timeScale = 0) 或程式卡頓仍持續計時；若需要跟隨遊戲暫停與變速的計時，請改用 DeltaTimer (詳見模組選型)。

播放狀態​

重要 計時器建構後預設為停止狀態，需呼叫 Play (或使用建構子 autoPlay: true) 才會開始計時。

提醒 Stop 會清空所有計時數據 (保留時間速度)；Reset 會連同時間速度一併重置為預設值；Pause 僅暫停，可由 Play 續播。

建構子​

public RealTimer()

public RealTimer(bool autoPlay)

建立計時器並以建立當下的系統時間作為基準點 (內部會先執行 Reset)，autoPlay 為 true 時建立後立即開始計時。

播放控制​

方法總覽​

方法說明
GetRealTime取得自實例建立以來的真實經過秒數。
Play開始或續播計時。
Pause暫停計時 (可續播)。
Stop停止並清空計時數據。
Reset重置所有狀態 (含時間速度)。
IsPlaying是否正在計時。
IsPause是否為暫停 (停止) 狀態。
GetTime取得計時器當前時間 (秒)。
SetTimeSpeed設置時間運轉速度。
GetTimeSpeed取得時間運轉速度。

GetRealTime​

public float GetRealTime()

取得自計時器實例建立以來的真實經過秒數 (以系統時鐘 DateTime.Now 計算，不受播放狀態與時間速度影響)。

Play​

public void Play()

開始計時或自暫停狀態續播 (會扣除暫停期間的真實時間，不會跳段)。

Pause​

public void Pause()

暫停計時，記錄暫停時間點，可由 Play 續播。

Stop​

public void Stop()

停止計時並清空所有計時數據 (Timer / Tick / Mark 設置皆歸零)，但保留時間速度 (timeSpeed)。

Reset​

public void Reset()

重置所有狀態為預設值 (含時間速度重置為 1)，並回到停止狀態。

IsPlaying​

public bool IsPlaying()

返回是否正在計時中。

IsPause​

public bool IsPause()

返回是否為暫停 (非播放) 狀態。

GetTime​

public float GetTime()

取得計時器的當前累計時間 (秒)，計時中會受 SetTimeSpeed 影響；暫停時返回暫停當下的時間。

SetTimeSpeed​

public void SetTimeSpeed(float timeSpeed)

設置時間運轉速度 (預設 1)，影響 GetTime 的時間流速 (連帶影響 Timer / Tick / Mark 判斷)。

GetTimeSpeed​

public float GetTimeSpeed()

取得當前時間運轉速度。

Timer 單次計時​

依照設置的秒數進行單次倒數計時。

方法總覽​

方法說明
SetTimer設置要計時的秒數。
TimerCountdown取得倒數剩餘秒數 (到時返回 0)。
IsTimerTimeout返回計時時間是否已經到了。
GetTimerCountdownRatio取得倒數時間比率 (1 遞減至 0)。

SetTimer​

public void SetTimer(float timeSeconds)

設置要計時的秒數 (以當前時間 + 秒數作為觸發時間點)。

this._realTimer.SetTimer(10f);
this._realTimer.Play();

TimerCountdown​

public float TimerCountdown()

計算觸發時間的倒數剩餘秒數，如果已超過設置的觸發時間將直接返回 0。

IsTimerTimeout​

public bool IsTimerTimeout()

返回計時時間是否已經到了 (超過觸發時間點返回 true)。

提醒 時間到後 IsTimerTimeout() 會持續返回 true，一次性行為請於觸發後自行 Stop 或重新 SetTimer。

GetTimerCountdownRatio​

public float GetTimerCountdownRatio()

取得 Timer 倒數計時的時間比率，1 遞減至 0，0 = 時間到 (適合驅動進度條 UI)。

Tick 循環計時​

持續依照設置的間隔秒數循環觸發 (Timeout 後自動重新裝填)。

方法總覽​

方法說明
SetTick設置 Tick 間隔秒數。
GetTick取得設置的 Tick 間隔秒數。
TickCountdown取得本次 Tick 的倒數剩餘秒數。
IsTickTimeout返回 Tick 時間是否已經到了 (自動重新裝填)。
GetTickCountdownRatio取得 Tick 倒數時間比率 (1 遞減至 0)。

SetTick​

public void SetTick(float tickSeconds)

設置 Tick 間隔秒數，當 IsTickTimeout 觸發後仍會持續循環 Tick。

// 每 2 秒觸發一次 (真實時間)
this._realTimer.SetTick(2f);
this._realTimer.Play();

GetTick​

public float GetTick()

取得設置的 Tick 間隔秒數。

TickCountdown​

public float TickCountdown()

取得本次 Tick 觸發時間的倒數剩餘秒數，如果已超過觸發時間將直接返回 0。

IsTickTimeout​

public bool IsTickTimeout()

返回 Tick 時間是否已經到了；返回 true 時會自動以當前時間重新裝填下一次 Tick，形成循環觸發。

private void Update()
{
    if (this._realTimer.IsPlaying() &&
        this._realTimer.IsTickTimeout())
    {
        // 每個 Tick 週期觸發一次
    }
}

重要 IsTickTimeout() 返回 true 時會自動重新裝填，該次觸發即被「消耗」，同一週期內請僅由單一呼叫端檢查一次，否則觸發會被其他呼叫端吃掉。

GetTickCountdownRatio​

public float GetTickCountdownRatio()

取得 Tick 倒數計時的時間比率，1 遞減至 0，0 = 時間到。

Mark 時間標記​

標記某個時間點，用於計算經過時間 (碼表用途)。

方法總覽​

方法說明
SetMark以當前時間設置標記。
GetMark取得標記時間。
GetElapsedMarkTime取得自標記以來的經過時間 (秒)。

SetMark​

public void SetMark()

以計時器的當前時間設置標記時間。

GetMark​

public float GetMark()

取得標記時間。

GetElapsedMarkTime​

public float GetElapsedMarkTime()

取得自上次標記以來的經過時間 (秒)，尚未超過標記時間點時返回 0。

this._realTimer.SetMark();

// ... 一段時間後
float elapsed = this._realTimer.GetElapsedMarkTime();