xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rebuild Scene API content

Browse Source
This commit is contained in:
ssdfasd
2026-03-26 19:34:24 +08:00
parent dc252502ac
commit 5ca5ca1f19
40 changed files with 752 additions and 658 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/api/XCEngine/Scene/Scene.md
View File

@@ -1,21 +1,50 @@
# Scene # Scene
**命名空间**: `XCEngine::Scene` **命名空间**: `XCEngine::Components`
**类型**: `module` **类型**: `module`
**描述**: 场景与场景管理器 API。 **描述**: 提供场景容器 `Scene` 与多场景入口 `SceneManager`，负责组织 `GameObject` 层级、场景级更新与自定义文本序列化。
## 概览 ## 概述
该目录与 `XCEngine/Scene` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。 `XCEngine/Scene` 这组头文件位于 `Scene` 目录下，但公开类型实际放在 `XCEngine::Components` 命名空间中。这反映了当前引擎的建模方式：
- `Scene` 负责持有一组 `GameObject`。
- `GameObject` 负责父子层级、`TransformComponent` 和其它组件。
- `SceneManager` 负责持有多个已加载场景，并暴露“当前活动场景”入口。
这和商业引擎里常见的 Unity 风格思路接近：场景是对象集合与生命周期边界，真正可组合的行为仍然落在对象与组件层。
## 当前实现成熟度
这一组 API 已经能支撑基础场景树、更新和保存/加载，但需要对当前边界保持诚实：
- `Scene::IsActive()` / `SetActive()` 当前只是存储一个标志位，不会阻止 `Update()`、`FixedUpdate()` 或 `LateUpdate()` 运行。
- `FindGameObjectWithTag()` 当前并没有真正的 tag 系统支持，实际按对象名称匹配。
- `Scene::~Scene()` 不会逐个调用 `DestroyGameObject()`，因此不会触发场景销毁事件，也不会为组件调用 `OnDestroy()`。
- `SceneManager::LoadSceneAsync()` 当前不是异步加载，只是同步包装。
- `SceneManager` 的活动场景指针，与 `Scene` 自身的 active 标志当前是两套彼此独立的状态。
## 设计要点
- `Scene` 采用“所有权集中、访问返回裸指针”的模式：内部由 `std::unique_ptr<GameObject>` 持有对象，API 对外返回非拥有指针。
- 根对象列表与父子层级分开维护，这让“遍历根对象”和“对象挂接到父节点”可以各自保持简单。
- 序列化走的是引擎私有文本格式，而不是通用 JSON。这样实现成本低、易于直接落地组件自定义序列化，但兼容性和健壮性也相对有限。
## 头文件 ## 头文件
- [Scene](Scene/Scene.md) - `Scene.h` - [Scene](Scene/Scene.md) - `Scene.h`，单个场景容器、更新入口和序列化接口。
- [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h` - [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h`，多场景注册表与活动场景入口。
## 相关指南
- [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)
- [上级目录](../XCEngine.md) - [上级目录](../XCEngine.md)
- [API 总索引](../../main.md) - [API 总索引](../../main.md)

43
docs/api/XCEngine/Scene/Scene/Constructor.md
View File

@@ -1,41 +1,30 @@
# Scene::Scene() # Scene::Constructor
构造对象。 构造一个场景对象。
该方法在 `XCEngine/Scene/Scene.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
Scene(); Scene();
```
**参数：** 无。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp
explicit Scene(const std::string& name); explicit Scene(const std::string& name);
``` ```
**参数：** ## 行为说明
- `name` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 当前有两个重载：
**示例：** - `Scene()` 会把场景名初始化为 `"Untitled"`。
- `Scene(const std::string& name)` 会把场景名初始化为传入值。
```cpp 无论哪个重载，`m_active` 都会保留成员默认值 `true`，并从空的对象集合开始。
#include <XCEngine/Scene/Scene.h>
void Example() { ## 参数
XCEngine::Components::Scene object;
} - `name` - 仅命名构造重载使用的场景名称。
```
## 返回值
- 无。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [SetName](SetName.md)

42
docs/api/XCEngine/Scene/Scene/CreateGameObject.md
View File

@@ -1,32 +1,40 @@
# Scene::CreateGameObject # Scene::CreateGameObject
创建新对象或资源。 在当前场景中创建一个新对象。
```cpp ```cpp
GameObject* CreateGameObject(const std::string& name, GameObject* parent = nullptr); GameObject* CreateGameObject(const std::string& name, GameObject* parent = nullptr);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现按以下顺序执行：
- `name` - 参数语义详见头文件声明。
- `parent` - 参数语义详见头文件声明。
**返回：** `GameObject*` - 返回值语义详见头文件声明。 1. 构造一个 `GameObject(name)`。
2. 把对象登记到 `GameObject` 全局注册表。
3. 把对象登记到当前场景的 `m_gameObjects`、`m_gameObjectIDs`。
4. 写入 `ptr->m_scene = this`。
5. 如果提供 `parent`，调用 `ptr->SetParent(parent)`；否则把对象记为根对象。
6. 调用 `ptr->Awake()`。
7. 触发 [OnGameObjectCreated](OnGameObjectCreated.md) 事件。
**示例：** ## 参数
```cpp - `name` - 新对象名称。
#include <XCEngine/Scene/Scene.h> - `parent` - 可选父对象；为空时对象会成为根对象。
void Example() { ## 返回值
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::CreateGameObject(...)。 - `GameObject*` - 新对象的非拥有指针；所有权仍然属于当前 `Scene`。
(void)object;
} ## 注意事项
```
- 当前不会校验 `parent` 是否也属于当前场景；跨场景挂接可能制造不一致状态。
- 返回指针在对象被 [DestroyGameObject](DestroyGameObject.md) 销毁或场景销毁后失效。
- `Awake()` 在事件触发前调用。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [DestroyGameObject](DestroyGameObject.md)
- [OnGameObjectCreated](OnGameObjectCreated.md)

39
docs/api/XCEngine/Scene/Scene/DeserializeFromString.md
View File

@@ -1,31 +1,38 @@
# Scene::DeserializeFromString # Scene::DeserializeFromString
公开方法，详见头文件声明。 从字符串重建当前场景内容。
```cpp ```cpp
void DeserializeFromString(const std::string& data); void DeserializeFromString(const std::string& data);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会先清空 `m_gameObjects`、`m_rootGameObjects` 和 `m_gameObjectIDs`，然后解析自定义文本格式，分两阶段重建场景：
- `data` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 1. 先读取所有 `gameobject_begin` / `gameobject_end` 块，收集待创建对象、父子关系、Transform 数据和组件 payload。
2. 再创建所有 `GameObject` 实例，恢复 ID、UUID、active、自定义组件和层级关系。
**示例：** 解析完成后，如果文件中的最大对象 ID 大于等于 `GameObject::s_nextID`，当前实现还会把全局自增 ID 推进到 `maxId + 1`。
```cpp ## 参数
#include <XCEngine/Scene/Scene.h>
void Example() { - `data` - 序列化后的场景文本。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::DeserializeFromString(...)。 ## 返回值
(void)object;
} - 无。
```
## 当前实现限制
- 旧对象被清空时不会逐个调用 [DestroyGameObject](DestroyGameObject.md)，因此不会触发销毁事件，也不会对组件调用 `OnDestroy()`。
- 新对象是直接构建出来的，不会触发 [OnGameObjectCreated](OnGameObjectCreated.md)，也不会调用 `Awake()` / `Start()`。
- 组件创建依赖 `ComponentFactoryRegistry`；未注册的组件类型会被跳过。
- 对于损坏的数字字段，`std::stoull` 抛出的异常当前不会在这里捕获。
- 如果父对象 ID 缺失或找不到，对象会被回退为根对象。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [SerializeToString](SerializeToString.md)
- [Load](Load.md)

39
docs/api/XCEngine/Scene/Scene/DestroyGameObject.md
View File

@@ -1,31 +1,38 @@
# Scene::DestroyGameObject # Scene::DestroyGameObject
公开方法，详见头文件声明。 从当前场景中递归销毁一个对象。
```cpp ```cpp
void DestroyGameObject(GameObject* gameObject); void DestroyGameObject(GameObject* gameObject);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `gameObject` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 1. 在 `gameObject == nullptr` 或对象不属于当前场景时直接返回。
2. 先递归销毁所有子对象。
3. 把对象从父对象子列表或根对象列表中移除。
4. 触发 [OnGameObjectDestroyed](OnGameObjectDestroyed.md)。
5. 调用 `gameObject->OnDestroy()`。
6. 从 ID 集合和 `m_gameObjects` 中移除对象。
**示例：** ## 参数
```cpp - `gameObject` - 待销毁对象。
#include <XCEngine/Scene/Scene.h>
void Example() { ## 返回值
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::DestroyGameObject(...)。 - 无。
(void)object;
} ## 注意事项
```
- 销毁事件当前先于 `GameObject::OnDestroy()` 触发。
- 删除 `m_gameObjects` 中的 `unique_ptr` 后，对象指针会立即失效。
- 场景析构当前不会逐个走这个入口。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [CreateGameObject](CreateGameObject.md)
- [OnGameObjectDestroyed](OnGameObjectDestroyed.md)

37
docs/api/XCEngine/Scene/Scene/Destructor.md
View File

@@ -1,29 +1,34 @@
# Scene::~Scene() # Scene::Destructor
销毁对象并释放相关资源。 销毁场景对象。
```cpp ```cpp
~Scene(); ~Scene();
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现只有一行：
**返回：** `void` - 无返回值。
**示例：**
```cpp ```cpp
#include <XCEngine/Scene/Scene.h> m_gameObjects.clear();
void Example() {
XCEngine::Components::Scene object;
// 对象离开作用域时会自动触发析构。
}
``` ```
也就是说，场景析构只是让内部 `unique_ptr<GameObject>` 容器整体释放。
## 返回值
- 无。
## 当前实现限制
- 不会逐个调用 [DestroyGameObject](DestroyGameObject.md)。
- 不会触发 [OnGameObjectDestroyed](OnGameObjectDestroyed.md)。
- 不会为组件调用 `OnDestroy()`。
如果你的清理逻辑依赖显式销毁事件或组件销毁回调，应在场景析构前主动销毁对象，而不是依赖 `~Scene()`。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [DestroyGameObject](DestroyGameObject.md)

29
docs/api/XCEngine/Scene/Scene/Find.md
View File

@@ -1,31 +1,28 @@
# Scene::Find # Scene::Find
查找并返回匹配对象。 按对象名称查找场景中的第一个匹配对象。
```cpp ```cpp
GameObject* Find(const std::string& name) const; GameObject* Find(const std::string& name) const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现从根对象开始做深度优先递归查找：
- `name` - 参数语义详见头文件声明。
**返回：** `GameObject*` - 返回值语义详见头文件声明。 1. 先检查每个根对象自身名称。
2. 再递归检查其子对象。
3. 找到第一个匹配项后立即返回。
**示例：** ## 参数
```cpp - `name` - 目标对象名称。
#include <XCEngine/Scene/Scene.h>
void Example() { ## 返回值
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::Find(...)。 - `GameObject*` - 第一个匹配对象；找不到时返回 `nullptr`。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [FindByID](FindByID.md)

25
docs/api/XCEngine/Scene/Scene/FindByID.md
View File

@@ -1,31 +1,24 @@
# Scene::FindByID # Scene::FindByID
查找并返回匹配对象。 按对象 ID 查找场景中的对象。
```cpp ```cpp
GameObject* FindByID(GameObjectID id) const; GameObject* FindByID(GameObjectID id) const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现直接对 `m_gameObjects` 做哈希表查找。
- `id` - 参数语义详见头文件声明。
**返回：** `GameObject*` - 返回值语义详见头文件声明。 ## 参数
**示例：** - `id` - 目标对象 ID。
```cpp ## 返回值
#include <XCEngine/Scene/Scene.h>
void Example() { - `GameObject*` - 找到时返回对象指针；找不到时返回 `nullptr`。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::FindByID(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [Find](Find.md)

33
docs/api/XCEngine/Scene/Scene/FindGameObjectWithTag.md
View File

@@ -1,31 +1,30 @@
# Scene::FindGameObjectWithTag # Scene::FindGameObjectWithTag
查找并返回匹配对象。 查找带指定“tag”的对象。
```cpp ```cpp
GameObject* FindGameObjectWithTag(const std::string& tag) const; GameObject* FindGameObjectWithTag(const std::string& tag) const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 接口名称里写的是 tag，但当前实现实际比较的是：
- `tag` - 参数语义详见头文件声明。
**返回：** `GameObject*` - 返回值语义详见头文件声明。
**示例：**
```cpp ```cpp
#include <XCEngine/Scene/Scene.h> go->GetName() == tag
void Example() {
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::FindGameObjectWithTag(...)。
(void)object;
}
``` ```
也就是说，它现在的行为与“按名称递归查找第一个匹配对象”更接近，而不是使用独立 tag 字段。
## 参数
- `tag` - 当前实现下实际被当作对象名称使用的字符串。
## 返回值
- `GameObject*` - 第一个匹配对象；找不到时返回 `nullptr`。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [Find](Find.md)

32
docs/api/XCEngine/Scene/Scene/FindObjectOfType.md
View File

@@ -1,30 +1,30 @@
# Scene::FindObjectOfType # Scene::FindObjectOfType
查找并返回匹配对象。 查找场景中的第一个指定类型组件。
```cpp ```cpp
template<typename T> T* FindObjectOfType() const; template<typename T>
T* FindObjectOfType() const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前模板实现会：
**返回：** `template<typename T> T*` - 返回值语义详见头文件声明。 1. 遍历所有根对象。
2. 先检查根对象自身的 `GetComponent<T>()`。
3. 再递归检查子对象。
4. 返回第一个命中的组件指针。
**示例：** ## 模板参数
```cpp - `T` - 目标组件类型。
#include <XCEngine/Scene/Scene.h>
void Example() { ## 返回值
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::FindObjectOfType(...)。 - `T*` - 第一个匹配组件；找不到时返回 `nullptr`。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [FindObjectsOfType](FindObjectsOfType.md)

31
docs/api/XCEngine/Scene/Scene/FindObjectsOfType.md
View File

@@ -1,30 +1,29 @@
# Scene::FindObjectsOfType # Scene::FindObjectsOfType
查找并返回匹配对象。 查找场景中的所有指定类型组件。
```cpp ```cpp
template<typename T> std::vector<T*> FindObjectsOfType() const; template<typename T>
std::vector<T*> FindObjectsOfType() const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前模板实现会从所有根对象开始做深度优先遍历：
**返回：** `template<typename T> std::vector<T*>` - 返回值语义详见头文件声明。 - 根对象自身匹配时先加入结果。
- 再递归扫描全部子对象。
- 返回收集到的所有 `T*`。
**示例：** ## 模板参数
```cpp - `T` - 目标组件类型。
#include <XCEngine/Scene/Scene.h>
void Example() { ## 返回值
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::FindObjectsOfType(...)。 - `std::vector<T*>` - 所有匹配组件组成的数组；找不到时返回空数组。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [FindObjectOfType](FindObjectOfType.md)

31
docs/api/XCEngine/Scene/Scene/FixedUpdate.md
View File

@@ -1,31 +1,30 @@
# Scene::FixedUpdate # Scene::FixedUpdate
公开方法，详见头文件声明。 驱动场景的固定步长更新。
```cpp ```cpp
void FixedUpdate(float fixedDeltaTime); void FixedUpdate(float fixedDeltaTime);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会遍历根对象，并对处于 `IsActiveInHierarchy()` 状态的对象调用 `go->FixedUpdate()`。
- `fixedDeltaTime` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `fixedDeltaTime` - 固定步长参数。
```cpp ## 返回值
#include <XCEngine/Scene/Scene.h>
void Example() { - 无。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::FixedUpdate(...)。 ## 当前实现限制
(void)object;
} - `fixedDeltaTime` 当前没有被向下传递，`GameObject::FixedUpdate()` 也不接收这个参数。
``` - `Scene::m_active` 当前不会阻止这条更新链运行。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [Update](Update.md)
- [LateUpdate](LateUpdate.md)

24
docs/api/XCEngine/Scene/Scene/GetName.md
View File

@@ -1,30 +1,20 @@
# Scene::GetName # Scene::GetName
获取相关状态或对象。 查询场景名称。
```cpp ```cpp
const std::string& GetName() const; const std::string& GetName() const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前头文件内联实现直接返回 `m_name` 的常量引用。
**返回：** `const std::string&` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `const std::string&` - 当前场景名称。
```cpp
#include <XCEngine/Scene/Scene.h>
void Example() {
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::GetName(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [SetName](SetName.md)

25
docs/api/XCEngine/Scene/Scene/GetRootGameObjects.md
View File

@@ -1,30 +1,25 @@
# Scene::GetRootGameObjects # Scene::GetRootGameObjects
获取相关状态或对象。 获取当前场景的根对象列表。
```cpp ```cpp
std::vector<GameObject*> GetRootGameObjects() const; std::vector<GameObject*> GetRootGameObjects() const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现会按 `m_rootGameObjects` 中保存的 ID 顺序重新组装结果数组，并跳过已经不存在于 `m_gameObjects` 中的条目。
**返回：** `std::vector<GameObject*>` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `std::vector<GameObject*>` - 当前根对象指针数组。
```cpp ## 注意事项
#include <XCEngine/Scene/Scene.h>
void Example() { - 返回的是值复制后的数组，不是内部存储引用。
XCEngine::Components::Scene object; - 指针本身仍由 `Scene` 拥有。
// 根据上下文补齐参数后调用 Scene::GetRootGameObjects(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [CreateGameObject](CreateGameObject.md)

25
docs/api/XCEngine/Scene/Scene/IsActive.md
View File

@@ -1,30 +1,25 @@
# Scene::IsActive # Scene::IsActive
查询当前状态。 查询场景 active 标志。
```cpp ```cpp
bool IsActive() const; bool IsActive() const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前头文件内联实现直接返回 `m_active`。
**返回：** `bool` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `bool` - 场景的 active 标志值。
```cpp ## 注意事项
#include <XCEngine/Scene/Scene.h>
void Example() { - 这个标志当前不会阻止 [Update](Update.md)、[FixedUpdate](FixedUpdate.md) 或 [LateUpdate](LateUpdate.md) 执行。
XCEngine::Components::Scene object; - `SceneManager` 的活动场景指针也不会自动同步这个值。
// 根据上下文补齐参数后调用 Scene::IsActive(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [SetActive](SetActive.md)

29
docs/api/XCEngine/Scene/Scene/LateUpdate.md
View File

@@ -1,31 +1,28 @@
# Scene::LateUpdate # Scene::LateUpdate
公开方法，详见头文件声明。 驱动场景的晚更新。
```cpp ```cpp
void LateUpdate(float deltaTime); void LateUpdate(float deltaTime);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会遍历根对象，并对处于 `IsActiveInHierarchy()` 状态的对象调用 `go->LateUpdate(deltaTime)`。子对象递归更新由 `GameObject::LateUpdate()` 负责。
- `deltaTime` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `deltaTime` - 当前帧时间步长。
```cpp ## 返回值
#include <XCEngine/Scene/Scene.h>
void Example() { - 无。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::LateUpdate(...)。 ## 注意事项
(void)object;
} - `Scene::m_active` 当前不会阻止这条更新链运行。
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [Update](Update.md)

31
docs/api/XCEngine/Scene/Scene/Load.md
View File

@@ -1,31 +1,30 @@
# Scene::Load # Scene::Load
加载资源或数据。 从文件加载场景内容。
```cpp ```cpp
void Load(const std::string& filePath); void Load(const std::string& filePath);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会尝试打开 `filePath`，然后把整个文件内容读入字符串并传给 [DeserializeFromString](DeserializeFromString.md)。
- `filePath` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `filePath` - 场景文件路径。
```cpp ## 返回值
#include <XCEngine/Scene/Scene.h>
void Example() { - 无。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::Load(...)。 ## 当前实现限制
(void)object;
} - 文件打开失败时会静默返回，不会抛出异常，也不会返回错误码。
``` - 加载过程沿用 [DeserializeFromString](DeserializeFromString.md) 的所有限制：不会触发生命周期事件、依赖组件工厂注册等。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [Save](Save.md)
- [DeserializeFromString](DeserializeFromString.md)

25
docs/api/XCEngine/Scene/Scene/OnGameObjectCreated.md
View File

@@ -1,30 +1,23 @@
# Scene::OnGameObjectCreated # Scene::OnGameObjectCreated
公开方法，详见头文件声明。 访问对象创建事件。
```cpp ```cpp
Core::Event<GameObject*>& OnGameObjectCreated(); Core::Event<GameObject*>& OnGameObjectCreated();
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前头文件内联实现直接返回内部事件对象 `m_onGameObjectCreated` 的引用。
**返回：** `Core::Event<GameObject*>&` - 返回值语义详见头文件声明。 该事件在 [CreateGameObject](CreateGameObject.md) 成功创建并调用 `Awake()` 之后触发。
**示例：** ## 返回值
```cpp - `Core::Event<GameObject*>&` - 创建事件对象引用。
#include <XCEngine/Scene/Scene.h>
void Example() {
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::OnGameObjectCreated(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [CreateGameObject](CreateGameObject.md)
- [Event](../../Core/Event/Event.md)

25
docs/api/XCEngine/Scene/Scene/OnGameObjectDestroyed.md
View File

@@ -1,30 +1,23 @@
# Scene::OnGameObjectDestroyed # Scene::OnGameObjectDestroyed
公开方法，详见头文件声明。 访问对象销毁事件。
```cpp ```cpp
Core::Event<GameObject*>& OnGameObjectDestroyed(); Core::Event<GameObject*>& OnGameObjectDestroyed();
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前头文件内联实现直接返回内部事件对象 `m_onGameObjectDestroyed` 的引用。
**返回：** `Core::Event<GameObject*>&` - 返回值语义详见头文件声明。 该事件在 [DestroyGameObject](DestroyGameObject.md) 中先于 `gameObject->OnDestroy()` 触发。
**示例：** ## 返回值
```cpp - `Core::Event<GameObject*>&` - 销毁事件对象引用。
#include <XCEngine/Scene/Scene.h>
void Example() {
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::OnGameObjectDestroyed(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [DestroyGameObject](DestroyGameObject.md)
- [Event](../../Core/Event/Event.md)

31
docs/api/XCEngine/Scene/Scene/Save.md
View File

@@ -1,31 +1,30 @@
# Scene::Save # Scene::Save
公开方法，详见头文件声明。 把当前场景保存到文件。
```cpp ```cpp
void Save(const std::string& filePath); void Save(const std::string& filePath);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会尝试打开输出文件，并把 [SerializeToString](SerializeToString.md) 的结果直接写入文件。
- `filePath` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `filePath` - 输出文件路径。
```cpp ## 返回值
#include <XCEngine/Scene/Scene.h>
void Example() { - 无。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::Save(...)。 ## 当前实现限制
(void)object;
} - 文件打开失败时会静默返回。
``` - 采用的是引擎私有文本格式，而不是带版本控制的通用交换格式。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [Load](Load.md)
- [SerializeToString](SerializeToString.md)

91
docs/api/XCEngine/Scene/Scene/Scene.md
View File

@@ -6,47 +6,72 @@
**头文件**: `XCEngine/Scene/Scene.h` **头文件**: `XCEngine/Scene/Scene.h`
**描述**: 定义 `XCEngine/Scene` 子目录中的 `Scene` public API。 **描述**: 持有一组 `GameObject`、驱动场景级更新，并提供场景保存/加载能力的场景容器。
## 概述 ## 概述
`Scene.h` 是 `XCEngine/Scene` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `Scene` 是当前引擎里“对象集合”的所有权边界。它内部同时维护：
## 声明概览 - `m_gameObjects`，按 ID 保存 `GameObject` 的唯一所有权。
- `m_rootGameObjects`，保存根对象 ID 列表。
- `m_gameObjectIDs`，保存当前场景内出现过的对象 ID 集合。
- 两个创建/销毁事件入口。
| 声明 | 类型 | 说明 | 这类结构在商业引擎里很常见：场景负责对象集合、根节点入口和存档边界；对象本身再负责组件与层级递归。
|------|------|------|
| `Scene` | `class` | 头文件中的公开声明。 |
## 公共方法 ## 生命周期与所有权
| 方法 | 描述 | - [Constructor](Constructor.md) 创建空场景，默认激活状态为 `true`。
- [CreateGameObject](CreateGameObject.md) 分配并登记一个新对象。
- [DestroyGameObject](DestroyGameObject.md) 从当前场景树中递归移除对象。
- [Destructor](Destructor.md) 当前直接清空内部 `unique_ptr` 容器。
`Scene` 对对象有所有权，但绝大多数查询接口都返回裸指针。因此调用方必须把这些指针看成“场景拥有、只在场景存活且对象未被销毁时有效”的观察指针。
## 当前实现边界
- `m_active` 当前不会参与更新门控；即使场景 inactive，`Update()` 系列接口照样执行。
- [FindGameObjectWithTag](FindGameObjectWithTag.md) 名字里是 tag，实际实现里比较的是 `GameObject::GetName()`。
- [Destructor](Destructor.md) 不会触发 `OnGameObjectDestroyed()`，也不会为组件调用 `OnDestroy()`。
- [DeserializeFromString](DeserializeFromString.md) 直接重建内部状态，不经过 [CreateGameObject](CreateGameObject.md)，因此不会触发生命周期和创建事件。
- [Save](Save.md) / [Load](Load.md) 打开文件失败时当前静默返回。
- [SetName](SetName.md) 只会修改场景对象内部名称；如果场景由 `SceneManager` 管理，管理器的 key 不会随之更新。
## 线程语义
- 当前没有锁；应在主线程或外部同步前提下使用。
## 公开方法
| 方法 | 说明 |
|------|------| |------|------|
| [Scene()](Constructor.md) | 构造对象。 | | [Constructor](Constructor.md) | 构造空场景。 |
| [~Scene()](Destructor.md) | 销毁对象并释放相关资源。 | | [Destructor](Destructor.md) | 销毁场景。 |
| [GetName](GetName.md) | 获取相关状态或对象。 | | [GetName](GetName.md) | 查询场景名称。 |
| [SetName](SetName.md) | 设置相关状态或配置。 | | [SetName](SetName.md) | 设置场景名称。 |
| [IsActive](IsActive.md) | 查询当前状态。 | | [IsActive](IsActive.md) | 查询场景 active 标志。 |
| [SetActive](SetActive.md) | 设置相关状态或配置。 | | [SetActive](SetActive.md) | 设置场景 active 标志。 |
| [CreateGameObject](CreateGameObject.md) | 创建新对象或资源。 | | [CreateGameObject](CreateGameObject.md) | 创建场景对象。 |
| [DestroyGameObject](DestroyGameObject.md) | 公开方法，详见头文件声明。 | | [DestroyGameObject](DestroyGameObject.md) | 销毁场景对象。 |
| [Find](Find.md) | 查找并返回匹配对象。 | | [Find](Find.md) | 按名称查找对象。 |
| [FindByID](FindByID.md) | 查找并返回匹配对象。 | | [FindByID](FindByID.md) | 按 ID 查找对象。 |
| [FindGameObjectWithTag](FindGameObjectWithTag.md) | 查找并返回匹配对象。 | | [FindGameObjectWithTag](FindGameObjectWithTag.md) | 按“tag”查找；当前实际按名称匹配。 |
| [FindObjectOfType](FindObjectOfType.md) | 查找并返回匹配对象。 | | [FindObjectOfType](FindObjectOfType.md) | 查找第一个匹配组件。 |
| [FindObjectsOfType](FindObjectsOfType.md) | 查找并返回匹配对象。 | | [FindObjectsOfType](FindObjectsOfType.md) | 查找所有匹配组件。 |
| [GetRootGameObjects](GetRootGameObjects.md) | 获取相关状态或对象。 | | [GetRootGameObjects](GetRootGameObjects.md) | 获取根对象列表。 |
| [Update](Update.md) | 更新运行时状态。 | | [Update](Update.md) | 驱动每帧更新。 |
| [FixedUpdate](FixedUpdate.md) | 公开方法，详见头文件声明。 | | [FixedUpdate](FixedUpdate.md) | 驱动固定步长更新。 |
| [LateUpdate](LateUpdate.md) | 公开方法，详见头文件声明。 | | [LateUpdate](LateUpdate.md) | 驱动晚更新。 |
| [Save](Save.md) | 公开方法，详见头文件声明。 | | [Save](Save.md) | 保存到文件。 |
| [Load](Load.md) | 加载资源或数据。 | | [Load](Load.md) | 从文件加载。 |
| [SerializeToString](SerializeToString.md) | 公开方法，详见头文件声明。 | | [SerializeToString](SerializeToString.md) | 序列化为字符串。 |
| [DeserializeFromString](DeserializeFromString.md) | 公开方法，详见头文件声明。 | | [DeserializeFromString](DeserializeFromString.md) | 从字符串反序列化。 |
| [OnGameObjectCreated](OnGameObjectCreated.md) | 公开方法，详见头文件声明。 | | [OnGameObjectCreated](OnGameObjectCreated.md) | 访问对象创建事件。 |
| [OnGameObjectDestroyed](OnGameObjectDestroyed.md) | 公开方法，详见头文件声明。 | | [OnGameObjectDestroyed](OnGameObjectDestroyed.md) | 访问对象销毁事件。 |
## 相关文档 ## 相关文档
- [当前目录](../Scene.md) - 返回 `Scene` 平行目录 - [当前模块](../Scene.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [GameObject](../../Components/GameObject/GameObject.md)
- [TransformComponent](../../Components/TransformComponent/TransformComponent.md)
- [Scene Lifecycle And Serialization](../../../_guides/Scene/Scene-Lifecycle-And-Serialization.md)

33
docs/api/XCEngine/Scene/Scene/SerializeToString.md
View File

@@ -1,30 +1,33 @@
# Scene::SerializeToString # Scene::SerializeToString
公开方法，详见头文件声明。 把当前场景序列化为字符串。
```cpp ```cpp
std::string SerializeToString() const; std::string SerializeToString() const;
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现生成的是自定义文本格式，内容大致包括：
**返回：** `std::string` - 返回值语义详见头文件声明。 - 文件头 `# XCEngine Scene File`
- `scene=...`
- `active=...`
- 每个对象的 `gameobject_begin` / `gameobject_end` 块
- 对象 ID、UUID、名称、父对象 ID、Transform 数据和组件数据
**示例：** 对象输出顺序是“根对象顺序 + 深度优先递归子树”。
```cpp ## 返回值
#include <XCEngine/Scene/Scene.h>
void Example() { - `std::string` - 序列化后的场景文本。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::SerializeToString(...)。 ## 注意事项
(void)object;
} - 这不是 JSON、YAML 或 glTF 一类的通用格式。
``` - 名称字段会经过简单转义；组件内容如何写入，取决于各组件自己的 `Serialize()` 实现。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [DeserializeFromString](DeserializeFromString.md)

37
docs/api/XCEngine/Scene/Scene/SetActive.md
View File

@@ -1,31 +1,34 @@
# Scene::SetActive # Scene::SetActive
设置相关状态或配置。 设置场景 active 标志。
```cpp ```cpp
void SetActive(bool active); void SetActive(bool active);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前头文件内联实现只有一行：
- `active` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
**示例：**
```cpp ```cpp
#include <XCEngine/Scene/Scene.h> m_active = active;
void Example() {
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::SetActive(...)。
(void)object;
}
``` ```
## 参数
- `active` - 要写入的标志值。
## 返回值
- 无。
## 当前实现限制
- 不会同步到 `SceneManager::GetActiveScene()`。
- 不会自动启停对象更新链。
- 更适合把它当作可序列化的场景状态位，而不是完整的运行时调度开关。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [IsActive](IsActive.md)

30
docs/api/XCEngine/Scene/Scene/SetName.md
View File

@@ -1,31 +1,29 @@
# Scene::SetName # Scene::SetName
设置相关状态或配置。 设置场景名称。
```cpp ```cpp
void SetName(const std::string& name); void SetName(const std::string& name);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前头文件内联实现直接执行 `m_name = name`。
- `name` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 ## 参数
**示例：** - `name` - 新场景名称。
```cpp ## 返回值
#include <XCEngine/Scene/Scene.h>
void Example() { - 无。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::SetName(...)。 ## 注意事项
(void)object;
} - 如果当前场景已经由 `SceneManager` 按某个 key 保存到 `m_scenes` 中，这个调用不会同步修改那个 key。
``` - 因此 `Scene::GetName()` 与 `SceneManager::GetScene(...)` 使用的查找字符串，后续可能出现不一致。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [GetName](GetName.md)

36
docs/api/XCEngine/Scene/Scene/Update.md
View File

@@ -1,31 +1,35 @@
# Scene::Update # Scene::Update
更新运行时状态。 驱动场景的每帧更新。
```cpp ```cpp
void Update(float deltaTime); void Update(float deltaTime);
``` ```
该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会遍历根对象，并对处于 `IsActiveInHierarchy()` 状态的根对象执行：
- `deltaTime` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 1. `go->Start()`
2. `go->Update(deltaTime)`
**示例：** 对象树的递归传播由 `GameObject::Start()` 和 `GameObject::Update()` 自己完成。
```cpp ## 参数
#include <XCEngine/Scene/Scene.h>
void Example() { - `deltaTime` - 当前帧时间步长。
XCEngine::Components::Scene object;
// 根据上下文补齐参数后调用 Scene::Update(...)。 ## 返回值
(void)object;
} - 无。
```
## 注意事项
- `Start()` 每帧都会被调用到根对象入口，但 `GameObject` 内部会用 `m_started` 保证组件 `Start()` 只真正执行一次。
- `Scene::m_active` 当前不会阻止这条更新链运行。
## 相关文档 ## 相关文档
- [返回类总览](Scene.md) - [返回类型总览](Scene.md)
- [返回模块目录](../Scene.md) - [FixedUpdate](FixedUpdate.md)
- [LateUpdate](LateUpdate.md)

36
docs/api/XCEngine/Scene/SceneManager/CreateScene.md
View File

@@ -1,31 +1,35 @@
# SceneManager::CreateScene # SceneManager::CreateScene
创建新对象或资源。 创建并登记一个新场景。
```cpp ```cpp
Scene* CreateScene(const std::string& name); Scene* CreateScene(const std::string& name);
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `name` - 参数语义详见头文件声明。
**返回：** `Scene*` - 返回值语义详见头文件声明。 1. 构造 `std::make_unique<Scene>(name)`。
2. 把场景存入 `m_scenes[name]`。
3. 如果当前没有活动场景，则把 `m_activeScene` 设为新场景。
4. 触发 [OnSceneLoaded](OnSceneLoaded.md)。
**示例：** ## 参数
```cpp - `name` - 新场景名称，同时也是 `m_scenes` 的 key。
#include <XCEngine/Scene/SceneManager.h>
void Example() { ## 返回值
XCEngine::Components::SceneManager object;
// 根据上下文补齐参数后调用 SceneManager::CreateScene(...)。 - `Scene*` - 新场景的非拥有指针。
(void)object;
} ## 当前实现限制
```
- 如果同名 key 已存在，旧场景会被替换；先前拿到的裸指针可能失效。
- 当它成为第一个活动场景时，当前不会额外触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [GetScene](GetScene.md)
- [OnSceneLoaded](OnSceneLoaded.md)

24
docs/api/XCEngine/Scene/SceneManager/Get.md
View File

@@ -1,29 +1,23 @@
# SceneManager::Get # SceneManager::Get
获取相关状态或对象。 获取全局 `SceneManager` 单例。
```cpp ```cpp
static SceneManager& Get(); static SceneManager& Get();
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现通过函数内静态对象返回进程级单例：
**返回：** `SceneManager&` - 返回值语义详见头文件声明。
**示例：**
```cpp ```cpp
#include <XCEngine/Scene/SceneManager.h> static SceneManager instance;
void Example() {
auto& instance = XCEngine::Components::SceneManager::Get();
(void)instance;
}
``` ```
## 返回值
- `SceneManager&` - 全局场景管理器实例引用。
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md)

25
docs/api/XCEngine/Scene/SceneManager/GetActiveScene.md
View File

@@ -1,30 +1,25 @@
# SceneManager::GetActiveScene # SceneManager::GetActiveScene
获取相关状态或对象。 获取当前活动场景。
```cpp ```cpp
Scene* GetActiveScene() const; Scene* GetActiveScene() const;
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前头文件内联实现直接返回 `m_activeScene`。
**返回：** `Scene*` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `Scene*` - 当前活动场景指针；没有活动场景时返回 `nullptr`。
```cpp ## 注意事项
#include <XCEngine/Scene/SceneManager.h>
void Example() { - 这是非拥有指针。
XCEngine::Components::SceneManager object; - 它与 `Scene::IsActive()` 当前不是同一个概念，也不会自动同步。
// 根据上下文补齐参数后调用 SceneManager::GetActiveScene(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [SetActiveScene](SetActiveScene.md)

24
docs/api/XCEngine/Scene/SceneManager/GetAllScenes.md
View File

@@ -1,30 +1,24 @@
# SceneManager::GetAllScenes # SceneManager::GetAllScenes
获取相关状态或对象。 获取全部已登记场景。
```cpp ```cpp
std::vector<Scene*> GetAllScenes() const; std::vector<Scene*> GetAllScenes() const;
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前实现会遍历 `m_scenes`，把每个 `unique_ptr<Scene>` 的裸指针收集到结果数组中返回。
**返回：** `std::vector<Scene*>` - 返回值语义详见头文件声明。 ## 返回值
**示例：** - `std::vector<Scene*>` - 所有已登记场景的非拥有指针数组。
```cpp ## 注意事项
#include <XCEngine/Scene/SceneManager.h>
void Example() { - 返回顺序取决于 `std::unordered_map` 的迭代顺序，不应把它当作稳定顺序。
XCEngine::Components::SceneManager object;
// 根据上下文补齐参数后调用 SceneManager::GetAllScenes(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [GetScene](GetScene.md)

30
docs/api/XCEngine/Scene/SceneManager/GetScene.md
View File

@@ -1,31 +1,29 @@
# SceneManager::GetScene # SceneManager::GetScene
获取相关状态或对象。 按内部 key 获取场景。
```cpp ```cpp
Scene* GetScene(const std::string& name) const; Scene* GetScene(const std::string& name) const;
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现直接用 `name` 在 `m_scenes` 里做哈希表查找。
- `name` - 参数语义详见头文件声明。
**返回：** `Scene*` - 返回值语义详见头文件声明。 ## 参数
**示例：** - `name` - 场景 key。
```cpp ## 返回值
#include <XCEngine/Scene/SceneManager.h>
void Example() { - `Scene*` - 找到时返回场景指针；找不到时返回 `nullptr`。
XCEngine::Components::SceneManager object;
// 根据上下文补齐参数后调用 SceneManager::GetScene(...)。 ## 注意事项
(void)object;
} - 这个 `name` 对于 [CreateScene](CreateScene.md) 来说是创建时传入的名称。
``` - 对于 [LoadScene](LoadScene.md) 来说，它是文件名 stem，而不一定等于场景内部的 `Scene::GetName()`。
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [LoadScene](LoadScene.md)

38
docs/api/XCEngine/Scene/SceneManager/LoadScene.md
View File

@@ -1,31 +1,37 @@
# SceneManager::LoadScene # SceneManager::LoadScene
加载资源或数据。 从文件加载并登记一个场景。
```cpp ```cpp
void LoadScene(const std::string& filePath); void LoadScene(const std::string& filePath);
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现会：
- `filePath` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 1. 构造一个默认 `Scene`。
2. 调用 `scene->Load(filePath)`。
3. 从 `filePath` 中提取“文件名去扩展名”的字符串作为 map key。
4. 把场景存入 `m_scenes[key]`。
5. 触发 [OnSceneLoaded](OnSceneLoaded.md)。
**示例：** ## 参数
```cpp - `filePath` - 场景文件路径。
#include <XCEngine/Scene/SceneManager.h>
void Example() { ## 返回值
XCEngine::Components::SceneManager object;
// 根据上下文补齐参数后调用 SceneManager::LoadScene(...)。 - 无。
(void)object;
} ## 当前实现限制
```
- 当前不会在首次加载时自动设置 `m_activeScene`。
- 如果同 key 场景已存在，旧场景会被替换。
- `Scene::GetName()` 可能来自文件内部内容，而 `SceneManager` 保存的 key 来自文件名，两者可能不同。
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [LoadSceneAsync](LoadSceneAsync.md)
- [GetScene](GetScene.md)

35
docs/api/XCEngine/Scene/SceneManager/LoadSceneAsync.md
View File

@@ -1,32 +1,33 @@
# SceneManager::LoadSceneAsync # SceneManager::LoadSceneAsync
加载资源或数据。 异步加载场景。
```cpp ```cpp
void LoadSceneAsync(const std::string& filePath, std::function<void(Scene*)> callback); void LoadSceneAsync(const std::string& filePath, std::function<void(Scene*)> callback);
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 当前实现实际上并没有启动后台任务，而是：
- `filePath` - 参数语义详见头文件声明。
- `callback` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 1. 直接调用 [LoadScene](LoadScene.md)。
2. 如果 `callback` 非空，再执行 `callback(GetScene(filePath))`。
**示例：** ## 参数
```cpp - `filePath` - 场景文件路径。
#include <XCEngine/Scene/SceneManager.h> - `callback` - 加载结束后调用的回调。
void Example() { ## 返回值
XCEngine::Components::SceneManager object;
// 根据上下文补齐参数后调用 SceneManager::LoadSceneAsync(...)。 - 无。
(void)object;
} ## 当前实现限制
```
- 当前完全是同步执行，不是线程化或任务系统驱动的异步加载。
- 回调查找使用的是原始 `filePath`，而 [LoadScene](LoadScene.md) 存储使用的是文件名 stem。对于常见的 `assets/scenes/Main.xc` 这类输入，`GetScene(filePath)` 通常会返回 `nullptr`。
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [LoadScene](LoadScene.md)

26
docs/api/XCEngine/Scene/SceneManager/OnActiveSceneChanged.md
View File

@@ -1,30 +1,26 @@
# SceneManager::OnActiveSceneChanged # SceneManager::OnActiveSceneChanged
公开方法，详见头文件声明。 访问活动场景切换事件。
```cpp ```cpp
Core::Event<Scene*>& OnActiveSceneChanged(); Core::Event<Scene*>& OnActiveSceneChanged();
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前头文件内联实现直接返回 `m_onActiveSceneChanged` 的引用。
**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。 这个事件会在：
**示例：** - [SetActiveScene](SetActiveScene.md) 真正改变 `m_activeScene` 时触发。
- [UnloadScene](UnloadScene.md) 卸载当前活动场景并自动选择新的后备场景时触发。
```cpp ## 返回值
#include <XCEngine/Scene/SceneManager.h>
void Example() { - `Core::Event<Scene*>&` - 活动场景切换事件对象引用。
XCEngine::Components::SceneManager object;
// 根据上下文补齐参数后调用 SceneManager::OnActiveSceneChanged(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [SetActiveScene](SetActiveScene.md)
- [Event](../../Core/Event/Event.md)

25
docs/api/XCEngine/Scene/SceneManager/OnSceneLoaded.md
View File

@@ -1,30 +1,23 @@
# SceneManager::OnSceneLoaded # SceneManager::OnSceneLoaded
公开方法，详见头文件声明。 访问场景加载事件。
```cpp ```cpp
Core::Event<Scene*>& OnSceneLoaded(); Core::Event<Scene*>& OnSceneLoaded();
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前头文件内联实现直接返回 `m_onSceneLoaded` 的引用。
**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。 这个事件在 [CreateScene](CreateScene.md) 和 [LoadScene](LoadScene.md) 中都会触发。
**示例：** ## 返回值
```cpp - `Core::Event<Scene*>&` - 场景加载事件对象引用。
#include <XCEngine/Scene/SceneManager.h>
void Example() {
XCEngine::Components::SceneManager object;
// 根据上下文补齐参数后调用 SceneManager::OnSceneLoaded(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [CreateScene](CreateScene.md)
- [LoadScene](LoadScene.md)

24
docs/api/XCEngine/Scene/SceneManager/OnSceneUnloaded.md
View File

@@ -1,30 +1,22 @@
# SceneManager::OnSceneUnloaded # SceneManager::OnSceneUnloaded
公开方法，详见头文件声明。 访问场景卸载事件。
```cpp ```cpp
Core::Event<Scene*>& OnSceneUnloaded(); Core::Event<Scene*>& OnSceneUnloaded();
``` ```
该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。 ## 行为说明
**参数：** 无。 当前头文件内联实现直接返回 `m_onSceneUnloaded` 的引用。
**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。 该事件在 [UnloadScene](UnloadScene.md) 找到并真正移除场景时触发。
**示例：** ## 返回值
```cpp - `Core::Event<Scene*>&` - 场景卸载事件对象引用。
#include <XCEngine/Scene/SceneManager.h>
void Example() {
XCEngine::Components::SceneManager object;
// 根据上下文补齐参数后调用 SceneManager::OnSceneUnloaded(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [UnloadScene](UnloadScene.md)

65
docs/api/XCEngine/Scene/SceneManager/SceneManager.md
View File

@@ -6,36 +6,57 @@
**头文件**: `XCEngine/Scene/SceneManager.h` **头文件**: `XCEngine/Scene/SceneManager.h`
**描述**: 定义 `XCEngine/Scene` 子目录中的 `SceneManager` public API。 **描述**: 维护已加载场景集合并提供活动场景入口的全局场景管理器。
## 概述 ## 概述
`SceneManager.h` 是 `XCEngine/Scene` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。 `SceneManager` 负责的是“场景注册表”和“当前活动场景指针”，而不是完整的场景调度框架。它内部维护：
## 声明概览 - `m_scenes`，按字符串 key 保存场景唯一所有权。
- `m_activeScene`，保存当前活动场景裸指针。
- 三个场景级事件对象。
| 声明 | 类型 | 说明 | 这种设计对应很多商业引擎里的“全局场景入口”思路：上层系统通过一个统一位置拿到活动场景或切换已加载场景，而不是自己持有所有场景集合。
|------|------|------|
| `SceneManager` | `class` | 头文件中的公开声明。 |
## 公共方法 ## 所有权与 key 规则
| 方法 | 描述 | - [CreateScene](CreateScene.md) 创建的场景以传入 `name` 作为 map key。
- [LoadScene](LoadScene.md) 加载的场景以“文件名 stem”作为 map key，而不是文件内部保存的 `scene=` 名称。
- `GetScene()`、`UnloadScene(const std::string&)` 和 `SetActiveScene(const std::string&)` 都使用这个内部 key。
- 如果场景对象后续调用 `Scene::SetName()` 改名，当前 key 不会自动重建。
## 当前实现边界
- 当前没有锁；不适合并发加载或并发卸载。
- [LoadSceneAsync](LoadSceneAsync.md) 目前不是异步，只是同步调用再执行回调。
- [LoadSceneAsync](LoadSceneAsync.md) 的回调查找使用原始 `filePath` 做 key，常见情况下会得到 `nullptr`。
- `SceneManager` 的活动场景指针，与 `Scene::IsActive()` / `SetActive()` 当前没有自动同步关系。
- [SetActiveScene](SetActiveScene.md) 的指针重载不会校验传入场景是否真的来自 `m_scenes`。
- 如果使用相同 key 重复创建或加载场景，旧场景会被新场景替换；这可能让先前缓存的裸指针失效。
## 线程语义
- 当前没有内部同步；应把它当作主线程系统使用。
## 公开方法
| 方法 | 说明 |
|------|------| |------|------|
| [Get](Get.md) | 获取相关状态或对象。 | | [Get](Get.md) | 获取单例。 |
| [CreateScene](CreateScene.md) | 创建新对象或资源。 | | [CreateScene](CreateScene.md) | 创建并登记场景。 |
| [LoadScene](LoadScene.md) | 加载资源或数据。 | | [LoadScene](LoadScene.md) | 从文件加载并登记场景。 |
| [LoadSceneAsync](LoadSceneAsync.md) | 加载资源或数据。 | | [LoadSceneAsync](LoadSceneAsync.md) | 当前的同步包装“异步”加载接口。 |
| [UnloadScene](UnloadScene.md) | 卸载资源或释放缓存。 | | [UnloadScene](UnloadScene.md) | 卸载场景。 |
| [SetActiveScene](SetActiveScene.md) | 设置相关状态或配置。 | | [SetActiveScene](SetActiveScene.md) | 设置活动场景。 |
| [GetActiveScene](GetActiveScene.md) | 获取相关状态或对象。 | | [GetActiveScene](GetActiveScene.md) | 获取活动场景。 |
| [GetScene](GetScene.md) | 获取相关状态或对象。 | | [GetScene](GetScene.md) | 按 key 获取场景。 |
| [GetAllScenes](GetAllScenes.md) | 获取相关状态或对象。 | | [GetAllScenes](GetAllScenes.md) | 获取全部已登记场景。 |
| [OnSceneLoaded](OnSceneLoaded.md) | 公开方法，详见头文件声明。 | | [OnSceneLoaded](OnSceneLoaded.md) | 访问场景加载事件。 |
| [OnSceneUnloaded](OnSceneUnloaded.md) | 公开方法，详见头文件声明。 | | [OnSceneUnloaded](OnSceneUnloaded.md) | 访问场景卸载事件。 |
| [OnActiveSceneChanged](OnActiveSceneChanged.md) | 公开方法，详见头文件声明。 | | [OnActiveSceneChanged](OnActiveSceneChanged.md) | 访问活动场景切换事件。 |
## 相关文档 ## 相关文档
- [当前目录](../Scene.md) - 返回 `Scene` 平行目录 - [当前模块](../Scene.md)
- [API 总索引](../../../main.md) - 返回顶层索引 - [Scene](../Scene/Scene.md)
- [Scene Lifecycle And Serialization](../../../_guides/Scene/Scene-Lifecycle-And-Serialization.md)

50
docs/api/XCEngine/Scene/SceneManager/SetActiveScene.md
View File

@@ -1,44 +1,36 @@
# SceneManager::SetActiveScene # SceneManager::SetActiveScene
设置相关状态或配置。 设置活动场景。
该方法在 `XCEngine/Scene/SceneManager.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void SetActiveScene(Scene* scene); void SetActiveScene(Scene* scene);
```
**参数：**
- `scene` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp
void SetActiveScene(const std::string& sceneName); void SetActiveScene(const std::string& sceneName);
``` ```
**参数：** ## 行为说明
- `sceneName` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 当前有两个重载：
**示例：** - 指针重载会在 `m_activeScene != scene` 时直接写入 `m_activeScene = scene`，然后触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
- 字符串重载会先在 `m_scenes` 中查找 key，找到后再调用指针重载。
```cpp ## 参数
#include <XCEngine/Scene/SceneManager.h>
void Example() { - `scene` - 目标活动场景指针。
XCEngine::Components::SceneManager object; - `sceneName` - 目标场景 key。
// 根据上下文补齐参数后调用 SceneManager::SetActiveScene(...)。
(void)object; ## 返回值
}
``` - 无。
## 当前实现限制
- 指针重载不会校验 `scene` 是否真的来自 `SceneManager` 当前持有的场景集合。
- 当前不会同步 `Scene::SetActive()`。
- 如果传入的指针就是当前活动场景，不会触发事件。
- 传入 `nullptr` 时，如果当前活动场景非空，会把活动场景清空并触发切换事件。
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [GetActiveScene](GetActiveScene.md)

55
docs/api/XCEngine/Scene/SceneManager/UnloadScene.md
View File

@@ -1,44 +1,41 @@
# SceneManager::UnloadScene # SceneManager::UnloadScene
卸载资源或释放缓存。 卸载一个已登记场景。
该方法在 `XCEngine/Scene/SceneManager.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
## 重载 1: 声明
```cpp ```cpp
void UnloadScene(Scene* scene); void UnloadScene(Scene* scene);
```
**参数：**
- `scene` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。
## 重载 2: 声明
```cpp
void UnloadScene(const std::string& sceneName); void UnloadScene(const std::string& sceneName);
``` ```
**参数：** ## 行为说明
- `sceneName` - 参数语义详见头文件声明。
**返回：** `void` - 无返回值。 当前有两个重载：
**示例：** - 指针重载：
1. `scene == nullptr` 时直接返回。
2. 如果它正好是 `m_activeScene`，先把活动场景清空。
3. 在 `m_scenes` 里线性查找匹配指针。
4. 找到后触发 [OnSceneUnloaded](OnSceneUnloaded.md)，然后擦除。
5. 如果活动场景为空且仍有剩余场景，选择 `m_scenes.begin()` 作为新的活动场景，并触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
- 字符串重载：先按 key 查找，再转到指针重载。
```cpp ## 参数
#include <XCEngine/Scene/SceneManager.h>
void Example() { - `scene` - 待卸载场景指针。
XCEngine::Components::SceneManager object; - `sceneName` - 待卸载场景 key。
// 根据上下文补齐参数后调用 SceneManager::UnloadScene(...)。
(void)object; ## 返回值
}
``` - 无。
## 当前实现限制
- 后备活动场景来自 `unordered_map` 首元素，选择顺序不稳定。
- 如果卸载的是最后一个活动场景，当前不会额外发出“活动场景变为 `nullptr`”的切换事件。
- 指针重载内部需要线性扫描 map 找到匹配场景。
## 相关文档 ## 相关文档
- [返回类总览](SceneManager.md) - [返回类型总览](SceneManager.md)
- [返回模块目录](../Scene.md) - [OnSceneUnloaded](OnSceneUnloaded.md)
- [OnActiveSceneChanged](OnActiveSceneChanged.md)

85
docs/api/_guides/Scene/Scene-Lifecycle-And-Serialization.md Normal file
View File

@@ -0,0 +1,85 @@
# Scene Lifecycle And Serialization
## 为什么场景系统通常这样分层
商业级游戏引擎很少把“场景”“对象”“组件”揉成一个类。更常见的拆法是：
- 场景负责对象集合、根节点入口和存档边界。
- 对象负责层级关系与生命周期转发。
- 组件负责真正的可组合行为。
`XCEngine` 当前的 `Scene` / `GameObject` / `Component` 关系基本就是这个思路，所以它看上去会比较像 Unity 风格的设计，而不是传统单一 Entity 容器。
## `Scene` 真正负责什么
当前 `Scene` 最核心的职责有三件事：
1. 持有 `GameObject` 的唯一所有权。
2. 从根对象入口驱动 `Update` / `FixedUpdate` / `LateUpdate`。
3. 作为保存和加载的边界，把一整棵对象树序列化出去或重新建回来。
这样做的好处是，场景可以被理解成“一个可整体保存、整体切换的运行时世界片段”。
## 为什么要有根对象列表
场景里既有对象树，又单独保存 `m_rootGameObjects`，这不是重复设计，而是为了让两件事都变简单：
- 查“从哪里开始遍历场景”时，不用扫描全体对象找没有父节点的项。
- 对象挂接和脱离父节点时，只要同步更新根列表即可。
这是很多商用引擎场景树都会采用的做法，因为“根入口”和“局部子树”是两种不同维度的查询。
## 当前 active 状态有两层，但还没有完全打通
理解这块很重要：
- `SceneManager::GetActiveScene()` 是“哪一个场景被管理器认为是当前活动场景”。
- `Scene::IsActive()` 是 `Scene` 自己保存的一个布尔标志。
- `GameObject::IsActiveInHierarchy()` 才是对象更新真正参与的门槛。
在当前实现里，这三者并没有完全联动：
- `Scene::SetActive(false)` 不会阻止 `Scene::Update()`。
- `SceneManager::SetActiveScene()` 也不会自动改 `Scene::IsActive()`。
这意味着现在更稳妥的理解方式是：
- `SceneManager` 的 active scene 更接近“当前选中的场景引用”。
- `Scene::m_active` 更接近“一个可保存的场景状态位”。
## 序列化为什么用自定义文本格式
当前 `Scene::SerializeToString()` 没有走 JSON，而是用了非常直接的文本块格式。这样做的现实好处是：
- 实现简单。
- 组件可以继续用自己的 `Serialize(std::ostream&)` 输出。
- 调试时直接打开文本就能看见对象、父子关系和组件条目。
但代价也很明确：
- 格式是引擎私有的，没有版本协商。
- 解析鲁棒性有限。
- 组件恢复依赖 `ComponentFactoryRegistry`，组件名或注册表变化都会影响加载结果。
## 当前最需要小心的几个事实
- 场景析构不会自动为所有对象走显式销毁流程，所以不要把 `~Scene()` 当成完整生命周期清理器。
- `FindGameObjectWithTag()` 现在其实是在按名字查。
- `LoadSceneAsync()` 现在不是异步，更多只是一个名字上预留好的 API。
- `LoadScene()` 后的管理器 key 来自文件名，而不是场景内部保存的 `scene=` 名称。
## 实际使用建议
如果你现在基于这套系统开发，比较稳妥的做法通常是：
- 需要 `OnDestroy` 或场景事件时，显式调用对象销毁入口，不要只依赖场景析构。
- 需要稳定查场景时，优先用 `CreateScene()` 的名称或加载文件的文件名 stem，不要假设一定等于场景内部名字。
- 不要把 `LoadSceneAsync()` 当成真正的后台加载接口。
- 不要把 `FindGameObjectWithTag()` 当成完整 tag 系统。
## 相关 API
- [Scene Module](../../XCEngine/Scene/Scene.md)
- [Scene](../../XCEngine/Scene/Scene/Scene.md)
- [SceneManager](../../XCEngine/Scene/SceneManager/SceneManager.md)
- [GameObject](../../XCEngine/Components/GameObject/GameObject.md)

4
docs/api/_meta/rebuild-status.md
View File

@@ -1,12 +1,12 @@
# API 文档重构状态 # API 文档重构状态
**生成时间**: `2026-03-26 18:01:19` **生成时间**: `2026-03-26 19:32:04`
**来源**: `docs/api/_tools/audit_api_docs.py` **来源**: `docs/api/_tools/audit_api_docs.py`
## 摘要 ## 摘要
- Markdown 页面数（全部）: `2444` - Markdown 页面数（全部）: `2445`
- Markdown 页面数（canonical）: `2436` - Markdown 页面数（canonical）: `2436`
- Public headers 数: `185` - Public headers 数: `185`
- 有效头文件引用数（全部）: `185` - 有效头文件引用数（全部）: `185`