From 1c8c28e32b2220bcbc4499778778022c5f1db809 Mon Sep 17 00:00:00 2001
From: ssdfasd <2156608475@qq.com>
Date: Thu, 2 Apr 2026 23:17:57 +0800
Subject: [PATCH] docs: add runtime loop API docs

---
 .../XCEngine/Scene/RuntimeLoop/Constructor.md | 28 ++++++
 docs/api/XCEngine/Scene/RuntimeLoop/Pause.md  | 30 +++++++
 docs/api/XCEngine/Scene/RuntimeLoop/Resume.md | 30 +++++++
 .../XCEngine/Scene/RuntimeLoop/RuntimeLoop.md | 87 +++++++++++++++++++
 .../XCEngine/Scene/RuntimeLoop/SetSettings.md | 30 +++++++
 docs/api/XCEngine/Scene/RuntimeLoop/Start.md  | 34 ++++++++
 .../XCEngine/Scene/RuntimeLoop/StepFrame.md   | 33 +++++++
 docs/api/XCEngine/Scene/RuntimeLoop/Stop.md   | 31 +++++++
 docs/api/XCEngine/Scene/RuntimeLoop/Tick.md   | 49 +++++++++++
 9 files changed, 352 insertions(+)
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/Constructor.md
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/Pause.md
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/Resume.md
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/RuntimeLoop.md
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/SetSettings.md
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/Start.md
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/StepFrame.md
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/Stop.md
 create mode 100644 docs/api/XCEngine/Scene/RuntimeLoop/Tick.md

diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/Constructor.md b/docs/api/XCEngine/Scene/RuntimeLoop/Constructor.md
new file mode 100644
index 00000000..2b0561f0
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/Constructor.md
@@ -0,0 +1,28 @@
+# RuntimeLoop::Constructor
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+## 签名
+
+```cpp
+explicit RuntimeLoop(Settings settings = {});
+```
+
+## 作用
+
+创建一个新的 runtime loop，并对传入设置做规范化。
+
+## 当前实现行为
+
+- 构造时会调用内部 `SanitizeSettings(...)`
+- 非法 fixed-step 配置会被回退到安全默认值
+- 不会自动启动任何 `Scene`
+
+## 相关文档
+
+- [RuntimeLoop](RuntimeLoop.md)
+- [SetSettings](SetSettings.md)
diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/Pause.md b/docs/api/XCEngine/Scene/RuntimeLoop/Pause.md
new file mode 100644
index 00000000..21742d85
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/Pause.md
@@ -0,0 +1,30 @@
+# RuntimeLoop::Pause
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+## 签名
+
+```cpp
+void Pause();
+```
+
+## 作用
+
+暂停自动推进 runtime loop。
+
+## 当前实现行为
+
+- 仅在运行中生效
+- 把 `m_paused` 置为 `true`
+- 同时清除 `m_stepRequested`
+
+之后普通 `Tick()` 会直接返回，直到调用 [Resume](Resume.md) 或 [StepFrame](StepFrame.md)。
+
+## 相关文档
+
+- [Resume](Resume.md)
+- [StepFrame](StepFrame.md)
diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/Resume.md b/docs/api/XCEngine/Scene/RuntimeLoop/Resume.md
new file mode 100644
index 00000000..23e99bd6
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/Resume.md
@@ -0,0 +1,30 @@
+# RuntimeLoop::Resume
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+## 签名
+
+```cpp
+void Resume();
+```
+
+## 作用
+
+恢复 runtime loop 的自动推进。
+
+## 当前实现行为
+
+- 仅在运行中生效
+- 把 `m_paused` 置为 `false`
+- 清除 `m_stepRequested`
+
+恢复后，后续 `Tick()` 会重新按正常 fixed-step / variable-step 规则推进。
+
+## 相关文档
+
+- [Pause](Pause.md)
+- [Tick](Tick.md)
diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/RuntimeLoop.md b/docs/api/XCEngine/Scene/RuntimeLoop/RuntimeLoop.md
new file mode 100644
index 00000000..f7ff3f51
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/RuntimeLoop.md
@@ -0,0 +1,87 @@
+# RuntimeLoop
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+**描述**: 在 `SceneRuntime` 之上提供 fixed step、暂停、单帧步进和最大追帧限制的轻量运行时主循环。
+
+## 概览
+
+如果说 [SceneRuntime](../SceneRuntime/SceneRuntime.md) 负责“把一个场景跑起来”，那么 `RuntimeLoop` 负责“按什么节拍去跑”。
+
+它在 `SceneRuntime` 外面再包了一层时间控制逻辑，解决的是：
+
+- fixed update 累积
+- 超大帧时间钳制
+- 每帧最多执行多少次 fixed step
+- 暂停、恢复和单帧步进
+
+## Settings
+
+`RuntimeLoop::Settings` 当前包含三个字段：
+
+| 字段 | 默认值 | 作用 |
+|------|------|------|
+| `fixedDeltaTime` | `1/50` | 每次 `FixedUpdate` 的时间步长。 |
+| `maxFrameDeltaTime` | `0.1` | 单帧输入 `deltaTime` 的最大钳制值。 |
+| `maxFixedStepsPerFrame` | `4` | 一帧内最多补跑多少次 fixed step。 |
+
+构造函数和 `SetSettings()` 都会先做一次 sanitize：
+
+- `fixedDeltaTime <= 0` 时回退到 `1/50`
+- `maxFrameDeltaTime < 0` 时回退到 `0`
+- `maxFixedStepsPerFrame == 0` 时回退到 `1`
+
+## 生命周期
+
+### `Start()`
+
+- 清空 fixed accumulator
+- 清空暂停 / 单步状态
+- 把场景交给内部 `SceneRuntime`
+
+### `Stop()`
+
+- 停止内部 `SceneRuntime`
+- 清空 fixed accumulator
+- 清空暂停 / 单步状态
+
+## Tick 规则
+
+`Tick(deltaTime)` 的当前行为是：
+
+1. 如果没有运行中的场景，直接返回。
+2. 如果处于暂停状态且没有请求单帧步进，直接返回。
+3. 把输入 `deltaTime` 钳制到 `[0, maxFrameDeltaTime]`。
+4. 累加到 `m_fixedAccumulator`。
+5. 在 accumulator 足够且未超过 `maxFixedStepsPerFrame` 时，重复执行 `SceneRuntime::FixedUpdate(fixedDeltaTime)`。
+6. 无论 fixed step 执行了多少次，只要本次 tick 没被早退，就各执行一次 `Update(clampedDeltaTime)` 与 `LateUpdate(clampedDeltaTime)`。
+7. 清除单帧步进标记。
+
+## 暂停与单帧步进
+
+- `Pause()` 只在运行中生效，并把 `m_paused` 置为 `true`
+- `Resume()` 只在运行中生效，并取消暂停
+- `StepFrame()` 会保持暂停状态，但允许下一次 `Tick()` 放行一帧
+
+执行完单帧步进后，loop 仍保持暂停。
+
+## 真实使用位置
+
+- `editor/src/Core/PlaySessionController.h` 持有一个 `RuntimeLoop`，用于 play mode 控制。
+- `tests/Scene/test_runtime_loop.cpp` 覆盖了 fixed step 累积、delta 钳制、最大 fixed 次数、暂停与单帧步进行为。
+
+## 当前实现边界
+
+- 它当前只包着一个 [SceneRuntime](../SceneRuntime/SceneRuntime.md)，不是全引擎级 player loop。
+- 没有独立的渲染、输入或音频阶段调度，只处理场景运行时更新。
+- 暂停语义只阻止 `Tick()` 自动推进，不会冻结外部系统的时间源。
+
+## 相关文档
+
+- [当前模块](../Scene.md)
+- [SceneRuntime](../SceneRuntime/SceneRuntime.md)
+- [Scene](../Scene/Scene.md)
diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/SetSettings.md b/docs/api/XCEngine/Scene/RuntimeLoop/SetSettings.md
new file mode 100644
index 00000000..491ecd46
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/SetSettings.md
@@ -0,0 +1,30 @@
+# RuntimeLoop::SetSettings
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+## 签名
+
+```cpp
+void SetSettings(const Settings& settings);
+```
+
+## 作用
+
+更新 runtime loop 的 fixed-step 配置。
+
+## 当前实现行为
+
+- 新设置会先经过和构造函数相同的 sanitize 过程
+- 不会重置当前 `m_fixedAccumulator`
+- 不会自动 pause / resume / restart 当前场景
+
+这意味着运行中修改设置会影响后续 tick 语义，但不会帮你“重开一局”。
+
+## 相关文档
+
+- [Constructor](Constructor.md)
+- [Tick](Tick.md)
diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/Start.md b/docs/api/XCEngine/Scene/RuntimeLoop/Start.md
new file mode 100644
index 00000000..08a44cc9
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/Start.md
@@ -0,0 +1,34 @@
+# RuntimeLoop::Start
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+## 签名
+
+```cpp
+void Start(Scene* scene);
+```
+
+## 作用
+
+开始驱动一个场景的运行循环。
+
+## 当前实现流程
+
+1. 清零 `m_fixedAccumulator`
+2. 清除 `m_paused`
+3. 清除 `m_stepRequested`
+4. 调用内部 `SceneRuntime::Start(scene)`
+
+## 注意点
+
+- 这里不会自动执行 `Tick()`，所以不会立即产生一帧 `FixedUpdate/Update/LateUpdate`
+- 若 `scene == nullptr`，后续运行状态由 `SceneRuntime::Start()` 的行为决定
+
+## 相关文档
+
+- [Stop](Stop.md)
+- [Tick](Tick.md)
diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/StepFrame.md b/docs/api/XCEngine/Scene/RuntimeLoop/StepFrame.md
new file mode 100644
index 00000000..3f3d4a5c
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/StepFrame.md
@@ -0,0 +1,33 @@
+# RuntimeLoop::StepFrame
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+## 签名
+
+```cpp
+void StepFrame();
+```
+
+## 作用
+
+请求在 paused 状态下单步推进一帧。
+
+## 当前实现行为
+
+- 仅在运行中生效
+- 会把 `m_paused` 维持为 `true`
+- 把 `m_stepRequested` 置为 `true`
+- 不会立即执行场景更新；真正的一帧推进仍要等下一次 [Tick](Tick.md)
+
+## 典型使用点
+
+当前 editor 的 `PlaySessionController::StepPlay(...)` 就是依赖这个语义：UI 层只发出“单步一帧”的请求，真正的执行仍在下一次主循环 `Update()` 中发生。
+
+## 相关文档
+
+- [Pause](Pause.md)
+- [Tick](Tick.md)
diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/Stop.md b/docs/api/XCEngine/Scene/RuntimeLoop/Stop.md
new file mode 100644
index 00000000..158ac986
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/Stop.md
@@ -0,0 +1,31 @@
+# RuntimeLoop::Stop
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+## 签名
+
+```cpp
+void Stop();
+```
+
+## 作用
+
+停止当前运行循环并重置内部状态。
+
+## 当前实现行为
+
+- 调用 `SceneRuntime::Stop()`
+- 清零 `m_fixedAccumulator`
+- 清除 `m_paused`
+- 清除 `m_stepRequested`
+
+因此 `Stop()` 不只是停场景运行，也会把 pause / step 状态一起清干净。
+
+## 相关文档
+
+- [Start](Start.md)
+- [Pause](Pause.md)
diff --git a/docs/api/XCEngine/Scene/RuntimeLoop/Tick.md b/docs/api/XCEngine/Scene/RuntimeLoop/Tick.md
new file mode 100644
index 00000000..ca48a947
--- /dev/null
+++ b/docs/api/XCEngine/Scene/RuntimeLoop/Tick.md
@@ -0,0 +1,49 @@
+# RuntimeLoop::Tick
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/RuntimeLoop.h`
+
+## 签名
+
+```cpp
+void Tick(float deltaTime);
+```
+
+## 作用
+
+推进一帧 runtime loop。
+
+## 当前实现流程
+
+1. 若当前未运行，直接返回。
+2. 若当前处于 paused 且没有 step 请求，直接返回。
+3. 把输入 `deltaTime` clamp 到 `[0, maxFrameDeltaTime]`。
+4. 将 clamp 后的时间累加到 `m_fixedAccumulator`。
+5. 在 `m_fixedAccumulator >= fixedDeltaTime` 且本帧 fixed step 次数未达到 `maxFixedStepsPerFrame` 时，循环调用：
+
+```cpp
+m_sceneRuntime.FixedUpdate(m_settings.fixedDeltaTime);
+```
+
+6. 然后执行一次：
+
+```cpp
+m_sceneRuntime.Update(clampedDeltaTime);
+m_sceneRuntime.LateUpdate(clampedDeltaTime);
+```
+
+7. 清掉 `m_stepRequested`。
+
+## 语义重点
+
+- `Update` / `LateUpdate` 用的是 clamp 后的原始帧时间，不是 `fixedDeltaTime`
+- fixed step 次数即使被上限截断，剩余时间也会保留在 accumulator 中，留给后续帧继续追
+- paused + step 模式下，`Tick()` 仍会完整推进一帧
+
+## 相关文档
+
+- [Pause](Pause.md)
+- [StepFrame](StepFrame.md)