From 94c56dd279972f1763d467a47ef9aaec69622a49 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 27 Mar 2026 14:40:29 +0800 Subject: [PATCH] docs: add Editor API documentation --- .../Actions/ActionBinding/ActionBinding.md | 46 ++++++ .../Actions/ActionRouting/ActionRouting.md | 50 ++++++ docs/api/XCEngine/Editor/Actions/Actions.md | 37 +++++ .../ConsoleActionRouter.md | 48 ++++++ .../EditActionRouter/EditActionRouter.md | 51 ++++++ .../Actions/EditorActions/EditorActions.md | 59 +++++++ .../HierarchyActionRouter.md | 51 ++++++ .../InspectorActionRouter.md | 50 ++++++ .../MainMenuActionRouter.md | 52 ++++++ .../ProjectActionRouter.md | 52 ++++++ .../Editor/Application/Application.md | 56 +++++++ docs/api/XCEngine/Editor/Commands/Commands.md | 37 +++++ .../ComponentCommands/ComponentCommands.md | 52 ++++++ .../Commands/EntityCommands/EntityCommands.md | 54 +++++++ .../ProjectCommands/ProjectCommands.md | 49 ++++++ .../Commands/SceneCommands/SceneCommands.md | 49 ++++++ .../CameraComponentEditor.md | 52 ++++++ .../ComponentEditorRegistry.md | 41 +++++ .../ComponentEditors/ComponentEditors.md | 33 ++++ .../IComponentEditor/IComponentEditor.md | 40 +++++ .../LightComponentEditor.md | 46 ++++++ .../TransformComponentEditor.md | 54 +++++++ .../Editor/Core/AssetItem/AssetItem.md | 35 ++++ docs/api/XCEngine/Editor/Core/Core.md | 53 ++++++ .../EditorActionRoute/EditorActionRoute.md | 39 +++++ .../EditorConsoleSink/EditorConsoleSink.md | 42 +++++ .../Core/EditorContext/EditorContext.md | 43 +++++ .../Editor/Core/EditorEvents/EditorEvents.md | 44 +++++ .../EditorLoggingSetup/EditorLoggingSetup.md | 50 ++++++ .../EditorWindowTitle/EditorWindowTitle.md | 41 +++++ .../Core/EditorWorkspace/EditorWorkspace.md | 45 ++++++ .../XCEngine/Editor/Core/EventBus/EventBus.md | 43 +++++ .../Core/IEditorContext/IEditorContext.md | 45 ++++++ .../Core/IProjectManager/IProjectManager.md | 41 +++++ .../Core/ISceneManager/ISceneManager.md | 38 +++++ .../ISelectionManager/ISelectionManager.md | 36 +++++ .../Editor/Core/IUndoManager/IUndoManager.md | 50 ++++++ .../Core/SceneSnapshot/SceneSnapshot.md | 43 +++++ .../Core/SelectionManager/SelectionManager.md | 36 +++++ .../Editor/Core/UndoManager/UndoManager.md | 39 +++++ docs/api/XCEngine/Editor/Editor.md | 56 +++++++ .../Editor/Layers/EditorLayer/EditorLayer.md | 40 +++++ docs/api/XCEngine/Editor/Layers/Layers.md | 21 +++ .../DockLayoutController.md | 48 ++++++ docs/api/XCEngine/Editor/Layout/Layout.md | 19 +++ docs/api/XCEngine/Editor/Managers/Managers.md | 29 ++++ .../Managers/ProjectManager/ProjectManager.md | 40 +++++ .../Managers/SceneManager/SceneManager.md | 46 ++++++ .../SelectionManager/SelectionManager.md | 44 +++++ .../D3D12WindowRenderer.md | 43 +++++ docs/api/XCEngine/Editor/Platform/Platform.md | 34 ++++ .../Win32EditorHost/Win32EditorHost.md | 35 ++++ .../Editor/Platform/Win32Utf8/Win32Utf8.md | 43 +++++ .../WindowsProcessDiagnostics.md | 50 ++++++ docs/api/XCEngine/Editor/Theme/Theme.md | 27 ++++ .../UI/AboutEditorDialog/AboutEditorDialog.md | 46 ++++++ .../XCEngine/Editor/UI/BaseTheme/BaseTheme.md | 49 ++++++ .../ConsoleFilterState/ConsoleFilterState.md | 38 +++++ .../ConsoleLogFormatter.md | 44 +++++ docs/api/XCEngine/Editor/UI/Core/Core.md | 46 ++++++ .../Editor/UI/DockHostStyle/DockHostStyle.md | 35 ++++ .../ImGuiBackendBridge/ImGuiBackendBridge.md | 51 ++++++ .../Editor/UI/ImGuiSession/ImGuiSession.md | 38 +++++ .../Editor/UI/PanelChrome/PanelChrome.md | 45 ++++++ .../Editor/UI/PopupState/PopupState.md | 49 ++++++ .../Editor/UI/PropertyGrid/PropertyGrid.md | 49 ++++++ .../UI/ScalarControls/ScalarControls.md | 46 ++++++ .../UI/SceneStatusWidget/SceneStatusWidget.md | 36 +++++ .../Editor/UI/StyleTokens/StyleTokens.md | 46 ++++++ docs/api/XCEngine/Editor/UI/UI.md | 50 ++++++ .../UI/VectorControls/VectorControls.md | 49 ++++++ .../api/XCEngine/Editor/UI/Widgets/Widgets.md | 52 ++++++ .../SceneEditorUtils/SceneEditorUtils.md | 40 +++++ .../Editor/Utils/UndoUtils/UndoUtils.md | 35 ++++ docs/api/XCEngine/Editor/Utils/Utils.md | 26 +++ .../panels/ConsolePanel/ConsolePanel.md | 33 ++++ .../panels/GameViewPanel/GameViewPanel.md | 28 ++++ .../panels/HierarchyPanel/HierarchyPanel.md | 50 ++++++ .../panels/InspectorPanel/InspectorPanel.md | 41 +++++ .../XCEngine/Editor/panels/MenuBar/MenuBar.md | 31 ++++ .../api/XCEngine/Editor/panels/Panel/Panel.md | 43 +++++ .../panels/PanelCollection/PanelCollection.md | 37 +++++ .../panels/ProjectPanel/ProjectPanel.md | 41 +++++ .../panels/SceneViewPanel/SceneViewPanel.md | 28 ++++ docs/api/XCEngine/Editor/panels/panels.md | 37 +++++ docs/api/XCEngine/XCEngine.md | 8 +- .../Editor-Architecture-And-Workflow.md | 153 ++++++++++++++++++ 87 files changed, 3795 insertions(+), 2 deletions(-) create mode 100644 docs/api/XCEngine/Editor/Actions/ActionBinding/ActionBinding.md create mode 100644 docs/api/XCEngine/Editor/Actions/ActionRouting/ActionRouting.md create mode 100644 docs/api/XCEngine/Editor/Actions/Actions.md create mode 100644 docs/api/XCEngine/Editor/Actions/ConsoleActionRouter/ConsoleActionRouter.md create mode 100644 docs/api/XCEngine/Editor/Actions/EditActionRouter/EditActionRouter.md create mode 100644 docs/api/XCEngine/Editor/Actions/EditorActions/EditorActions.md create mode 100644 docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md create mode 100644 docs/api/XCEngine/Editor/Actions/InspectorActionRouter/InspectorActionRouter.md create mode 100644 docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md create mode 100644 docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md create mode 100644 docs/api/XCEngine/Editor/Application/Application.md create mode 100644 docs/api/XCEngine/Editor/Commands/Commands.md create mode 100644 docs/api/XCEngine/Editor/Commands/ComponentCommands/ComponentCommands.md create mode 100644 docs/api/XCEngine/Editor/Commands/EntityCommands/EntityCommands.md create mode 100644 docs/api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md create mode 100644 docs/api/XCEngine/Editor/Commands/SceneCommands/SceneCommands.md create mode 100644 docs/api/XCEngine/Editor/ComponentEditors/CameraComponentEditor/CameraComponentEditor.md create mode 100644 docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md create mode 100644 docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md create mode 100644 docs/api/XCEngine/Editor/ComponentEditors/IComponentEditor/IComponentEditor.md create mode 100644 docs/api/XCEngine/Editor/ComponentEditors/LightComponentEditor/LightComponentEditor.md create mode 100644 docs/api/XCEngine/Editor/ComponentEditors/TransformComponentEditor/TransformComponentEditor.md create mode 100644 docs/api/XCEngine/Editor/Core/AssetItem/AssetItem.md create mode 100644 docs/api/XCEngine/Editor/Core/Core.md create mode 100644 docs/api/XCEngine/Editor/Core/EditorActionRoute/EditorActionRoute.md create mode 100644 docs/api/XCEngine/Editor/Core/EditorConsoleSink/EditorConsoleSink.md create mode 100644 docs/api/XCEngine/Editor/Core/EditorContext/EditorContext.md create mode 100644 docs/api/XCEngine/Editor/Core/EditorEvents/EditorEvents.md create mode 100644 docs/api/XCEngine/Editor/Core/EditorLoggingSetup/EditorLoggingSetup.md create mode 100644 docs/api/XCEngine/Editor/Core/EditorWindowTitle/EditorWindowTitle.md create mode 100644 docs/api/XCEngine/Editor/Core/EditorWorkspace/EditorWorkspace.md create mode 100644 docs/api/XCEngine/Editor/Core/EventBus/EventBus.md create mode 100644 docs/api/XCEngine/Editor/Core/IEditorContext/IEditorContext.md create mode 100644 docs/api/XCEngine/Editor/Core/IProjectManager/IProjectManager.md create mode 100644 docs/api/XCEngine/Editor/Core/ISceneManager/ISceneManager.md create mode 100644 docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md create mode 100644 docs/api/XCEngine/Editor/Core/IUndoManager/IUndoManager.md create mode 100644 docs/api/XCEngine/Editor/Core/SceneSnapshot/SceneSnapshot.md create mode 100644 docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md create mode 100644 docs/api/XCEngine/Editor/Core/UndoManager/UndoManager.md create mode 100644 docs/api/XCEngine/Editor/Editor.md create mode 100644 docs/api/XCEngine/Editor/Layers/EditorLayer/EditorLayer.md create mode 100644 docs/api/XCEngine/Editor/Layers/Layers.md create mode 100644 docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md create mode 100644 docs/api/XCEngine/Editor/Layout/Layout.md create mode 100644 docs/api/XCEngine/Editor/Managers/Managers.md create mode 100644 docs/api/XCEngine/Editor/Managers/ProjectManager/ProjectManager.md create mode 100644 docs/api/XCEngine/Editor/Managers/SceneManager/SceneManager.md create mode 100644 docs/api/XCEngine/Editor/Managers/SelectionManager/SelectionManager.md create mode 100644 docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/D3D12WindowRenderer.md create mode 100644 docs/api/XCEngine/Editor/Platform/Platform.md create mode 100644 docs/api/XCEngine/Editor/Platform/Win32EditorHost/Win32EditorHost.md create mode 100644 docs/api/XCEngine/Editor/Platform/Win32Utf8/Win32Utf8.md create mode 100644 docs/api/XCEngine/Editor/Platform/WindowsProcessDiagnostics/WindowsProcessDiagnostics.md create mode 100644 docs/api/XCEngine/Editor/Theme/Theme.md create mode 100644 docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md create mode 100644 docs/api/XCEngine/Editor/UI/BaseTheme/BaseTheme.md create mode 100644 docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md create mode 100644 docs/api/XCEngine/Editor/UI/ConsoleLogFormatter/ConsoleLogFormatter.md create mode 100644 docs/api/XCEngine/Editor/UI/Core/Core.md create mode 100644 docs/api/XCEngine/Editor/UI/DockHostStyle/DockHostStyle.md create mode 100644 docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md create mode 100644 docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md create mode 100644 docs/api/XCEngine/Editor/UI/PanelChrome/PanelChrome.md create mode 100644 docs/api/XCEngine/Editor/UI/PopupState/PopupState.md create mode 100644 docs/api/XCEngine/Editor/UI/PropertyGrid/PropertyGrid.md create mode 100644 docs/api/XCEngine/Editor/UI/ScalarControls/ScalarControls.md create mode 100644 docs/api/XCEngine/Editor/UI/SceneStatusWidget/SceneStatusWidget.md create mode 100644 docs/api/XCEngine/Editor/UI/StyleTokens/StyleTokens.md create mode 100644 docs/api/XCEngine/Editor/UI/UI.md create mode 100644 docs/api/XCEngine/Editor/UI/VectorControls/VectorControls.md create mode 100644 docs/api/XCEngine/Editor/UI/Widgets/Widgets.md create mode 100644 docs/api/XCEngine/Editor/Utils/SceneEditorUtils/SceneEditorUtils.md create mode 100644 docs/api/XCEngine/Editor/Utils/UndoUtils/UndoUtils.md create mode 100644 docs/api/XCEngine/Editor/Utils/Utils.md create mode 100644 docs/api/XCEngine/Editor/panels/ConsolePanel/ConsolePanel.md create mode 100644 docs/api/XCEngine/Editor/panels/GameViewPanel/GameViewPanel.md create mode 100644 docs/api/XCEngine/Editor/panels/HierarchyPanel/HierarchyPanel.md create mode 100644 docs/api/XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md create mode 100644 docs/api/XCEngine/Editor/panels/MenuBar/MenuBar.md create mode 100644 docs/api/XCEngine/Editor/panels/Panel/Panel.md create mode 100644 docs/api/XCEngine/Editor/panels/PanelCollection/PanelCollection.md create mode 100644 docs/api/XCEngine/Editor/panels/ProjectPanel/ProjectPanel.md create mode 100644 docs/api/XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md create mode 100644 docs/api/XCEngine/Editor/panels/panels.md create mode 100644 docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md diff --git a/docs/api/XCEngine/Editor/Actions/ActionBinding/ActionBinding.md b/docs/api/XCEngine/Editor/Actions/ActionBinding/ActionBinding.md new file mode 100644 index 00000000..6fbd3311 --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/ActionBinding/ActionBinding.md @@ -0,0 +1,46 @@ +# ActionBinding + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header utility set` + +**源文件**: `editor/src/Actions/ActionBinding.h` + +**描述**: 定义快捷键和 UI 动作绑定数据结构，并提供菜单、按钮和快捷键处理辅助函数。 + +## 概述 + +`ActionBinding.h` 当前不是单一 class，而是一组围绕动作绑定组织起来的轻量工具： + +- `ShortcutChord` +- `ShortcutRoute` +- `ShortcutContext` +- `ActionBinding` +- 一系列 `Shortcut(...)` / `MakeAction(...)` / `Draw*Action(...)` / `HandleShortcut(...)` 辅助函数 + +## 当前实现说明 + +- 一个 `ActionBinding` 最多保存两个快捷键 chord。 +- `ShortcutContext` 当前支持 `Global` 和 `FocusedWindow` 两种上下文。 +- `MakeAction()` 用来快速构造动作描述对象。 +- `DrawMenuAction()` / `DrawButtonAction()` / `DrawInspectorAction()` / `DrawToolbarAction()` 等函数把动作直接映射成 UI 绘制。 +- `HandleShortcut()` 则把动作和快捷键触发逻辑连起来。 + +## 设计说明 + +这类做法很像商业工具链里常见的 command metadata + shortcut binding 层： + +- 动作有 label、shortcut、enabled、selected 等状态 +- UI 表现和实际执行函数分离 +- 快捷键逻辑能复用在菜单、按钮和工具栏上 + +## 当前实现边界 + +- 当前快捷键判断直接基于 ImGui input state。 +- 当前没有统一的命令注册表或可重绑定快捷键配置系统。 + +## 相关文档 + +- [Actions](../Actions.md) +- [UI](../../UI/UI.md) +- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) diff --git a/docs/api/XCEngine/Editor/Actions/ActionRouting/ActionRouting.md b/docs/api/XCEngine/Editor/Actions/ActionRouting/ActionRouting.md new file mode 100644 index 00000000..ddb072ef --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/ActionRouting/ActionRouting.md @@ -0,0 +1,50 @@ +# ActionRouting + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header-helper` + +**源文件**: `editor/src/Actions/ActionRouting.h` + +**描述**: 根据当前 ImGui 窗口焦点更新 `EditorActionRoute`，让 Edit 菜单和快捷键知道“当前应该作用于哪个面板”。 + +## 概述 + +`ActionRouting.h` 提供的是一组很小但很关键的粘合函数： + +- `ObserveFocusedActionRoute` 在当前窗口获得根窗口焦点时，把上下文的活动路由设置为指定值 +- `ObserveInactiveActionRoute` 把活动路由显式重置为 `EditorActionRoute::None` +- `IsActionRouteActive` 用于查询当前路由 + +这层设计的意义，不是再造一套复杂命令系统，而是把“UI 焦点”翻译成“编辑目标”。这样 `ProjectPanel` 获得焦点时，`Delete` 可以删除资源；`HierarchyPanel` 获得焦点时，同样的按键变成删除实体。 + +## 当前实现 + +- 路由判断直接依赖 `ImGui::IsWindowFocused(ImGuiFocusedFlags_RootAndChildWindows)` +- 没有独立的焦点管理器，也没有优先级仲裁器 +- 当前只有 `Hierarchy`、`Project` 和 `None` 三种路由状态 +- `HierarchyPanel` 与 `ProjectPanel` 会设置显式路由；`InspectorPanel` 与 `ConsolePanel` 当前会调用 `ObserveInactiveActionRoute` + +## 设计说明 + +这是一种很典型的商业编辑器做法：把“全局 Edit 菜单”做成上下文敏感，而不是把复制、粘贴、删除分别硬编码进每个面板。 +相对 Unity、Unreal 这类编辑器，这里的实现还很轻量，但方向是一致的： + +- 面板负责声明自己何时成为当前编辑目标 +- `EditActionRouter` 负责根据当前目标解析动作 +- `Commands` 层负责真正落地状态变更 + +这样拆开以后，快捷键、菜单栏和右键菜单可以共享同一套行为，不容易出现同一操作在不同入口行为不一致的问题。 + +## 当前限制 + +- 焦点路由完全依赖 ImGui 窗口焦点，尚未覆盖更细粒度的控件级编辑上下文 +- `Inspector` 尚未注册独立路由，因此它不会接管全局 Edit 行为 +- 没有多窗口、多文档或浮动工具窗之间的冲突处理策略 + +## 相关文档 + +- [Actions](../Actions.md) +- [EditorActions](../EditorActions/EditorActions.md) +- [EditActionRouter](../EditActionRouter/EditActionRouter.md) +- [EditorActionRoute](../../Core/EditorActionRoute/EditorActionRoute.md) diff --git a/docs/api/XCEngine/Editor/Actions/Actions.md b/docs/api/XCEngine/Editor/Actions/Actions.md new file mode 100644 index 00000000..0402cdf6 --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/Actions.md @@ -0,0 +1,37 @@ +# Actions + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `submodule` + +**描述**: 编辑器动作与快捷键绑定层，连接菜单、按钮、工具栏和快捷键触发逻辑。 + +## 概述 + +`Actions` 子模块当前承担的是“UI 交互元素如何对应到一个可执行动作”的抽象。 + +已文档化的核心页面： + +- [ActionBinding](ActionBinding/ActionBinding.md) +- [EditorActions](EditorActions/EditorActions.md) +- [ActionRouting](ActionRouting/ActionRouting.md) +- [EditActionRouter](EditActionRouter/EditActionRouter.md) +- [MainMenuActionRouter](MainMenuActionRouter/MainMenuActionRouter.md) +- [HierarchyActionRouter](HierarchyActionRouter/HierarchyActionRouter.md) +- [ProjectActionRouter](ProjectActionRouter/ProjectActionRouter.md) +- [InspectorActionRouter](InspectorActionRouter/InspectorActionRouter.md) +- [ConsoleActionRouter](ConsoleActionRouter/ConsoleActionRouter.md) + +它们共同构成当前编辑器的动作分层： + +- `EditorActions` 定义动作标签、快捷键和启用条件 +- `ActionRouting` 声明当前哪个面板拥有编辑焦点 +- 各种 `*ActionRouter` 把菜单、按钮、快捷键翻译成具体命令或事件 + +这种组织方式和商业编辑器常见的 context-sensitive edit menu 思路一致，能避免相同行为在多个 UI 入口里各自实现一遍。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [Commands](../Commands/Commands.md) +- [UI](../UI/UI.md) diff --git a/docs/api/XCEngine/Editor/Actions/ConsoleActionRouter/ConsoleActionRouter.md b/docs/api/XCEngine/Editor/Actions/ConsoleActionRouter/ConsoleActionRouter.md new file mode 100644 index 00000000..00712e38 --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/ConsoleActionRouter/ConsoleActionRouter.md @@ -0,0 +1,48 @@ +# ConsoleActionRouter + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header-helper` + +**源文件**: `editor/src/Actions/ConsoleActionRouter.h` + +**描述**: 为 Console 面板提供工具栏动作和日志列表绘制逻辑。 + +## 概述 + +`ConsoleActionRouter` 目前主要负责两件事： + +- `DrawConsoleToolbarActions` 绘制清空按钮和 Info / Warn / Error 过滤切换 +- `DrawConsoleLogRows` 读取 `EditorConsoleSink` 中的日志，并按过滤条件输出到面板 + +`ConsolePanel.cpp` 只负责搭窗口和滚动区域，真正的交互逻辑由这层统一承接。这样 Console 面板本身会保持很薄，不会把过滤策略、日志格式化和按钮语义都堆在一个类里。 + +## 当前实现 + +- 数据源固定为 [`EditorConsoleSink`](../../Core/EditorConsoleSink/EditorConsoleSink.md) +- 过滤状态由 [`ConsoleFilterState`](../../UI/ConsoleFilterState/ConsoleFilterState.md) 持有 +- 每条日志通过 [`BuildConsoleLogText`](../../UI/ConsoleLogFormatter/ConsoleLogFormatter.md) 生成展示字符串 +- 点击日志行时会把完整字符串复制到剪贴板 + +## 设计说明 + +这层拆分的价值在于把“日志存储”和“日志呈现”分开： + +- `EditorConsoleSink` 关注线程安全和日志缓存 +- `ConsoleActionRouter` 关注工具栏与列表交互 +- `UI` 辅助函数负责外观和文本格式 + +这种分层比直接在 `ConsolePanel::Render` 中处理全部逻辑更容易维护，也更接近商业级编辑器里常见的 presenter / controller 风格。 + +## 当前限制 + +- 当前过滤粒度只有三档：信息、警告、错误 +- 没有搜索、分类树、时间戳列或堆栈追踪展开 +- `GetLogs()` 会复制整个日志数组，日志量继续增大后可能需要增量视图或虚拟列表 + +## 相关文档 + +- [Actions](../Actions.md) +- [ConsolePanel](../../panels/ConsolePanel/ConsolePanel.md) +- [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) +- [ConsoleFilterState](../../UI/ConsoleFilterState/ConsoleFilterState.md) diff --git a/docs/api/XCEngine/Editor/Actions/EditActionRouter/EditActionRouter.md b/docs/api/XCEngine/Editor/Actions/EditActionRouter/EditActionRouter.md new file mode 100644 index 00000000..3016feef --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/EditActionRouter/EditActionRouter.md @@ -0,0 +1,51 @@ +# EditActionRouter + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header-helper` + +**源文件**: `editor/src/Actions/EditActionRouter.h` + +**描述**: 把全局 Edit 菜单和快捷键解析为上下文敏感的实体编辑或资源编辑动作。 + +## 概述 + +`EditActionRouter` 是当前编辑器“上下文式编辑命令”的核心桥接层。它先通过 `ResolveEditActionTarget` 读取： + +- 当前活动路由 `EditorActionRoute` +- 当前选中的实体 +- 当前选中的资源项 + +然后再决定 `Open`、`Delete`、`Rename`、`Copy`、`Paste`、`Duplicate`、`Navigate Back` 这些动作是否可用，以及真正应该调用哪个 `Commands` 函数。 + +## 当前实现 + +- `Project` 路由下，编辑动作主要映射到 [`ProjectCommands`](../../Commands/ProjectCommands/ProjectCommands.md) +- `Hierarchy` 路由下，编辑动作主要映射到 [`EntityCommands`](../../Commands/EntityCommands/EntityCommands.md) +- `HandleEditShortcuts` 统一处理快捷键 +- `DrawEditActions` 统一绘制菜单项 +- `Undo` / `Redo` 由当前上下文的 `IUndoManager` 直接提供 + +`EditActionTarget` 本身是一个轻量快照结构，不持有复杂状态，也不缓存引用生命周期。 + +## 设计说明 + +很多编辑器最容易退化的地方，就是每个面板各写一套删除、复制、粘贴逻辑。 +`EditActionRouter` 的作用正好相反：它把不同面板共享的“编辑语义”集中到一处，只把具体数据对象交给路由判断。 + +这和 Unity 菜单栏的思路很接近：同一个 `Delete` 菜单项，在不同焦点上下文里对应不同对象，但用户感知到的是统一操作。 + +## 当前限制 + +- `Cut` 仍然是禁用占位动作，没有真正实现 +- `Inspector` 没有独立路由，因此不会接管复制粘贴等全局编辑行为 +- `Paste` 当前只在 Hierarchy 路由下生效，不支持资源粘贴 +- 没有多选批处理版本的删除、复制与重命名 + +## 相关文档 + +- [Actions](../Actions.md) +- [ActionRouting](../ActionRouting/ActionRouting.md) +- [EditorActions](../EditorActions/EditorActions.md) +- [EntityCommands](../../Commands/EntityCommands/EntityCommands.md) +- [ProjectCommands](../../Commands/ProjectCommands/ProjectCommands.md) diff --git a/docs/api/XCEngine/Editor/Actions/EditorActions/EditorActions.md b/docs/api/XCEngine/Editor/Actions/EditorActions/EditorActions.md new file mode 100644 index 00000000..26cae114 --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/EditorActions/EditorActions.md @@ -0,0 +1,59 @@ +# EditorActions + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header-helper` + +**源文件**: `editor/src/Actions/EditorActions.h` + +**描述**: 定义编辑器中可复用的动作描述，包括菜单标题、快捷键、启用状态和选中项解析辅助函数。 + +## 概述 + +`EditorActions.h` 并不直接执行命令，它负责生产 [`ActionBinding`](../ActionBinding/ActionBinding.md)。 + +当前文件中的动作工厂可以分成几类： + +- 场景级动作：`MakeNewSceneAction`、`MakeOpenSceneAction`、`MakeSaveSceneAction` +- 编辑级动作：`MakeUndoAction`、`MakeRedoAction`、`MakeCopyEntityAction`、`MakePasteEntityAction` +- 层级面板动作：`MakeCreateChildEntityAction`、`MakeDetachEntityAction` +- 项目面板动作：`MakeNavigateBackAction`、`MakeOpenAssetAction`、`MakeCreateFolderAction` +- Inspector / Console 动作：`MakeAddComponentButtonAction`、`MakeRemoveComponentAction`、`MakeClearConsoleAction` + +此外它还提供： + +- `GetSelectedGameObject` +- `GetSelectedAssetItem` + +用于把当前上下文解析为后续路由与命令层需要的对象。 + +## 当前实现 + +- 动作标签、快捷键文本和 `ImGuiKey` 触发条件都集中写在这里 +- `Undo` / `Redo` 标签会根据 `IUndoManager` 动态显示历史项名称 +- `Paste`、`Delete`、`Duplicate` 等动作会根据当前选择动态启用或禁用 +- 资源选择解析依赖 `IProjectManager::GetSelectedIndex()` 和 `GetCurrentItems()` + +## 设计说明 + +把动作描述统一集中，是商业编辑器里常见的稳定做法。 +原因很直接： + +- 菜单栏、工具栏、右键菜单、快捷键需要共享同一组语义 +- “名称、快捷键、是否可用” 应该只有一个权威来源 +- 如果动作定义分散在各个面板里，最终会出现文本不一致、快捷键冲突和启用逻辑漂移 + +所以 `EditorActions` 更像编辑器的“动作字典”，而 `ActionRouter` 是“动作分发器”，`Commands` 则是“真正执行业务变更的地方”。 + +## 当前限制 + +- 动作仍然以手写 inline 工厂为主，尚未发展成可注册、可枚举的统一 action registry +- 没有本地化层，标签文本直接写死为英文 +- 资源动作当前只覆盖文件夹导航和场景资源打开 + +## 相关文档 + +- [Actions](../Actions.md) +- [ActionBinding](../ActionBinding/ActionBinding.md) +- [EditActionRouter](../EditActionRouter/EditActionRouter.md) +- [MainMenuActionRouter](../MainMenuActionRouter/MainMenuActionRouter.md) diff --git a/docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md b/docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md new file mode 100644 index 00000000..58f4bbc9 --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md @@ -0,0 +1,51 @@ +# HierarchyActionRouter + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header-helper` + +**源文件**: `editor/src/Actions/HierarchyActionRouter.h` + +**描述**: 封装 Hierarchy 面板中的选中、重命名、拖拽重挂接、排序和上下文菜单动作。 + +## 概述 + +`HierarchyActionRouter` 是当前实体层级树交互的主要承载者。它把 `HierarchyPanel.cpp` 中最容易膨胀的逻辑拆成了几类可复用动作： + +- 选择与背景点击清空选择 +- 实体重命名请求与提交 +- 拖拽实体到其他父节点或根节点 +- 创建 / 删除 / 复制 / 粘贴 / 重复实体 +- 排序选项弹窗 + +## 当前实现 + +- 拖拽载荷类型固定为字符串 `"ENTITY_PTR"` +- `HandleHierarchySelectionClick` 只实现了单选和 Ctrl 增选 +- `CommitEntityRename` 会先验证实体存在且名字非空，再调用 [`RenameEntity`](../../Commands/EntityCommands/EntityCommands.md) +- 拖拽重挂接时会调用 `Commands::CanReparentEntity` 和 `ReparentEntityPreserveWorldTransform` +- 背景右键菜单可以直接创建空物体、Camera、Light，以及命名为 `Cube` / `Sphere` / `Plane` 的空实体 + +## 设计说明 + +这类层级树交互通常非常碎，如果全写在面板类里，后续一加多选、拖放规则或菜单项就会迅速失控。 +把交互逻辑集中在 router 里有三个好处： + +- 面板类仍然只负责树结构遍历和 UI 布局 +- 所有入口都能复用同一套实体命令 +- 可以明确把“层级树交互规则”与“SceneManager 真正修改场景”的职责隔开 + +这和 Unity Hierarchy 的设计也比较接近：Hierarchy 面板只是入口，真正的数据修改要落到场景编辑命令层。 + +## 当前限制 + +- 暂不支持多实体批量拖拽 +- 只有 `Ctrl` 增选，没有框选、Shift 范围选中等高级交互 +- `Cube` / `Sphere` / `Plane` 当前只是命名约定，不会自动附加网格或渲染组件 + +## 相关文档 + +- [Actions](../Actions.md) +- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md) +- [EntityCommands](../../Commands/EntityCommands/EntityCommands.md) +- [EditorEvents](../../Core/EditorEvents/EditorEvents.md) diff --git a/docs/api/XCEngine/Editor/Actions/InspectorActionRouter/InspectorActionRouter.md b/docs/api/XCEngine/Editor/Actions/InspectorActionRouter/InspectorActionRouter.md new file mode 100644 index 00000000..ba4134d3 --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/InspectorActionRouter/InspectorActionRouter.md @@ -0,0 +1,50 @@ +# InspectorActionRouter + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header-helper` + +**源文件**: `editor/src/Actions/InspectorActionRouter.h` + +**描述**: 为 Inspector 面板封装组件添加、组件菜单和交互式撤销收尾逻辑。 + +## 概述 + +`InspectorActionRouter` 把 Inspector 面板里最核心的交互从 `InspectorPanel` 中抽离出来： + +- 选中对象变化时重置弹窗状态 +- 绘制 “Add Component” 按钮与弹窗 +- 遍历注册的组件编辑器，生成添加菜单 +- 绘制组件右上角菜单中的 “Remove Component” +- 在控件停止交互后，结束交互式撤销录制 + +## 当前实现 + +- `HandleInspectorSelectionChanged` 会在切换选中对象时主动结束未完成的交互式改动 +- 组件添加菜单依赖 [`ComponentEditorRegistry`](../../ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md) +- 如果没有任何注册 editor，弹窗会显示 “No registered component editors” +- `FinalizeInspectorInteractiveChangeIfIdle` 通过 `ImGui::IsAnyItemActive()` 判断当前是否仍在拖拽或编辑 + +## 设计说明 + +Inspector 是最容易把 UI、数据绑定、撤销系统缠在一起的地方。 +当前设计明确把职责拆开： + +- `IComponentEditor` 负责某个组件的字段 UI +- `InspectorActionRouter` 负责 Inspector 面板级别的交互 +- `ComponentCommands` 负责真正添加/删除组件并写入撤销 + +这比把 “Add Component” 和 “Remove Component” 直接嵌进每个组件 editor 更稳定，也更容易在后续演进到搜索、分类和脚本组件等复杂场景。 + +## 当前限制 + +- 添加组件菜单尚无搜索框与分类树 +- 组件排序、拖拽重排还没有实现 +- 当前删除组件只依赖 editor 的 `CanRemove` 规则，没有更高层的依赖分析 + +## 相关文档 + +- [Actions](../Actions.md) +- [InspectorPanel](../../panels/InspectorPanel/InspectorPanel.md) +- [ComponentCommands](../../Commands/ComponentCommands/ComponentCommands.md) +- [ComponentEditorRegistry](../../ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md) diff --git a/docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md b/docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md new file mode 100644 index 00000000..2f235d77 --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/MainMenuActionRouter/MainMenuActionRouter.md @@ -0,0 +1,52 @@ +# MainMenuActionRouter + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header-helper` + +**源文件**: `editor/src/Actions/MainMenuActionRouter.h` + +**描述**: 实现主菜单栏的文件、编辑、视图、帮助菜单，以及相应的全局快捷键和弹窗入口。 + +## 概述 + +`MainMenuActionRouter` 是 `MenuBar` 面板背后的实际逻辑层。当前它负责： + +- 新建、打开、保存场景 +- 撤销与重做 +- 请求退出编辑器 +- 请求重置 Dock 布局 +- 打开 About 弹窗 +- 在菜单栏右侧绘制当前场景状态 + +## 当前实现 + +- `ExecuteNewScene` / `ExecuteOpenScene` / `ExecuteSaveScene` 最终调用 [`SceneCommands`](../../Commands/SceneCommands/SceneCommands.md) +- `RequestEditorExit` 发布 `EditorExitRequestedEvent` +- `RequestDockLayoutReset` 发布 `DockLayoutResetRequestedEvent` +- `RequestAboutPopup` 通过 [`DeferredPopupState`](../../UI/PopupState/PopupState.md) 延迟打开 About 对话框 +- `HandleMenuBarShortcuts` 目前使用 `GlobalShortcutContext()` + +`MenuBar.cpp` 的 `Render()` 顺序也比较清晰：先处理快捷键，再绘制菜单栏，最后绘制弹窗覆盖层。 + +## 设计说明 + +把主菜单作为单独 router，而不是直接在 `MenuBar::Render` 里写一大串 `ImGui::MenuItem`，有两个明显收益： + +- 菜单项逻辑可以和命令层、事件总线清晰对接 +- 快捷键和菜单点击能共享同一套执行入口 + +这正是商业编辑器常见的菜单层设计方式。菜单不是业务逻辑本体，它只是统一入口。 + +## 当前限制 + +- 文件菜单当前只覆盖场景级工作流，没有项目级导入、构建或设置入口 +- About 弹窗内容仍然是开发中状态说明，不是正式产品级信息页 +- 全局快捷键冲突处理比较简单，尚未提供用户可配置热键系统 + +## 相关文档 + +- [Actions](../Actions.md) +- [MenuBar](../../panels/MenuBar/MenuBar.md) +- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) +- [PopupState](../../UI/PopupState/PopupState.md) diff --git a/docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md b/docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md new file mode 100644 index 00000000..88a1663e --- /dev/null +++ b/docs/api/XCEngine/Editor/Actions/ProjectActionRouter/ProjectActionRouter.md @@ -0,0 +1,52 @@ +# ProjectActionRouter + +**命名空间**: `XCEngine::Editor::Actions` + +**类型**: `header-helper` + +**源文件**: `editor/src/Actions/ProjectActionRouter.h` + +**描述**: 封装 Project 面板中的资源选择、导航、拖放、上下文菜单和创建文件夹弹窗流程。 + +## 概述 + +`ProjectActionRouter` 让 `ProjectPanel.cpp` 可以专注于资源网格布局，而把交互行为集中管理。当前覆盖的能力包括： + +- 资源项选中与右键上下文菜单 +- 文件夹打开与返回上级导航 +- 资源拖放到目录 +- 空白区域上下文菜单 +- “Create Folder” 弹窗与提交 + +## 当前实现 + +- 资源拖拽载荷类型固定为 `"ASSET_ITEM"` +- 打开资源时只支持两类：文件夹与 `type == "Scene"` 的资源 +- 删除资源调用 [`DeleteAsset`](../../Commands/ProjectCommands/ProjectCommands.md) +- 移动资源调用 `MoveAssetToFolder` +- 创建目录弹窗依赖 [`TextInputPopupState`](../../UI/PopupState/PopupState.md) + +`FindProjectItemIndex` 还额外做了 `fullPath` 匹配，这说明当前实现允许在某些刷新路径下通过值语义重新定位资源项，而不是完全依赖共享指针地址。 + +## 设计说明 + +Project 面板本质上是一个资产浏览器。 +把这些动作单独放在 router 层，有助于把以下两类变化隔开： + +- 视觉变化：列表改网格、加图标、加搜索、加分栏 +- 交互语义变化：打开、删除、移动、创建目录 + +这样后续即使 Project 面板彻底重画 UI，动作语义仍然可以稳定保留。 + +## 当前限制 + +- 当前资源系统没有更细的资源类型分发，场景之外的资源多数只能展示，不能打开 +- 资源重命名、复制、粘贴尚未实现 +- 没有回收站、删除确认和批量操作 + +## 相关文档 + +- [Actions](../Actions.md) +- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) +- [ProjectCommands](../../Commands/ProjectCommands/ProjectCommands.md) +- [PopupState](../../UI/PopupState/PopupState.md) diff --git a/docs/api/XCEngine/Editor/Application/Application.md b/docs/api/XCEngine/Editor/Application/Application.md new file mode 100644 index 00000000..45646783 --- /dev/null +++ b/docs/api/XCEngine/Editor/Application/Application.md @@ -0,0 +1,56 @@ +# Application + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (singleton)` + +**源文件**: `editor/src/Application.h` + +**描述**: 编辑器应用主入口，负责窗口渲染器、ImGui 后端、LayerStack 和 `EditorContext` 的初始化、渲染与关闭。 + +## 概述 + +`Application` 是当前编辑器应用真正的壳层对象。 + +它负责把几类本来分散的系统拼成一个可运行编辑器： + +- Win32 宿主窗口句柄 +- [Platform::D3D12WindowRenderer](../Platform/D3D12WindowRenderer/D3D12WindowRenderer.md) +- [UI::ImGuiSession](../UI/ImGuiSession/ImGuiSession.md) +- ImGui 平台/渲染后端桥 +- `LayerStack` +- [Core::EditorContext](../Core/EditorContext/EditorContext.md) +- [Layers::EditorLayer](../Layers/EditorLayer/EditorLayer.md) + +## 当前实现说明 + +- 采用单例入口 `Get()`。 +- `Initialize(HWND)` 会安装崩溃过滤器、配置日志、初始化窗口渲染器、创建编辑器上下文、初始化 ImGui，并挂接 `EditorLayer`。 +- `Shutdown()` 会按反向顺序关闭 layer、ImGui 和窗口渲染器。 +- `Render()` 当前只是执行一帧编辑器 UI 渲染。 +- `OnResize()` 会把尺寸变化转发给窗口渲染器。 + +## 关键公开接口 + +| 方法 | 作用 | +|------|------| +| `Get()` | 获取全局应用单例。 | +| `Initialize(HWND)` | 初始化编辑器应用。 | +| `Shutdown()` | 关闭编辑器应用。 | +| `Render()` | 绘制一帧编辑器。 | +| `OnResize(int, int)` | 处理窗口尺寸变化。 | +| `GetWindowHandle()` | 获取当前窗口句柄。 | +| `GetEditorContext()` | 获取当前编辑器上下文。 | + +## 当前实现边界 + +- 目前窗口渲染路径绑定到 D3D12 窗口渲染器，不是抽象后端。 +- `InitializeEditorContext()` 当前默认把项目路径设为可执行目录。 +- `Render()` 当前只走 ImGui 帧，不承载独立游戏循环或模拟步进逻辑。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [EditorContext](../Core/EditorContext/EditorContext.md) +- [EditorLayer](../Layers/EditorLayer/EditorLayer.md) +- [Win32EditorHost](../Platform/Win32EditorHost/Win32EditorHost.md) diff --git a/docs/api/XCEngine/Editor/Commands/Commands.md b/docs/api/XCEngine/Editor/Commands/Commands.md new file mode 100644 index 00000000..4e877785 --- /dev/null +++ b/docs/api/XCEngine/Editor/Commands/Commands.md @@ -0,0 +1,37 @@ +# Commands + +**命名空间**: `XCEngine::Editor::Commands` + +**类型**: `submodule` + +**描述**: 编辑器高层命令封装层，把场景、项目、实体与组件编辑工作流收束成可复用操作。 + +## 概述 + +`Commands` 层的定位，是把 UI 或 action router 中触发的具体操作，收口为更高层的编辑命令。 + +当前目录中包括： + +- [SceneCommands](SceneCommands/SceneCommands.md) +- [ProjectCommands](ProjectCommands/ProjectCommands.md) +- [EntityCommands](EntityCommands/EntityCommands.md) +- [ComponentCommands](ComponentCommands/ComponentCommands.md) + +## 设计说明 + +把面板代码里的按钮逻辑收束到命令层，是必要的。否则菜单、工具栏、快捷键和上下文菜单会各自复制一套场景操作流程。 + +从当前代码看，`Commands` 的职责边界已经比较清楚： + +- `SceneCommands` 负责场景文件生命周期 +- `ProjectCommands` 负责资产浏览器中的资源动作 +- `EntityCommands` 负责场景树结构编辑 +- `ComponentCommands` 负责 Inspector 中的组件增删 + +这正是商业级编辑器 API 文档里应当强调的部分：用户不应只知道“这里有几个 helper”，而应明确知道“不同级别的修改应该落到哪一层”。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [Actions](../Actions/Actions.md) +- [Core](../Core/Core.md) diff --git a/docs/api/XCEngine/Editor/Commands/ComponentCommands/ComponentCommands.md b/docs/api/XCEngine/Editor/Commands/ComponentCommands/ComponentCommands.md new file mode 100644 index 00000000..70100c88 --- /dev/null +++ b/docs/api/XCEngine/Editor/Commands/ComponentCommands/ComponentCommands.md @@ -0,0 +1,52 @@ +# ComponentCommands + +**命名空间**: `XCEngine::Editor::Commands` + +**类型**: `header-helper` + +**源文件**: `editor/src/Commands/ComponentCommands.h` + +**描述**: 封装组件添加与移除命令，并把这些操作统一纳入场景撤销系统。 + +## 概述 + +`ComponentCommands` 处理的是 Inspector 中最典型的一类结构性编辑操作： + +- 给实体添加某种组件 +- 从实体移除某个组件 + +它并不直接知道 Camera、Light、Transform 的具体字段，而是通过 [`IComponentEditor`](../../ComponentEditors/IComponentEditor/IComponentEditor.md) 提供的能力判断： + +- 某个组件能否添加到该实体 +- 某个组件能否被移除 + +## 当前实现 + +- `AddComponent` 会通过 `editor.AddTo(gameObject)` 完成真实创建 +- `RemoveComponent` 会调用 `gameObject->RemoveComponent(component)` +- 两类操作都会使用 [`UndoUtils::ExecuteSceneCommand`](../../Utils/UndoUtils/UndoUtils.md) 包装 +- 操作成功后会显式调用 `SceneManager::MarkSceneDirty()` + +## 设计说明 + +这层命令抽象的意义，是把组件编辑器从“直接改场景结构”里解耦出来。 +组件编辑器更适合回答“这个组件怎么画 UI、能不能加、能不能删”，而不适合自己关心： + +- 如何录制撤销 +- 如何标记场景 dirty +- 如何统一命令标签 + +这正是 `ComponentCommands` 应该做的事。 + +## 当前限制 + +- 组件依赖关系仍然很弱，没有自动补齐必需组件的机制 +- 删除组件时没有跨组件引用检查 +- 当前命令标签主要由组件显示名拼接，不支持更丰富的操作上下文 + +## 相关文档 + +- [Commands](../Commands.md) +- [InspectorActionRouter](../../Actions/InspectorActionRouter/InspectorActionRouter.md) +- [IComponentEditor](../../ComponentEditors/IComponentEditor/IComponentEditor.md) +- [UndoUtils](../../Utils/UndoUtils/UndoUtils.md) diff --git a/docs/api/XCEngine/Editor/Commands/EntityCommands/EntityCommands.md b/docs/api/XCEngine/Editor/Commands/EntityCommands/EntityCommands.md new file mode 100644 index 00000000..a248f8e3 --- /dev/null +++ b/docs/api/XCEngine/Editor/Commands/EntityCommands/EntityCommands.md @@ -0,0 +1,54 @@ +# EntityCommands + +**命名空间**: `XCEngine::Editor::Commands` + +**类型**: `header-helper` + +**源文件**: `editor/src/Commands/EntityCommands.h` + +**描述**: 封装实体创建、重命名、删除、复制粘贴、重复和父子重挂接等场景编辑命令。 + +## 概述 + +`EntityCommands` 是当前 Scene 编辑工作流里最重要的一层命令辅助。 +Hierarchy 面板、Edit 菜单和快捷键触发的实体级操作，最终大多落到这里。 + +当前覆盖： + +- 创建空实体、Camera、Light +- 重命名与删除实体 +- 复制、粘贴、重复实体 +- 重挂接父节点并尽量保持世界变换 +- 从父节点分离实体 + +## 当前实现 + +- 结构性修改统一通过 [`UndoUtils::ExecuteSceneCommand`](../../Utils/UndoUtils/UndoUtils.md) 包装 +- 创建实体后会自动把新实体设置为当前选中对象 +- `CreateCameraEntity` 与 `CreateLightEntity` 会附加对应组件 +- `CanReparentEntity` 会阻止把对象挂到自己的子孙节点下 +- `ReparentEntityPreserveWorldTransform` 会缓存当前位置、旋转和缩放，再执行 `MoveEntity` + +## 设计说明 + +把实体编辑动作做成独立命令层，是编辑器架构里非常关键的一步。 +如果直接在 Hierarchy 面板里 `CreateEntity`、`DeleteEntity`、`MoveEntity`，会很快遇到三个问题： + +- 撤销历史无法统一 +- 菜单栏、快捷键、右键菜单会重复同一逻辑 +- 结构修改和 UI 交互代码缠在一起 + +`EntityCommands` 把“编辑行为语义”稳定下来，面板和 router 只需要负责调用它。 + +## 当前限制 + +- `CreateCubeEntity` / `CreateSphereEntity` / `CreatePlaneEntity` 在当前路由中实际上还是创建命名后的空实体，不会自动生成渲染组件 +- 粘贴和重复的深拷贝语义完全依赖 `ISceneManager` 当前实现 +- 多实体批量命令尚未覆盖 + +## 相关文档 + +- [Commands](../Commands.md) +- [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) +- [UndoUtils](../../Utils/UndoUtils/UndoUtils.md) diff --git a/docs/api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md b/docs/api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md new file mode 100644 index 00000000..3483d2ea --- /dev/null +++ b/docs/api/XCEngine/Editor/Commands/ProjectCommands/ProjectCommands.md @@ -0,0 +1,49 @@ +# ProjectCommands + +**命名空间**: `XCEngine::Editor::Commands` + +**类型**: `header-helper` + +**源文件**: `editor/src/Commands/ProjectCommands.h` + +**描述**: 封装 Project 面板中与资源打开、目录创建、删除和移动相关的高层操作。 + +## 概述 + +`ProjectCommands` 当前是一个很轻量的命令头，但它已经把 Project 面板最基础的资源管理语义集中起来： + +- `CanOpenAsset` +- `OpenAsset` +- `CreateFolder` +- `DeleteAsset` +- `MoveAssetToFolder` + +这让资源浏览面板不必直接操作底层 manager 细节。 + +## 当前实现 + +- 资源能否打开，当前只看两种情况：目录，或 `item->type == "Scene"` +- 打开目录时调用 `IProjectManager::NavigateToFolder` +- 打开场景资源时转发到 [`LoadScene`](../SceneCommands/SceneCommands.md) +- 创建目录和删除资源只做最小参数校验，然后委托给 `IProjectManager` +- 资源拖入目录时会比较源路径与目标路径，避免把资源移动到自己身上 + +## 设计说明 + +现在这层看起来很薄，但它依然有存在价值。 +原因在于 Project 面板的 UI 以后很可能持续变化，而“什么资源能打开、什么动作合法、如何调用 manager”这些规则应该集中在一个稳定位置。 + +这也是商业编辑器常见的演进路径：先用轻量命令层收口，等资源类型和导入系统成熟后，再逐渐扩展成完整 asset workflow。 + +## 当前限制 + +- 只能打开文件夹和场景资源 +- 没有资源重命名、复制粘贴、导入和重新导入 +- 删除和移动操作没有事务、确认框或冲突解决策略 + +## 相关文档 + +- [Commands](../Commands.md) +- [ProjectActionRouter](../../Actions/ProjectActionRouter/ProjectActionRouter.md) +- [ProjectManager](../../Managers/ProjectManager/ProjectManager.md) +- [SceneCommands](../SceneCommands/SceneCommands.md) diff --git a/docs/api/XCEngine/Editor/Commands/SceneCommands/SceneCommands.md b/docs/api/XCEngine/Editor/Commands/SceneCommands/SceneCommands.md new file mode 100644 index 00000000..cfa224b5 --- /dev/null +++ b/docs/api/XCEngine/Editor/Commands/SceneCommands/SceneCommands.md @@ -0,0 +1,49 @@ +# SceneCommands + +**命名空间**: `XCEngine::Editor::Commands` + +**类型**: `header utility set` + +**源文件**: `editor/src/Commands/SceneCommands.h` + +**描述**: 提供场景新建、加载、保存、启动场景加载和脏场景保存回退等高层编辑命令。 + +## 概述 + +`SceneCommands.h` 当前是一组 inline 命令函数，不是 class。 + +当前包含的核心命令包括： + +- `ResetSceneEditingState()` +- `NewScene()` +- `LoadScene()` +- `OpenSceneWithDialog()` +- `SaveCurrentScene()` +- `SaveSceneAsWithDialog()` +- `LoadStartupScene()` +- `SaveDirtySceneWithFallback()` + +## 当前实现说明 + +- 这些命令统一依赖 [IEditorContext](../../Core/IEditorContext/IEditorContext.md)。 +- 新建/切换场景前会通过 `SceneEditorUtils::ConfirmSceneSwitch()` 进行确认。 +- 成功切换场景后会清空选择并清理 undo 历史。 +- `SaveSceneAsWithDialog()` 成功后会刷新项目面板当前目录。 +- `SaveDirtySceneWithFallback()` 在当前场景脏且普通保存失败时，会尝试保存到给定回退路径。 + +## 设计说明 + +这类命令层让： + +- 菜单栏 +- 快捷键 +- 工具栏 +- 关闭工作区流程 + +都能复用同一套场景操作语义。 + +## 相关文档 + +- [Commands](../Commands.md) +- [IEditorContext](../../Core/IEditorContext/IEditorContext.md) +- [EditorWorkspace](../../Core/EditorWorkspace/EditorWorkspace.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/CameraComponentEditor/CameraComponentEditor.md b/docs/api/XCEngine/Editor/ComponentEditors/CameraComponentEditor/CameraComponentEditor.md new file mode 100644 index 00000000..2d6fe6e2 --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/CameraComponentEditor/CameraComponentEditor.md @@ -0,0 +1,52 @@ +# CameraComponentEditor + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/ComponentEditors/CameraComponentEditor.h` + +**描述**: `CameraComponent` 的专用 Inspector 编辑器，负责投影模式、裁剪面、主摄像机和清屏色等属性编辑。 + +## 概述 + +`CameraComponentEditor` 把运行时摄像机组件转换成 Inspector 中可直接编辑的字段组。 +当前覆盖的字段包括： + +- 投影类型 `Perspective / Orthographic` +- 透视视野或正交尺寸 +- Near / Far Clip +- Depth +- Primary +- Clear Color + +## 当前实现 + +- 仅接受 `CameraComponent` +- 投影模式切换通过 `DrawPropertyCombo` 实现 +- 透视模式下显示 `Field Of View` +- 正交模式下显示 `Orthographic Size` +- `CanAddTo` 要求目标实体当前没有 `CameraComponent` +- `CanRemove` 允许删除已经能被本编辑器识别的 Camera 组件 + +## 设计说明 + +把摄像机编辑做成独立 editor，而不是塞进通用属性反射层，有两个现实收益： + +- UI 可以按照摄像机语义分支展示，而不是无差别列字段 +- Inspector 可以明确控制哪些组合合法，比如只在正交模式下显示正交尺寸 + +这和 Unity 的 Camera Inspector 思路类似：不是简单罗列成员变量，而是按摄影机工作方式组织编辑体验。 + +## 当前限制 + +- 没有视口预览、Frustum 可视化或 Gizmo 联动 +- 没有后处理、渲染层、输出目标等更高阶配置 +- `Far Clip` 的最小值只基于 `nearClip + 0.001f` 做轻量约束 + +## 相关文档 + +- [ComponentEditors](../ComponentEditors.md) +- [IComponentEditor](../IComponentEditor/IComponentEditor.md) +- [ComponentCommands](../../Commands/ComponentCommands/ComponentCommands.md) +- [PropertyGrid](../../UI/PropertyGrid/PropertyGrid.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md b/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md new file mode 100644 index 00000000..ec6ffa3e --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md @@ -0,0 +1,41 @@ +# ComponentEditorRegistry + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (singleton)` + +**源文件**: `editor/src/ComponentEditors/ComponentEditorRegistry.h` + +**描述**: 持有并注册所有组件编辑器实例，按组件类型名为 Inspector 提供查询入口。 + +## 概述 + +`ComponentEditorRegistry` 是当前组件编辑器系统的注册中心。 + +它负责： + +- 注册 `IComponentEditor` +- 根据组件实例查找对应 editor +- 根据组件类型名查找 editor +- 暴露全部 editor 列表 + +## 当前实现说明 + +- 采用单例 `Get()`。 +- 构造函数里会自动注册： + - `TransformComponentEditor` + - `CameraComponentEditor` + - `LightComponentEditor` +- `m_editors` 负责拥有这些 editor 对象。 +- `m_editorsByType` 提供按组件类型名的快速查找。 + +## 当前实现边界 + +- 当前注册列表写死在构造函数中，不是插件式发现机制。 +- 如果后注册 editor 与已有类型名重复，`m_editorsByType` 会被覆盖，但 `m_editors` 里仍会保留多个对象。 + +## 相关文档 + +- [ComponentEditors](../ComponentEditors.md) +- [IComponentEditor](../IComponentEditor/IComponentEditor.md) +- [InspectorPanel](../../panels/InspectorPanel/InspectorPanel.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md b/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md new file mode 100644 index 00000000..234c9979 --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/ComponentEditors.md @@ -0,0 +1,33 @@ +# ComponentEditors + +**命名空间**: `XCEngine::Editor` + +**类型**: `submodule` + +**描述**: 组件属性编辑器层，负责把运行时组件映射到 Inspector 中的具体编辑 UI。 + +## 概述 + +当前目录包含： + +- [IComponentEditor](IComponentEditor/IComponentEditor.md) +- [ComponentEditorRegistry](ComponentEditorRegistry/ComponentEditorRegistry.md) +- [TransformComponentEditor](TransformComponentEditor/TransformComponentEditor.md) +- [CameraComponentEditor](CameraComponentEditor/CameraComponentEditor.md) +- [LightComponentEditor](LightComponentEditor/LightComponentEditor.md) + +这说明 Inspector 当前走的是“按组件类型注册专用 editor”的路线。这和商业编辑器里常见的 custom inspector / property drawer 思路是一致的。 + +当前这组 editor 也已经体现出比较明确的分层： + +- `IComponentEditor` 定义统一契约 +- `ComponentEditorRegistry` 负责注册和查找 +- 具体 editor 只处理本组件的 Inspector 体验 + +这比把所有组件字段硬塞进一个大而全的 Inspector 渲染器更容易扩展。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [panels](../panels/panels.md) +- [Components](../../Components/Components.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/IComponentEditor/IComponentEditor.md b/docs/api/XCEngine/Editor/ComponentEditors/IComponentEditor/IComponentEditor.md new file mode 100644 index 00000000..b36cfb35 --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/IComponentEditor/IComponentEditor.md @@ -0,0 +1,40 @@ +# IComponentEditor + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (abstract)` + +**源文件**: `editor/src/ComponentEditors/IComponentEditor.h` + +**描述**: 定义 Inspector 中单个组件编辑器的统一接口，包括显示名、可编辑性、渲染逻辑以及组件添加/移除相关能力。 + +## 概述 + +`IComponentEditor` 是当前 Inspector 扩展点的核心接口。 + +它把每个组件在编辑器中的专用处理统一抽象成几类能力： + +- 识别自己负责的组件类型 +- 渲染该组件的编辑 UI +- 决定是否显示在 Add Component 菜单里 +- 决定是否可被添加到某个 `GameObject` +- 决定组件是否可移除 + +## 当前实现说明 + +- 默认 `CanEdit()` 按 `component->GetName() == GetComponentTypeName()` 判断。 +- 默认 `AddTo()` 会通过 `ComponentFactoryRegistry` 按组件名创建组件。 +- 默认 `CanAddTo()` 和 `CanRemove()` 都返回 `false`，因此派生类需要显式放开能力。 + +## 设计说明 + +这条路线和很多商业编辑器里的 custom inspector 模型很像： + +- 运行时组件保持干净 +- 编辑器层通过专用 editor 决定如何显示和编辑它 + +## 相关文档 + +- [ComponentEditors](../ComponentEditors.md) +- [ComponentEditorRegistry](../ComponentEditorRegistry/ComponentEditorRegistry.md) +- [InspectorPanel](../../panels/InspectorPanel/InspectorPanel.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/LightComponentEditor/LightComponentEditor.md b/docs/api/XCEngine/Editor/ComponentEditors/LightComponentEditor/LightComponentEditor.md new file mode 100644 index 00000000..39f98e2d --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/LightComponentEditor/LightComponentEditor.md @@ -0,0 +1,46 @@ +# LightComponentEditor + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/ComponentEditors/LightComponentEditor.h` + +**描述**: `LightComponent` 的专用 Inspector 编辑器，负责灯光类型、颜色、强度、范围和阴影开关等属性编辑。 + +## 概述 + +`LightComponentEditor` 当前覆盖的是最基本的光源参数编辑： + +- 灯光类型 `Directional / Point / Spot` +- 颜色 +- 强度 +- 范围 +- 聚光角度 +- 是否投射阴影 + +## 当前实现 + +- 仅接受 `LightComponent` +- 方向光不会显示 `Range` +- 只有聚光灯会显示 `Spot Angle` +- `CanAddTo` 要求目标实体当前没有 `LightComponent` +- `CanRemove` 允许删除已存在的 Light 组件 + +## 设计说明 + +灯光编辑和摄像机编辑类似，天然需要条件式 UI。 +如果走完全通用的字段表单，很容易把不适用于当前灯光类型的选项也暴露出来，给用户造成误导。当前这种专用 editor 设计更贴近商业编辑器常见的“按组件语义组织 Inspector”。 + +## 当前限制 + +- 没有阴影贴图、衰减曲线、颜色温度等更高级设置 +- 没有场景视图里的灯光 Gizmo 或范围预览 +- 多光源批量编辑尚未覆盖 + +## 相关文档 + +- [ComponentEditors](../ComponentEditors.md) +- [IComponentEditor](../IComponentEditor/IComponentEditor.md) +- [ComponentCommands](../../Commands/ComponentCommands/ComponentCommands.md) +- [PropertyGrid](../../UI/PropertyGrid/PropertyGrid.md) diff --git a/docs/api/XCEngine/Editor/ComponentEditors/TransformComponentEditor/TransformComponentEditor.md b/docs/api/XCEngine/Editor/ComponentEditors/TransformComponentEditor/TransformComponentEditor.md new file mode 100644 index 00000000..e905e68f --- /dev/null +++ b/docs/api/XCEngine/Editor/ComponentEditors/TransformComponentEditor/TransformComponentEditor.md @@ -0,0 +1,54 @@ +# TransformComponentEditor + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/ComponentEditors/TransformComponentEditor.h` + +**描述**: `TransformComponent` 的专用 Inspector 编辑器，负责位置、旋转和缩放字段的交互式编辑。 + +## 概述 + +`TransformComponentEditor` 是当前 Inspector 中最基础的组件编辑器之一。 +它实现了 [`IComponentEditor`](../IComponentEditor/IComponentEditor.md)，并专门处理： + +- 本地位置 `LocalPosition` +- 本地欧拉角 / 四元数旋转 +- 本地缩放 `LocalScale` + +这类编辑器的职责不是管理场景结构，而是把组件字段以可交互、可撤销的方式暴露给用户。 + +## 当前实现 + +- 仅接受 `TransformComponent`，内部通过 `dynamic_cast` 验证类型 +- 属性绘制基于 [`PropertyGrid`](../../UI/PropertyGrid/PropertyGrid.md) 和 [`VectorControls`](../../UI/VectorControls/VectorControls.md) +- 每次字段修改都会通过 `UI::ApplyPropertyChange` 触发交互式撤销录制 +- `Transform` 被视为内建组件： + - `CanAddTo` 永远返回 `false` + - `GetAddDisabledReason` 返回 `"Built-in"` + - `CanRemove` 永远返回 `false` + +## 旋转编辑策略 + +旋转编辑是这页里最值得注意的设计点。 +当前实现没有直接把四元数原样暴露给用户，而是： + +- 用 `RotationEditState` 缓存展示中的欧拉角 +- 当检测到外部旋转变化时，同步刷新缓存 +- 只有在当前控件不处于编辑状态时，才用最新四元数回写展示值 + +这比直接每帧做欧拉角往返转换更稳定，能减少拖拽过程中数值跳变。商业编辑器通常也会做类似的“显示态缓存”。 + +## 当前限制 + +- 状态缓存以 `TransformComponent*` 为键，当前实现里没有显式清理失效键 +- 只覆盖本地变换，不提供世界坐标 / 局部坐标切换 +- 没有多对象联动编辑 + +## 相关文档 + +- [ComponentEditors](../ComponentEditors.md) +- [IComponentEditor](../IComponentEditor/IComponentEditor.md) +- [InspectorPanel](../../panels/InspectorPanel/InspectorPanel.md) +- [PropertyGrid](../../UI/PropertyGrid/PropertyGrid.md) diff --git a/docs/api/XCEngine/Editor/Core/AssetItem/AssetItem.md b/docs/api/XCEngine/Editor/Core/AssetItem/AssetItem.md new file mode 100644 index 00000000..010cc5ad --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/AssetItem/AssetItem.md @@ -0,0 +1,35 @@ +# AssetItem + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct + alias` + +**源文件**: `editor/src/Core/AssetItem.h` + +**描述**: 表示 Project 面板中的一个资产或文件夹节点，并定义共享指针别名 `AssetItemPtr`。 + +## 概述 + +`AssetItem` 当前是项目浏览器里最基础的树节点结构。 + +字段包括： + +- `name` +- `type` +- `isFolder` +- `fullPath` +- `children` + +同时还定义了： + +- `using AssetItemPtr = std::shared_ptr` + +## 设计说明 + +当前项目浏览器把目录树直接建成共享指针树，优点是结构简单、递归扫描方便；缺点是没有额外的懒加载或虚拟化机制。 + +## 相关文档 + +- [Core](../Core.md) +- [IProjectManager](../IProjectManager/IProjectManager.md) +- [ProjectManager](../../Managers/ProjectManager/ProjectManager.md) diff --git a/docs/api/XCEngine/Editor/Core/Core.md b/docs/api/XCEngine/Editor/Core/Core.md new file mode 100644 index 00000000..1a3f7c4f --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/Core.md @@ -0,0 +1,53 @@ +# Core + +**命名空间**: `XCEngine::Editor` + +**类型**: `submodule` + +**描述**: 编辑器核心上下文与服务层，包含事件总线、上下文接口、场景快照、撤销与选择系统的基础抽象。 + +## 概述 + +`Editor/Core` 是编辑器应用的状态中枢。这里的类型决定了各个面板、命令和管理器如何共享状态。 + +当前最关键的核心对象包括： + +- [IEditorContext](IEditorContext/IEditorContext.md) +- [EditorContext](EditorContext/EditorContext.md) +- [EventBus](EventBus/EventBus.md) +- [EditorEvents](EditorEvents/EditorEvents.md) +- [EditorActionRoute](EditorActionRoute/EditorActionRoute.md) +- [EditorConsoleSink](EditorConsoleSink/EditorConsoleSink.md) +- [EditorLoggingSetup](EditorLoggingSetup/EditorLoggingSetup.md) +- [EditorWindowTitle](EditorWindowTitle/EditorWindowTitle.md) +- [EditorWorkspace](EditorWorkspace/EditorWorkspace.md) +- [IProjectManager](IProjectManager/IProjectManager.md) +- [ISceneManager](ISceneManager/ISceneManager.md) +- [ISelectionManager](ISelectionManager/ISelectionManager.md) +- [IUndoManager](IUndoManager/IUndoManager.md) +- [SceneSnapshot](SceneSnapshot/SceneSnapshot.md) +- [SelectionManager](SelectionManager/SelectionManager.md) +- [UndoManager](UndoManager/UndoManager.md) +- [AssetItem](AssetItem/AssetItem.md) + +## 设计说明 + +把 manager 接口、事件系统和上下文聚合都放在 `Core` 层，是很合理的工具架构做法： + +- 面板层不必直接 new 具体管理器。 +- 命令层可以只依赖 `IEditorContext`。 +- undo/selection/project/scene 这些服务可以被统一组织和替换。 + +当前还可以看到一个很清晰的工程化方向： + +- `EditorActionRoute` 负责动作路由语义 +- `SceneSnapshot + UndoManager` 负责状态回滚 +- `EditorConsoleSink + EditorLoggingSetup` 负责把引擎日志接入编辑器壳层 +- `EditorWindowTitle` 负责把底层状态翻译成可见的主窗口反馈 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [Managers](../Managers/Managers.md) +- [Commands](../Commands/Commands.md) +- [panels](../panels/panels.md) diff --git a/docs/api/XCEngine/Editor/Core/EditorActionRoute/EditorActionRoute.md b/docs/api/XCEngine/Editor/Core/EditorActionRoute/EditorActionRoute.md new file mode 100644 index 00000000..433a0422 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/EditorActionRoute/EditorActionRoute.md @@ -0,0 +1,39 @@ +# EditorActionRoute + +**命名空间**: `XCEngine::Editor` + +**类型**: `enum class` + +**源文件**: `editor/src/Core/EditorActionRoute.h` + +**描述**: 定义当前全局编辑动作应该作用到哪个面板上下文。 + +## 概述 + +`EditorActionRoute` 是 `ActionRouting` 和 `EditActionRouter` 之间的最小契约。 +当前枚举值只有三个： + +- `None` +- `Hierarchy` +- `Project` + +它本质上回答的是一个问题：当用户按下 `Delete`、`Ctrl+C` 或 `Ctrl+V` 时，编辑器到底应该操作实体树，还是资产浏览器，还是暂时不响应。 + +## 设计说明 + +把路由显式枚举出来，而不是靠每个面板自己判断快捷键，有几个直接收益： + +- 全局 Edit 菜单可以统一生成启用状态 +- 快捷键处理逻辑可以收口到 `EditActionRouter` +- 不同面板之间的编辑语义冲突会更容易排查 + +## 当前限制 + +- 当前只覆盖 `Hierarchy` 和 `Project` +- `Inspector`、`Console`、未来的材质编辑器或资源检查器都还没有自己的路由值 + +## 相关文档 + +- [Core](../Core.md) +- [ActionRouting](../../Actions/ActionRouting/ActionRouting.md) +- [EditActionRouter](../../Actions/EditActionRouter/EditActionRouter.md) diff --git a/docs/api/XCEngine/Editor/Core/EditorConsoleSink/EditorConsoleSink.md b/docs/api/XCEngine/Editor/Core/EditorConsoleSink/EditorConsoleSink.md new file mode 100644 index 00000000..7d73dd90 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/EditorConsoleSink/EditorConsoleSink.md @@ -0,0 +1,42 @@ +# EditorConsoleSink + +**命名空间**: `XCEngine::Debug` + +**类型**: `class` + +**源文件**: `editor/src/Core/EditorConsoleSink.h` + +**描述**: 编辑器专用日志 sink，把引擎日志桥接到 Console 面板可读取的内存缓冲区。 + +## 概述 + +`EditorConsoleSink` 虽然位于 `editor/src/Core`，但命名空间属于 `XCEngine::Debug`。 +它的定位很明确：作为 `Logger` 的一个输出目标，把日志保存在内存中，供 Console 面板显示。 + +## 当前实现 + +- 继承自 `ILogSink` +- 通过 `std::mutex` 保护 `m_logs` +- `Log()` 会把新日志追加到数组尾部 +- 最大缓存条数固定为 `1000` +- 超限时直接丢弃最早的一条日志 +- `GetLogs()` 返回日志数组的拷贝 +- `GetInstance()` 在没有显式注册实例时会返回一个静态 fallback 实例 + +## 设计说明 + +这是一个典型的“工具层 sink”。 +引擎日志系统不应该知道编辑器面板怎么画 UI，但编辑器又确实需要消费同一份日志流。把桥接能力做成一个 `ILogSink` 子类，是最干净的集成方式。 + +## 当前限制 + +- 当前只保留最近 1000 条日志 +- `GetLogs()` 会复制整个缓冲区 +- `SetCallback()` 没有更复杂的线程调度机制，回调触发策略非常轻量 + +## 相关文档 + +- [Core](../Core.md) +- [ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md) +- [ConsolePanel](../../panels/ConsolePanel/ConsolePanel.md) +- [Debug::Logger](../../../Debug/Logger/Logger.md) diff --git a/docs/api/XCEngine/Editor/Core/EditorContext/EditorContext.md b/docs/api/XCEngine/Editor/Core/EditorContext/EditorContext.md new file mode 100644 index 00000000..dcc2de10 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/EditorContext/EditorContext.md @@ -0,0 +1,43 @@ +# EditorContext + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Core/EditorContext.h` + +**描述**: 当前编辑器默认的上下文实现，负责创建并持有事件总线、选择管理、场景管理、撤销管理和项目管理对象。 + +## 概述 + +`EditorContext` 是 [IEditorContext](../IEditorContext/IEditorContext.md) 的默认实现。 + +它当前在构造时就把主要编辑器服务完整拼装出来： + +- `EventBus` +- `SelectionManager` +- `SceneManager` +- `UndoManager` +- `ProjectManager` + +并额外订阅 `EntityDeletedEvent`，在被删实体刚好是当前选中实体时清理选择状态。 + +## 当前实现说明 + +- 事件总线采用 `unique_ptr` 持有。 +- `UndoManager` 依赖 `SceneManager` 与 `SelectionManager`。 +- 通过 `EditorActionRoute` 记录当前激活的动作路由。 +- 同时保存项目路径字符串。 + +## 当前实现边界 + +- 当前所有服务都在构造时固定实例化，不是懒加载。 +- 当前不是插件化服务容器，没有注册/替换任意服务的通用机制。 +- 删除实体时自动清理选择这一逻辑是直接写在构造函数订阅里的。 + +## 相关文档 + +- [Core](../Core.md) +- [IEditorContext](../IEditorContext/IEditorContext.md) +- [EventBus](../EventBus/EventBus.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) diff --git a/docs/api/XCEngine/Editor/Core/EditorEvents/EditorEvents.md b/docs/api/XCEngine/Editor/Core/EditorEvents/EditorEvents.md new file mode 100644 index 00000000..5f43c2f8 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/EditorEvents/EditorEvents.md @@ -0,0 +1,44 @@ +# EditorEvents + +**命名空间**: `XCEngine::Editor` + +**类型**: `event set` + +**源文件**: `editor/src/Core/EditorEvents.h` + +**描述**: 定义编辑器内部事件类型，包括选择变化、实体生命周期、场景变化、播放模式变化、Dock 布局重置和退出请求等事件。 + +## 概述 + +`EditorEvents.h` 当前定义的是一组轻量事件结构体，而不是复杂基类层级。 + +这和当前 [EventBus](../EventBus/EventBus.md) 的模板化设计很匹配：只要是明确的结构体类型，就能被直接作为事件类型发布与订阅。 + +## 当前事件 + +| 事件 | 作用 | +|------|------| +| `SelectionChangedEvent` | 选择集合变化。 | +| `EntityCreatedEvent` | 新建实体。 | +| `EntityDeletedEvent` | 删除实体。 | +| `EntityChangedEvent` | 实体内容变化。 | +| `EntityRenameRequestedEvent` | 请求重命名实体。 | +| `EntityParentChangedEvent` | 实体父子关系变化。 | +| `SceneChangedEvent` | 当前场景发生变化。 | +| `PlayModeStartedEvent` / `Stopped` / `Paused` | 编辑器播放模式状态变化。 | +| `EditorModeChangedEvent` | 编辑器模式切换。 | +| `DockLayoutResetRequestedEvent` | 请求重置 dock 布局。 | +| `EditorExitRequestedEvent` | 请求关闭编辑器。 | + +## 特别说明 + +- `GameObjectID` 当前被定义为 `uint64_t` 别名。 +- `SelectionChangedEvent` 同时包含完整选择列表和主选择。 +- `EditorModeChangedEvent` 当前使用整数记录旧模式/新模式，而不是更强类型的枚举。 + +## 相关文档 + +- [Core](../Core.md) +- [EventBus](../EventBus/EventBus.md) +- [SelectionManager](../SelectionManager/SelectionManager.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) diff --git a/docs/api/XCEngine/Editor/Core/EditorLoggingSetup/EditorLoggingSetup.md b/docs/api/XCEngine/Editor/Core/EditorLoggingSetup/EditorLoggingSetup.md new file mode 100644 index 00000000..d745f2c6 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/EditorLoggingSetup/EditorLoggingSetup.md @@ -0,0 +1,50 @@ +# EditorLoggingSetup + +**命名空间**: `XCEngine::Editor` + +**类型**: `header-helper` + +**源文件**: `editor/src/Core/EditorLoggingSetup.h` + +**描述**: 配置编辑器启动时的日志输出目标，包括控制台、编辑器内存 sink 和磁盘日志文件。 + +## 概述 + +`ConfigureEditorLogging` 是应用启动流程里非常早期的一步。它会把编辑器需要的日志通道一次性接到全局 `Debug::Logger` 上。 + +当前会注册： + +- `Debug::ConsoleLogSink` +- `Debug::EditorConsoleSink` +- `Debug::FileLogSink` + +然后写入两条启动信息，说明编辑器已启动以及日志文件路径。 + +## 当前实现 + +- 日志文件路径固定为 `{executableDirectory}\\editor.log` +- 使用 `Logger::Get()` 直接操作全局单例 +- 没有去重逻辑，也没有“只初始化一次”的保护 + +## 设计说明 + +对编辑器来说，同时拥有三份日志出口是合理的： + +- 控制台便于开发调试 +- 内存 sink 便于 UI 面板即时查看 +- 文件 sink 便于排查启动期和崩溃前问题 + +这也是商业工具软件常见的组合，尤其是在图形程序里，单靠控制台通常不够。 + +## 当前限制 + +- 如果重复调用，sink 可能被重复注册 +- 日志文件路径策略目前不可配置 +- 没有按等级或模块分别路由到不同文件 + +## 相关文档 + +- [Core](../Core.md) +- [EditorConsoleSink](../EditorConsoleSink/EditorConsoleSink.md) +- [Application](../../Application/Application.md) +- [Logger](../../../Debug/Logger/Logger.md) diff --git a/docs/api/XCEngine/Editor/Core/EditorWindowTitle/EditorWindowTitle.md b/docs/api/XCEngine/Editor/Core/EditorWindowTitle/EditorWindowTitle.md new file mode 100644 index 00000000..202d4632 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/EditorWindowTitle/EditorWindowTitle.md @@ -0,0 +1,41 @@ +# EditorWindowTitle + +**命名空间**: `XCEngine::Editor` + +**类型**: `header-helper` + +**源文件**: `editor/src/Core/EditorWindowTitle.h` + +**描述**: 根据当前场景状态构造编辑器主窗口标题字符串。 + +## 概述 + +`BuildEditorWindowTitle` 会从 `IEditorContext` 中读取当前场景信息，并拼出类似下面的标题： + +- `No Scene - XCEngine Editor` +- `Untitled Scene * (Unsaved) - XCEngine Editor` +- `Main Scene - Main.xc - XCEngine Editor` + +这类函数虽然简单，但它把编辑器当前状态的用户反馈统一到了一个位置。 + +## 当前实现 + +- 没有活动场景时显示 `No Scene` +- 场景名为空时显示 `Untitled Scene` +- 场景 dirty 时追加 `*` +- 没有场景路径时追加 `(Unsaved)` +- 有路径时会额外拼接文件名 + +`Application.cpp` 会在每帧窗口标题刷新时把它转成宽字符，再交给 Win32 宿主窗口。 + +## 设计说明 + +商业编辑器通常都会把“场景是否已保存”“当前文件名是什么”直接反映在窗口标题上，因为这是最低成本但很有效的状态反馈。 +把标题拼接逻辑独立出来，也能避免窗口宿主层去关心场景管理细节。 + +## 相关文档 + +- [Core](../Core.md) +- [Application](../../Application/Application.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) +- [Win32Utf8](../../Platform/Win32Utf8/Win32Utf8.md) diff --git a/docs/api/XCEngine/Editor/Core/EditorWorkspace/EditorWorkspace.md b/docs/api/XCEngine/Editor/Core/EditorWorkspace/EditorWorkspace.md new file mode 100644 index 00000000..5fe88c53 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/EditorWorkspace/EditorWorkspace.md @@ -0,0 +1,45 @@ +# EditorWorkspace + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Core/EditorWorkspace.h` + +**描述**: 负责组织编辑器面板集合、Dock 布局控制器以及工作区级 attach/detach/update/render 生命周期。 + +## 概述 + +`EditorWorkspace` 是当前编辑器 UI 结构真正聚合起来的地方。 + +在 [Attach](../../Layers/EditorLayer/EditorLayer.md) 阶段，它会： + +- 清空并配置 `PanelCollection` +- 创建 `MenuBar` +- 创建 `HierarchyPanel` +- 创建 `SceneViewPanel` +- 创建 `GameViewPanel` +- 创建 `InspectorPanel` +- 创建 `ConsolePanel` +- 创建 `ProjectPanel` +- 创建 `DockLayoutController` +- 初始化项目面板并尝试加载启动场景 + +## 当前实现说明 + +- `Attach(IEditorContext&)` 是工作区初始化入口。 +- `Detach(IEditorContext&)` 会在拆除 UI 前调用 `SaveDirtySceneWithFallback()` 保存脏场景。 +- `Update(float)`、`DispatchEvent(void*)` 和 `Render()` 都只是把行为转发给面板集合与 dock 控制器。 + +## 当前实现边界 + +- 默认工作区结构目前是硬编码的。 +- `BuildFallbackScenePath()` 当前固定回退到 `/Assets/Scenes/Main.xc`。 +- 当前没有多工作区方案，也没有动态工作区配置对象。 + +## 相关文档 + +- [Core](../Core.md) +- [EditorLayer](../../Layers/EditorLayer/EditorLayer.md) +- [PanelCollection](../../panels/PanelCollection/PanelCollection.md) +- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) diff --git a/docs/api/XCEngine/Editor/Core/EventBus/EventBus.md b/docs/api/XCEngine/Editor/Core/EventBus/EventBus.md new file mode 100644 index 00000000..38a26eca --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/EventBus/EventBus.md @@ -0,0 +1,43 @@ +# EventBus + +**命名空间**: `XCEngine::Editor` + +**类型**: `class template host` + +**源文件**: `editor/src/Core/EventBus.h` + +**描述**: 提供编辑器内部的轻量级泛型事件总线，支持按事件类型订阅、取消订阅、发布和清空。 + +## 概述 + +`EventBus` 是当前编辑器内部通信的基础设施。 + +它的核心机制是： + +- 每个事件类型通过 `EventTypeId` 获得一个静态类型 ID。 +- `Subscribe()` 返回 handler ID。 +- `Publish()` 根据类型 ID 找到对应处理器并逐个调用。 + +同时这个头里还定义了： + +- `EventTypeRegistry` +- `EventTypeId` + +## 当前实现说明 + +- 订阅表使用 `std::unordered_map>`。 +- `Subscribe` / `Unsubscribe` 使用 `std::lock_guard`。 +- `Publish` 使用 `std::shared_lock`。 +- `Clear()` 会清空全部 handler。 + +## 当前实现风险与边界 + +- `Publish()` 在持有共享锁时直接执行 handler。 +- 如果某个 handler 在回调内部再次对同一个 `EventBus` 做需要独占锁的订阅/取消订阅操作，重入语义需要格外小心。 +- 当前没有事件排队、延迟分发或线程切换机制。 + +## 相关文档 + +- [Core](../Core.md) +- [EditorEvents](../EditorEvents/EditorEvents.md) +- [EditorContext](../EditorContext/EditorContext.md) diff --git a/docs/api/XCEngine/Editor/Core/IEditorContext/IEditorContext.md b/docs/api/XCEngine/Editor/Core/IEditorContext/IEditorContext.md new file mode 100644 index 00000000..d4e54de9 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/IEditorContext/IEditorContext.md @@ -0,0 +1,45 @@ +# IEditorContext + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (abstract)` + +**源文件**: `editor/src/Core/IEditorContext.h` + +**描述**: 定义编辑器服务定位接口，为面板、命令和 layer 提供统一的项目、场景、选择、撤销和事件访问入口。 + +## 概述 + +`IEditorContext` 是当前编辑器架构里最关键的接口之一。 + +它把编辑器里最常被共享的服务统一收口到一个对象上： + +- `EventBus` +- `ISelectionManager` +- `ISceneManager` +- `IProjectManager` +- `IUndoManager` +- 当前激活的动作路由 +- 当前项目路径 + +## 核心接口 + +| 方法 | 作用 | +|------|------| +| `GetEventBus()` | 获取事件总线。 | +| `GetSelectionManager()` | 获取选择管理服务。 | +| `GetSceneManager()` | 获取场景管理服务。 | +| `GetProjectManager()` | 获取项目管理服务。 | +| `GetUndoManager()` | 获取撤销管理服务。 | +| `SetActiveActionRoute()` / `GetActiveActionRoute()` | 管理当前动作路由。 | +| `SetProjectPath()` / `GetProjectPath()` | 管理当前项目根路径。 | + +## 设计说明 + +这类 context 接口和商业编辑器工具链里常见的 service hub / editor context 是一致的。 + +## 相关文档 + +- [Core](../Core.md) +- [EditorContext](../EditorContext/EditorContext.md) +- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) diff --git a/docs/api/XCEngine/Editor/Core/IProjectManager/IProjectManager.md b/docs/api/XCEngine/Editor/Core/IProjectManager/IProjectManager.md new file mode 100644 index 00000000..6ae7aa50 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/IProjectManager/IProjectManager.md @@ -0,0 +1,41 @@ +# IProjectManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (abstract)` + +**源文件**: `editor/src/Core/IProjectManager.h` + +**描述**: 定义项目浏览器接口，负责当前资产列表、路径导航、文件夹刷新以及基础资源文件操作。 + +## 概述 + +`IProjectManager` 面向的是编辑器 Project 面板这一类工作流。 + +它的接口组合非常清晰： + +- 当前目录的资产项列表 +- 当前选中项索引 +- 路径导航 +- 项目根路径 +- 文件夹刷新/创建/删除/移动 + +## 核心接口 + +| 方法 | 作用 | +|------|------| +| `GetCurrentItems()` | 获取当前目录条目。 | +| `GetSelectedIndex()` / `SetSelectedIndex()` | 管理当前选中项索引。 | +| `NavigateToFolder()` / `NavigateBack()` / `NavigateToIndex()` | 处理路径导航。 | +| `CanNavigateBack()` | 判断能否返回上一级。 | +| `GetCurrentPath()` / `GetPathDepth()` / `GetPathName()` | 查询当前路径面包屑。 | +| `Initialize()` | 初始化项目目录。 | +| `RefreshCurrentFolder()` | 刷新当前目录内容。 | +| `CreateFolder()` / `DeleteItem()` / `MoveItem()` | 执行基础文件操作。 | +| `GetProjectPath()` | 获取项目根目录。 | + +## 相关文档 + +- [Core](../Core.md) +- [AssetItem](../AssetItem/AssetItem.md) +- [ProjectManager](../../Managers/ProjectManager/ProjectManager.md) diff --git a/docs/api/XCEngine/Editor/Core/ISceneManager/ISceneManager.md b/docs/api/XCEngine/Editor/Core/ISceneManager/ISceneManager.md new file mode 100644 index 00000000..390059da --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/ISceneManager/ISceneManager.md @@ -0,0 +1,38 @@ +# ISceneManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (abstract)` + +**源文件**: `editor/src/Core/ISceneManager.h` + +**描述**: 定义编辑器场景服务接口，覆盖实体创建/删除/重命名、复制粘贴、层级移动、场景加载保存和脏状态管理。 + +## 概述 + +`ISceneManager` 当前承担的是编辑器场景服务的统一接口层。 + +它同时覆盖了三类职责： + +- 实体层级操作 +- 场景文件生命周期 +- 剪贴板与脏状态管理 + +## 核心接口 + +| 方法 | 作用 | +|------|------| +| `CreateEntity()` / `DeleteEntity()` / `RenameEntity()` | 实体生命周期管理。 | +| `GetEntity()` / `GetRootEntities()` | 查询当前实体树。 | +| `CopyEntity()` / `PasteEntity()` / `DuplicateEntity()` / `MoveEntity()` | 编辑器层级编辑操作。 | +| `HasClipboardData()` | 查询是否有可粘贴内容。 | +| `NewScene()` / `LoadScene()` / `SaveScene()` / `SaveSceneAs()` / `LoadStartupScene()` | 场景文件生命周期。 | +| `HasActiveScene()` / `IsSceneDirty()` / `MarkSceneDirty()` | 当前场景状态。 | +| `GetCurrentScenePath()` / `GetCurrentSceneName()` | 当前场景元信息。 | +| `CreateDemoScene()` | 创建内置示例场景。 | + +## 相关文档 + +- [Core](../Core.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) +- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) diff --git a/docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md b/docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md new file mode 100644 index 00000000..0fabfa7e --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md @@ -0,0 +1,36 @@ +# ISelectionManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (abstract)` + +**源文件**: `editor/src/Core/ISelectionManager.h` + +**描述**: 定义编辑器选择集合接口，以实体 ID 为中心管理当前选中对象列表。 + +## 概述 + +`ISelectionManager` 当前使用的是“按实体 ID 管理选择”的模型，而不是直接保存 `GameObject*`。 + +这样做的好处是： + +- 选择状态更适合跨场景快照与撤销系统保存。 +- 不直接依赖对象指针生命周期。 + +## 核心接口 + +| 方法 | 作用 | +|------|------| +| `SetSelectedEntity()` | 设置单选对象。 | +| `SetSelectedEntities()` | 设置多选集合。 | +| `AddToSelection()` / `RemoveFromSelection()` | 增删选择。 | +| `ClearSelection()` | 清空选择。 | +| `GetSelectedEntity()` / `GetSelectedEntities()` | 查询当前选择。 | +| `HasSelection()` / `GetSelectionCount()` | 查询选择状态。 | +| `IsSelected()` | 判断某实体是否已选中。 | + +## 相关文档 + +- [Core](../Core.md) +- [SelectionManager](../SelectionManager/SelectionManager.md) +- [UndoManager](../UndoManager/UndoManager.md) diff --git a/docs/api/XCEngine/Editor/Core/IUndoManager/IUndoManager.md b/docs/api/XCEngine/Editor/Core/IUndoManager/IUndoManager.md new file mode 100644 index 00000000..6813787a --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/IUndoManager/IUndoManager.md @@ -0,0 +1,50 @@ +# IUndoManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (abstract) + struct` + +**源文件**: `editor/src/Core/IUndoManager.h` + +**描述**: 定义撤销/重做接口与快照结构，支持命令历史和交互式修改收束。 + +## 概述 + +`IUndoManager` 当前不是传统 command object 继承体系，而是以“前后状态快照”作为撤销数据核心。 + +这里同时定义了： + +- `UndoStateSnapshot` +- `IUndoManager` + +其中 `UndoStateSnapshot` 当前包含： + +- `SceneSnapshot scene` +- `std::vector selectionIds` + +## 核心接口 + +| 方法 | 作用 | +|------|------| +| `ClearHistory()` | 清空撤销历史。 | +| `CanUndo()` / `CanRedo()` | 查询撤销重做能力。 | +| `GetUndoLabel()` / `GetRedoLabel()` | 查询当前可见动作标签。 | +| `Undo()` / `Redo()` | 执行撤销或重做。 | +| `CaptureCurrentState()` | 抓取当前编辑状态快照。 | +| `PushCommand()` | 推入一条历史记录。 | +| `BeginInteractiveChange()` / `FinalizeInteractiveChange()` / `CancelInteractiveChange()` | 支持拖拽等交互式修改的合并记录。 | +| `HasPendingInteractiveChange()` | 判断是否有未收束的交互更改。 | + +## 设计说明 + +对当前编辑器规模来说，快照式 undo 是非常务实的选择： + +- 实现简单。 +- 容易和场景序列化结合。 +- 不必为每个编辑动作都设计一套命令对象。 + +## 相关文档 + +- [Core](../Core.md) +- [UndoManager](../UndoManager/UndoManager.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) diff --git a/docs/api/XCEngine/Editor/Core/SceneSnapshot/SceneSnapshot.md b/docs/api/XCEngine/Editor/Core/SceneSnapshot/SceneSnapshot.md new file mode 100644 index 00000000..e22df216 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/SceneSnapshot/SceneSnapshot.md @@ -0,0 +1,43 @@ +# SceneSnapshot + +**命名空间**: `XCEngine::Editor` + +**类型**: `struct` + +**源文件**: `editor/src/Core/SceneSnapshot.h` + +**描述**: 表示一个可用于撤销/重做恢复的场景状态快照。 + +## 概述 + +`SceneSnapshot` 是编辑器撤销系统使用的基础数据结构。当前字段很少，但角色明确： + +- `hasScene` 表示当前是否存在有效场景 +- `sceneData` 保存序列化后的场景内容 +- `scenePath` 保存场景文件路径 +- `dirty` 保存场景脏标记 + +它通常不会单独暴露给 UI 层，而是作为 [`UndoStateSnapshot`](../IUndoManager/IUndoManager.md) 的一部分被 `UndoManager` 和 `SceneManager` 消费。 + +## 当前实现 + +- [`SceneManager`](../../Managers/SceneManager/SceneManager.md) 负责捕获和恢复 `SceneSnapshot` +- [`UndoManager`](../UndoManager/UndoManager.md) 会把它和选择状态一起组成一条撤销记录 +- 状态相等判断会比较 `hasScene`、`scenePath`、`sceneData`、`dirty` + +## 设计说明 + +当前实现选择了“序列化场景快照 + 选择集”的方式，而不是更复杂的命令对象增量回放。 +这种设计对中小规模编辑器很实用： + +- 撤销逻辑简单直接 +- 组件字段、实体层级和场景文件状态都能统一恢复 +- 对 Action / Command 层没有额外入侵 + +代价是快照体积和序列化成本会随着场景规模增加而增长。 + +## 相关文档 + +- [Core](../Core.md) +- [UndoManager](../UndoManager/UndoManager.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) diff --git a/docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md b/docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md new file mode 100644 index 00000000..4e32ddb5 --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md @@ -0,0 +1,36 @@ +# SelectionManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Core/SelectionManager.h` + +**描述**: `ISelectionManager` 的默认实现，维护当前选中实体 ID 列表并通过 `EventBus` 发布 `SelectionChangedEvent`。 + +## 概述 + +`SelectionManager` 当前非常直接： + +- 内部只保存一个 `std::vector`。 +- 所有选择变化都会调用 `PublishSelectionChanged()`。 +- 事件内容由 [SelectionChangedEvent](../EditorEvents/EditorEvents.md) 表示。 + +## 当前实现说明 + +- 单选通过 `SetSelectedEntity()` 实现，本质上会把选择列表压缩成一个元素。 +- `GetSelectedEntity()` 返回当前列表最后一个元素。 +- 空实体 ID `0` 不会被 `AddToSelection()` 添加。 + +## 当前实现边界 + +- 当前没有选择历史。 +- 当前没有“激活对象”和“多选主对象”以外的更多选择语义。 +- 当前选择变化完全是同步事件。 + +## 相关文档 + +- [Core](../Core.md) +- [ISelectionManager](../ISelectionManager/ISelectionManager.md) +- [EditorEvents](../EditorEvents/EditorEvents.md) +- [UndoManager](../UndoManager/UndoManager.md) diff --git a/docs/api/XCEngine/Editor/Core/UndoManager/UndoManager.md b/docs/api/XCEngine/Editor/Core/UndoManager/UndoManager.md new file mode 100644 index 00000000..a366d5cd --- /dev/null +++ b/docs/api/XCEngine/Editor/Core/UndoManager/UndoManager.md @@ -0,0 +1,39 @@ +# UndoManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Core/UndoManager.h` + +**描述**: 基于场景快照和选择快照实现编辑器撤销/重做历史，并支持交互式修改的合并提交。 + +## 概述 + +`UndoManager` 是当前 [IUndoManager](../IUndoManager/IUndoManager.md) 的默认实现。 + +它内部维护： + +- 有标签的命令历史 `m_history` +- 当前历史游标 `m_nextIndex` +- 一个可选的交互式修改暂存 `m_pendingInteractiveChange` + +## 当前实现说明 + +- 历史上限当前固定为 `128`。 +- `Undo()` 会先 finalize 未结束的交互修改，再回退到 `before` 快照。 +- `Redo()` 同理会应用 `after` 快照。 +- `CaptureCurrentState()` 会抓取当前场景快照，并仅保留仍然有效的选中实体 ID。 +- `PushCommand()` 会在状态没变化时直接丢弃该记录。 + +## 当前实现边界 + +- 这是快照式 undo，不是细粒度命令式 undo。 +- 历史存储大小和场景序列化数据量直接相关。 +- `ApplyState()` 当前依赖 [SceneManager](../../Managers/SceneManager/SceneManager.md) 恢复场景，然后再恢复选择。 + +## 相关文档 + +- [Core](../Core.md) +- [IUndoManager](../IUndoManager/IUndoManager.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) diff --git a/docs/api/XCEngine/Editor/Editor.md b/docs/api/XCEngine/Editor/Editor.md new file mode 100644 index 00000000..bbfcfedd --- /dev/null +++ b/docs/api/XCEngine/Editor/Editor.md @@ -0,0 +1,56 @@ +# Editor + +**命名空间**: `XCEngine::Editor` + +**类型**: `app-module` + +**描述**: 编辑器应用层 API 文档入口，镜像 `editor/src` 的目录结构，覆盖编辑器启动、上下文、面板工作区、项目浏览、场景编辑与 UI 基础设施。 + +## 概述 + +这一组文档对应的不是 `engine/include/XCEngine` 的 public engine headers，而是独立编辑器应用 `editor/src/**`。 + +因此这里需要先建立一个正确心智模型： + +- `XCEngine` 引擎模块负责运行时系统。 +- `Editor` 模块负责围绕这些运行时系统搭建编辑器应用。 +- 它更接近“应用层/工具层 API”，而不是给游戏代码直接依赖的稳定引擎 ABI。 + +当前编辑器的主链路大致是： + +1. [Application](Application/Application.md) 启动 Win32 窗口、D3D12 窗口渲染器和 ImGui 会话。 +2. [Core::EditorContext](Core/EditorContext/EditorContext.md) 组装事件总线、场景管理、项目管理、选择管理和撤销系统。 +3. [Layers::EditorLayer](Layers/EditorLayer/EditorLayer.md) 承载编辑器工作区生命周期。 +4. [Core::EditorWorkspace](Core/EditorWorkspace/EditorWorkspace.md) 组织菜单、层级、场景视图、GameView、Inspector、Console 和 Project 等面板。 + +## 当前实现边界 + +- 当前编辑器主要是 Windows + D3D12 + ImGui 路径。 +- 这组代码整体是应用层源码，不像 engine public headers 那样已经完全按稳定 SDK 方式整理。 +- 当前文档页会优先标注 `源文件`，而不是 `头文件`，以反映它们来自 `editor/src/**`。 +- 当前自动审计脚本仍以 `engine/include/XCEngine` 为主，因此 `Editor` 这组页主要靠链接完整性和人工结构约束维护。 + +## 目录 + +- [Application](Application/Application.md) - 顶层编辑器应用入口。 +- [Theme](Theme/Theme.md) - 顶层主题入口。 +- [Core](Core/Core.md) - 上下文、事件、撤销、选择与基础数据结构。 +- [Managers](Managers/Managers.md) - 项目与场景管理实现。 +- [panels](panels/panels.md) - 编辑器面板基础设施。 +- [Layers](Layers/Layers.md) - 编辑器 layer 封装。 +- [Platform](Platform/Platform.md) - Win32 窗口宿主与 D3D12 窗口渲染器。 +- [UI](UI/UI.md) - ImGui 会话与编辑器 UI 基础设施。 +- [Actions](Actions/Actions.md) - 菜单/按钮/快捷键动作绑定与路由层。 +- [Commands](Commands/Commands.md) - 面向场景与项目操作的高层命令封装。 +- [ComponentEditors](ComponentEditors/ComponentEditors.md) - 组件属性编辑器注册与实现层。 +- [Layout](Layout/Layout.md) - Dock 布局控制。 +- [Utils](Utils/Utils.md) - 场景编辑与撤销相关辅助函数。 + +## 相关文档 + +- [XCEngine 根目录](../XCEngine.md) +- [Scene](../Scene/Scene.md) +- [Components](../Components/Components.md) +- [Rendering](../Rendering/Rendering.md) +- [Editor Architecture And Workflow](../../_guides/Editor/Editor-Architecture-And-Workflow.md) +- [API 总索引](../../main.md) diff --git a/docs/api/XCEngine/Editor/Layers/EditorLayer/EditorLayer.md b/docs/api/XCEngine/Editor/Layers/EditorLayer/EditorLayer.md new file mode 100644 index 00000000..37a27e99 --- /dev/null +++ b/docs/api/XCEngine/Editor/Layers/EditorLayer/EditorLayer.md @@ -0,0 +1,40 @@ +# EditorLayer + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Layers/EditorLayer.h` + +**描述**: 编辑器 UI 的 Layer 封装，负责把 `EditorWorkspace` 接入 `Core::Layer` 生命周期。 + +## 概述 + +`EditorLayer` 当前是 `Core::Layer` 的一个专用适配层。 + +它把： + +- 一个共享的 `IEditorContext` +- 一个 [EditorWorkspace](../../Core/EditorWorkspace/EditorWorkspace.md) + +接到引擎的 layer 生命周期中。 + +## 当前实现说明 + +- 构造函数把 layer 名设为 `"Editor"`。 +- `SetContext()` 用于外部注入共享上下文。 +- `onAttach()` 若未提供上下文，会自行创建一个 `EditorContext`。 +- `onAttach()` / `onDetach()` / `onUpdate()` / `onEvent()` / `onImGuiRender()` 都只是把行为转发给 `EditorWorkspace`。 + +## 设计说明 + +这让： + +- `Application` 不必自己直接处理每个面板。 +- 编辑器 UI 能复用已有的 `LayerStack` 机制。 + +## 相关文档 + +- [Layers](../Layers.md) +- [Application](../../Application/Application.md) +- [EditorWorkspace](../../Core/EditorWorkspace/EditorWorkspace.md) diff --git a/docs/api/XCEngine/Editor/Layers/Layers.md b/docs/api/XCEngine/Editor/Layers/Layers.md new file mode 100644 index 00000000..81a2bf5e --- /dev/null +++ b/docs/api/XCEngine/Editor/Layers/Layers.md @@ -0,0 +1,21 @@ +# Layers + +**命名空间**: `XCEngine::Editor` + +**类型**: `submodule` + +**描述**: 编辑器的 Layer 封装层，当前核心是 `EditorLayer`，用于把编辑器工作区挂到引擎的 `LayerStack` 中。 + +## 概述 + +当前 `Layers` 子模块主要承担“把编辑器 UI 嵌入应用层 LayerStack”的职责。 + +已文档化的核心类型： + +- [EditorLayer](EditorLayer/EditorLayer.md) + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [Application](../Application/Application.md) +- [Core](../Core/Core.md) diff --git a/docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md b/docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md new file mode 100644 index 00000000..08e29c42 --- /dev/null +++ b/docs/api/XCEngine/Editor/Layout/DockLayoutController/DockLayoutController.md @@ -0,0 +1,48 @@ +# DockLayoutController + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Layout/DockLayoutController.h` + +**描述**: 控制编辑器主 Dockspace 的建立、默认布局构建以及布局重置请求的处理。 + +## 概述 + +`DockLayoutController` 负责当前编辑器主窗口里最上层的 Dock 布局控制。 + +它主要做三件事： + +- 订阅 `DockLayoutResetRequestedEvent` +- 在 ImGui 中创建主 Dockspace +- 在需要时重建默认布局 + +## 当前实现说明 + +- `Attach(IEditorContext&)` 会订阅布局重置事件。 +- `Detach()` 会取消订阅并把 `m_layoutDirty` 重新标记为 `true`。 +- `RenderDockspace()` 每帧都会绘制全窗口 dock host，并在 `m_layoutDirty` 为真时重建默认布局。 +- 默认布局当前是： + - 左边 `Hierarchy` + - 中间 `Scene` / `Game` + - 右边 `Inspector` + - 底部 `Console` / `Project` + +## 设计说明 + +把布局控制单独拿出来很合理，因为： + +- 工作区本身负责“有哪些面板” +- 布局控制器负责“这些面板怎么停靠” + +## 当前实现边界 + +- 当前默认布局是硬编码的。 +- 当前只依赖 ImGui DockBuilder，没有更高层布局配置文件系统。 + +## 相关文档 + +- [Layout](../Layout.md) +- [EditorWorkspace](../../Core/EditorWorkspace/EditorWorkspace.md) +- [EditorEvents](../../Core/EditorEvents/EditorEvents.md) diff --git a/docs/api/XCEngine/Editor/Layout/Layout.md b/docs/api/XCEngine/Editor/Layout/Layout.md new file mode 100644 index 00000000..f8772fde --- /dev/null +++ b/docs/api/XCEngine/Editor/Layout/Layout.md @@ -0,0 +1,19 @@ +# Layout + +**命名空间**: `XCEngine::Editor` + +**类型**: `submodule` + +**描述**: 编辑器布局控制层，当前主要由 `DockLayoutController` 负责 ImGui Dockspace 布局。 + +## 概述 + +`Layout` 子模块当前规模不大，但职责很明确：控制编辑器的 Dock 布局与布局重置行为。 + +它直接服务于 [EditorWorkspace](../Core/EditorWorkspace/EditorWorkspace.md)。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [EditorWorkspace](../Core/EditorWorkspace/EditorWorkspace.md) +- [UI](../UI/UI.md) diff --git a/docs/api/XCEngine/Editor/Managers/Managers.md b/docs/api/XCEngine/Editor/Managers/Managers.md new file mode 100644 index 00000000..307bed71 --- /dev/null +++ b/docs/api/XCEngine/Editor/Managers/Managers.md @@ -0,0 +1,29 @@ +# Managers + +**命名空间**: `XCEngine::Editor` + +**类型**: `submodule` + +**描述**: 编辑器状态服务的默认实现层，当前主要包括项目管理与场景管理实现。 + +## 概述 + +`Managers` 层的角色，是把 `Core` 里定义的抽象接口真正落成可工作的默认实现。 + +当前主要文档化的实现有： + +- [ProjectManager](ProjectManager/ProjectManager.md) +- [SceneManager](SceneManager/SceneManager.md) +- [SelectionManager](SelectionManager/SelectionManager.md) + +## 当前实现特征 + +- `ProjectManager` 更偏文件系统浏览器。 +- `SceneManager` 更偏场景编辑服务与场景文件生命周期管理。 +- `SelectionManager` 则是旧版单例实现，当前主链路已转向 `Core/ISelectionManager + Core/SelectionManager`。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [Core](../Core/Core.md) +- [Commands](../Commands/Commands.md) diff --git a/docs/api/XCEngine/Editor/Managers/ProjectManager/ProjectManager.md b/docs/api/XCEngine/Editor/Managers/ProjectManager/ProjectManager.md new file mode 100644 index 00000000..24868c2a --- /dev/null +++ b/docs/api/XCEngine/Editor/Managers/ProjectManager/ProjectManager.md @@ -0,0 +1,40 @@ +# ProjectManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Managers/ProjectManager.h` + +**描述**: `IProjectManager` 的默认实现，负责扫描项目 `Assets` 目录、维护面包屑路径，并支持基础文件夹与文件操作。 + +## 概述 + +`ProjectManager` 当前本质上是一个面向 `Assets` 目录的轻量文件系统浏览器。 + +它负责： + +- 初始化项目目录结构 +- 扫描目录并构建 `AssetItem` 树 +- 维护当前路径栈 +- 创建文件夹、删除项、移动项 + +## 当前实现说明 + +- `Initialize(projectPath)` 会确保 `/Assets` 以及若干默认子目录存在。 +- 若第一次初始化发现目录不存在，会自动创建 `Textures/Models/Scripts/Materials/Scenes` 等目录，并生成少量示例文件。 +- `GetCurrentItems()` 返回当前路径末尾节点的 `children`。 +- 目录扫描时，文件夹会排在文件前面，并按名字排序。 +- 资源类型当前按扩展名启发式推断，例如 `.png -> Texture`、`.fbx -> Model`、`.cs/.cpp/.h -> Script`。 + +## 当前实现边界 + +- 目前是实时扫描树，不是文件系统监听模式。 +- 异常处理大多是吞掉异常并保持当前状态，错误反馈很弱。 +- 类型判断完全靠扩展名映射，不依赖资源导入数据库。 + +## 相关文档 + +- [Managers](../Managers.md) +- [IProjectManager](../../Core/IProjectManager/IProjectManager.md) +- [AssetItem](../../Core/AssetItem/AssetItem.md) diff --git a/docs/api/XCEngine/Editor/Managers/SceneManager/SceneManager.md b/docs/api/XCEngine/Editor/Managers/SceneManager/SceneManager.md new file mode 100644 index 00000000..165f5b20 --- /dev/null +++ b/docs/api/XCEngine/Editor/Managers/SceneManager/SceneManager.md @@ -0,0 +1,46 @@ +# SceneManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/Managers/SceneManager.h` + +**描述**: `ISceneManager` 的默认实现，负责编辑器场景对象树、复制粘贴、场景文件加载保存、脏状态与快照恢复。 + +## 概述 + +`SceneManager` 是当前编辑器里最重的服务之一。 + +它当前同时负责： + +- `Scene` 与根实体列表 +- 实体新建/删除/重命名 +- 复制/粘贴/复制快照 +- 层级移动 +- 场景文件新建、加载、保存 +- 场景脏状态 +- 场景快照抓取与恢复 +- 向 `EventBus` 和本地 `Core::Event` 发布事件 + +## 当前实现说明 + +- 内部持有 `std::unique_ptr`。 +- `CreateEntity()` 会在没有场景时自动创建 `"EditorScene"`。 +- 删除实体时会递归删除全部子节点。 +- 剪贴板数据是自定义 `ClipboardData` 树，不是系统剪贴板。 +- `CaptureSceneSnapshot()` / `RestoreSceneSnapshot()` 是当前 undo 的基础。 + +## 当前实现边界 + +- 事件通知是同步的。 +- 复制粘贴依赖 `ComponentFactoryRegistry` 和组件自己的 `Serialize/Deserialize`。 +- 当前没有更高级的 prefab、variant 或 scene diff 机制。 +- `HasClipboardData()` 和 clipboard 生命周期都只在当前进程内有效。 + +## 相关文档 + +- [Managers](../Managers.md) +- [ISceneManager](../../Core/ISceneManager/ISceneManager.md) +- [UndoManager](../../Core/UndoManager/UndoManager.md) +- [Scene](../../../Scene/Scene.md) diff --git a/docs/api/XCEngine/Editor/Managers/SelectionManager/SelectionManager.md b/docs/api/XCEngine/Editor/Managers/SelectionManager/SelectionManager.md new file mode 100644 index 00000000..07e9be0b --- /dev/null +++ b/docs/api/XCEngine/Editor/Managers/SelectionManager/SelectionManager.md @@ -0,0 +1,44 @@ +# SelectionManager + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (legacy singleton)` + +**源文件**: `editor/src/Managers/SelectionManager.h` + +**描述**: 旧版基于 `GameObject*` 的单例选择管理器，当前主编辑器链路已经不再以它为核心。 + +## 概述 + +这个 `Managers/SelectionManager.h` 与当前正在使用的 [`Core/SelectionManager`](../../Core/SelectionManager/SelectionManager.md) 不是同一套实现。 + +它的特征是： + +- 单例访问 `SelectionManager::Get()` +- 直接保存 `GameObject*` +- 通过 `OnSelectionChanged` 事件对象通知变化 + +而当前 `EditorContext` 真实接入的是 `Core/SelectionManager`，后者实现了 `ISelectionManager`，并以实体 ID 为核心，与 `EventBus` 结合得更紧。 + +## 当前状态判断 + +按当前仓库搜索结果，`Managers/SelectionManager.h` 没有出现在现行 Editor 主路径引用中。 +因此更合理的理解是：它属于重构前残留实现，文档保留是为了说明历史包袱，而不是推荐新代码继续依赖。 + +## 使用建议 + +- 新代码应优先依赖 [`ISelectionManager`](../../Core/ISelectionManager/ISelectionManager.md) +- 默认实现应优先使用 [`Core/SelectionManager`](../../Core/SelectionManager/SelectionManager.md) +- 除非明确在迁移旧代码，否则不建议再引入这个单例版本 + +## 当前限制 + +- 直接持有 `GameObject*`，生命周期耦合更重 +- 不符合当前 `EditorContext` 的服务注入方向 +- 事件机制与新的 `EventBus + EditorEvents` 体系并不统一 + +## 相关文档 + +- [Managers](../Managers.md) +- [ISelectionManager](../../Core/ISelectionManager/ISelectionManager.md) +- [Core::SelectionManager](../../Core/SelectionManager/SelectionManager.md) diff --git a/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/D3D12WindowRenderer.md b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/D3D12WindowRenderer.md new file mode 100644 index 00000000..c655f6b0 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/D3D12WindowRenderer/D3D12WindowRenderer.md @@ -0,0 +1,43 @@ +# D3D12WindowRenderer + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `class` + +**源文件**: `editor/src/Platform/D3D12WindowRenderer.h` + +**描述**: 编辑器专用的 D3D12 窗口渲染器，负责交换链、RTV/SRV 堆、命令列表和 ImGui 绘制提交。 + +## 概述 + +`D3D12WindowRenderer` 解决的是“编辑器 UI 窗口本身怎么被呈现到屏幕”这个问题。 + +它当前自己管理： + +- `ID3D12Device` +- `ID3D12CommandQueue` +- `ID3D12CommandAllocator` +- `ID3D12GraphicsCommandList` +- `IDXGISwapChain3` +- RTV / SRV descriptor heap +- back buffer render targets +- fence + +## 当前实现说明 + +- `Initialize(hwnd, width, height)` 会创建设备与渲染目标。 +- `Render(imguiBackend, clearColor)` 会完成 back buffer 状态切换、清屏、ImGui draw data 提交、present 和 fence signal。 +- `Resize()` 会重建 back buffer RTV。 +- `GetDevice()` / `GetSrvHeap()` 为 ImGui backend 提供初始化依赖。 + +## 当前实现边界 + +- 当前完全是编辑器宿主级 D3D12 代码，不走引擎自己的 RHI 抽象。 +- 当前资源释放与错误处理都比较直接，没有更高层的资源状态对象。 +- `SetEventOnCompletion()` 当前传的是 `nullptr` 事件句柄，这个等待路径仍然很原始。 + +## 相关文档 + +- [Platform](../Platform.md) +- [Application](../../Application/Application.md) +- [Win32EditorHost](../Win32EditorHost/Win32EditorHost.md) diff --git a/docs/api/XCEngine/Editor/Platform/Platform.md b/docs/api/XCEngine/Editor/Platform/Platform.md new file mode 100644 index 00000000..44c725f0 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/Platform.md @@ -0,0 +1,34 @@ +# Platform + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `submodule` + +**描述**: 编辑器宿主平台层，当前主要围绕 Win32 窗口消息循环与 D3D12 窗口渲染路径实现。 + +## 概述 + +当前 `Platform` 子模块的角色非常直接： + +- 提供 Win32 宿主窗口和消息循环入口 +- 提供一个专用于编辑器的 D3D12 窗口渲染器 + +已文档化的核心类型/入口： + +- [Win32EditorHost](Win32EditorHost/Win32EditorHost.md) +- [D3D12WindowRenderer](D3D12WindowRenderer/D3D12WindowRenderer.md) +- [Win32Utf8](Win32Utf8/Win32Utf8.md) +- [WindowsProcessDiagnostics](WindowsProcessDiagnostics/WindowsProcessDiagnostics.md) + +## 当前实现边界 + +- 目前平台宿主明确偏向 Windows。 +- 窗口渲染器明确绑定 D3D12。 +- 这层更像编辑器宿主实现，不是跨平台窗口抽象框架。 +- 编码转换、崩溃日志和 `stderr` 重定向也都放在这一层，体现出“编辑器宿主进程基础设施”这一定位。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [Application](../Application/Application.md) +- [UI](../UI/UI.md) diff --git a/docs/api/XCEngine/Editor/Platform/Win32EditorHost/Win32EditorHost.md b/docs/api/XCEngine/Editor/Platform/Win32EditorHost/Win32EditorHost.md new file mode 100644 index 00000000..e341ad24 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/Win32EditorHost/Win32EditorHost.md @@ -0,0 +1,35 @@ +# Win32EditorHost + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `host entry` + +**源文件**: `editor/src/Platform/Win32EditorHost.h` + +**描述**: 提供 Win32 编辑器宿主入口，包括窗口过程 `EditorWndProc` 和主循环函数 `RunEditor()`。 + +## 概述 + +`Win32EditorHost.h` 当前不是传统意义上的 class，而是一组 inline 平台宿主入口： + +- `EditorWndProc` +- `RunEditor(HINSTANCE, int)` + +## 当前实现说明 + +- `EditorWndProc` 会先把消息交给 `ImGuiBackendBridge::HandleWindowMessage()`。 +- `WM_SIZE` 会转发到 `Application::OnResize()`。 +- `WM_DESTROY` 会发出 `PostQuitMessage(0)`。 +- `RunEditor()` 负责注册窗口类、创建窗口、调用 `Application::Initialize()`，并在消息循环空闲时执行 `Application::Render()`。 + +## 当前实现边界 + +- 这是典型的 Win32 专用宿主入口。 +- 当前没有抽象出更高层的平台无关 host interface。 +- 默认窗口类名和标题字符串目前写死在实现里。 + +## 相关文档 + +- [Platform](../Platform.md) +- [Application](../../Application/Application.md) +- [ImGuiSession](../../UI/ImGuiSession/ImGuiSession.md) diff --git a/docs/api/XCEngine/Editor/Platform/Win32Utf8/Win32Utf8.md b/docs/api/XCEngine/Editor/Platform/Win32Utf8/Win32Utf8.md new file mode 100644 index 00000000..eb6df3f0 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/Win32Utf8/Win32Utf8.md @@ -0,0 +1,43 @@ +# Win32Utf8 + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `header-helper` + +**源文件**: `editor/src/Platform/Win32Utf8.h` + +**描述**: 提供 Win32 宽字符与 UTF-8 字符串互转，以及可执行文件目录获取辅助函数。 + +## 概述 + +Windows API 与编辑器内部字符串在编码层面并不一致。 +`Win32Utf8.h` 的职责就是把这些转换集中在一个地方，避免编码细节散落到 Application、文件对话框和路径辅助函数中。 + +当前提供： + +- `WideToUtf8` +- `Utf8ToWide` +- `GetExecutableDirectoryUtf8` + +## 当前实现 + +- 转换基于 `WideCharToMultiByte` 与 `MultiByteToWideChar` +- 空字符串会直接返回空结果 +- `GetExecutableDirectoryUtf8` 使用 `GetModuleFileNameW` 读取当前进程路径，再取目录部分 + +## 设计说明 + +把编码转换集中封装，是 Windows 工具程序里非常必要的工程卫生。 +否则你会很快在应用启动、文件对话框、窗口标题和日志路径中混用 `std::string` 与 `std::wstring`，最后让边界越来越混乱。 + +## 当前限制 + +- `GetExecutableDirectoryUtf8` 使用固定 `MAX_PATH` 缓冲区 +- 没有专门处理更复杂的错误码或长路径场景 +- 只覆盖了编辑器当前主路径所需的最小转换能力 + +## 相关文档 + +- [Platform](../Platform.md) +- [Application](../../Application/Application.md) +- [EditorWindowTitle](../../Core/EditorWindowTitle/EditorWindowTitle.md) diff --git a/docs/api/XCEngine/Editor/Platform/WindowsProcessDiagnostics/WindowsProcessDiagnostics.md b/docs/api/XCEngine/Editor/Platform/WindowsProcessDiagnostics/WindowsProcessDiagnostics.md new file mode 100644 index 00000000..0433b958 --- /dev/null +++ b/docs/api/XCEngine/Editor/Platform/WindowsProcessDiagnostics/WindowsProcessDiagnostics.md @@ -0,0 +1,50 @@ +# WindowsProcessDiagnostics + +**命名空间**: `XCEngine::Editor::Platform` + +**类型**: `header-helper` + +**源文件**: `editor/src/Platform/WindowsProcessDiagnostics.h` + +**描述**: 提供 Windows 进程级崩溃日志和 `stderr` 重定向辅助函数。 + +## 概述 + +`WindowsProcessDiagnostics.h` 负责编辑器启动期的两类进程级诊断措施： + +- 安装未处理异常过滤器 +- 把 `stderr` 重定向到可执行目录下的日志文件 + +当前提供的入口包括： + +- `GetExecutableLogPath` +- `CrashExceptionFilter` +- `InstallCrashExceptionFilter` +- `RedirectStderrToExecutableLog` + +## 当前实现 + +- 崩溃信息会追加写入 `crash.log` +- 同时也会把崩溃摘要写到 `stderr` +- `stderr` 会被重定向到 `stderr.log` +- 路径基础依赖 [`GetExecutableDirectoryUtf8`](../Win32Utf8/Win32Utf8.md) + +`Application.cpp` 会在应用初始化早期调用这些函数，因此它们更偏“进程启动保护”，而不是普通运行时 API。 + +## 设计说明 + +对图形编辑器来说，启动早期和窗口系统崩溃阶段往往最难排查。 +在这种情况下，哪怕只有一条异常码和地址，也比完全静默退出强得多。 +所以这类轻量诊断入口非常符合商业工具软件的最小可运维要求。 + +## 当前限制 + +- 只记录非常基础的异常信息，没有 minidump +- 依赖 Windows SEH，不是跨平台方案 +- `freopen` 重定向策略比较直接，没有控制台回显复用 + +## 相关文档 + +- [Platform](../Platform.md) +- [Win32Utf8](../Win32Utf8/Win32Utf8.md) +- [Application](../../Application/Application.md) diff --git a/docs/api/XCEngine/Editor/Theme/Theme.md b/docs/api/XCEngine/Editor/Theme/Theme.md new file mode 100644 index 00000000..a55bab94 --- /dev/null +++ b/docs/api/XCEngine/Editor/Theme/Theme.md @@ -0,0 +1,27 @@ +# Theme + +**命名空间**: `XCEngine::Editor` + +**类型**: `namespace utility` + +**源文件**: `editor/src/Theme.h` + +**描述**: 编辑器顶层主题入口，当前暴露 `ApplyUnityDarkTheme()` 用于应用 Unity 风格深色主题。 + +## 概述 + +`Theme.h` 当前很轻，只暴露一个顶层主题函数： + +- `ApplyUnityDarkTheme()` + +这说明当前编辑器主题系统的真正细节主要还是沉在 [UI](../UI/UI.md) 子模块里，而顶层 `Theme` 更像统一入口。 + +## 当前实现边界 + +- 该头文件本身只声明接口，不承载复杂主题配置结构。 +- 命名空间采用 `inline namespace Editor` 风格，这和大多数 `XCEngine::Editor` 写法略有差异。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [UI](../UI/UI.md) diff --git a/docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md b/docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md new file mode 100644 index 00000000..955135ff --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/AboutEditorDialog/AboutEditorDialog.md @@ -0,0 +1,46 @@ +# AboutEditorDialog + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/AboutEditorDialog.h` + +**描述**: 绘制编辑器 About 模态弹窗。 + +## 概述 + +`DrawEditorAboutDialog` 是一个很轻量的 UI helper，用来响应主菜单 Help -> About 的弹窗请求。 +它依赖 [`DeferredPopupState`](../PopupState/PopupState.md) 控制打开时机，并在弹窗中显示： + +- 编辑器名称 +- 简短说明文字 +- 固定日期信息 +- 当前项目路径 + +## 当前实现 + +- 弹窗 ID 固定为 `About XCEngine Editor` +- 打开请求由 `popupState.ConsumeOpenRequest()` 驱动 +- 如果传入上下文，会显示 `context->GetProjectPath()` +- 关闭方式只有一个 `Close` 按钮 + +## 设计说明 + +About 弹窗本身不是复杂系统，但把它收口成独立 helper 是合理的： + +- `MainMenuActionRouter` 不需要关心弹窗内部布局 +- `MenuBar` 不需要持有具体 UI 绘制细节 +- 日后扩展版本号、版权、第三方库列表时，改动面会更集中 + +## 当前限制 + +- 日期 `2026-03-27` 是硬编码文本，不是构建时自动注入 +- “UI Refactor in progress” 也是当前开发态说明，不是正式产品文案 +- 没有版本号、提交哈希或许可证信息 + +## 相关文档 + +- [UI](../UI.md) +- [PopupState](../PopupState/PopupState.md) +- [MainMenuActionRouter](../../Actions/MainMenuActionRouter/MainMenuActionRouter.md) diff --git a/docs/api/XCEngine/Editor/UI/BaseTheme/BaseTheme.md b/docs/api/XCEngine/Editor/UI/BaseTheme/BaseTheme.md new file mode 100644 index 00000000..7fc8dc80 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/BaseTheme/BaseTheme.md @@ -0,0 +1,49 @@ +# BaseTheme + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/BaseTheme.h` + +**描述**: 定义编辑器默认 Dear ImGui 主题的颜色与尺寸指标。 + +## 概述 + +`BaseTheme.h` 把编辑器默认外观拆成三层函数： + +- `ApplyBaseThemeColors` +- `ApplyBaseThemeMetrics` +- `ApplyBaseTheme` + +这让主题既能整体应用，也能在需要时分别覆盖颜色或间距。 + +## 当前实现 + +- 主题整体是偏中性、低饱和的灰色编辑器风格 +- Docking 标签、按钮、工具栏、表格、滚动条等颜色都在这里集中定义 +- 圆角、边框、间距和 padding 也都由这里设置 +- [`ImGuiSession`](../ImGuiSession/ImGuiSession.md) 和 `Theme.cpp` 会使用这组 helper + +## 设计说明 + +商业编辑器通常不会把颜色和 spacing 散落在所有面板里，而是会先建立一套基础主题。 +这样做的好处是： + +- 新面板默认继承统一视觉语言 +- 后续品牌化或皮肤切换时有一个集中入口 +- 设计 token 和实际 ImGui style 之间的边界更清楚 + +当前实现已经具备这个方向，虽然还不是完整可换肤系统。 + +## 当前限制 + +- 主题参数主要是硬编码值 +- 没有亮色主题或用户配置 +- 主题切换和局部覆盖机制尚未成体系 + +## 相关文档 + +- [UI](../UI.md) +- [StyleTokens](../StyleTokens/StyleTokens.md) +- [ImGuiSession](../ImGuiSession/ImGuiSession.md) diff --git a/docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md b/docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md new file mode 100644 index 00000000..e0b8775f --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ConsoleFilterState/ConsoleFilterState.md @@ -0,0 +1,38 @@ +# ConsoleFilterState + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `class` + +**源文件**: `editor/src/UI/ConsoleFilterState.h` + +**描述**: 保存 Console 面板的日志等级过滤开关。 + +## 概述 + +`ConsoleFilterState` 是一个很小的状态对象，负责决定哪些日志等级会在 Console 面板中显示。 + +当前内部维护三组布尔值： + +- `m_showInfo` +- `m_showWarning` +- `m_showError` + +## 当前实现 + +- `ShowInfo()` / `ShowWarning()` / `ShowError()` 返回可写引用，便于直接绑定工具栏切换按钮 +- `Allows()` 的等级映射如下： + - `Verbose` / `Debug` / `Info` 归到 Info + - `Warning` 归到 Warning + - `Error` / `Fatal` 归到 Error + +## 设计说明 + +这种“三档过滤”很像商业编辑器控制台的第一层筛选：先把低成本的等级过滤做好，再考虑更重的搜索、分类和标签系统。 +对于当前阶段的编辑器，这已经能显著提升日志可读性。 + +## 相关文档 + +- [UI](../UI.md) +- [ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md) +- [ConsolePanel](../../panels/ConsolePanel/ConsolePanel.md) diff --git a/docs/api/XCEngine/Editor/UI/ConsoleLogFormatter/ConsoleLogFormatter.md b/docs/api/XCEngine/Editor/UI/ConsoleLogFormatter/ConsoleLogFormatter.md new file mode 100644 index 00000000..4839b7c9 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ConsoleLogFormatter/ConsoleLogFormatter.md @@ -0,0 +1,44 @@ +# ConsoleLogFormatter + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/ConsoleLogFormatter.h` + +**描述**: 把 `Debug::LogEntry` 转换为 Console 面板展示文本。 + +## 概述 + +`ConsoleLogFormatter.h` 负责把引擎日志记录格式化为用户在 Console 面板里看到的单行文本。 +当前主要入口： + +- `ConsoleLogPrefix` +- `BuildConsoleLogText` + +## 当前实现 + +- `Info` / `Debug` / `Verbose` 会被统一格式化为 `[INFO]` +- `Warning` 会格式化为 `[WARN]` +- `Error` / `Fatal` 会格式化为 `[ERROR]` +- 最终文本格式是：`[PREFIX] [Category] message` + +## 设计说明 + +把格式化独立出来很有必要，因为： + +- 日志采集层不应关心 UI 文本长什么样 +- Console 面板也不应自己拼接 category 和 level +- 后续如果引入时间戳、来源文件、富文本高亮，只需要收敛改这一层 + +## 当前限制 + +- 当前格式是纯文本单行 +- 没有时间戳、线程号或源码位置 +- `Debug` 和 `Verbose` 被归并到 Info，颗粒度较粗 + +## 相关文档 + +- [UI](../UI.md) +- [ConsoleActionRouter](../../Actions/ConsoleActionRouter/ConsoleActionRouter.md) +- [EditorConsoleSink](../../Core/EditorConsoleSink/EditorConsoleSink.md) diff --git a/docs/api/XCEngine/Editor/UI/Core/Core.md b/docs/api/XCEngine/Editor/UI/Core/Core.md new file mode 100644 index 00000000..ede5aa12 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/Core/Core.md @@ -0,0 +1,46 @@ +# Core + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/Core.h` + +**描述**: 提供更高层 UI helper 依赖的底层 ImGui 包装，包括控制行、样式栈、弹窗包装和工具栏按钮。 + +## 概述 + +不要把这个文件和 `Editor/Core` 子模块混淆。 +`UI/Core.h` 是 UI 辅助层自己的基础工具头，许多上层 helper 都会依赖它，包括： + +- 控件行绘制 `DrawControlRow` +- 样式压栈 / 出栈辅助 +- 带统一 padding 的 Popup 包装 +- `ToolbarButton` +- 当前窗口底边线绘制 + +## 当前实现 + +- `DrawControlRow` 用 ImGui table 实现“标签列 + 控件列”的双列布局 +- `BeginPopup` / `BeginPopupContextItem` / `BeginModalPopup` 都会统一应用 popup window padding +- `BeginDisabled` / `EndDisabled` 做了条件包装，便于上层少写分支 +- 这是 [`ScalarControls`](../ScalarControls/ScalarControls.md) 与 [`VectorControls`](../VectorControls/VectorControls.md) 的基础依赖 + +## 设计说明 + +这类“内部基础 UI helper”在商业编辑器里很常见。 +原因是 ImGui 原生 API 非常灵活，但如果每个面板都直接手写 style push/pop、table 布局和 popup 细节，代码会很快失控。 +先建立一层统一的 UI Core，能让上层组件写得更稳、更少样板代码。 + +## 当前限制 + +- 这层仍然是 inline helper 集合，不是完整 widget framework +- 样式栈安全主要依赖调用约定，没有更强的静态约束 +- 仍然明显偏向当前编辑器自己的使用场景 + +## 相关文档 + +- [UI](../UI.md) +- [ScalarControls](../ScalarControls/ScalarControls.md) +- [VectorControls](../VectorControls/VectorControls.md) +- [PropertyGrid](../PropertyGrid/PropertyGrid.md) diff --git a/docs/api/XCEngine/Editor/UI/DockHostStyle/DockHostStyle.md b/docs/api/XCEngine/Editor/UI/DockHostStyle/DockHostStyle.md new file mode 100644 index 00000000..2013a469 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/DockHostStyle/DockHostStyle.md @@ -0,0 +1,35 @@ +# DockHostStyle + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `class` + +**源文件**: `editor/src/UI/DockHostStyle.h` + +**描述**: 为主 DockSpace 应用一组临时样式覆盖的 RAII scope。 + +## 概述 + +`DockHostStyleScope` 的角色很单一：在进入主 DockSpace 绘制前压入一组 docking 相关样式，在离开时自动恢复。 + +它主要服务于 [`DockLayoutController`](../../Layout/DockLayoutController/DockLayoutController.md)。 + +## 当前实现 + +- 构造时 `PushStyleVar` 5 次，`PushStyleColor` 7 次 +- 覆盖内容主要是： + - Dock tab padding + - Tab 边框与 overline + - Tab 的普通 / hover / selected / dimmed 颜色 +- 析构时自动对称 `Pop` + +## 设计说明 + +这是一种标准 RAII UI 封装。 +对于 ImGui 这种依赖成对 push/pop 的库，scope 包装几乎是最稳妥的工程化手段之一，能显著减少忘记恢复样式导致的串色问题。 + +## 相关文档 + +- [UI](../UI.md) +- [StyleTokens](../StyleTokens/StyleTokens.md) +- [DockLayoutController](../../Layout/DockLayoutController/DockLayoutController.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md new file mode 100644 index 00000000..395af467 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ImGuiBackendBridge/ImGuiBackendBridge.md @@ -0,0 +1,51 @@ +# ImGuiBackendBridge + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `class` + +**源文件**: `editor/src/UI/ImGuiBackendBridge.h` + +**描述**: 封装 Dear ImGui Win32 + D3D12 backend 的初始化、逐帧驱动和窗口消息桥接。 + +## 概述 + +`ImGuiBackendBridge` 是编辑器 UI 栈里很关键但很底层的一环。 +它不创建 ImGui context，也不负责布局，而是把现有 context 接到具体平台和渲染后端上。 + +当前核心职责： + +- 初始化 `imgui_impl_win32` +- 初始化 `imgui_impl_dx12` +- 每帧调用 backend 的 `NewFrame` +- 把 `ImGui::GetDrawData()` 提交到 D3D12 command list +- 处理 Win32 消息转发 + +## 当前实现 + +- `Initialize()` 需要 `HWND`、`ID3D12Device*` 和 SRV heap +- 默认 frame count 为 `3` +- 默认 back buffer format 为 `DXGI_FORMAT_R8G8B8A8_UNORM` +- `HandleWindowMessage()` 是静态 helper，直接转发给 `ImGui_ImplWin32_WndProcHandler` + +## 设计说明 + +把 backend 绑定层单独抽出来，有两个很现实的好处： + +- `Application` 不需要直接依赖第三方 backend 细节 +- 如果未来替换成别的渲染后端或宿主窗口层，修改点更集中 + +在商业级编辑器里，这一层通常都存在，即使名字不同，本质上也是“UI 平台绑定桥”。 + +## 当前限制 + +- 当前明确绑定 Win32 + D3D12 +- 没有重复初始化保护之外的更复杂状态机 +- 不负责 ImGui context 生命周期，那部分由 [`ImGuiSession`](../ImGuiSession/ImGuiSession.md) 管理 + +## 相关文档 + +- [UI](../UI.md) +- [ImGuiSession](../ImGuiSession/ImGuiSession.md) +- [Application](../../Application/Application.md) +- [D3D12WindowRenderer](../../Platform/D3D12WindowRenderer/D3D12WindowRenderer.md) diff --git a/docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md b/docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md new file mode 100644 index 00000000..16ef93c3 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ImGuiSession/ImGuiSession.md @@ -0,0 +1,38 @@ +# ImGuiSession + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `class` + +**源文件**: `editor/src/UI/ImGuiSession.h` + +**描述**: 管理编辑器的 ImGui 上下文、布局 ini 文件位置、基础字体配置和默认主题应用。 + +## 概述 + +`ImGuiSession` 负责的是 ImGui 自身的生命周期和持久化布局配置。 + +它当前主要做三件事： + +- 创建/销毁 ImGui context +- 把布局 ini 文件放到 `/.xceditor/imgui_layout.ini` +- 配置默认字体并应用基础主题 + +## 当前实现说明 + +- `Initialize(projectPath)` 会开启 `ImGuiConfigFlags_DockingEnable`。 +- 字体优先尝试加载 `C:/Windows/Fonts/msyh.ttc`，失败时回退到 ImGui 默认字体。 +- `Shutdown()` 会先保存设置，再销毁当前 context。 +- `SaveSettings()` 只在 context 存在且 ini 路径非空时生效。 + +## 当前实现边界 + +- 当前字体路径写死为 Windows 字体目录。 +- 当前 ini 文件位置策略是项目局部目录，而不是全局用户目录。 +- 当前主要负责会话和基础样式，不处理平台/渲染后端桥接。 + +## 相关文档 + +- [UI](../UI.md) +- [Application](../../Application/Application.md) +- [Win32EditorHost](../../Platform/Win32EditorHost/Win32EditorHost.md) diff --git a/docs/api/XCEngine/Editor/UI/PanelChrome/PanelChrome.md b/docs/api/XCEngine/Editor/UI/PanelChrome/PanelChrome.md new file mode 100644 index 00000000..0459a072 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/PanelChrome/PanelChrome.md @@ -0,0 +1,45 @@ +# PanelChrome + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/PanelChrome.h` + +**描述**: 提供编辑器面板窗口、工具栏和内容区的 RAII 外壳。 + +## 概述 + +`PanelChrome.h` 让各个面板可以用统一方式搭建三段式结构： + +- `PanelWindowScope` +- `PanelToolbarScope` +- `PanelContentScope` + +这几乎就是当前编辑器所有面板的“标准壳层”。 + +## 当前实现 + +- 三个 scope 都在构造时 Begin，在析构时 End +- 会统一应用窗口 padding、工具栏背景色、item spacing 等样式 +- `PanelToolbarScope` 还会在退出时绘制底部分隔线 + +从 `HierarchyPanel`、`ProjectPanel`、`ConsolePanel`、`InspectorPanel` 当前实现看，这套壳层已经成为面板 UI 的主路径。 + +## 设计说明 + +这是很典型的商业编辑器代码组织方式： +先把窗口 chrome 标准化，再让具体面板只关心业务内容。 + +收益非常直接： + +- 面板外观一致 +- Begin/End 对称性更安全 +- 工具栏和内容区的布局约束自然统一 + +## 相关文档 + +- [UI](../UI.md) +- [StyleTokens](../StyleTokens/StyleTokens.md) +- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md) +- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) diff --git a/docs/api/XCEngine/Editor/UI/PopupState/PopupState.md b/docs/api/XCEngine/Editor/UI/PopupState/PopupState.md new file mode 100644 index 00000000..b57b0e18 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/PopupState/PopupState.md @@ -0,0 +1,49 @@ +# PopupState + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/PopupState.h` + +**描述**: 提供延迟弹窗、定向弹窗、文本输入弹窗和行内重命名状态容器。 + +## 概述 + +`PopupState.h` 当前包含四类非常实用的 UI 状态辅助类型： + +- `DeferredPopupState` +- `TargetedPopupState` +- `TextInputPopupState` +- `InlineTextEditState` + +它们共同解决一个问题：把 ImGui 的即时模式弹窗交互变成可维护的状态机。 + +## 当前实现 + +- `DeferredPopupState` 负责“下一帧打开弹窗” +- `TargetedPopupState` 在打开弹窗的同时绑定一个目标对象 +- `TextInputPopupState` 内置固定容量字符缓冲区，适合创建目录等对话框 +- `InlineTextEditState` 适合 Hierarchy 中的行内重命名 + +## 设计说明 + +即时模式 UI 最大的痛点之一，就是弹窗、右键菜单和重命名输入框的状态容易散。 +把这些交互状态抽成小类型，是非常划算的工程化投资： + +- 面板类不会充满零散布尔标志和字符数组 +- 打开请求和真正 `OpenPopup()` 的时机能被清晰区分 +- 复用性很好，多个面板都能直接用 + +## 当前限制 + +- 输入缓冲区容量是模板常量，需要调用者自己选大小 +- 没有更复杂的校验、历史记录或多字段表单状态 +- 目标对象状态主要依赖值拷贝或轻量句柄，不负责更深生命周期管理 + +## 相关文档 + +- [UI](../UI.md) +- [ProjectActionRouter](../../Actions/ProjectActionRouter/ProjectActionRouter.md) +- [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md) +- [AboutEditorDialog](../AboutEditorDialog/AboutEditorDialog.md) diff --git a/docs/api/XCEngine/Editor/UI/PropertyGrid/PropertyGrid.md b/docs/api/XCEngine/Editor/UI/PropertyGrid/PropertyGrid.md new file mode 100644 index 00000000..9775bf86 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/PropertyGrid/PropertyGrid.md @@ -0,0 +1,49 @@ +# PropertyGrid + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/PropertyGrid.h` + +**描述**: 在 Inspector 中提供统一的属性行控件，并集成交互式撤销辅助。 + +## 概述 + +`PropertyGrid.h` 是当前 Inspector 属性编辑体验的中枢之一。 +它在 [`ScalarControls`](../ScalarControls/ScalarControls.md) 和 [`VectorControls`](../VectorControls/VectorControls.md) 之上封装了一组更贴近 Inspector 语义的 API： + +- `DrawPropertyFloat` +- `DrawPropertyBool` +- `DrawPropertyColor4` +- `DrawPropertyCombo` +- `DrawPropertyVec3Input` +- `ApplyPropertyChange` + +## 当前实现 + +- 统一使用 `InspectorPropertyLabelWidth()` 作为标签列宽 +- `ApplyPropertyChange` 在字段变化时可选地调用 `undoManager->BeginInteractiveChange()` +- 具体组件编辑器通常会先调用 `DrawProperty*`，再把结果交给 `ApplyPropertyChange` + +## 设计说明 + +商业编辑器里的 Inspector 很少直接暴露底层控件 API，而是会先收口成属性网格层。 +这样做的好处是： + +- 全部组件 editor 的标签宽度、排版和交互节奏统一 +- 撤销系统可以自然嵌入属性修改路径 +- 组件编辑器代码更接近“编辑语义”，而不是原始 ImGui 调用 + +## 当前限制 + +- 目前仍然是手写属性 helper，不是基于反射的通用属性系统 +- `ApplyPropertyChange` 只负责开始交互式改动，最终收尾仍要靠 Inspector 路由层 +- 主要面向 Inspector，不是通用任意表单框架 + +## 相关文档 + +- [UI](../UI.md) +- [ScalarControls](../ScalarControls/ScalarControls.md) +- [VectorControls](../VectorControls/VectorControls.md) +- [TransformComponentEditor](../../ComponentEditors/TransformComponentEditor/TransformComponentEditor.md) diff --git a/docs/api/XCEngine/Editor/UI/ScalarControls/ScalarControls.md b/docs/api/XCEngine/Editor/UI/ScalarControls/ScalarControls.md new file mode 100644 index 00000000..ec633843 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/ScalarControls/ScalarControls.md @@ -0,0 +1,46 @@ +# ScalarControls + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/ScalarControls.h` + +**描述**: 提供基于双列表格布局的标量属性控件，如 float、int、bool、颜色和下拉框。 + +## 概述 + +`ScalarControls.h` 封装的是 Inspector 最基础的输入部件： + +- `DrawFloat` +- `DrawInt` +- `DrawBool` +- `DrawColor3` +- `DrawColor4` +- `DrawSliderFloat` +- `DrawSliderInt` +- `DrawCombo` + +## 当前实现 + +- 所有控件都建立在 [`DrawControlRow`](../Core/Core.md) 之上 +- 默认列宽来自 `DefaultControlLabelWidth()` +- 每个控件都统一使用 `##value` 作为内部 item id 后缀，并通过外层 `PushID(label)` 隔离 + +## 设计说明 + +这层的价值在于把“输入控件长什么样”从组件编辑器里抽出来。 +否则每个组件 editor 都会重复写： + +- 两列表格 +- 标签列宽 +- `SetNextItemWidth` +- 不同控件的 ImGui 参数模板 + +`ScalarControls` 让上层代码只保留业务字段名和少量范围参数。 + +## 相关文档 + +- [UI](../UI.md) +- [Core](../Core/Core.md) +- [PropertyGrid](../PropertyGrid/PropertyGrid.md) diff --git a/docs/api/XCEngine/Editor/UI/SceneStatusWidget/SceneStatusWidget.md b/docs/api/XCEngine/Editor/UI/SceneStatusWidget/SceneStatusWidget.md new file mode 100644 index 00000000..02317fbf --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/SceneStatusWidget/SceneStatusWidget.md @@ -0,0 +1,36 @@ +# SceneStatusWidget + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/SceneStatusWidget.h` + +**描述**: 在主菜单栏右侧绘制当前场景文件状态，并在悬停时提供详细提示。 + +## 概述 + +`DrawSceneStatusWidget` 是一个很小但很有价值的状态反馈组件。 +它会把当前场景的保存状态浓缩成菜单栏右侧的一段文本，并在悬停时展开 tooltip。 + +## 当前实现 + +- dirty 场景会以前缀 `* ` 标记 +- 没有场景路径时会显示 `Unsaved.xc` +- 有路径时只显示文件名 +- tooltip 中会进一步展示： + - 场景名 + - 文件名 + - 状态 `Modified / Saved` + - 完整路径或“尚未保存”提示 + +## 设计说明 + +这非常符合商业编辑器的 UI 习惯： +把高频状态压缩成轻量但始终可见的角落信息，而不是每次都让用户去打开另一个面板确认场景是否已保存。 + +## 相关文档 + +- [UI](../UI.md) +- [MainMenuActionRouter](../../Actions/MainMenuActionRouter/MainMenuActionRouter.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) diff --git a/docs/api/XCEngine/Editor/UI/StyleTokens/StyleTokens.md b/docs/api/XCEngine/Editor/UI/StyleTokens/StyleTokens.md new file mode 100644 index 00000000..dca8ae36 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/StyleTokens/StyleTokens.md @@ -0,0 +1,46 @@ +# StyleTokens + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/StyleTokens.h` + +**描述**: 统一定义编辑器 UI 使用的颜色、尺寸、间距和布局 token。 + +## 概述 + +`StyleTokens.h` 是当前 UI 层的设计 token 中心。 +它集中提供了大量 inline token helper，例如： + +- Dock 标签颜色 +- 工具栏高度与 padding +- 资产网格尺寸 +- Inspector 标签列宽 +- 弹窗按钮尺寸 +- 向量控件按钮颜色 +- Console 状态颜色 + +## 设计说明 + +这是商业编辑器 UI 非常推荐的做法。 +不要在控件代码里到处写 `6.0f`、`0.24f`、`104.0f` 这种魔法数字，而应先抽象成 token。 + +收益包括： + +- 调整风格时能集中修改 +- 命名本身就表达设计意图 +- 高层 widget 与具体数值解耦 + +## 当前限制 + +- 仍然是 header inline 常量函数，而不是数据驱动主题系统 +- token 数量已经较多，后续可能需要再分层 +- 当前主要围绕唯一默认主题设计 + +## 相关文档 + +- [UI](../UI.md) +- [BaseTheme](../BaseTheme/BaseTheme.md) +- [PanelChrome](../PanelChrome/PanelChrome.md) +- [Widgets](../Widgets/Widgets.md) diff --git a/docs/api/XCEngine/Editor/UI/UI.md b/docs/api/XCEngine/Editor/UI/UI.md new file mode 100644 index 00000000..e2f2a778 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/UI.md @@ -0,0 +1,50 @@ +# UI + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `submodule` + +**描述**: 编辑器 ImGui 基础设施、主题、控件与面板绘制辅助层。 + +## 概述 + +`UI` 子模块当前内容很多，但核心方向很清楚： + +- 维护 ImGui 会话与布局文件 +- 封装统一视觉主题 +- 提供属性面板、工具栏、菜单、场景状态等 UI 辅助 + +已文档化的核心页面： + +- [ImGuiSession](ImGuiSession/ImGuiSession.md) +- [ImGuiBackendBridge](ImGuiBackendBridge/ImGuiBackendBridge.md) +- [BaseTheme](BaseTheme/BaseTheme.md) +- [StyleTokens](StyleTokens/StyleTokens.md) +- [Core](Core/Core.md) +- [PanelChrome](PanelChrome/PanelChrome.md) +- [Widgets](Widgets/Widgets.md) +- [PopupState](PopupState/PopupState.md) +- [ScalarControls](ScalarControls/ScalarControls.md) +- [VectorControls](VectorControls/VectorControls.md) +- [PropertyGrid](PropertyGrid/PropertyGrid.md) +- [DockHostStyle](DockHostStyle/DockHostStyle.md) +- [ConsoleFilterState](ConsoleFilterState/ConsoleFilterState.md) +- [ConsoleLogFormatter](ConsoleLogFormatter/ConsoleLogFormatter.md) +- [SceneStatusWidget](SceneStatusWidget/SceneStatusWidget.md) +- [AboutEditorDialog](AboutEditorDialog/AboutEditorDialog.md) + +`UI/UI.h` 本身只是聚合入口，真正值得阅读的是这些分层 helper： + +- `ImGuiSession + ImGuiBackendBridge` 负责上下文与后端绑定 +- `BaseTheme + StyleTokens` 负责视觉规范 +- `Core + PanelChrome + Widgets` 负责通用交互壳层 +- `ScalarControls + VectorControls + PropertyGrid` 负责 Inspector 表单体验 + +这样拆分的好处，是把 Dear ImGui 容易失控的即时模式代码收束成一套可复用部件库。 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [Application](../Application/Application.md) +- [Platform](../Platform/Platform.md) +- [Editor Architecture And Workflow](../../../_guides/Editor/Editor-Architecture-And-Workflow.md) diff --git a/docs/api/XCEngine/Editor/UI/VectorControls/VectorControls.md b/docs/api/XCEngine/Editor/UI/VectorControls/VectorControls.md new file mode 100644 index 00000000..41f83767 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/VectorControls/VectorControls.md @@ -0,0 +1,49 @@ +# VectorControls + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/VectorControls.h` + +**描述**: 提供向量属性的多轴输入控件，支持带重置按钮和纯输入两种模式。 + +## 概述 + +`VectorControls.h` 当前提供： + +- `DrawVec2` +- `DrawVec3` +- `DrawVec3Input` +- 更底层的 `DrawAxisFloatControls` + +它是 Transform 类组件编辑体验的核心基础。 + +## 当前实现 + +- `DrawVec3` / `DrawVec2` 提供带轴按钮的重置式控件 +- `DrawVec3Input` 提供更紧凑的纯输入版本 +- 可选输出 `isActive`，用于让 Inspector 感知控件是否仍在持续拖拽 +- 每个轴以 `AxisFloatControlSpec` 描述 + +## 设计说明 + +相比直接把 `Vector3` 画成三个普通 `DragFloat`，这种按轴组织的控件更符合编辑器习惯： + +- X/Y/Z 维度更直观 +- 重置按钮更利于快速归零 +- 更容易和交互式撤销衔接 + +这和 Unity Inspector 中 Transform 的体验方向是相近的，只是当前实现更轻量。 + +## 当前限制 + +- 只覆盖 `Vector2` / `Vector3` +- 没有 quaternion、rect、bounds 等更复杂类型控件 +- 没有多对象混合值显示 + +## 相关文档 + +- [UI](../UI.md) +- [PropertyGrid](../PropertyGrid/PropertyGrid.md) +- [TransformComponentEditor](../../ComponentEditors/TransformComponentEditor/TransformComponentEditor.md) diff --git a/docs/api/XCEngine/Editor/UI/Widgets/Widgets.md b/docs/api/XCEngine/Editor/UI/Widgets/Widgets.md new file mode 100644 index 00000000..0c7f7ab9 --- /dev/null +++ b/docs/api/XCEngine/Editor/UI/Widgets/Widgets.md @@ -0,0 +1,52 @@ +# Widgets + +**命名空间**: `XCEngine::Editor::UI` + +**类型**: `header-helper` + +**源文件**: `editor/src/UI/Widgets.h` + +**描述**: 提供更接近编辑器业务语义的中高层 widget，如菜单命令、层级树节点、资产格子、组件区块和对话框按钮行。 + +## 概述 + +如果说 [`Core`](../Core/Core.md) 是底层 UI 包装，那么 `Widgets.h` 就是更贴近编辑器业务的通用组件库。 +当前文件涵盖的内容很多，主要可以分成几类： + +- 菜单与命令：`MenuCommand`、`DrawMenuScope`、`DrawMenuCommands` +- 工具栏：搜索框、标签、切换按钮、面包屑 +- Hierarchy / Project：`DrawHierarchyNode`、`DrawAssetTile`、`DrawAssetIcon` +- Inspector：`BeginComponentSection` +- 对话框与 tooltip：`DrawDialogActionRow`、`BeginTitledPopup`、`BeginTitledTooltip` +- Console：`DrawConsoleLogRow` + +## 设计说明 + +这类文件在商业编辑器里通常非常关键，因为它决定了“多个面板是否共享同一种交互语言”。 +比如： + +- Hierarchy 节点的点击、展开和双击 +- Project 资源网格的卡片样式 +- Inspector 组件区块的标题和右键菜单 + +如果这些都散落在各个面板里，最终 UI 行为会越来越不一致。 + +## 当前实现特征 + +- `MenuCommand` 把菜单项和分隔线统一成一个小数据结构 +- `AssetTileResult`、`HierarchyNodeResult` 等结果结构让调用方更容易写流程判断 +- 组件区块与工具栏、搜索框都已经形成可复用构件 + +## 当前限制 + +- 仍然是 header inline helpers，而不是独立 widget 类库 +- 某些 widget 仍然高度耦合当前编辑器视觉风格 +- 还没有更高级的虚拟列表、树过滤高亮或多列资源浏览控件 + +## 相关文档 + +- [UI](../UI.md) +- [Core](../Core/Core.md) +- [StyleTokens](../StyleTokens/StyleTokens.md) +- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md) +- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md) diff --git a/docs/api/XCEngine/Editor/Utils/SceneEditorUtils/SceneEditorUtils.md b/docs/api/XCEngine/Editor/Utils/SceneEditorUtils/SceneEditorUtils.md new file mode 100644 index 00000000..333e03f7 --- /dev/null +++ b/docs/api/XCEngine/Editor/Utils/SceneEditorUtils/SceneEditorUtils.md @@ -0,0 +1,40 @@ +# SceneEditorUtils + +**命名空间**: `XCEngine::Editor::SceneEditorUtils` + +**类型**: `header utility set` + +**源文件**: `editor/src/Utils/SceneEditorUtils.h` + +**描述**: 提供场景编辑相关辅助函数，包括 UTF-8/UTF-16 转换、场景文件对话框、当前场景保存和切换确认逻辑。 + +## 概述 + +`SceneEditorUtils.h` 当前是一组围绕“场景文件工作流”组织起来的 inline 工具函数。 + +主要能力包括： + +- UTF-8 / Wide 字符串转换 +- 场景文件名清洗 +- 打开 / 保存场景文件对话框 +- 保存当前场景 +- 切换场景前确认是否保存脏场景 + +## 当前实现说明 + +- 文件对话框走 Win32 `GetOpenFileNameW` / `GetSaveFileNameW`。 +- 默认场景目录是 `/Assets/Scenes`。 +- 支持 `.xc`，并兼容部分 legacy scene 扩展名过滤。 +- `ConfirmSceneSwitch()` 在场景脏时会弹出 `Yes / No / Cancel` 对话框。 + +## 当前实现边界 + +- 当前是明显的 Windows 工具函数集合。 +- 对话框 owner window 来自 `GetActiveWindow()` / `GetForegroundWindow()`。 +- 工具函数直接依赖 `IEditorContext`，不是无状态纯工具库。 + +## 相关文档 + +- [Utils](../Utils.md) +- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) +- [IEditorContext](../../Core/IEditorContext/IEditorContext.md) diff --git a/docs/api/XCEngine/Editor/Utils/UndoUtils/UndoUtils.md b/docs/api/XCEngine/Editor/Utils/UndoUtils/UndoUtils.md new file mode 100644 index 00000000..9884b991 --- /dev/null +++ b/docs/api/XCEngine/Editor/Utils/UndoUtils/UndoUtils.md @@ -0,0 +1,35 @@ +# UndoUtils + +**命名空间**: `XCEngine::Editor::UndoUtils` + +**类型**: `header utility set` + +**源文件**: `editor/src/Utils/UndoUtils.h` + +**描述**: 提供把任意编辑操作包裹进撤销历史的辅助模板函数。 + +## 概述 + +`UndoUtils.h` 当前核心就是一个模板工具： + +- `ExecuteSceneCommand(IEditorContext&, const std::string&, Func&&)` + +它的职责很直接：在执行某个编辑动作前后抓取状态快照，并自动把这次操作推入 undo 历史。 + +## 当前实现说明 + +- 若当前还有 pending interactive change，会先 finalize。 +- 先抓 `before` 快照。 +- 执行传入的 `func`。 +- 再抓 `after` 快照并调用 `PushCommand()`。 +- 同时兼容 `void` 返回和非 `void` 返回两种调用。 + +## 设计说明 + +这个工具很实用，因为它把“如何接入 undo”从按钮逻辑、菜单逻辑和命令逻辑里抽离出来了。 + +## 相关文档 + +- [Utils](../Utils.md) +- [IUndoManager](../../Core/IUndoManager/IUndoManager.md) +- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) diff --git a/docs/api/XCEngine/Editor/Utils/Utils.md b/docs/api/XCEngine/Editor/Utils/Utils.md new file mode 100644 index 00000000..be173b4e --- /dev/null +++ b/docs/api/XCEngine/Editor/Utils/Utils.md @@ -0,0 +1,26 @@ +# Utils + +**命名空间**: `XCEngine::Editor` + +**类型**: `submodule` + +**描述**: 编辑器辅助函数层，当前主要围绕场景切换确认、文件对话框和撤销相关辅助展开。 + +## 概述 + +当前 `Utils` 目录包括： + +- `SceneEditorUtils.h` +- `UndoUtils.h` + +这些工具函数本身不构成一个很强的对象模型，但它们支撑了： + +- 场景打开/保存对话框 +- 场景切换确认 +- 撤销与交互式修改配合 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [Commands](../Commands/Commands.md) +- [Core](../Core/Core.md) diff --git a/docs/api/XCEngine/Editor/panels/ConsolePanel/ConsolePanel.md b/docs/api/XCEngine/Editor/panels/ConsolePanel/ConsolePanel.md new file mode 100644 index 00000000..e7f691d3 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/ConsolePanel/ConsolePanel.md @@ -0,0 +1,33 @@ +# ConsolePanel + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/panels/ConsolePanel.h` + +**描述**: 控制台面板，负责根据过滤状态显示编辑器日志，并绘制日志工具栏。 + +## 概述 + +`ConsolePanel` 当前围绕两块逻辑展开： + +- 一个 `UI::ConsoleFilterState` +- 一个 `EditorConsoleSink` 日志源 + +## 当前实现说明 + +- 构造时面板名为 `"Console"`。 +- `Render()` 里会先绘制工具栏，再绘制日志滚动区域。 +- 日志行实际绘制和工具栏动作主要委托给 `Actions` 层。 + +## 当前实现边界 + +- 当前控制台面板自身很薄，大部分行为来自 action router 和 `EditorConsoleSink`。 +- 当前过滤状态存在面板实例内，不是全局日志视图配置对象。 + +## 相关文档 + +- [panels](../panels.md) +- [Actions](../../Actions/Actions.md) +- [UI](../../UI/UI.md) diff --git a/docs/api/XCEngine/Editor/panels/GameViewPanel/GameViewPanel.md b/docs/api/XCEngine/Editor/panels/GameViewPanel/GameViewPanel.md new file mode 100644 index 00000000..87194de7 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/GameViewPanel/GameViewPanel.md @@ -0,0 +1,28 @@ +# GameViewPanel + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/panels/GameViewPanel.h` + +**描述**: Game 视图面板，占位承载 Game 窗口并标记动作路由焦点。 + +## 概述 + +当前 `GameViewPanel` 和 [SceneViewPanel](../SceneViewPanel/SceneViewPanel.md) 一样，都属于轻量占位面板。 + +它目前主要做两件事： + +- 以 `"Game"` 为名字打开一个面板窗口 +- 在该窗口激活时通知 `Actions` 层观察焦点路由 + +## 当前实现边界 + +- 当前没有真正的 runtime frame 嵌入或 play mode 画面输出。 +- 它现在更像未来 Game View 能力的承载容器。 + +## 相关文档 + +- [panels](../panels.md) +- [Actions](../../Actions/Actions.md) diff --git a/docs/api/XCEngine/Editor/panels/HierarchyPanel/HierarchyPanel.md b/docs/api/XCEngine/Editor/panels/HierarchyPanel/HierarchyPanel.md new file mode 100644 index 00000000..3fda87e2 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/HierarchyPanel/HierarchyPanel.md @@ -0,0 +1,50 @@ +# HierarchyPanel + +**命名空间**: `XCEngine::Editor` + +**类型**: `class + enum class` + +**源文件**: `editor/src/panels/HierarchyPanel.h` + +**描述**: 层级面板，负责显示场景对象树、搜索、排序、拖放层级调整以及内联重命名。 + +## 概述 + +`HierarchyPanel` 是当前编辑器里交互最丰富的面板之一。 + +它当前承载的功能包括： + +- 订阅选择变化和重命名请求事件 +- 层级树渲染 +- 搜索过滤 +- 排序选项 +- 拖拽层级调整 +- 右键上下文菜单 +- 内联重命名 + +头文件里还定义了： + +- `enum class SortMode { Name, ComponentCount, TransformFirst }` + +## 当前实现说明 + +- `OnAttach()` 会订阅 `SelectionChangedEvent` 和 `EntityRenameRequestedEvent`。 +- 搜索过滤当前按名字子串匹配，并递归检查子节点。 +- 排序支持： + - `Name` + - `ComponentCount` + - `TransformFirst` +- 双击节点会进入重命名状态。 +- 背景点击、右键菜单和拖放逻辑主要委托给 `Actions` 层。 + +## 当前实现边界 + +- 当前排序和过滤都在 UI 渲染阶段直接对实体列表做处理。 +- `TransformFirst` 排序实际上是“有 Transform 的对象优先”，而不是更复杂的 transform-aware hierarchy order。 + +## 相关文档 + +- [panels](../panels.md) +- [SelectionManager](../../Core/SelectionManager/SelectionManager.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) +- [EditorEvents](../../Core/EditorEvents/EditorEvents.md) diff --git a/docs/api/XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md b/docs/api/XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md new file mode 100644 index 00000000..34c35b86 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md @@ -0,0 +1,41 @@ +# InspectorPanel + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/panels/InspectorPanel.h` + +**描述**: 检查器面板，负责显示当前选中对象的组件列表，并通过 `ComponentEditorRegistry` 渲染对应组件编辑 UI。 + +## 概述 + +`InspectorPanel` 是组件编辑系统的主要承载面板。 + +它当前的工作流是： + +1. 订阅选择变化。 +2. 根据当前选中实体拿到 `GameObject`。 +3. 遍历其组件。 +4. 通过 `ComponentEditorRegistry` 找到对应的 `IComponentEditor`。 +5. 渲染每个组件 section。 + +## 当前实现说明 + +- 没有选中对象时会显示 empty state。 +- 若选中对象已失效，也会显示 empty state。 +- `RenderGameObject()` 里会绘制 Add Component 按钮和弹窗。 +- 若某个组件没有已注册 editor，会显示提示文本。 +- 组件 editor 返回 `true` 时，当前会标记场景为 dirty。 + +## 当前实现边界 + +- 当前 Inspector 完全依赖组件 editor 注册表，不是基于反射自动生成 UI。 +- 组件 section 的移除、添加和交互式编辑配合主要通过 `Actions` 层完成。 + +## 相关文档 + +- [panels](../panels.md) +- [IComponentEditor](../../ComponentEditors/IComponentEditor/IComponentEditor.md) +- [ComponentEditorRegistry](../../ComponentEditors/ComponentEditorRegistry/ComponentEditorRegistry.md) +- [SceneManager](../../Managers/SceneManager/SceneManager.md) diff --git a/docs/api/XCEngine/Editor/panels/MenuBar/MenuBar.md b/docs/api/XCEngine/Editor/panels/MenuBar/MenuBar.md new file mode 100644 index 00000000..1edecf06 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/MenuBar/MenuBar.md @@ -0,0 +1,31 @@ +# MenuBar + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/panels/MenuBar.h` + +**描述**: 编辑器主菜单栏面板，负责绘制主菜单、处理菜单相关快捷键，并承载 About 弹窗状态。 + +## 概述 + +`MenuBar` 当前是最薄的一类面板：它自己不直接承载大量业务，而是把菜单相关逻辑委托给 `Actions` 层。 + +## 当前实现说明 + +- 构造时面板名为 `"MenuBar"`。 +- `Render()` 当前会： + - 调用 `HandleMenuBarShortcuts(*m_context)` + - 调用 `DrawMainMenuBar(*m_context, m_aboutPopup)` + - 调用 `DrawMainMenuOverlays(m_context, m_aboutPopup)` + +## 设计说明 + +这是合理的分层：菜单面板负责“我是菜单栏这个容器”，动作与绘制细节则交给 action router。 + +## 相关文档 + +- [panels](../panels.md) +- [ActionBinding](../../Actions/ActionBinding/ActionBinding.md) +- [SceneCommands](../../Commands/SceneCommands/SceneCommands.md) diff --git a/docs/api/XCEngine/Editor/panels/Panel/Panel.md b/docs/api/XCEngine/Editor/panels/Panel/Panel.md new file mode 100644 index 00000000..e132ecf1 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/Panel/Panel.md @@ -0,0 +1,43 @@ +# Panel + +**命名空间**: `XCEngine::Editor` + +**类型**: `class (abstract base)` + +**源文件**: `editor/src/panels/Panel.h` + +**描述**: 所有编辑器面板的抽象基类，定义 attach/detach/update/event/render 生命周期与上下文注入能力。 + +## 概述 + +`Panel` 当前是所有具体面板的共同基类。 + +它提供： + +- 名称 +- 开关状态 +- `IEditorContext*` +- 一组可覆写生命周期钩子 + +## 关键接口 + +| 方法 | 作用 | +|------|------| +| `OnAttach()` / `OnDetach()` | 面板挂接与拆除。 | +| `OnUpdate(float)` | 每帧更新。 | +| `OnEvent(void*)` | 处理外部事件。 | +| `Render()` | 渲染面板 UI。 | +| `GetName()` | 获取面板名。 | +| `IsOpen()` / `SetOpen()` / `Toggle()` | 控制开关状态。 | +| `SetContext()` / `GetContext()` / `HasContext()` | 管理编辑器上下文。 | + +## 当前实现边界 + +- `SetContext()` 当前带断言，不允许重复设置上下文。 +- 事件参数是 `void*`，说明当前事件分发层还比较宽松，没有统一强类型 UI 事件基类。 + +## 相关文档 + +- [panels](../panels.md) +- [PanelCollection](../PanelCollection/PanelCollection.md) +- [IEditorContext](../../Core/IEditorContext/IEditorContext.md) diff --git a/docs/api/XCEngine/Editor/panels/PanelCollection/PanelCollection.md b/docs/api/XCEngine/Editor/panels/PanelCollection/PanelCollection.md new file mode 100644 index 00000000..a142a339 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/PanelCollection/PanelCollection.md @@ -0,0 +1,37 @@ +# PanelCollection + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/panels/PanelCollection.h` + +**描述**: 负责持有一组 `Panel` 对象，并统一处理上下文注入、attach/detach、update、event dispatch 和 render。 + +## 概述 + +`PanelCollection` 是当前面板系统的统一调度容器。 + +它提供： + +- `SetContext()` 给全部面板注入上下文 +- `Emplace()` 构造并注册新面板 +- `AttachAll()` / `DetachAll()` +- `UpdateAll()` / `DispatchEvent()` / `RenderAll()` +- `Clear()` + +## 当前实现说明 + +- 面板以 `std::unique_ptr` 保存在内部数组中。 +- `SetContext()` 会把上下文补发给之前尚未绑定上下文的面板。 +- `DetachAll()` 当前按逆序拆除面板，这个细节是合理的。 + +## 设计说明 + +在当前编辑器规模下，用一个简单容器统一驱动所有面板生命周期，比引入更复杂的窗口管理框架更务实。 + +## 相关文档 + +- [panels](../panels.md) +- [Panel](../Panel/Panel.md) +- [EditorWorkspace](../../Core/EditorWorkspace/EditorWorkspace.md) diff --git a/docs/api/XCEngine/Editor/panels/ProjectPanel/ProjectPanel.md b/docs/api/XCEngine/Editor/panels/ProjectPanel/ProjectPanel.md new file mode 100644 index 00000000..f2b7b689 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/ProjectPanel/ProjectPanel.md @@ -0,0 +1,41 @@ +# ProjectPanel + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/panels/ProjectPanel.h` + +**描述**: 项目面板，负责展示当前资产目录、面包屑导航、搜索、资产瓦片交互以及文件夹创建与上下文菜单。 + +## 概述 + +`ProjectPanel` 当前是 [ProjectManager](../../Managers/ProjectManager/ProjectManager.md) 的主要 UI 前端。 + +它负责： + +- 初始化项目浏览器 +- 绘制工具栏与面包屑 +- 绘制资产网格 +- 搜索过滤 +- 资产点击、打开、拖放和右键菜单 +- 空白区域上下文菜单 +- 新建文件夹弹窗 + +## 当前实现说明 + +- `Initialize(projectPath)` 直接调用 `m_context->GetProjectManager().Initialize(projectPath)`。 +- `Render()` 中资产会按自适应列数排成网格。 +- 搜索当前按名字子串过滤。 +- 资产图标当前按 `isFolder` 区分 folder/file，再配合 action/router 决定交互。 + +## 当前实现边界 + +- 当前搜索是前端过滤，不是索引搜索。 +- 资产预览目前还是轻量瓦片，不是完整导入数据库浏览器。 + +## 相关文档 + +- [panels](../panels.md) +- [ProjectManager](../../Managers/ProjectManager/ProjectManager.md) +- [AssetItem](../../Core/AssetItem/AssetItem.md) diff --git a/docs/api/XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md b/docs/api/XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md new file mode 100644 index 00000000..f229442d --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/SceneViewPanel/SceneViewPanel.md @@ -0,0 +1,28 @@ +# SceneViewPanel + +**命名空间**: `XCEngine::Editor` + +**类型**: `class` + +**源文件**: `editor/src/panels/SceneViewPanel.h` + +**描述**: 场景视图面板，占位承载 Scene 视图窗口并标记动作路由焦点。 + +## 概述 + +当前 `SceneViewPanel` 还很轻。 + +它目前主要做两件事： + +- 以 `"Scene"` 为名字打开一个面板窗口 +- 在该窗口激活时通知 `Actions` 层观察焦点路由 + +## 当前实现边界 + +- 当前没有真正的编辑器视口渲染、相机操控或 gizmo 逻辑。 +- 它现在更像后续 Scene View 功能的面板占位入口。 + +## 相关文档 + +- [panels](../panels.md) +- [Actions](../../Actions/Actions.md) diff --git a/docs/api/XCEngine/Editor/panels/panels.md b/docs/api/XCEngine/Editor/panels/panels.md new file mode 100644 index 00000000..fc630ae8 --- /dev/null +++ b/docs/api/XCEngine/Editor/panels/panels.md @@ -0,0 +1,37 @@ +# panels + +**命名空间**: `XCEngine::Editor` + +**类型**: `submodule` + +**描述**: 编辑器面板基础设施与具体面板集合，当前以 `Panel` 基类和 `PanelCollection` 容器为核心。 + +## 概述 + +`editor/src/panels` 目录当前包含菜单栏、Hierarchy、SceneView、GameView、Inspector、Console、Project 等具体面板。 + +当前这组文档当前覆盖了： + +- [Panel](Panel/Panel.md) +- [PanelCollection](PanelCollection/PanelCollection.md) +- [MenuBar](MenuBar/MenuBar.md) +- [HierarchyPanel](HierarchyPanel/HierarchyPanel.md) +- [ProjectPanel](ProjectPanel/ProjectPanel.md) +- [InspectorPanel](InspectorPanel/InspectorPanel.md) +- [ConsolePanel](ConsolePanel/ConsolePanel.md) +- [SceneViewPanel](SceneViewPanel/SceneViewPanel.md) +- [GameViewPanel](GameViewPanel/GameViewPanel.md) + +## 设计说明 + +当前面板系统的思路很直接： + +- 每个面板继承 `Panel` +- 生命周期由 `PanelCollection` 统一调度 +- 上下文通过 `IEditorContext*` 注入到每个面板 + +## 相关文档 + +- [Editor 模块](../Editor.md) +- [EditorWorkspace](../Core/EditorWorkspace/EditorWorkspace.md) +- [Layers](../Layers/Layers.md) diff --git a/docs/api/XCEngine/XCEngine.md b/docs/api/XCEngine/XCEngine.md index 19aa7d2b..6629c7fb 100644 --- a/docs/api/XCEngine/XCEngine.md +++ b/docs/api/XCEngine/XCEngine.md @@ -4,11 +4,13 @@ **类型**: `module-root` -**描述**: 与 `engine/include/XCEngine` 平行的 API 文档根目录。 +**描述**: 以 `XCEngine` 为统一入口的 API 文档根目录；主体与 `engine/include/XCEngine` 平行，同时承载独立编辑器应用 `editor/src` 的 `Editor` API 文档。 ## 概览 -该目录与 `XCEngine` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。 +该目录的主体与 `engine/include/XCEngine` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。 + +额外地，当前也在这里统一收纳了 [Editor](Editor/Editor.md) 应用层文档，用于描述独立编辑器程序 `editor/src/**` 的 API 与架构。 ## 子目录 @@ -16,10 +18,12 @@ - [Components](Components/Components.md) - [Core](Core/Core.md) - [Debug](Debug/Debug.md) +- [Editor](Editor/Editor.md) - [Input](Input/Input.md) - [Memory](Memory/Memory.md) - [Platform](Platform/Platform.md) - [RHI](RHI/RHI.md) +- [Rendering](Rendering/Rendering.md) - [Resources](Resources/Resources.md) - [Scene](Scene/Scene.md) - [Threading](Threading/Threading.md) diff --git a/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md b/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md new file mode 100644 index 00000000..9c6c2bb4 --- /dev/null +++ b/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md @@ -0,0 +1,153 @@ +# Editor Architecture And Workflow + +## 先建立正确心智模型 + +`docs/api/XCEngine/Editor/**` 对应的是编辑器应用层，而不是引擎运行时 public API。 +它更接近 Unity Editor、Unreal Editor 这类“工具壳层”的实现文档，而不是给游戏逻辑直接链接的稳定 SDK。 + +可以把当前架构粗略理解成六层： + +1. `Platform` 负责 Win32 进程、窗口消息、崩溃日志和 D3D12 窗口渲染。 +2. `UI` 负责 ImGui 会话、主题、面板 chrome 和通用控件。 +3. `Core` 负责上下文、事件总线、动作路由、选择和撤销。 +4. `Managers` 负责项目和场景服务的默认实现。 +5. `Actions` 负责把按钮、菜单和快捷键翻译成“可执行动作”。 +6. `Commands` 负责真正修改项目、场景、实体和组件状态。 + +`panels`、`Layout` 和 `ComponentEditors` 则横向挂在这些层之间： + +- `panels` 是用户直接看到的编辑器窗口 +- `Layout` 决定这些窗口如何 Dock +- `ComponentEditors` 决定 Inspector 如何按组件类型渲染 + +## 为什么要拆成 Actions 和 Commands + +这是当前 Editor 文档里最重要的一条设计线。 +如果不拆，最常见的退化就是： + +- 菜单栏自己写一套保存逻辑 +- 快捷键自己写一套删除逻辑 +- 右键菜单再写一套复制粘贴逻辑 + +时间一长，你会得到三个入口、三份行为、三种 bug。 + +当前实现把它拆成： + +- `EditorActions` 定义动作名称、快捷键和启用状态 +- `ActionRouting` 和 `EditorActionRoute` 决定当前动作应该作用在哪个面板上下文 +- `*ActionRouter` 负责具体入口的 UI 交互 +- `Commands` 负责真正修改状态 + +这就是商业编辑器很常见的分层方式。Unity 用户会很容易理解这件事： +菜单项、快捷键和 Inspector 按钮看起来入口不同，但背后应该落到同一条编辑命令语义上。 + +## 为什么 Inspector 不走完全反射，而是组件专用 editor + +当前 Inspector 采用的是： + +- `IComponentEditor` +- `ComponentEditorRegistry` +- `TransformComponentEditor` +- `CameraComponentEditor` +- `LightComponentEditor` + +这条路线更接近 Unity 的 custom inspector / property drawer 思想，而不是“把所有字段自动反射成一张表”。 + +这样做的好处是： + +- 条件式 UI 更自然，例如 Camera 的透视/正交分支 +- 撤销、字段分组和按钮布局更可控 +- 组件编辑体验可以按照组件语义而不是成员变量顺序组织 + +代价是： + +- 每个组件都要写专门 editor +- 通用自动化程度较低 + +但对当前阶段的编辑器，这是更稳妥的商业级做法，因为它优先保证可解释性和可维护性。 + +## 从一次用户点击看整条链路 + +以 Hierarchy 中“右键删除实体”为例，当前主路径大致是： + +1. `HierarchyPanel` 负责渲染树和弹出上下文菜单。 +2. `HierarchyActionRouter` 负责把“Delete”菜单项映射为删除动作。 +3. `EntityCommands::DeleteEntity` 负责发起真正的场景修改。 +4. `UndoUtils` 和 `UndoManager` 负责录制撤销快照。 +5. `SceneManager` 负责真正删除实体并发布事件。 +6. `SelectionManager`、`InspectorPanel` 等其它系统通过事件感知更新。 + +这条链路说明了一个核心原则： +面板不应该直接修改场景，面板应该只描述用户意图。 + +## 为什么当前大量使用小型 helper header + +很多用户第一次看会觉得：为什么 `UI`、`Actions`、`Commands` 下有这么多小头文件？ + +这是 Dear ImGui 风格编辑器常见的工程取舍。原因很现实： + +- 即时模式 UI 很容易把一切都塞进 `Render()` +- 一旦不拆 helper，单个面板 cpp 会迅速膨胀 +- 把“交互语义”“控件语义”“状态容器”拆成小头文件后，代码更容易复用和迁移 + +所以这些 header 不是“碎片化设计”，而是在对抗 UI 工具代码天然容易失控的问题。 + +## 当前架构最像 Unity 的部分 + +- `HierarchyPanel / ProjectPanel / InspectorPanel / ConsolePanel` 这组窗口组合很像 Unity Editor 的基本工作区。 +- `ComponentEditors` 很像 Unity 的 custom inspector。 +- `SceneCommands + UndoManager` 很像 Unity 编辑态里对场景对象做结构修改时的命令路径。 + +## 当前又明显还不像 Unity 的地方 + +- 当前只有 Windows + D3D12 + ImGui 主路径。 +- Project 面板还不是完整资产导入系统。 +- Inspector 还没有脚本组件、搜索式 Add Component、批量多选混合值等成熟体验。 +- Console 还是轻量列表，不是完整诊断中心。 + +所以更准确的表述应该是： +它采用了很多 Unity 风格的编辑器设计理念，但当前实现仍然是一个处在快速重构期的、轻量但方向正确的编辑器壳层。 + +## 如果你要继续扩展这个编辑器，推荐从哪层下手 + +### 新增一个全新面板 + +通常顺序是： + +1. 在 `panels` 下建立新 Panel 类型。 +2. 优先复用 `PanelWindowScope / PanelToolbarScope / PanelContentScope`。 +3. 如果面板需要上下文敏感快捷键，再接入 `ActionRouting`。 +4. 如果面板要真正修改数据，优先写 `Commands`，不要直接改 manager。 + +### 给 Inspector 新增一个组件编辑器 + +推荐顺序是： + +1. 实现新的 `IComponentEditor`。 +2. 在 `ComponentEditorRegistry` 注册。 +3. 优先通过 `PropertyGrid`、`ScalarControls`、`VectorControls` 组装 UI。 +4. 涉及结构性变化时，通过 `ComponentCommands` 或新的命令 helper 进入撤销链。 + +### 给菜单栏或快捷键新增动作 + +推荐顺序是： + +1. 在 `EditorActions` 中先定义动作描述。 +2. 在合适的 `*ActionRouter` 中接 UI 入口。 +3. 真实变更落到 `Commands`。 +4. 如果动作取决于当前焦点面板，再考虑是否需要新的 `EditorActionRoute`。 + +## 当前文档应该怎么读 + +如果你是第一次接触这一套代码，推荐按这个顺序： + +1. [Editor](../../XCEngine/Editor/Editor.md) +2. [Application](../../XCEngine/Editor/Application/Application.md) +3. [Core](../../XCEngine/Editor/Core/Core.md) +4. [Actions](../../XCEngine/Editor/Actions/Actions.md) +5. [Commands](../../XCEngine/Editor/Commands/Commands.md) +6. [panels](../../XCEngine/Editor/panels/panels.md) +7. [ComponentEditors](../../XCEngine/Editor/ComponentEditors/ComponentEditors.md) +8. [UI](../../XCEngine/Editor/UI/UI.md) + +这能让你先看清系统骨架，再下钻到具体类型页，而不是一开始就陷进某个 helper 文件里。