# 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)