docs(scripting): add baseline api reference and guide

docs/api/XCEngine/Scene/SceneRuntime/FixedUpdate.md

@@ -0,0 +1,33 @@
+# SceneRuntime::FixedUpdate
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/SceneRuntime.h`
+
+## 签名
+
+```cpp
+void FixedUpdate(float fixedDeltaTime);
+```
+
+## 作用
+
+驱动固定步长更新阶段。
+
+## 当前实现行为
+
+- 只有在 `m_running == true`、`m_scene != nullptr` 且 `m_scene->IsActive()` 时才继续执行。
+- 执行顺序固定为：
+  1. `ScriptEngine::Get().OnFixedUpdate(fixedDeltaTime)`
+  2. `m_scene->FixedUpdate(fixedDeltaTime)`
+
+## 设计重点
+
+脚本先于原生组件运行，这样脚本在固定步长阶段做出的状态修改能被同一帧的原生组件观察到。测试 `tests/Scene/test_scene_runtime.cpp` 已验证这个顺序。
+
+## 相关文档
+
+- [SceneRuntime](SceneRuntime.md)
+- [SceneRuntime::Update](Update.md)

docs/api/XCEngine/Scene/SceneRuntime/LateUpdate.md

@@ -0,0 +1,33 @@
+# SceneRuntime::LateUpdate
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/SceneRuntime.h`
+
+## 签名
+
+```cpp
+void LateUpdate(float deltaTime);
+```
+
+## 作用
+
+驱动后更新阶段。
+
+## 当前实现行为
+
+- 与 `FixedUpdate` / `Update` 一样，只有在运行中且场景活动时才执行。
+- 当前顺序为：
+  1. `ScriptEngine::Get().OnLateUpdate(deltaTime)`
+  2. `m_scene->LateUpdate(deltaTime)`
+
+## 设计含义
+
+这维持了当前运行时一贯的脚本优先策略。对商业引擎文档来说，这一点必须明确，因为很多用户会默认认为 `LateUpdate` 主要用于相机跟随、动画后修正和最终姿态收敛，而顺序差异会直接影响结果。
+
+## 相关文档
+
+- [SceneRuntime](SceneRuntime.md)
+- [SceneRuntime::Update](Update.md)

docs/api/XCEngine/Scene/SceneRuntime/SceneRuntime.md

@@ -0,0 +1,63 @@
+# SceneRuntime
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Scene/SceneRuntime.h`
+
+**描述**: 把 `Scene` 的逐帧更新与 `ScriptEngine` 的运行时生命周期绑在一起的轻量执行器。
+
+## 概览
+
+`SceneRuntime` 不是场景数据本身，而是“让一个 `Scene` 真正跑起来”的那层对象。当前职责主要有两件：
+
+- 管理“当前正在运行哪一个场景”。
+- 在每个帧阶段先驱动脚本，再驱动原生组件更新。
+
+这种拆分和 Unity 里“Scene 是数据容器，PlayerLoop/Runtime 才是执行者”的思路接近。好处是场景对象本身可以继续承担加载、保存和对象组织职责，而运行态切换、脚本启动和帧阶段调度则集中在一个小类里。
+
+## 生命周期
+
+- [Start](Start.md) 会先停止旧运行时，再接管新场景。
+- [Stop](Stop.md) 会通知 `ScriptEngine` 结束运行，并清空当前场景。
+- 运行中 `GetScene()` 返回当前绑定场景，`IsRunning()` 表示是否处于运行状态。
+
+## 线程语义
+
+- 当前实现没有内部同步。
+- `Start()`、`Stop()` 和三类帧更新函数都应视为主线程 API。
+
+## 当前实现边界
+
+- 只有场景本身 `IsActive()` 为真时，帧更新才会继续执行。
+- 每个阶段都先调 `ScriptEngine`，再调 `Scene` 本体，因此脚本改动会在同一帧被后续原生组件看见。
+- `SceneRuntime` 当前只管理单个活动场景，不负责多场景叠加或异步切换。
+
+## 公开方法
+
+| 方法 | 说明 |
+|------|------|
+| [Start](Start.md) | 开始运行一个场景。 |
+| [Stop](Stop.md) | 停止当前场景运行。 |
+| [FixedUpdate](FixedUpdate.md) | 驱动物理步长阶段。 |
+| [Update](Update.md) | 驱动常规逐帧更新阶段。 |
+| [LateUpdate](LateUpdate.md) | 驱动后更新阶段。 |
+
+## 真实行为依据
+
+- `engine/src/Scene/SceneRuntime.cpp`
+- `tests/Scene/test_scene_runtime.cpp`
+
+这些测试明确验证了：
+
+- 启停会转发到 `ScriptEngine`。
+- 脚本生命周期调用先于原生组件。
+- 非活动场景会跳过帧执行。
+- 切到新场景前会先停掉旧场景。
+
+## 相关文档
+
+- [Scene](../Scene/Scene.md)
+- [ScriptEngine](../../Scripting/ScriptEngine/ScriptEngine.md)
+- [Scene Lifecycle And Serialization](../../../_guides/Scene/Scene-Lifecycle-And-Serialization.md)

docs/api/XCEngine/Scene/SceneRuntime/Start.md

@@ -0,0 +1,42 @@
+# SceneRuntime::Start
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/SceneRuntime.h`
+
+## 签名
+
+```cpp
+void Start(Scene* scene);
+```
+
+## 作用
+
+让一个场景进入运行状态，并启动其脚本运行时。
+
+## 当前实现流程
+
+按 `engine/src/Scene/SceneRuntime.cpp`：
+
+1. 如果当前已经在运行同一个 `scene`，直接返回。
+2. 先调用 [Stop](Stop.md) 清掉旧运行时。
+3. 如果传入空场景，返回。
+4. 写入 `m_scene`，把 `m_running` 设为 `true`。
+5. 调用 `ScriptEngine::Get().OnRuntimeStart(scene)`。
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `scene` | 要开始运行的场景；可为空，空时表示“停掉当前运行时但不启动新场景”。 |
+
+## 设计含义
+
+这种“先停再启”的切换方式很直接，也和很多商业引擎的 play mode 切场景行为一致。优点是生命周期边界清晰；代价是当前没有做平滑切换或状态迁移。
+
+## 相关文档
+
+- [SceneRuntime](SceneRuntime.md)
+- [SceneRuntime::Stop](Stop.md)

docs/api/XCEngine/Scene/SceneRuntime/Stop.md

@@ -0,0 +1,34 @@
+# SceneRuntime::Stop
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/SceneRuntime.h`
+
+## 签名
+
+```cpp
+void Stop();
+```
+
+## 作用
+
+停止当前场景运行并结束脚本运行时。
+
+## 当前实现行为
+
+- 如果当前并不处于运行状态，只会把 `m_scene` 清成 `nullptr`。
+- 如果当前正在运行：
+  - 先调用 `ScriptEngine::Get().OnRuntimeStop()`。
+  - 再把 `m_running` 置为 `false`。
+  - 最后把 `m_scene` 清空。
+
+## 副作用
+
+`ScriptEngine` 当前会在 `OnRuntimeStop()` 中触发脚本的 `OnDisable`、`OnDestroy`、实例销毁和运行时停止回调，因此这个接口不只是“停更”，而是真正结束脚本运行态。
+
+## 相关文档
+
+- [SceneRuntime](SceneRuntime.md)
+- [ScriptEngine::OnRuntimeStop](../../Scripting/ScriptEngine/OnRuntimeStop.md)

docs/api/XCEngine/Scene/SceneRuntime/Update.md

@@ -0,0 +1,33 @@
+# SceneRuntime::Update
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scene/SceneRuntime.h`
+
+## 签名
+
+```cpp
+void Update(float deltaTime);
+```
+
+## 作用
+
+驱动常规逐帧更新阶段。
+
+## 当前实现行为
+
+- 运行条件与 [FixedUpdate](FixedUpdate.md) 相同：必须正在运行，场景存在且活动。
+- 当前顺序为：
+  1. `ScriptEngine::Get().OnUpdate(deltaTime)`
+  2. `m_scene->Update(deltaTime)`
+
+## 额外说明
+
+`ScriptEngine::OnUpdate()` 当前还负责在第一次正常帧更新前补发脚本 `Start`，因此 `SceneRuntime::Update()` 实际上承担了“脚本 Start 落地阶段”的入口职责。
+
+## 相关文档
+
+- [SceneRuntime](SceneRuntime.md)
+- [ScriptEngine::OnUpdate](../../Scripting/ScriptEngine/OnUpdate.md)