场景系统 · 使用说明

〇它是干什么的

先花 30 秒建立直觉，再动手写。

await RevScene.LoadAsync("Battle");                          // ① 异步切场景（推荐）
RevScene.OnProgress += p => bar.value = p;                   // ② 进度挂一次，全局生效

一3 分钟跑起来（可粘贴）

不用初始化、不用挂脚本。

// ① 最常用：异步切场景（async 方法里直接 await）
async RevTask GoBattle()
{
    await RevScene.LoadAsync("Battle");
    RevLog.Info("已经在战斗场景了");            // 这一行执行时，新场景已激活
}

// ② 带进度条（回调参数是 0~1，单调不减，可直接喂 Slider）
await RevScene.LoadAsync("Battle", p => loadingBar.value = p);

// ③ 不想 await？挂事件就够了（挂一次，全局生效）
RevScene.OnLoadStart += name => loadingPanel.Open(name);
RevScene.OnProgress  += p    => loadingBar.value = p;
RevScene.OnLoaded    += name => loadingPanel.Close();
RevScene.OnLoadFailed += why  => RevLog.Error(why);
RevScene.LoadAsync("Login").Forget();        // Forget = 明确表示"故意不 await"

// ④ 死亡重开 / 断线重连：重开当前场景
await RevScene.ReloadAsync();

// ⑤ 最后：切场景时收自己的摊子（对象池框架已经帮你清了，这里只管你自己的）
RevScene.OnLoadStart += _ =>
{
    RevUI.ShutdownAll();                                       // 关掉所有界面
    RevSound.StopAll();                                        // 停掉音效
    RevResBootstrap.Instance.Shutdown(RevResGroup.Battle);     // 按业务域卸资源
};

二"我要做 X" 对照表（全部 API）

左边找需求，右边抄一行。入口统一是 RevScene。

三三个关键约定（记住这三条就够了）

① 进度永远是 0~1，而且到 100% 才真正切

Unity 的 AsyncOperation.progress 在场景激活前最高只到 0.9 —— 直接喂给进度条就是"卡在 90% 再瞬间跳满"。框架的做法：

• 关掉自动激活（allowSceneActivation = false）；
• 把 [0, 0.9] 归一化成 [0, 1]，并且只增不减（采样抖动不会让进度条回退）；
• 显示到 100%（且满足最短时长）才放行激活。

于是你拿到的 p / RevScene.Progress 永远可以直接喂 Slider.value，不用自己乘系数。

② 最短展示时长：minSeconds

小场景加载只要几十毫秒，加载界面会"闪一下"。传 minSeconds（或全局 DefaultMinSeconds）后：

• 进度条最多按"这么长的节奏"走到 100%；
• 到点之前不会激活场景 —— 所以是"真的多显示了一会儿"，不是假进度。

③ 切之前清理：框架默认只清对象池，其余你一行挂上

四新手最容易踩的 4 个坑

五出问题怎么查 + 相关文档

3 分钟定位

1. 打开日志：RevScene.VerboseLog = true → 能看到"准备切换 → 场景名 / 开始异步切换 / 已进入场景 / 已清理对象池 N 个实例"。
2. 看状态：RevScene.State（Idle / Loading / Done / Failed）+ RevScene.Progress + RevScene.IsLoading。
3. 看失败原因：RevScene.OnLoadFailed += why => RevLog.Error(why); —— 原因里会写明是"场景不存在"还是"没进 Build Settings"。
4. 进度不动：正常现象是加载期间停在某个值（比如 40%），那是 Unity 还没到 0.9 平台期；真卡住不动要查是不是同步 IO 阻塞了主线程。

相关文档

• 同目录《场景系统 · 架构解析》：为什么关掉自动激活、为什么进度的换算是纯 C#、为什么只自动清对象池
• 《资源加载系统 · 使用说明》：场景切换时按业务域卸资源（RevResBootstrap.Instance.Shutdown(group)）
• 《UI 系统 · 使用说明》：加载界面用面板写（RevUI），关全部界面用 RevUI.ShutdownAll()