docs: expand scene manager API docs

2026-04-03 13:32:30 +08:00
parent cbc653fc97
commit 4016b35214
33 changed files with 1288 additions and 32 deletions
--- a/docs/api/XCEngine/Editor/Core/ISceneManager/Clipboard-And-Duplicate-Operations.md
+++ b/docs/api/XCEngine/Editor/Core/ISceneManager/Clipboard-And-Duplicate-Operations.md
@@ -0,0 +1,44 @@
+# ISceneManager Clipboard And Duplicate Operations
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `interface methods`
+
+**源文件**: `editor/src/Core/ISceneManager.h`
+
+## 签名
+
+```cpp
+virtual void CopyEntity(::XCEngine::Components::GameObject::ID id) = 0;
+virtual ::XCEngine::Components::GameObject::ID PasteEntity(
+    ::XCEngine::Components::GameObject::ID parent = 0) = 0;
+virtual ::XCEngine::Components::GameObject::ID DuplicateEntity(
+    ::XCEngine::Components::GameObject::ID id) = 0;
+virtual bool HasClipboardData() const = 0;
+```
+
+## 作用
+
+定义编辑器进程内实体复制、粘贴、复制副本与剪贴板可用性查询接口。
+
+## 契约语义
+
+- `CopyEntity(...)`
+  - 把指定实体子树复制到编辑器剪贴板。
+- `PasteEntity(...)`
+  - 从当前剪贴板恢复一棵实体子树。
+  - 可选指定目标父节点；`0` 通常表示粘贴到 root。
+- `DuplicateEntity(...)`
+  - 复制并立即粘贴一个实体子树。
+- `HasClipboardData()`
+  - 查询当前是否存在可粘贴内容。
+
+## 当前实现对应关系
+
+默认实现 [SceneManager](../../Managers/SceneManager/SceneManager.md) 当前使用的是进程内 `ClipboardData` 树，而不是系统剪贴板。
+
+## 相关文档
+
+- [ISceneManager](ISceneManager.md)
+- [Entity Tree Operations](Entity-Tree-Operations.md)
+- [SceneManager](../../Managers/SceneManager/SceneManager.md)
--- a/docs/api/XCEngine/Editor/Core/ISceneManager/Dirty-State-And-Snapshot.md
+++ b/docs/api/XCEngine/Editor/Core/ISceneManager/Dirty-State-And-Snapshot.md
@@ -0,0 +1,46 @@
+# ISceneManager Dirty State And Snapshot
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `interface methods`
+
+**源文件**: `editor/src/Core/ISceneManager.h`
+
+## 签名
+
+```cpp
+virtual bool IsSceneDirty() const = 0;
+virtual void MarkSceneDirty() = 0;
+virtual void SetSceneDocumentDirtyTrackingEnabled(bool enabled) = 0;
+virtual bool IsSceneDocumentDirtyTrackingEnabled() const = 0;
+virtual SceneSnapshot CaptureSceneSnapshot() const = 0;
+virtual bool RestoreSceneSnapshot(const SceneSnapshot& snapshot) = 0;
+```
+
+## 作用
+
+定义场景 dirty 状态管理，以及 play mode 前后编辑态恢复所需的快照接口。
+
+## 契约语义
+
+- `IsSceneDirty()`
+  - 查询当前场景是否被视为未保存。
+- `MarkSceneDirty()`
+  - 把当前编辑态标记为 dirty。
+- `SetSceneDocumentDirtyTrackingEnabled(...)`
+  - 控制实体编辑是否自动触发 dirty。
+- `CaptureSceneSnapshot()`
+  - 抓取可恢复的编辑态快照。
+- `RestoreSceneSnapshot(...)`
+  - 从快照恢复编辑态场景。
+
+## 设计含义
+
+- 这组接口让 `ISceneManager` 不只是“场景树服务”，还承担 play mode 进出的一部分状态恢复职责。
+- 因此它和 [SceneSnapshot](../SceneSnapshot/SceneSnapshot.md)、[PlaySessionController](../PlaySessionController/PlaySessionController.md) 有直接协作关系。
+
+## 相关文档
+
+- [ISceneManager](ISceneManager.md)
+- [Scene Lifecycle](Scene-Lifecycle.md)
+- [SceneSnapshot](../SceneSnapshot/SceneSnapshot.md)
--- a/docs/api/XCEngine/Editor/Core/ISceneManager/Entity-Tree-Operations.md
+++ b/docs/api/XCEngine/Editor/Core/ISceneManager/Entity-Tree-Operations.md
@@ -0,0 +1,57 @@
+# ISceneManager Entity Tree Operations
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `interface methods`
+
+**源文件**: `editor/src/Core/ISceneManager.h`
+
+## 签名
+
+```cpp
+virtual ::XCEngine::Components::GameObject* CreateEntity(
+    const std::string& name,
+    ::XCEngine::Components::GameObject* parent = nullptr) = 0;
+virtual void DeleteEntity(::XCEngine::Components::GameObject::ID id) = 0;
+virtual void RenameEntity(
+    ::XCEngine::Components::GameObject::ID id,
+    const std::string& newName) = 0;
+virtual ::XCEngine::Components::GameObject* GetEntity(
+    ::XCEngine::Components::GameObject::ID id) = 0;
+virtual const std::vector<::XCEngine::Components::GameObject*>& GetRootEntities() const = 0;
+virtual void MoveEntity(
+    ::XCEngine::Components::GameObject::ID id,
+    ::XCEngine::Components::GameObject::ID newParent) = 0;
+```
+
+## 作用
+
+定义编辑器实体树最基础的创建、查询、重命名、删除和层级移动能力。
+
+## 契约语义
+
+- `CreateEntity(...)`
+  - 在当前编辑态场景里创建一个实体。
+  - 可选挂到指定父节点下。
+- `DeleteEntity(...)`
+  - 删除指定实体。
+  - 默认实现通常会递归处理其子节点。
+- `RenameEntity(...)`
+  - 修改实体显示名。
+- `GetEntity(...)`
+  - 按 `entityId` 查询实体。
+- `GetRootEntities()`
+  - 返回当前场景 root 节点集合。
+- `MoveEntity(...)`
+  - 调整实体父级关系。
+
+## 设计含义
+
+- 这组接口定义的是“编辑器层级树服务”，不只是底层 `Scene` 容器访问。
+- 面板、命令和 action router 通常都通过这组接口改动层级，而不是直接操作 `Scene`。
+
+## 相关文档
+
+- [ISceneManager](ISceneManager.md)
+- [Clipboard And Duplicate Operations](Clipboard-And-Duplicate-Operations.md)
+- [SceneManager](../../Managers/SceneManager/SceneManager.md)
--- a/docs/api/XCEngine/Editor/Core/ISceneManager/ISceneManager.md
+++ b/docs/api/XCEngine/Editor/Core/ISceneManager/ISceneManager.md
@@ -20,19 +20,36 @@

 ## 核心接口

-| 方法 | 作用 |
-|------|------|
-| `CreateEntity()` / `DeleteEntity()` / `RenameEntity()` | 实体生命周期管理。 |
-| `GetEntity()` / `GetRootEntities()` | 查询当前实体树。 |
-| `CopyEntity()` / `PasteEntity()` / `DuplicateEntity()` / `MoveEntity()` | 编辑器层级编辑操作。 |
-| `HasClipboardData()` | 查询是否有可粘贴内容。 |
-| `NewScene()` / `LoadScene()` / `SaveScene()` / `SaveSceneAs()` / `LoadStartupScene()` | 场景文件生命周期。 |
-| `HasActiveScene()` / `IsSceneDirty()` / `MarkSceneDirty()` | 当前场景状态。 |
-| `GetCurrentScenePath()` / `GetCurrentSceneName()` | 当前场景元信息。 |
-| `CreateDemoScene()` | 创建内置示例场景。 |
+### 实体树操作
+
+- [Entity Tree Operations](Entity-Tree-Operations.md)
+
+### 剪贴板与复制副本
+
+- [Clipboard And Duplicate Operations](Clipboard-And-Duplicate-Operations.md)
+
+### 场景文件生命周期
+
+- [Scene Lifecycle](Scene-Lifecycle.md)
+
+### dirty 状态与快照
+
+- [Dirty State And Snapshot](Dirty-State-And-Snapshot.md)
+
+## 当前实现关注点
+
+当前默认实现 [SceneManager](../../Managers/SceneManager/SceneManager.md) 已经把接口从“实体树服务”扩展成了更完整的编辑态场景工作流服务，尤其包括：
+
+- 进程内实体剪贴板
+- dirty tracking 开关
+- 启动场景回退
+- `SceneSnapshot` 抓取与恢复
+
+如果你要理解这些接口在当前产品里的真实行为，优先看 `SceneManager` 的对应方法页，而不是只按接口命名做推断。

 ## 相关文档

 - [Core](../Core.md)
 - [SceneManager](../../Managers/SceneManager/SceneManager.md)
+- [SceneSnapshot](../SceneSnapshot/SceneSnapshot.md)
 - [SceneCommands](../../Commands/SceneCommands/SceneCommands.md)
--- a/docs/api/XCEngine/Editor/Core/ISceneManager/Scene-Lifecycle.md
+++ b/docs/api/XCEngine/Editor/Core/ISceneManager/Scene-Lifecycle.md
@@ -0,0 +1,56 @@
+# ISceneManager Scene Lifecycle
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `interface methods`
+
+**源文件**: `editor/src/Core/ISceneManager.h`
+
+## 签名
+
+```cpp
+virtual void NewScene(const std::string& name = "Untitled Scene") = 0;
+virtual bool LoadScene(const std::string& filePath) = 0;
+virtual bool SaveScene() = 0;
+virtual bool SaveSceneAs(const std::string& filePath) = 0;
+virtual bool LoadStartupScene(const std::string& projectPath) = 0;
+virtual bool HasActiveScene() const = 0;
+virtual const std::string& GetCurrentScenePath() const = 0;
+virtual const std::string& GetCurrentSceneName() const = 0;
+virtual ::XCEngine::Components::Scene* GetScene() = 0;
+virtual const ::XCEngine::Components::Scene* GetScene() const = 0;
+virtual void CreateDemoScene() = 0;
+```
+
+## 作用
+
+定义编辑态场景的创建、加载、保存、启动场景解析与当前场景查询接口。
+
+## 契约语义
+
+- `NewScene(...)`
+  - 创建新的编辑态场景。
+- `LoadScene(...)`
+  - 从磁盘载入场景文件。
+- `SaveScene()` / `SaveSceneAs(...)`
+  - 把当前编辑态写回磁盘。
+- `LoadStartupScene(...)`
+  - 按项目配置或默认规则解析启动场景。
+- `HasActiveScene()`
+  - 查询当前是否有活动场景。
+- `GetCurrentScenePath()` / `GetCurrentSceneName()`
+  - 返回当前场景元信息。
+- `GetScene()`
+  - 返回当前编辑态 `Scene` 指针。
+- `CreateDemoScene()`
+  - 创建最小可用示例场景。
+
+## 当前实现对应关系
+
+默认实现 [SceneManager](../../Managers/SceneManager/SceneManager.md) 当前还负责启动场景缺失时的 demo scene 回退。
+
+## 相关文档
+
+- [ISceneManager](ISceneManager.md)
+- [Dirty State And Snapshot](Dirty-State-And-Snapshot.md)
+- [SceneManager](../../Managers/SceneManager/SceneManager.md)