vault backup: 2026-05-31 16:07:40
This commit is contained in:
@@ -1,263 +0,0 @@
|
|||||||
---
|
|
||||||
tags:
|
|
||||||
- UE
|
|
||||||
- EasyEditorPlugin
|
|
||||||
- Puerts
|
|
||||||
- Editor
|
|
||||||
- TypeScript
|
|
||||||
created: 2026-05-31
|
|
||||||
---
|
|
||||||
|
|
||||||
# EasyEditorPlugin 架构分析
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
EasyEditorPlugin 是 `johnche`（腾讯，也是 Puerts 的作者）开发的 Unreal Engine **编辑器快速扩展插件**。它将 V8 JavaScript 运行时（通过 Puerts 的 `FJsEnv`）嵌入 Unreal Editor，让开发者可以用 TypeScript/JavaScript 编写编辑器扩展，而非 C++。
|
|
||||||
|
|
||||||
- **仓库**: `D:\MatrixTA\EasyEditorPlugin`
|
|
||||||
- **许可证**: MIT
|
|
||||||
- **引擎兼容**: UE 5.3+
|
|
||||||
- **核心价值**: 几行 TypeScript 完成编辑器菜单、工具栏、控制台命令、Detail 面板定制，支持热重载
|
|
||||||
|
|
||||||
## 目录结构
|
|
||||||
|
|
||||||
```
|
|
||||||
EasyEditorPlugin/
|
|
||||||
├── .gitignore
|
|
||||||
├── EasyEditorPlugin.uplugin # UE 插件描述符
|
|
||||||
├── LICENSE # MIT
|
|
||||||
├── README.md # 使用文档（英文）
|
|
||||||
├── Resources/
|
|
||||||
│ └── Icon128.png # 插件图标
|
|
||||||
├── Doc/
|
|
||||||
│ ├── extension.md # 第三方 C++ 库扩展指南
|
|
||||||
│ └── Pic/
|
|
||||||
│ └── easyeditor.gif # 演示动画
|
|
||||||
└── Source/
|
|
||||||
└── EasyEditorPlugin/
|
|
||||||
├── EasyEditorPlugin.Build.cs # UE 构建规则
|
|
||||||
├── Public/
|
|
||||||
│ └── EasyEditorPlugin.h # 模块头文件（公开 API）
|
|
||||||
└── Private/
|
|
||||||
└── EasyEditorPlugin.cpp # 完整实现（~320 行）
|
|
||||||
```
|
|
||||||
|
|
||||||
**单模块 Editor 插件**，无 Runtime/Gameplay 模块。
|
|
||||||
|
|
||||||
## .uplugin 定义
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"FileVersion": 3,
|
|
||||||
"Version": 1,
|
|
||||||
"VersionName": "1.0",
|
|
||||||
"FriendlyName": "EasyEditorPlugin",
|
|
||||||
"CanContainContent": true,
|
|
||||||
"Modules": [{
|
|
||||||
"Name": "EasyEditorPlugin",
|
|
||||||
"Type": "Editor", // ← 仅在 Unreal Editor 中加载
|
|
||||||
"LoadingPhase": "Default"
|
|
||||||
}],
|
|
||||||
"Plugins": [{
|
|
||||||
"Name": "Puerts",
|
|
||||||
"Enabled": true // ← 硬依赖 Puerts
|
|
||||||
}]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Build.cs 模块依赖
|
|
||||||
|
|
||||||
| 依赖 | 类型 | 用途 |
|
|
||||||
|------|------|------|
|
|
||||||
| `Core` | Public | 基础 UE 类型（`FString`, `TSharedPtr` 等） |
|
|
||||||
| `CoreUObject` | Private | UObject 系统 |
|
|
||||||
| `Engine` | Private | Engine 层类型 |
|
|
||||||
| `Slate` | Private | Slate UI 框架 |
|
|
||||||
| `SlateCore` | Private | 核心 Slate 类型（`FSlateIcon`） |
|
|
||||||
| `ToolMenus` | Private | UE5 可扩展菜单系统 |
|
|
||||||
| `UnrealEd` | Private | 编辑器 API（地图变更通知等） |
|
|
||||||
| `ContentBrowserData` | Private | Content Browser 上下文菜单 |
|
|
||||||
| **`JsEnv`** | Private | **Puerts JavaScript 环境** |
|
|
||||||
|
|
||||||
## 公开 API（`EasyEditorPlugin.h`）
|
|
||||||
|
|
||||||
```cpp
|
|
||||||
class FEasyEditorPluginModule : public IModuleInterface
|
|
||||||
{
|
|
||||||
public:
|
|
||||||
virtual void StartupModule() override;
|
|
||||||
virtual void ShutdownModule() override;
|
|
||||||
|
|
||||||
std::function<void()> OnJsEnvPreReload; // JS 环境重启前回调
|
|
||||||
std::function<void(const FString&)> Eval; // 执行 JS 字符串
|
|
||||||
TSparseArray<TUniquePtr<FAutoConsoleCommand>> TsConsoleCommands; // TS 注册的控制台命令
|
|
||||||
FSimpleMulticastDelegate OnJsEnvCleanup; // JS 环境清理广播
|
|
||||||
|
|
||||||
private:
|
|
||||||
TSharedPtr<puerts::FJsEnv> JsEnv; // ← 私有！外部无法访问
|
|
||||||
TSharedPtr<puerts::FSourceFileWatcher> SourceFileWatcher;
|
|
||||||
TUniquePtr<FAutoConsoleCommand> ConsoleCommand;
|
|
||||||
bool StartupScriptCalled = false;
|
|
||||||
|
|
||||||
void OnPostEngineInit();
|
|
||||||
void InitJsEnv();
|
|
||||||
void UnInitJsEnv();
|
|
||||||
bool Tick(float);
|
|
||||||
void HandleMapChanged(UWorld* InWorld, EMapChangeType InMapChangeType);
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
**关键点：`JsEnv` 是私有成员，外部 C++ 代码无法直接获取 JS 函数/对象。**
|
|
||||||
|
|
||||||
## Puerts 绑定（`AutoRegisterForEEP`）
|
|
||||||
|
|
||||||
静态初始化器在模块加载前（`StartupModule` 之前）自动注册以下 C++ 类型到 V8：
|
|
||||||
|
|
||||||
| C++ 类型 | 暴露的功能 |
|
|
||||||
|-----------|----------|
|
|
||||||
| `FSlateIcon` | 三个构造函数重载 |
|
|
||||||
| `FToolMenuEntry` | `InitMenuEntry`, `InitToolBarButton`, `InitComboButton` |
|
|
||||||
| `EasyEditorPlugin` | `SetOnJsEnvPreReload`, `SetEval`, `AddConsoleCommand`, `RemoveConsoleCommand` |
|
|
||||||
| `FContentBrowserItem` | `IsFolder`, `IsFile`, `GetItemName`, `GetItemPhysicalPath` |
|
|
||||||
|
|
||||||
## 生命周期
|
|
||||||
|
|
||||||
```
|
|
||||||
Module Load → AutoRegisterForEEP 构造（注册 Puerts 绑定）
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
StartupModule()
|
|
||||||
├── 设置 V8 --expose-gc 标志（允许显式 GC）
|
|
||||||
├── 注册 OnPostEngineInit 回调
|
|
||||||
└── 注册 OnMapChanged 处理器（地图卸载时 GC）
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
OnPostEngineInit()
|
|
||||||
├── InitJsEnv()
|
|
||||||
│ ├── 创建 FSourceFileWatcher（热重载）
|
|
||||||
│ └── 创建 FJsEnv，ModuleLoader 指向 "EasyEditorScripts"
|
|
||||||
├── 注册每帧 Tick
|
|
||||||
├── 注册 "EasyEditor.Restart" 控制台命令
|
|
||||||
└── 注册 "TypeScript" UToolMenus 字符串命令处理器
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
First Tick()
|
|
||||||
└── JsEnv->Start("Main") // 执行 Main.ts
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
[热重载循环]
|
|
||||||
SourceFileWatcher 检测文件变更
|
|
||||||
→ 读取文件
|
|
||||||
→ JsEnv->ReloadSource(InPath, Content)
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
ShutdownModule()
|
|
||||||
└── UnInitJsEnv()
|
|
||||||
├── Broadcast OnJsEnvCleanup
|
|
||||||
├── 清除 Eval / OnJsEnvPreReload
|
|
||||||
├── 清空 TsConsoleCommands
|
|
||||||
└── 重置 JsEnv 和 SourceFileWatcher
|
|
||||||
```
|
|
||||||
|
|
||||||
## `InitJsEnv()` 详细分析
|
|
||||||
|
|
||||||
```cpp
|
|
||||||
void FEasyEditorPluginModule::InitJsEnv()
|
|
||||||
{
|
|
||||||
// 1. 创建文件监听器（用于热重载）
|
|
||||||
SourceFileWatcher = MakeShared<puerts::FSourceFileWatcher>(
|
|
||||||
[this](const FString& InPath) {
|
|
||||||
if (JsEnv.IsValid()) {
|
|
||||||
TArray<uint8> Source;
|
|
||||||
if (FFileHelper::LoadFileToArray(Source, *InPath)) {
|
|
||||||
JsEnv->ReloadSource(InPath, puerts::PString(
|
|
||||||
(const char*)Source.GetData(), Source.Num()));
|
|
||||||
}
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
// 2. 创建 JsEnv
|
|
||||||
// 关键: DefaultJSModuleLoader("EasyEditorScripts")
|
|
||||||
// → 从项目 Content/EasyEditorScripts/ 加载 TS 文件
|
|
||||||
JsEnv = MakeShared<puerts::FJsEnv>(
|
|
||||||
std::make_shared<puerts::DefaultJSModuleLoader>(TEXT("EasyEditorScripts")),
|
|
||||||
std::make_shared<puerts::FDefaultLogger>(), -1,
|
|
||||||
[this](const FString& InPath) {
|
|
||||||
if (SourceFileWatcher.IsValid()) {
|
|
||||||
SourceFileWatcher->OnSourceLoaded(InPath);
|
|
||||||
}
|
|
||||||
});
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**当前限制**：
|
|
||||||
- `DefaultJSModuleLoader("EasyEditorScripts")` 只在项目 `Content/` 目录下搜索
|
|
||||||
- 不搜索插件 Content 目录
|
|
||||||
- 不能直接从插件的 `Resources/` 或 `Content/` 加载 TS
|
|
||||||
|
|
||||||
## 编辑器集成能力
|
|
||||||
|
|
||||||
### 菜单扩展（`UToolMenus`）
|
|
||||||
- `FToolMenuEntry.InitMenuEntry` — 添加普通菜单项
|
|
||||||
- `FToolMenuEntry.InitToolBarButton` — 添加工具栏按钮
|
|
||||||
- `FToolMenuEntry.InitComboButton` — 添加下拉工具栏按钮
|
|
||||||
|
|
||||||
### Content Browser 上下文菜单
|
|
||||||
- `FContentBrowserItem.IsFolder()`, `IsFile()`, `GetItemName()`, `GetItemPhysicalPath()`
|
|
||||||
|
|
||||||
### 控制台命令
|
|
||||||
- `EasyEditorPlugin.AddConsoleCommand(name, help, callback)` — 注册控制台命令
|
|
||||||
- `EasyEditorPlugin.RemoveConsoleCommand(index)` — 注销
|
|
||||||
|
|
||||||
### String Command Handler
|
|
||||||
`UToolMenus::RegisterStringCommandHandler("TypeScript", ...)` 让菜单项可以触发任意 TypeScript 代码。
|
|
||||||
|
|
||||||
### 重启命令
|
|
||||||
内置 `EasyEditor.Restart` 控制台命令：销毁 JS 环境 → 重新创建 → 重新加载 Main 脚本。
|
|
||||||
|
|
||||||
## 扩展点（给其他插件使用）
|
|
||||||
|
|
||||||
| 扩展点 | 类型 | 用途 |
|
|
||||||
|--------|------|------|
|
|
||||||
| `OnJsEnvCleanup` | `FSimpleMulticastDelegate` | JS 环境销毁前，其他插件清理状态 |
|
|
||||||
| `OnJsEnvPreReload` | `std::function<void()>` | 重启前执行 |
|
|
||||||
| `Eval` | `std::function<void(const FString&)>` | 执行任意 JS 字符串 |
|
|
||||||
|
|
||||||
其他插件的集成方式（以 EasyEditor_ImGui 为例）：
|
|
||||||
|
|
||||||
```cpp
|
|
||||||
// 注册清理回调
|
|
||||||
FModuleManager::LoadModuleChecked<FEasyEditorPluginModule>("EasyEditorPlugin")
|
|
||||||
.OnJsEnvCleanup.AddLambda([]() {
|
|
||||||
// 清理状态
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
## 脚本组织
|
|
||||||
|
|
||||||
- **脚本目录**: `Content/EasyEditorScripts/`（项目 Content 下）
|
|
||||||
- **入口文件**: `Main.js` 或 `Main.ts`
|
|
||||||
- **语言**: TypeScript（主要）/ JavaScript
|
|
||||||
- **热重载**: ✅ 支持
|
|
||||||
|
|
||||||
## 当前缺少的能力
|
|
||||||
|
|
||||||
1. **JsEnv 不公开** — 外部 C++ 无法获取 JS 函数引用（`FJsObject`）
|
|
||||||
2. **ModuleLoader 不灵活** — 只支持项目 Content 目录，不支持插件 Content 目录
|
|
||||||
3. **Editor-Only** — 无法用于游戏运行时业务逻辑
|
|
||||||
4. **无返回值调用** — `Eval` 只能执行字符串，无法获取返回值
|
|
||||||
5. **无结构化的 C++ → TS 调用 API** — 只能通过字符串 Eval 或 UE 反射间接调用
|
|
||||||
|
|
||||||
## 总结
|
|
||||||
|
|
||||||
| 方面 | 详情 |
|
|
||||||
|------|------|
|
|
||||||
| 设计目标 | 编辑器快速扩展 |
|
|
||||||
| 插件类型 | Editor-only |
|
|
||||||
| 运行时引擎 | V8（通过 `puerts::FJsEnv`） |
|
|
||||||
| 脚本语言 | TypeScript / JavaScript |
|
|
||||||
| 脚本入口 | `Main.ts`，从 `EasyEditorScripts/` 加载 |
|
|
||||||
| C++ 代码量 | ~320 行（极简） |
|
|
||||||
| 热重载 | ✅ |
|
|
||||||
| 可扩展性 | 其他插件可通过 `OnJsEnvCleanup` 回调集成 |
|
|
||||||
| 核心限制 | JsEnv 私有、脚本路径固定、Editor-Only |
|
|
||||||
@@ -2,6 +2,9 @@
|
|||||||
tags:
|
tags:
|
||||||
- UE
|
- UE
|
||||||
- Puerts
|
- Puerts
|
||||||
|
- EasyEditorPlugin
|
||||||
|
- UnrealMCP
|
||||||
|
- MCP
|
||||||
- TypeScript
|
- TypeScript
|
||||||
- V8
|
- V8
|
||||||
- 架构分析
|
- 架构分析
|
||||||
@@ -361,3 +364,350 @@ FPuertsModule::NotifyUObjectCreated()
|
|||||||
| `Content/JavaScript/puerts/callable.js` | 替代 Proxy callable 模式 |
|
| `Content/JavaScript/puerts/callable.js` | 替代 Proxy callable 模式 |
|
||||||
| `Content/JavaScript/puerts/hot_reload.js` | V8 Inspector 热重载 |
|
| `Content/JavaScript/puerts/hot_reload.js` | V8 Inspector 热重载 |
|
||||||
| `Content/JavaScript/puerts/pesaddon.js` | PESAPI 原生 addon 加载器 |
|
| `Content/JavaScript/puerts/pesaddon.js` | PESAPI 原生 addon 加载器 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# EasyEditorPlugin 架构分析
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
EasyEditorPlugin 是 `johnche`（腾讯，也是 Puerts 的作者）开发的 Unreal Engine **编辑器快速扩展插件**。它将 V8 JavaScript 运行时（通过 Puerts 的 `FJsEnv`）嵌入 Unreal Editor，让开发者可以用 TypeScript/JavaScript 编写编辑器扩展，而非 C++。
|
||||||
|
|
||||||
|
- **仓库**: `D:\MatrixTA\EasyEditorPlugin`
|
||||||
|
- **许可证**: MIT
|
||||||
|
- **引擎兼容**: UE 5.3+
|
||||||
|
- **核心价值**: 几行 TypeScript 完成编辑器菜单、工具栏、控制台命令、Detail 面板定制，支持热重载
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
EasyEditorPlugin/
|
||||||
|
├── .gitignore
|
||||||
|
├── EasyEditorPlugin.uplugin # UE 插件描述符
|
||||||
|
├── LICENSE # MIT
|
||||||
|
├── README.md # 使用文档（英文）
|
||||||
|
├── Resources/
|
||||||
|
│ └── Icon128.png # 插件图标
|
||||||
|
├── Doc/
|
||||||
|
│ ├── extension.md # 第三方 C++ 库扩展指南
|
||||||
|
│ └── Pic/
|
||||||
|
│ └── easyeditor.gif # 演示动画
|
||||||
|
└── Source/
|
||||||
|
└── EasyEditorPlugin/
|
||||||
|
├── EasyEditorPlugin.Build.cs # UE 构建规则
|
||||||
|
├── Public/
|
||||||
|
│ └── EasyEditorPlugin.h # 模块头文件（公开 API）
|
||||||
|
└── Private/
|
||||||
|
└── EasyEditorPlugin.cpp # 完整实现（~320 行）
|
||||||
|
```
|
||||||
|
|
||||||
|
**单模块 Editor 插件**，无 Runtime/Gameplay 模块。
|
||||||
|
|
||||||
|
## .uplugin 定义
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"FileVersion": 3,
|
||||||
|
"Version": 1,
|
||||||
|
"VersionName": "1.0",
|
||||||
|
"FriendlyName": "EasyEditorPlugin",
|
||||||
|
"CanContainContent": true,
|
||||||
|
"Modules": [{
|
||||||
|
"Name": "EasyEditorPlugin",
|
||||||
|
"Type": "Editor",
|
||||||
|
"LoadingPhase": "Default"
|
||||||
|
}],
|
||||||
|
"Plugins": [{
|
||||||
|
"Name": "Puerts",
|
||||||
|
"Enabled": true
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build.cs 模块依赖
|
||||||
|
|
||||||
|
| 依赖 | 类型 | 用途 |
|
||||||
|
|------|------|------|
|
||||||
|
| `Core` | Public | 基础 UE 类型（`FString`, `TSharedPtr` 等） |
|
||||||
|
| `CoreUObject` | Private | UObject 系统 |
|
||||||
|
| `Engine` | Private | Engine 层类型 |
|
||||||
|
| `Slate` | Private | Slate UI 框架 |
|
||||||
|
| `SlateCore` | Private | 核心 Slate 类型（`FSlateIcon`） |
|
||||||
|
| `ToolMenus` | Private | UE5 可扩展菜单系统 |
|
||||||
|
| `UnrealEd` | Private | 编辑器 API（地图变更通知等） |
|
||||||
|
| `ContentBrowserData` | Private | Content Browser 上下文菜单 |
|
||||||
|
| **`JsEnv`** | Private | **Puerts JavaScript 环境** |
|
||||||
|
|
||||||
|
## 公开 API（`EasyEditorPlugin.h`）
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
class FEasyEditorPluginModule : public IModuleInterface
|
||||||
|
{
|
||||||
|
public:
|
||||||
|
virtual void StartupModule() override;
|
||||||
|
virtual void ShutdownModule() override;
|
||||||
|
|
||||||
|
std::function<void()> OnJsEnvPreReload;
|
||||||
|
std::function<void(const FString&)> Eval;
|
||||||
|
TSparseArray<TUniquePtr<FAutoConsoleCommand>> TsConsoleCommands;
|
||||||
|
FSimpleMulticastDelegate OnJsEnvCleanup;
|
||||||
|
|
||||||
|
private:
|
||||||
|
TSharedPtr<puerts::FJsEnv> JsEnv; // ← 私有！外部无法访问
|
||||||
|
TSharedPtr<puerts::FSourceFileWatcher> SourceFileWatcher;
|
||||||
|
TUniquePtr<FAutoConsoleCommand> ConsoleCommand;
|
||||||
|
bool StartupScriptCalled = false;
|
||||||
|
|
||||||
|
void OnPostEngineInit();
|
||||||
|
void InitJsEnv();
|
||||||
|
void UnInitJsEnv();
|
||||||
|
bool Tick(float);
|
||||||
|
void HandleMapChanged(UWorld* InWorld, EMapChangeType InMapChangeType);
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
**关键点：`JsEnv` 是私有成员，外部 C++ 代码无法直接获取 JS 函数/对象。**
|
||||||
|
|
||||||
|
## Puerts 绑定（`AutoRegisterForEEP`）
|
||||||
|
|
||||||
|
静态初始化器在模块加载前（`StartupModule` 之前）自动注册以下 C++ 类型到 V8：
|
||||||
|
|
||||||
|
| C++ 类型 | 暴露的功能 |
|
||||||
|
|-----------|----------|
|
||||||
|
| `FSlateIcon` | 三个构造函数重载 |
|
||||||
|
| `FToolMenuEntry` | `InitMenuEntry`, `InitToolBarButton`, `InitComboButton` |
|
||||||
|
| `EasyEditorPlugin` | `SetOnJsEnvPreReload`, `SetEval`, `AddConsoleCommand`, `RemoveConsoleCommand` |
|
||||||
|
| `FContentBrowserItem` | `IsFolder`, `IsFile`, `GetItemName`, `GetItemPhysicalPath` |
|
||||||
|
|
||||||
|
## 生命周期
|
||||||
|
|
||||||
|
```
|
||||||
|
Module Load → AutoRegisterForEEP 构造（注册 Puerts 绑定）
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
StartupModule()
|
||||||
|
├── 设置 V8 --expose-gc 标志（允许显式 GC）
|
||||||
|
├── 注册 OnPostEngineInit 回调
|
||||||
|
└── 注册 OnMapChanged 处理器（地图卸载时 GC）
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
OnPostEngineInit()
|
||||||
|
├── InitJsEnv()
|
||||||
|
│ ├── 创建 FSourceFileWatcher（热重载）
|
||||||
|
│ └── 创建 FJsEnv，ModuleLoader 指向 "EasyEditorScripts"
|
||||||
|
├── 注册每帧 Tick
|
||||||
|
├── 注册 "EasyEditor.Restart" 控制台命令
|
||||||
|
└── 注册 "TypeScript" UToolMenus 字符串命令处理器
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
First Tick()
|
||||||
|
└── JsEnv->Start("Main") // 执行 Main.ts
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[热重载循环]
|
||||||
|
SourceFileWatcher 检测文件变更
|
||||||
|
→ 读取文件
|
||||||
|
→ JsEnv->ReloadSource(InPath, Content)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
ShutdownModule()
|
||||||
|
└── UnInitJsEnv()
|
||||||
|
├── Broadcast OnJsEnvCleanup
|
||||||
|
├── 清除 Eval / OnJsEnvPreReload
|
||||||
|
├── 清空 TsConsoleCommands
|
||||||
|
└── 重置 JsEnv 和 SourceFileWatcher
|
||||||
|
```
|
||||||
|
|
||||||
|
## `InitJsEnv()` 详细分析
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
void FEasyEditorPluginModule::InitJsEnv()
|
||||||
|
{
|
||||||
|
// 1. 创建文件监听器（用于热重载）
|
||||||
|
SourceFileWatcher = MakeShared<puerts::FSourceFileWatcher>(
|
||||||
|
[this](const FString& InPath) {
|
||||||
|
if (JsEnv.IsValid()) {
|
||||||
|
TArray<uint8> Source;
|
||||||
|
if (FFileHelper::LoadFileToArray(Source, *InPath)) {
|
||||||
|
JsEnv->ReloadSource(InPath, puerts::PString(
|
||||||
|
(const char*)Source.GetData(), Source.Num()));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// 2. 创建 JsEnv
|
||||||
|
// 关键: DefaultJSModuleLoader("EasyEditorScripts")
|
||||||
|
// → 从项目 Content/EasyEditorScripts/ 加载 TS 文件
|
||||||
|
JsEnv = MakeShared<puerts::FJsEnv>(
|
||||||
|
std::make_shared<puerts::DefaultJSModuleLoader>(TEXT("EasyEditorScripts")),
|
||||||
|
std::make_shared<puerts::FDefaultLogger>(), -1,
|
||||||
|
[this](const FString& InPath) {
|
||||||
|
if (SourceFileWatcher.IsValid()) {
|
||||||
|
SourceFileWatcher->OnSourceLoaded(InPath);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**当前限制**：
|
||||||
|
- `DefaultJSModuleLoader("EasyEditorScripts")` 只在项目 `Content/` 目录下搜索
|
||||||
|
- 不搜索插件 Content 目录
|
||||||
|
- 不能直接从插件的 `Resources/` 或 `Content/` 加载 TS
|
||||||
|
|
||||||
|
## 编辑器集成能力
|
||||||
|
|
||||||
|
### 菜单扩展（`UToolMenus`）
|
||||||
|
- `FToolMenuEntry.InitMenuEntry` — 添加普通菜单项
|
||||||
|
- `FToolMenuEntry.InitToolBarButton` — 添加工具栏按钮
|
||||||
|
- `FToolMenuEntry.InitComboButton` — 添加下拉工具栏按钮
|
||||||
|
|
||||||
|
### Content Browser 上下文菜单
|
||||||
|
- `FContentBrowserItem.IsFolder()`, `IsFile()`, `GetItemName()`, `GetItemPhysicalPath()`
|
||||||
|
|
||||||
|
### 控制台命令
|
||||||
|
- `EasyEditorPlugin.AddConsoleCommand(name, help, callback)` — 注册控制台命令
|
||||||
|
- `EasyEditorPlugin.RemoveConsoleCommand(index)` — 注销
|
||||||
|
|
||||||
|
### String Command Handler
|
||||||
|
`UToolMenus::RegisterStringCommandHandler("TypeScript", ...)` 让菜单项可以触发任意 TypeScript 代码。
|
||||||
|
|
||||||
|
### 重启命令
|
||||||
|
内置 `EasyEditor.Restart` 控制台命令：销毁 JS 环境 → 重新创建 → 重新加载 Main 脚本。
|
||||||
|
|
||||||
|
## 扩展点（给其他插件使用）
|
||||||
|
|
||||||
|
| 扩展点 | 类型 | 用途 |
|
||||||
|
|--------|------|------|
|
||||||
|
| `OnJsEnvCleanup` | `FSimpleMulticastDelegate` | JS 环境销毁前，其他插件清理状态 |
|
||||||
|
| `OnJsEnvPreReload` | `std::function<void()>` | 重启前执行 |
|
||||||
|
| `Eval` | `std::function<void(const FString&)>` | 执行任意 JS 字符串 |
|
||||||
|
|
||||||
|
其他插件的集成方式（以 EasyEditor_ImGui 为例）：
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
// 注册清理回调
|
||||||
|
FModuleManager::LoadModuleChecked<FEasyEditorPluginModule>("EasyEditorPlugin")
|
||||||
|
.OnJsEnvCleanup.AddLambda([]() {
|
||||||
|
// 清理状态
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## 脚本组织
|
||||||
|
|
||||||
|
- **脚本目录**: `Content/EasyEditorScripts/`（项目 Content 下）
|
||||||
|
- **入口文件**: `Main.js` 或 `Main.ts`
|
||||||
|
- **语言**: TypeScript（主要）/ JavaScript
|
||||||
|
- **热重载**: ✅ 支持
|
||||||
|
|
||||||
|
## 当前缺少的能力
|
||||||
|
|
||||||
|
1. **JsEnv 不公开** — 外部 C++ 无法获取 JS 函数引用（`FJsObject`）
|
||||||
|
2. **ModuleLoader 不灵活** — 只支持项目 Content 目录，不支持插件 Content 目录
|
||||||
|
3. **Editor-Only** — 无法用于游戏运行时业务逻辑
|
||||||
|
4. **无返回值调用** — `Eval` 只能执行字符串，无法获取返回值
|
||||||
|
5. **无结构化的 C++ → TS 调用 API** — 只能通过字符串 Eval 或 UE 反射间接调用
|
||||||
|
|
||||||
|
## 总结
|
||||||
|
|
||||||
|
| 方面 | 详情 |
|
||||||
|
|------|------|
|
||||||
|
| 设计目标 | 编辑器快速扩展 |
|
||||||
|
| 插件类型 | Editor-only |
|
||||||
|
| 运行时引擎 | V8（通过 `puerts::FJsEnv`） |
|
||||||
|
| 脚本语言 | TypeScript / JavaScript |
|
||||||
|
| 脚本入口 | `Main.ts`，从 `EasyEditorScripts/` 加载 |
|
||||||
|
| C++ 代码量 | ~320 行（极简） |
|
||||||
|
| 热重载 | ✅ |
|
||||||
|
| 可扩展性 | 其他插件可通过 `OnJsEnvCleanup` 回调集成 |
|
||||||
|
| 核心限制 | JsEnv 私有、脚本路径固定、Editor-Only |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# UnrealMCP 架构分析
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
UnrealMCP（npm 包: `unreal-engine-mcp-server`, v0.5.21）是由 ChiR24 开发的开源 MCP（Model Context Protocol）服务器，让 AI 助手（Claude Code、Cursor、Gemini 等）能够**远程实时控制和自动化 Unreal Engine 5.0-5.7**。
|
||||||
|
|
||||||
|
- **仓库**: `D:\AI\MCP\UnrealEngine\ChiR24_Unreal_mcp`
|
||||||
|
- **许可证**: MIT
|
||||||
|
- **GitHub**: `github.com/ChiR24/Unreal_mcp`
|
||||||
|
|
||||||
|
## 双组件架构（TypeScript Server + C++ 插件）
|
||||||
|
|
||||||
|
| 组件 | 语言 | 角色 |
|
||||||
|
|------|------|------|
|
||||||
|
| **TypeScript MCP Server** (`src/`) | TypeScript (Node.js 18+) | MCP 协议端点、schema 验证、请求路由、连接管理 |
|
||||||
|
| **McpAutomationBridge 插件** (`plugins/McpAutomationBridge/`) | C++ (Unreal Build Tool) | 原生 UE API 执行、WebSocket 服务器、属性反射、资产管理 |
|
||||||
|
|
||||||
|
两者通过 **WebSocket**（传统模式）或 C++ 插件直接服务 AI 客户端（Native HTTP/SSE，推荐模式）通信。
|
||||||
|
|
||||||
|
## 通信流
|
||||||
|
|
||||||
|
### Native MCP 模式（推荐）
|
||||||
|
|
||||||
|
```
|
||||||
|
AI Client (Claude Code, Cursor)
|
||||||
|
│ stdio / HTTP Streamable Transport
|
||||||
|
▼ http://localhost:3000/mcp
|
||||||
|
FMcpNativeTransport (FRunnable, 原始 socket HTTP 服务器)
|
||||||
|
│ 解析 JSON-RPC 2.0，管理 SSE 流
|
||||||
|
▼
|
||||||
|
UMcpAutomationBridgeSubsystem (UEditorSubsystem)
|
||||||
|
│ O(1) handler map 查找
|
||||||
|
▼
|
||||||
|
McpTool_*.cpp → UE Editor APIs
|
||||||
|
```
|
||||||
|
|
||||||
|
### TypeScript Bridge 模式（传统）
|
||||||
|
|
||||||
|
```
|
||||||
|
AI Client → TypeScript MCP Server (Node.js) → WebSocket ws://127.0.0.1:8091 → UE Plugin → UE APIs
|
||||||
|
```
|
||||||
|
|
||||||
|
## 插件详情
|
||||||
|
|
||||||
|
- **类型**: Editor-only (`"Type": "Editor"`)，不是 Runtime
|
||||||
|
- **模块**: `McpAutomationBridge`，LoadingPhase `Default`
|
||||||
|
- **基类**: `UEditorSubsystem`
|
||||||
|
- **设置**: `UDeveloperSettings` 子类，在 Project Settings > Plugins > MCP Automation Bridge 中配置
|
||||||
|
- **依赖**: EditorScriptingUtilities, Niagara
|
||||||
|
- **无 Puerts 依赖**：100% 原生 C++
|
||||||
|
|
||||||
|
## 安全特性
|
||||||
|
|
||||||
|
- 双向传输的能力令牌认证
|
||||||
|
- 默认仅 loopback 绑定（可选 LAN）
|
||||||
|
- 模式匹配的命令安全校验
|
||||||
|
- 每 IP/socket 速率限制
|
||||||
|
- TLS/SSL 支持
|
||||||
|
- 请求边界验证（Zod + AJV schema）
|
||||||
|
|
||||||
|
## 核心 MCP 工具
|
||||||
|
|
||||||
|
TypeScript 服务器暴露 **22 个合并的 MCP 工具**，每个是多 action 的父容器：
|
||||||
|
|
||||||
|
| 工具 | 域 |
|
||||||
|
|------|-----|
|
||||||
|
| `manage_asset` | 资产 CRUD、材质、依赖 |
|
||||||
|
| `manage_blueprint` | 蓝图、SCS 组件、图表编辑、UMG |
|
||||||
|
| `control_actor` | Actor 生成、物理、组件 |
|
||||||
|
| `control_editor` | PIE、相机、视口、截图 |
|
||||||
|
| `manage_level` | 关卡加载/保存、World Partition |
|
||||||
|
| `system_control` | UBT、测试、CVars、控制台命令 |
|
||||||
|
| `inspect` | 对象内省、属性 get/set |
|
||||||
|
| `animation_physics` | 动画蓝图、Control Rig、物理 |
|
||||||
|
| `manage_effect` | Niagara、粒子、调试形状 |
|
||||||
|
| `manage_gas` | Gameplay Ability System |
|
||||||
|
| `manage_character` | 角色创建、移动 |
|
||||||
|
| `manage_combat` | 武器、弹丸、伤害 |
|
||||||
|
| `manage_ai` | AI 控制器、行为树、EQS、感知 |
|
||||||
|
| `manage_sequence` | Sequencer、过场动画、关键帧 |
|
||||||
|
| `manage_audio` | 音效、音频组件 |
|
||||||
|
| `manage_networking` | 复制、RPC、会话 |
|
||||||
|
| `build_environment` | 地形、植被 |
|
||||||
|
| `manage_level_structure` | 子关卡、体积 |
|
||||||
|
| `manage_geometry` | 程序化网格 |
|
||||||
|
| `manage_inventory` | 物品、装备、战利品 |
|
||||||
|
| `manage_interaction` | 可交互对象、触发器 |
|
||||||
|
| `manage_tools` | 运行时工具启用/禁用 |
|
||||||
|
|||||||
@@ -5,15 +5,16 @@
|
|||||||
- Projects：UE工程目录。
|
- Projects：UE工程目录。
|
||||||
|
|
||||||
# 开发计划
|
# 开发计划
|
||||||
以Lyra为基础构建GAS Demo
|
|
||||||
1. 以Lyra为基础进行初始化
|
1. 以Lyra为基础进行初始化
|
||||||
1. 加入GitNexus 引擎代码 以及 项目代码。
|
1. 加入GitNexus 引擎代码 以及 项目代码。
|
||||||
2. CC + Obsidian CLI编写Lyra功能模块、代码逻辑文档、代码规范。
|
2. CC + Obsidian CLI编写Lyra功能模块、代码逻辑文档、代码规范。
|
||||||
3. 使用蓝图编译功能生成c++代码，让CC继续理解，并且迭代文档。
|
3. ~~使用蓝图编译功能生成c++代码，让CC继续理解，并且迭代文档。~~ 该功能已被废弃。
|
||||||
4. 加入Graphify管理文档。
|
4. GAS Document加入
|
||||||
|
5. 加入Graphify管理文档。
|
||||||
2. IDE相关MCP加入。
|
2. IDE相关MCP加入。
|
||||||
1. Rider
|
1. Rider
|
||||||
2. VSCode 编译与DebugUE工程
|
2. VSCode 编译与DebugUE工程
|
||||||
|
3. 5.8 MCP调研
|
||||||
3. 好功能移植
|
3. 好功能移植
|
||||||
1. GASShooter
|
1. GASShooter
|
||||||
2. Auro
|
2. Auro
|
||||||
@@ -22,6 +23,12 @@
|
|||||||
1. 自动测试功能探索。
|
1. 自动测试功能探索。
|
||||||
2. Puerts。
|
2. Puerts。
|
||||||
1. GitNexus
|
1. GitNexus
|
||||||
|
2. [[改造方案 - 将业务 TS 代码嵌入插件]]
|
||||||
|
3. QuickStart.ts 加入。
|
||||||
|
4. 编写相关Skill。
|
||||||
|
1. https://github.com/noobGuaTai/ue5-puerts-init-skill
|
||||||
|
2. Puerts 编码指南。
|
||||||
|
3. Lyra代码插件化与资产插件化。
|
||||||
5. 编写第三人称RPG的代码。
|
5. 编写第三人称RPG的代码。
|
||||||
1. 找案例移植？
|
1. 找案例移植？
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user