ActionBase

重要 注意 提醒

Coding Style wiki

---

ActionBase 是 ActionSystem 所有動作的抽象基類，自定義動作需繼承此類，並透過覆寫 OnStart / OnUpdate / OnDone 生命週期方法實作行為，以 SetDuration 控制持續時間 (設置 -1 表示依條件結束，需手動 MarkAsDone)；另外內建子動作 (Sub Action) 機制，可在動作內組合子動作。

命名空間	OxGKit.ActionSystem
類型	public abstract class ActionBase
原始碼	ActionBase.cs

using OxGKit.ActionSystem;

提醒 可透過 Right-Click Create/OxGKit/Action System/Template Action.cs 快速建立自定義 Action 腳本模板。

快速上手

計時型動作：於 OnStart 設置持續時間，時間到會自動標記完成 (觸發 OnDone)，可搭配 GetTimeElapsedRatio 製作進度漸變效果。

using OxGKit.ActionSystem;
using UnityEngine;

public class FadeOutAction : ActionBase
{
    #region Default Constructor
    public FadeOutAction()
    {
        this.name = nameof(FadeOutAction);
    }

    public FadeOutAction(int uid) : this()
    {
        this.uid = uid;
    }
    #endregion

    public CanvasGroup canvasGroup;
    public float duration;

    /// <summary>
    /// [Factory Mode] 透過靜態方法建立動作實例
    /// </summary>
    public static FadeOutAction CreateFadeOutAction(CanvasGroup canvasGroup, float duration)
    {
        var action = new FadeOutAction();
        action.canvasGroup = canvasGroup;
        action.duration = duration;
        return action;
    }

    protected override void OnStart()
    {
        // 設置持續時間 (時間到自動 MarkAsDone)
        this.SetDuration(this.duration);
    }

    protected override void OnUpdate(float dt)
    {
        // 依經過時間比例 (0 到 1) 進行漸變
        this.canvasGroup.alpha = 1f - this.GetTimeElapsedRatio();
    }

    protected override void OnDone()
    {
        this.canvasGroup.alpha = 0f;
    }
}

條件型動作：SetDuration(-1) 表示依條件結束，必須自行呼叫 MarkAsDone。

using OxGKit.ActionSystem;

public class WaitForServerAction : ActionBase
{
    public WaitForServerAction()
    {
        this.name = nameof(WaitForServerAction);
    }

    protected override void OnStart()
    {
        // -1 = 依條件結束，必須手動呼叫 MarkAsDone
        this.SetDuration(-1);

        // 條件達成時結束動作
        Server.Request(ok => this.MarkAsDone());
    }
}

通用規則

生命週期

1. RunStart：先 Reset() 重置狀態 (旗標、經過時間、子動作)，標記為已啟動後觸發 OnStart (於此設置 SetDuration 與初始邏輯)。
2. RunUpdate(dt)：由運行器每幀驅動，累計經過時間；未完成時，持續時間到會自動 MarkAsDone，否則觸發 OnUpdate，並同時更新子動作。
3. MarkAsDone：觸發 OnDone (僅一次) 並標記完成；當動作本身完成且子動作全部完成時，才會標記全部完成 (IsAllDone)，運行器以此判斷移除時機。

完成規則

重要 SetDuration(-1) 的動作永遠不會自動結束，必須保證 MarkAsDone() / MarkAllDone() 的呼叫路徑一定會觸發 (包含錯誤路徑)。

注意 動作為有狀態的一次性物件：重新運行 (RunStart) 會重置內部狀態，但請勿讓兩個運行器同時共用同一個動作實例。

---

成員

成員	說明
public int uid	動作唯一識別碼，可供 RemoveAction(uid) 依 UID 移除。
public string name	動作名稱 (預設類名)，用於日誌輸出識別。

保護欄位 (供衍生類使用)

成員	說明
protected bool _isStarted	是否已啟動旗標。
protected bool _isDone	動作本身完成旗標。
protected bool _isAllDone	全部完成旗標 (含子動作)。
protected float _duration	持續時間 (透過 SetDuration 設置)。
protected float _timeElapsed	已累計的經過時間。
protected QueueSet<ActionBase> _queueSubActions	子動作佇列 (QueueSet 為先進先出且不重複的佇列集合)。

---

生命週期覆寫

方法總覽

方法	說明
OnStart	動作啟動時觸發 (設置持續時間與初始邏輯)。
OnUpdate	動作每幀更新時觸發 (完成後不再呼叫)。
OnDone	呼叫 MarkAsDone 時觸發 (僅一次)。

---

OnStart

protected virtual void OnStart() { }

動作啟動時觸發 (由 RunStart 呼叫)，通常於此設置 SetDuration 並執行初始邏輯。

OnUpdate

protected virtual void OnUpdate(float dt) { }

動作每幀更新時觸發 (由 RunUpdate 驅動)；動作完成後不會再被呼叫。

OnDone

protected virtual void OnDone() { }

當呼叫 MarkAsDone 時觸發 (僅觸發一次)，可用於結尾處理 (回調、狀態清理)。

---

運行控制

方法總覽

方法	說明
RunStart	啟動動作 (重置狀態並觸發 OnStart)。
RunUpdate	更新動作 (含時間累計與子動作更新)。
Reset	重置動作狀態 (含清空子動作)。

---

RunStart

public void RunStart()

啟動動作：先 Reset 重置狀態、標記為已啟動，再觸發 OnStart。

提醒 通常由 ActionRunner 或組合動作 (SequenceAction 等) 呼叫，一般不需要自行呼叫。

RunUpdate

public void RunUpdate(float dt)

更新動作 (由運行器每幀驅動)：累計經過時間，持續時間到會自動 MarkAsDone，否則觸發 OnUpdate；並同時更新子動作，當動作本身與子動作皆完成時標記全部完成。

Reset

public void Reset()

重置動作狀態 (啟動/完成旗標、經過時間) 並清空子動作。

---

狀態查詢

方法總覽

方法	說明
IsStarted	是否已啟動。
IsDone	動作本身是否完成。
IsAllDone	是否全部完成 (含子動作)。
GetTimeElapsed	取得經過時間 (秒)。
GetTimeElapsedRatio	取得經過時間比例 (0 到 1)。

---

IsStarted

public bool IsStarted()

動作是否已啟動 (RunStart 後為 true)。

IsDone

public bool IsDone()

動作本身是否完成 (不含子動作)。

IsAllDone

public bool IsAllDone()

動作是否全部完成 (含子動作)；運行器以此判斷動作是否可移除。

GetTimeElapsed

public float GetTimeElapsed()

取得動作啟動後累計的經過時間 (秒)。

GetTimeElapsedRatio

public float GetTimeElapsedRatio()

取得經過時間比例 (0 到 1，依 SetDuration 設置的持續時間計算；duration 小於等於 0 時回傳 0)，適合用於漸變 (Lerp) 等進度效果。

---

完成控制

方法總覽

方法	說明
SetDuration	設置持續時間 (-1 = 依條件手動結束)。
MarkAsDone	標記動作完成 (觸發 OnDone)。
MarkAllDone	標記全部完成 (含子動作)。
CheckAndReduceTime	檢查持續時間是否已到 (protected)。

---

SetDuration

public void SetDuration(float duration)

設置動作持續時間 (秒)，時間到會自動 MarkAsDone；設置 -1 表示依條件結束。

重要 SetDuration(-1) 的動作永遠不會自動結束，必須自行呼叫 MarkAsDone (請保證回調路徑一定會觸發，包含錯誤路徑)。

MarkAsDone

public void MarkAsDone()

標記動作完成：觸發 OnDone (僅一次)；若子動作也全部完成，會一併標記全部完成 (IsAllDone)。

MarkAllDone

public void MarkAllDone()

標記動作全部完成 (含所有子動作)；運行器移除動作 (RemoveAction) 時也會呼叫此方法。

CheckAndReduceTime

protected bool CheckAndReduceTime()

檢查持續時間是否已到 (duration 為 -1 時恆回傳 false)，由 RunUpdate 自動呼叫，一般不需要自行呼叫。

---

子動作 (Sub Action)

供衍生類於動作內組合子動作的保護方法，子動作由基類的 RunUpdate 自動更新；當動作本身完成且子動作全部完成時，才會標記全部完成。

方法總覽

方法	說明
AddSubAction	加入並啟動子動作。
IsSubActionAllDone	檢查子動作是否全部完成。
UpdateSubActions	更新所有子動作。
MarkSubAllDone	標記所有子動作完成。
ClearSubActions	清空子動作。

---

AddSubAction

protected ActionBase AddSubAction(ActionBase action)

加入子動作 (同一實例不會重複加入，加入時會直接觸發其 OnStart)，回傳動作本身。

IsSubActionAllDone

protected bool IsSubActionAllDone()

檢查所有子動作是否全部完成 (無子動作時回傳 true)。

UpdateSubActions

protected void UpdateSubActions(float dt)

更新所有子動作 (由 RunUpdate 自動呼叫)。

MarkSubAllDone

protected void MarkSubAllDone()

標記所有子動作為全部完成 (由 MarkAllDone 自動呼叫)。

ClearSubActions

protected void ClearSubActions()

清空子動作佇列。