GSIBase

重要 注意 提醒

Coding Style wiki

---

GSIBase 是 GSIFrame（Game Stage Integration）的游戏阶段抽象基类。每个游戏阶段（如启动、商标、热更、登录、大厅）都以一个子类继承 GSIBase 实现，定义了 OnCreate → OnEnter → OnUpdate → OnExit 的完整阶段生命周期，由 GSIManagerBase 子类统一注册、切换与驱动。

命名空间	OxGFrame.GSIFrame
类型	public abstract class
源码	GSIBase.cs

using OxGFrame.GSIFrame;

声明

public abstract class GSIBase

继承 GSIBase 后，必须实现 OnCreate、OnEnter、OnUpdate、OnExit 四个生命周期方法（皆为 abstract）。

生命周期与调用时序

生命周期方法皆由管理器（GSIManagerBase 子类）在阶段切换与驱动更新时自动调用，无需手动触发。当管理器切换至该阶段时，内部初始流程依以下顺序执行：

1. 首次检查：若该阶段从未初始化过，先 await OnCreate（整个生命周期仅执行一次）。
2. Step 1：调用 StopUpdate，先暂停 OnUpdate 刷新。
3. Step 2：await OnEnter，执行进入阶段的初始逻辑。
4. Step 3：调用 RunUpdate，开启 OnUpdate 刷新。

之后，管理器在每帧驱动更新（DriveUpdate）时，若该阶段为当前阶段且 runUpdate 为 true，将调用 OnUpdate；切换至其他阶段时，管理器会先调用该阶段的 OnExit，再执行新阶段的初始流程。

提醒 OnCreate 与 OnEnter 皆为 UniTask 异步方法，可直接 await 资源加载等异步操作；初始流程会等 OnEnter 完成后才开启 OnUpdate 刷新。

注意 初始流程以 Forget()（Fire-and-Forget）方式启动，不会阻塞管理器的驱动更新。

继承实现示例

using Cysharp.Threading.Tasks;
using OxGFrame.GSIFrame;
using UnityEngine;

// 自定义游戏阶段：继承 GSIBase 并重写四个生命周期方法
public class StartupStageExample : GSIBase
{
    public async override UniTask OnCreate()
    {
        // 首次切换至该阶段时执行一次，适合进行一次性的初始
        Debug.Log($"StartupStage OnCreate, Id: {this.id}");
    }

    public async override UniTask OnEnter()
    {
        // 每次切换进入该阶段时执行
        // 可 await 资源预加载等异步操作，完成后才会开启 OnUpdate 刷新
        Debug.Log("StartupStage OnEnter");
    }

    public override void OnUpdate(float dt = 0.0f)
    {
        // 阶段活跃期间每帧执行（由管理器的驱动更新调用）
    }

    public override void OnExit()
    {
        // 切换至其他阶段时执行，清理该阶段产生的数据
        Debug.Log("StartupStage OnExit");
    }
}

阶段子类需通过 GSIManagerBase 子类进行注册与切换：

// 在任意处通过管理器切换至该阶段（详见 GSIManagerBase）
GSIManagerExample.ChangeStage<StartupStageExample>();

提醒 可通过 Project 窗口右键模板快速创建阶段子类：Create → OxGFrame → GSI Frame → Template Scripts → Template GSI.cs (Game Stage)。

成员总览

属性

属性	说明
id	阶段识别码（注册时由管理器自动设置）。
runUpdate	是否运行 OnUpdate 刷新的开关。

生命周期方法（abstract，继承后必须实现）

方法	说明
OnCreate	首次进入该阶段时执行一次（异步）。
OnEnter	每次切换进入该阶段时执行（异步）。
OnUpdate	阶段活跃期间每帧执行。
OnExit	切换离开该阶段时执行。

一般方法

方法	说明
SetId	设置阶段识别码（注册时由管理器自动调用）。
RunUpdate	开启 OnUpdate 刷新。
StopUpdate	停止 OnUpdate 刷新。

---

id

public int id { get; private set; }

说明

阶段的唯一识别码。在管理器注册阶段时自动设置：以泛型重载注册且未指定 id 时，为该类型的 GetHashCode()；有指定时则为传入的 id。外部仅可读取，只能通过 SetId 变更。

---

runUpdate

public bool runUpdate { get; private set; }

说明

是否运行 OnUpdate 刷新的开关。为 true 时，管理器的驱动更新才会调用该阶段的 OnUpdate。外部仅可读取，只能通过 RunUpdate / StopUpdate 变更。

---

OnCreate

public abstract UniTask OnCreate()

返回值

UniTask — 可等待的异步操作，初始流程会 await 其完成后才继续执行 OnEnter。

说明

该阶段首次被切换进入时执行，整个生命周期仅执行一次，适合进行一次性的初始或资源预加载。

注意 OnCreate 在首次切换进入该阶段时才会执行，并非注册（AddStage）当下。

---

OnEnter

public abstract UniTask OnEnter()

返回值

UniTask — 可等待的异步操作，初始流程会 await 其完成后才开启 OnUpdate 刷新。

说明

每次切换进入该阶段时执行，处理进入阶段的初始逻辑（如打开 UI、播放转场动画、预加载资源）。执行前初始流程会先调用 StopUpdate 暂停刷新，完成后自动调用 RunUpdate 开启刷新。

---

OnUpdate

public abstract void OnUpdate(float dt = 0.0f)

参数

参数	类型	说明
dt	float	帧间隔时间，由管理器的驱动更新传入（一般为 Time.deltaTime）。 默认值：0.0f

说明

阶段活跃期间的每帧更新。该阶段为当前阶段且 runUpdate 为 true 时，由管理器的驱动更新（DriveUpdate）每帧调用，处理阶段内的循环逻辑（如计时器、流程判断）。

---

OnExit

public abstract void OnExit()

说明

切换至其他阶段时，由管理器在执行新阶段的初始流程前调用。用于清理该阶段产生的数据、关闭相关 UI 或停止音效等收尾处理。

---

SetId

public void SetId(int id)

参数

参数	类型	说明
id	int	阶段识别码。

说明

设置阶段识别码 id。

提醒 注册阶段时（AddStage / AddGameStage）由管理器自动调用，一般无需手动调用。

---

RunUpdate

public void RunUpdate()

说明

将 runUpdate 设为 true，开启 OnUpdate 刷新。初始流程在 OnEnter 完成后会自动调用；也可在阶段内手动调用，恢复先前暂停的刷新。

---

StopUpdate

public void StopUpdate()

说明

将 runUpdate 设为 false，暂停 OnUpdate 刷新。可在阶段内手动调用（如过场期间暂停阶段更新），再通过 RunUpdate 恢复。

---