docs(scripting): add baseline api reference and guide

docs/api/XCEngine/Scene/Scene.md

@@ -4,47 +4,46 @@
 
 **类型**: `module`
 
-**描述**: 提供场景容器 `Scene` 与多场景入口 `SceneManager`，负责组织 `GameObject` 层级、场景级更新与自定义文本序列化。
+**描述**: 提供场景容器、多场景管理入口以及场景运行时调度器。
 
-## 概述
+## 概览
 
-`XCEngine/Scene` 这组头文件位于 `Scene` 目录下，但公开类型实际放在 `XCEngine::Components` 命名空间中。这反映了当前引擎的建模方式：
+当前 `XCEngine/Scene` 目录里的 public API 主要分成三层：
 
-- `Scene` 负责持有一组 `GameObject`。
-- `GameObject` 负责父子层级、`TransformComponent` 和其它组件。
-- `SceneManager` 负责持有多个已加载场景，并暴露“当前活动场景”入口。
+- [Scene](Scene/Scene.md) 负责对象树、场景级更新和场景序列化。
+- [SceneManager](SceneManager/SceneManager.md) 负责多场景注册与活动场景入口。
+- [SceneRuntime](SceneRuntime/SceneRuntime.md) 负责把某个场景真正“跑起来”，并和脚本系统衔接。
 
-这和商业引擎里常见的 Unity 风格思路接近：场景是对象集合与生命周期边界，真正可组合的行为仍然落在对象与组件层。
-
-## 当前实现成熟度
-
-这一组 API 已经能支撑基础场景树、更新和保存/加载，但需要对当前边界保持诚实：
-
-- `Scene::IsActive()` / `SetActive()` 当前只是存储一个标志位，不会阻止 `Update()`、`FixedUpdate()` 或 `LateUpdate()` 运行。
-- `FindGameObjectWithTag()` 当前并没有真正的 tag 系统支持，实际按对象名称匹配。
-- `Scene::~Scene()` 不会逐个调用 `DestroyGameObject()`，因此不会触发场景销毁事件，也不会为组件调用 `OnDestroy()`。
-- `SceneManager::LoadSceneAsync()` 当前不是异步加载，只是同步包装。
-- `SceneManager` 的活动场景指针，与 `Scene` 自身的 active 标志当前是两套彼此独立的状态。
+这种分层和商业引擎里常见的思路接近：`Scene` 是数据与对象容器，`SceneManager` 负责更高层的场景切换，而 `SceneRuntime` 则承担运行时执行语义。
 
 ## 设计要点
 
-- `Scene` 采用“所有权集中、访问返回裸指针”的模式：内部由 `std::unique_ptr<GameObject>` 持有对象，API 对外返回非拥有指针。
-- 根对象列表与父子层级分开维护，这让“遍历根对象”和“对象挂接到父节点”可以各自保持简单。
-- 序列化走的是引擎私有文本格式，而不是通用 JSON。这样实现成本低、易于直接落地组件自定义序列化，但兼容性和健壮性也相对有限。
+- `Scene` 专注对象拥有权、查询和序列化，不直接变成庞大的运行时调度中心。
+- `SceneRuntime` 把脚本生命周期和场景更新顺序集中管理，避免脚本系统散落到 `Scene` 内部。
+- `SceneManager` 让多场景入口和单个场景数据模型解耦，便于以后扩展更复杂的场景切换策略。
+
+## 当前实现边界
+
+- 当前公开类型都位于 `XCEngine::Components` 命名空间，而不是单独的 `XCEngine::Scene` 命名空间，这反映了引擎当前建模历史。
+- `SceneRuntime` 目前只管理单个运行中的场景。
+- `SceneManager::LoadSceneAsync()` 仍是同步包装，不是完整异步加载系统。
+- 场景序列化使用引擎私有文本格式，强调可落地而不是通用交换格式。
 
 ## 头文件
 
-- [Scene](Scene/Scene.md) - `Scene.h`，单个场景容器、更新入口和序列化接口。
-- [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h`，多场景注册表与活动场景入口。
+- [Scene](Scene/Scene.md) - `Scene.h`
+- [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h`
+- [SceneRuntime](SceneRuntime/SceneRuntime.md) - `SceneRuntime.h`
 
 ## 相关指南
 
-- [Scene Lifecycle And Serialization](../../_guides/Scene/Scene-Lifecycle-And-Serialization.md) - 解释场景树为什么这样设计、活动状态分层意味着什么，以及当前序列化链路的实际限制。
+- [Scene Lifecycle And Serialization](../../_guides/Scene/Scene-Lifecycle-And-Serialization.md) - 解释场景容器、运行时调度和序列化之间的关系，以及当前实现的真实限制。
 
 ## 相关文档
 
 - [GameObject](../Components/GameObject/GameObject.md)
 - [Component](../Components/Component/Component.md)
 - [TransformComponent](../Components/TransformComponent/TransformComponent.md)
+- [Scripting](../Scripting/Scripting.md)
 - [上级目录](../XCEngine.md)
 - [API 总索引](../../main.md)