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:
|
||||
- UE
|
||||
- Puerts
|
||||
- EasyEditorPlugin
|
||||
- UnrealMCP
|
||||
- MCP
|
||||
- TypeScript
|
||||
- V8
|
||||
- 架构分析
|
||||
@@ -361,3 +364,350 @@ FPuertsModule::NotifyUObjectCreated()
|
||||
| `Content/JavaScript/puerts/callable.js` | 替代 Proxy callable 模式 |
|
||||
| `Content/JavaScript/puerts/hot_reload.js` | V8 Inspector 热重载 |
|
||||
| `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工程目录。
|
||||
|
||||
# 开发计划
|
||||
以Lyra为基础构建GAS Demo
|
||||
1. 以Lyra为基础进行初始化
|
||||
1. 加入GitNexus 引擎代码 以及 项目代码。
|
||||
2. CC + Obsidian CLI编写Lyra功能模块、代码逻辑文档、代码规范。
|
||||
3. 使用蓝图编译功能生成c++代码,让CC继续理解,并且迭代文档。
|
||||
4. 加入Graphify管理文档。
|
||||
3. ~~使用蓝图编译功能生成c++代码,让CC继续理解,并且迭代文档。~~ 该功能已被废弃。
|
||||
4. GAS Document加入
|
||||
5. 加入Graphify管理文档。
|
||||
2. IDE相关MCP加入。
|
||||
1. Rider
|
||||
2. VSCode 编译与DebugUE工程
|
||||
3. 5.8 MCP调研
|
||||
3. 好功能移植
|
||||
1. GASShooter
|
||||
2. Auro
|
||||
@@ -22,6 +23,12 @@
|
||||
1. 自动测试功能探索。
|
||||
2. Puerts。
|
||||
1. GitNexus
|
||||
2. [[改造方案 - 将业务 TS 代码嵌入插件]]
|
||||
3. QuickStart.ts 加入。
|
||||
4. 编写相关Skill。
|
||||
1. https://github.com/noobGuaTai/ue5-puerts-init-skill
|
||||
2. Puerts 编码指南。
|
||||
3. Lyra代码插件化与资产插件化。
|
||||
5. 编写第三人称RPG的代码。
|
||||
1. 找案例移植?
|
||||
|
||||
|
||||
Reference in New Issue
Block a user