docs: add editor scripting workflow docs
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
# EditorScriptAssemblyBuilder
|
||||
|
||||
**命名空间**: `XCEngine::Editor::Scripting`
|
||||
|
||||
**类型**: `class`
|
||||
|
||||
**源文件**: `editor/src/Scripting/EditorScriptAssemblyBuilder.h`
|
||||
|
||||
**描述**: 负责把 Editor 项目里的 C# 源码编译成 `Library/ScriptAssemblies` 下的脚本程序集。
|
||||
|
||||
## 概述
|
||||
|
||||
`EditorScriptAssemblyBuilder` 是当前 Editor 脚本工作流里真正执行“编译”的那一层。
|
||||
|
||||
它会把两类源码分别编成：
|
||||
|
||||
- `XCEngine.ScriptCore.dll`
|
||||
- `GameScripts.dll`
|
||||
|
||||
并把结果统一落到：
|
||||
|
||||
- `<project>/Library/ScriptAssemblies/`
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [RebuildProjectAssemblies](RebuildProjectAssemblies.md) | 全量重建项目脚本程序集并返回结果消息。 |
|
||||
|
||||
这是当前唯一入口。返回 `EditorScriptAssemblyBuildResult`：
|
||||
|
||||
- `succeeded`
|
||||
- `message`
|
||||
|
||||
## 当前重建流程
|
||||
|
||||
按 `EditorScriptAssemblyBuilder.cpp` 当前实现，主流程大致是：
|
||||
|
||||
1. 校验项目路径非空。
|
||||
2. 解析仓库根与 Mono 根目录。
|
||||
3. 创建 `<project>/Library/ScriptAssemblies`。
|
||||
4. 在 `PATH` 上查找 `dotnet.exe`。
|
||||
5. 运行 `dotnet --list-sdks`，取最后一条 SDK 版本。
|
||||
6. 定位该 SDK 下的 `Roslyn/bincore/csc.dll`。
|
||||
7. 校验 `.NET Framework 4.7.2` 参考程序集存在。
|
||||
8. 收集 `managed/XCEngine.ScriptCore/**/*.cs`。
|
||||
9. 收集 `<project>/Assets/**/*.cs`。
|
||||
10. 若项目脚本为空，则生成 `Generated/EmptyProjectGameScripts.cs` 占位文件。
|
||||
11. 先编译 `XCEngine.ScriptCore.dll`。
|
||||
12. 仅当输出目录里还没有项目本地 `mscorlib.dll` 时，才从 Mono 目录复制一份；如果已经存在，则直接复用旧文件，避免在增量重建时覆盖仍可能被 Mono 映射的 corlib。
|
||||
13. 再引用 `XCEngine.ScriptCore.dll` 编译 `GameScripts.dll`。
|
||||
|
||||
## 真实使用位置
|
||||
|
||||
- `Application.cpp` 会在重建脚本程序集时调用它。
|
||||
- `tests/editor/test_editor_script_assembly_builder.cpp` 当前覆盖了两类关键语义：
|
||||
- 成功路径：`XCEngine.ScriptCore.dll`、`GameScripts.dll` 与项目本地 `mscorlib.dll` 都会落到 `Library/ScriptAssemblies`
|
||||
- 锁语义：如果活动 Mono runtime 仍持有已加载的 `GameScripts.dll`，直接重建会失败；释放 runtime 后再重建则可以成功并看到新增脚本类型
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 当前是全量重建，不是增量编译。
|
||||
- 编译链明显依赖 Windows 路径和本机安装的 `dotnet` SDK。
|
||||
- 参考程序集路径当前写死在 `.NET Framework 4.7.2` 目录。
|
||||
- 构建器本身不会主动卸载当前脚本运行时；如果调用方没有先释放 Mono app domain，`GameScripts.dll` 仍可能因为文件锁而构建失败。
|
||||
- 若外部环境缺少 `dotnet.exe`、Roslyn 或参考程序集，返回的只是一条失败消息，而不是更复杂的恢复策略。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Scripting](../Scripting.md)
|
||||
- [EditorScriptAssemblyBuilderUtils](../EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md)
|
||||
- [EditorScriptRuntimeStatus](../EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md)
|
||||
@@ -0,0 +1,68 @@
|
||||
# EditorScriptAssemblyBuilder::RebuildProjectAssemblies
|
||||
|
||||
**命名空间**: `XCEngine::Editor::Scripting`
|
||||
|
||||
**类型**: `method`
|
||||
|
||||
**源文件**: `editor/src/Scripting/EditorScriptAssemblyBuilder.h`
|
||||
|
||||
## 签名
|
||||
|
||||
```cpp
|
||||
static EditorScriptAssemblyBuildResult RebuildProjectAssemblies(const std::string& projectPath);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
把指定项目下的托管脚本源码全量编译到 `Library/ScriptAssemblies` 目录，并返回成功/失败消息。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
### 1. 解析路径与外部工具
|
||||
|
||||
- 要求 `projectPath` 非空，否则直接返回失败结果。
|
||||
- 会解析：
|
||||
- 仓库根目录
|
||||
- Mono 根目录
|
||||
- `managed/XCEngine.ScriptCore`
|
||||
- `<project>/Library/ScriptAssemblies`
|
||||
- 当前依赖系统 `PATH` 上可找到 `dotnet.exe`，并通过 `dotnet --list-sdks` 解析最新 SDK 版本，再定位对应 `Roslyn/bincore/csc.dll`。
|
||||
|
||||
### 2. 校验引用与源文件
|
||||
|
||||
- 校验 `.NET Framework 4.7.2` 参考程序集存在：
|
||||
- `mscorlib.dll`
|
||||
- `System.dll`
|
||||
- `System.Core.dll`
|
||||
- 校验 Mono 自带 `binary/mscorlib.dll` 存在。
|
||||
- 收集两组 C# 源文件：
|
||||
- `managed/XCEngine.ScriptCore/**/*.cs`
|
||||
- `<project>/Assets/**/*.cs`
|
||||
- 若项目脚本为空，会生成 `Generated/EmptyProjectGameScripts.cs` 占位源码。
|
||||
|
||||
### 3. 编译输出
|
||||
|
||||
- 先编译 `XCEngine.ScriptCore.dll`。
|
||||
- 仅当输出目录里还没有项目本地 `mscorlib.dll` 时，才从 Mono 目录复制一份；如果已经存在，则直接复用旧文件。
|
||||
- 然后引用 `XCEngine.ScriptCore.dll` 编译 `GameScripts.dll`。
|
||||
- 成功时返回：
|
||||
- `succeeded = true`
|
||||
- `message = "Rebuilt script assemblies in ..."`
|
||||
|
||||
### 4. 失败语义
|
||||
|
||||
- 任意路径校验、进程启动、编译失败、首次 `mscorlib.dll` 复制失败，或目标程序集仍被活动 Mono runtime 持有时，都会返回 `succeeded = false`。
|
||||
- 这个函数本身不负责关闭现有脚本运行时；如果调用方在同一进程里仍持有已加载的 `GameScripts.dll`，重建可能因为文件锁失败。
|
||||
- 函数内部还包了一层 `try/catch`，用于把标准异常和未知异常转成失败消息。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 当前是全量重建，不做增量分析。
|
||||
- 平台和工具链路径明显偏向 Windows + 本机安装 `.NET SDK`。
|
||||
- 参考程序集版本当前固定为 `.NET Framework 4.7.2`。
|
||||
- 输出目录里的 `mscorlib.dll` 当前采用“首次复制、后续复用”的策略，不会在每次重建时强制覆盖。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [EditorScriptAssemblyBuilder](EditorScriptAssemblyBuilder.md)
|
||||
- [EditorScriptAssemblyBuilderUtils](../EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md)
|
||||
@@ -0,0 +1,48 @@
|
||||
# EditorScriptAssemblyBuilderUtils
|
||||
|
||||
**命名空间**: `XCEngine::Editor::Scripting`
|
||||
|
||||
**类型**: `utility header`
|
||||
|
||||
**源文件**: `editor/src/Scripting/EditorScriptAssemblyBuilderUtils.h`
|
||||
|
||||
**描述**: 提供脚本程序集构建流程使用的路径转换、源码收集、SDK 版本解析和空项目占位源码 helper。
|
||||
|
||||
## 概述
|
||||
|
||||
`EditorScriptAssemblyBuilderUtils.h` 是 [EditorScriptAssemblyBuilder](../EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md) 的一组纯 helper。
|
||||
|
||||
它主要做四类小事：
|
||||
|
||||
- 路径转 UTF-8
|
||||
- 递归收集 `.cs` 源码
|
||||
- 从 `dotnet --list-sdks` 输出里取最新 SDK 版本
|
||||
- 在项目没有脚本时生成一个可编译的占位源码文件
|
||||
|
||||
## 公开函数
|
||||
|
||||
| 函数 | 当前行为 |
|
||||
|------|------|
|
||||
| `ScriptBuilderPathToUtf8()` | 把 `filesystem::path` 转成 UTF-8 字符串。 |
|
||||
| `CollectCSharpSourceFiles()` | 递归收集指定根目录下所有 `.cs` 文件，并按路径排序。 |
|
||||
| `ParseLatestDotnetSdkVersion()` | 逐行扫描 `dotnet --list-sdks` 输出，返回最后一条版本号。 |
|
||||
| `EnsurePlaceholderProjectScriptSource()` | 当项目没有任何脚本时，创建 `EmptyProjectGameScriptsMarker` 占位源码。 |
|
||||
|
||||
## 测试覆盖
|
||||
|
||||
`tests/editor/test_editor_script_assembly_builder_utils.cpp` 当前已覆盖：
|
||||
|
||||
- `.cs` 文件递归收集与排序
|
||||
- SDK 版本解析
|
||||
- 占位源码创建与幂等行为
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- `ParseLatestDotnetSdkVersion()` 默认把最后一条有效行视为最新 SDK，没有做语义化版本比较。
|
||||
- 占位脚本只服务于“项目没有任何脚本但仍需要产出 GameScripts.dll”这一特例。
|
||||
- 这组 helper 明显偏向当前构建器实现，并不是通用 C# 项目扫描库。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Scripting](../Scripting.md)
|
||||
- [EditorScriptAssemblyBuilder](../EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md)
|
||||
@@ -0,0 +1,47 @@
|
||||
# EditorScriptRuntimeStatus
|
||||
|
||||
**命名空间**: `XCEngine::Editor`
|
||||
|
||||
**类型**: `struct`
|
||||
|
||||
**源文件**: `editor/src/Scripting/EditorScriptRuntimeStatus.h`
|
||||
|
||||
**描述**: 汇总编辑器当前脚本后端、程序集发现和运行时加载状态的轻量状态对象。
|
||||
|
||||
## 概述
|
||||
|
||||
`EditorScriptRuntimeStatus` 是脚本相关 UI 和应用层之间的最小状态契约。它不负责构建程序集，也不负责执行脚本，只负责把当前脚本子系统是否可用描述清楚。
|
||||
|
||||
## 字段
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `backendEnabled` | 当前构建是否启用了脚本后端。 |
|
||||
| `assembliesFound` | 预期程序集目录里是否已经找到了脚本程序集。 |
|
||||
| `runtimeLoaded` | 运行时后端是否已经成功载入。 |
|
||||
| `assemblyDirectory` | 当前脚本程序集目录。 |
|
||||
| `statusMessage` | 面向 UI 的状态提示文本。 |
|
||||
|
||||
## 真实使用位置
|
||||
|
||||
- `Application` 持有一份当前状态并通过 `GetScriptRuntimeStatus()` 暴露出去。
|
||||
- `ScriptComponentEditor` 和 `ScriptComponentEditorUtils` 用它决定：
|
||||
- 是否显示脚本不可用提示
|
||||
- 是否允许 `Reload Scripts`
|
||||
- 是否允许 `Rebuild Scripts`
|
||||
|
||||
## 当前设计取向
|
||||
|
||||
它刻意保持很轻：
|
||||
|
||||
- 没有复杂错误码
|
||||
- 没有后端枚举
|
||||
- 没有状态机方法
|
||||
|
||||
因为当前目的只是给 Inspector 和菜单层提供足够稳定、足够可展示的一份脚本状态快照。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Scripting](../Scripting.md)
|
||||
- [Application](../../Application/Application.md)
|
||||
- [ScriptComponentEditorUtils](../../ComponentEditors/ScriptComponentEditorUtils/ScriptComponentEditorUtils.md)
|
||||
43
docs/api/XCEngine/Editor/Scripting/Scripting.md
Normal file
43
docs/api/XCEngine/Editor/Scripting/Scripting.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Scripting
|
||||
|
||||
**命名空间**: `XCEngine::Editor::Scripting`
|
||||
|
||||
**类型**: `submodule`
|
||||
|
||||
**描述**: 编辑器侧脚本程序集构建与脚本运行时状态子模块，负责项目 C# 程序集重建和相关状态反馈。
|
||||
|
||||
## 概述
|
||||
|
||||
`editor/src/Scripting` 当前不是游戏运行时脚本系统本身，而是 Editor 为脚本工作流补的那一层工具能力。
|
||||
|
||||
它主要回答两类问题：
|
||||
|
||||
- 当前脚本后端和程序集是否可用
|
||||
- 项目 `Assets/**/*.cs` 如何重建成 `Library/ScriptAssemblies/*.dll`
|
||||
|
||||
## 当前链路
|
||||
|
||||
1. [EditorScriptAssemblyBuilder](EditorScriptAssemblyBuilder/EditorScriptAssemblyBuilder.md)
|
||||
负责真正调用 `dotnet + csc.dll` 生成 `XCEngine.ScriptCore.dll` 与 `GameScripts.dll`
|
||||
2. [EditorScriptAssemblyBuilderUtils](EditorScriptAssemblyBuilderUtils/EditorScriptAssemblyBuilderUtils.md)
|
||||
负责收集源码、解析 SDK 版本和兜底生成空脚本占位文件
|
||||
3. [EditorScriptRuntimeStatus](EditorScriptRuntimeStatus/EditorScriptRuntimeStatus.md)
|
||||
负责把“后端启用、程序集是否找到、运行时是否已加载、当前提示文本”等状态传给 UI
|
||||
|
||||
## 真实调用关系
|
||||
|
||||
- `Application.cpp` 在切项目和重载脚本运行时时更新 `EditorScriptRuntimeStatus`
|
||||
- `Application.cpp` 也会通过 `EditorScriptAssemblyBuilder` 触发脚本程序集重建
|
||||
- `ScriptComponentEditor` 与 `ScriptComponentEditorUtils` 会读取 runtime status，决定显示 `Rebuild Scripts` / `Reload Scripts` 按钮和提示文案
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 这组代码明显面向 Windows 桌面开发环境，依赖 `dotnet.exe` 和本机参考程序集路径。
|
||||
- 它只管 Editor 侧程序集构建与状态反馈，不直接承载运行时脚本执行。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Editor](../Editor.md)
|
||||
- [Application](../Application/Application.md)
|
||||
- [ScriptComponentEditor](../ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md)
|
||||
- [Scripting](../../Scripting/Scripting.md)
|
||||
Reference in New Issue
Block a user