跳至主要内容

DeltaTimer

重要 注意 提醒

Coding Style wiki​

DeltaTimer 是以外部餵入的 deltaTime 累加驅動的計時器 (遊戲時間)，需由擁有者 (MonoBehaviour 的 Update 等) 持續呼叫 UpdateTimer(dt) 驅動；停止餵入即凍結，餵入 Time.deltaTime 時自然跟隨 Time.timeScale 與遊戲暫停。支持 Timer (單次計時)、Tick (循環計時)、Mark (時間標記) 三種模式與時間速度調整。

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

快速上手​

using OxGKit.TimeSystem;
using UnityEngine;

public class SkillCooldown : MonoBehaviour
{
    private DeltaTimer _cooldown;

    private void Start()
    {
        // 建立並自動播放 (autoPlay: true)
        this._cooldown = new DeltaTimer(true);
        // 設置 3 秒冷卻
        this._cooldown.SetTimer(3f);
    }

    private void Update()
    {
        // 必須持續餵入 deltaTime 驅動計時器
        this._cooldown.UpdateTimer(Time.deltaTime);

        if (this._cooldown.IsTimerTimeout())
        {
            // 冷卻結束 (時間到)
        }
    }
}

通用規則​

DeltaTimer vs RealTimer​

注意 DeltaTimer 的時間僅在被餵入 UpdateTimer(dt) 時前進，餵入 Time.deltaTime 時會跟隨 Time.timeScale 與遊戲暫停 (凍結)；RealTimer 則以系統時鐘計算，即使遊戲暫停仍持續計時，請依情境選用 (詳見模組選型)。

播放狀態​

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

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

建構子​

public DeltaTimer()

public DeltaTimer(bool autoPlay)

建立計時器 (內部會先執行 Reset)，autoPlay 為 true 時建立後立即開始計時。

成員​

成員說明
public float deltaTime { get; }最後一次透過 UpdateTimer 餵入的 deltaTime。

驅動與播放控制​

方法總覽​

方法說明
UpdateTimer由擁有者餵入 deltaTime 驅動計時器。
Play開始或續播計時。
Pause暫停計時 (可續播)。
Stop停止並清空計時數據。
Reset重置所有狀態 (含時間速度)。
IsPlaying是否正在計時。
IsPause是否為暫停 (停止) 狀態。
GetTime取得計時器當前時間 (秒)。
SetTimeSpeed設置時間運轉速度。
GetTimeSpeed取得時間運轉速度。

UpdateTimer​

public void UpdateTimer(float dt)

需要透過 MonoBehaviour 的 Update 持續餵入 deltaTime 驅動計時器 (內部進行累加)。

private void Update()
{
    this._deltaTimer.UpdateTimer(Time.deltaTime);
}

重要 停止餵入 = 計時凍結，所有 Timer / Tick / Mark 的判斷皆不會前進。

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._deltaTimer.SetTimer(3f);
this._deltaTimer.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。

// 每 0.5 秒觸發一次
this._deltaTimer.SetTick(0.5f);
this._deltaTimer.Play();

GetTick​

public float GetTick()

取得設置的 Tick 間隔秒數。

TickCountdown​

public float TickCountdown()

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

IsTickTimeout​

public bool IsTickTimeout()

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

private void Update()
{
    this._deltaTimer.UpdateTimer(Time.deltaTime);

    if (this._deltaTimer.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._deltaTimer.SetMark();

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