--- tags: - UE - Puerts - TypeScript - V8 - 架构分析 created: 2026-05-31 --- # Puerts 架构深度分析 ## 概述 Puerts（发音 "pu-erts"）是腾讯开源的 Unreal Engine TypeScript/JavaScript 运行时。它将 V8 JavaScript 引擎直接嵌入 UE 的模块系统，实现 C++ 和 TypeScript 的双向互操作。 - **仓库**: `D:\MatrixTA\puerts` - **UE 端源码**: `puerts\unreal\Puerts\` - **许可证**: BSD 3-Clause ## 插件结构 `Puerts.uplugin` 定义了 **6 个模块**，有严格的初始化顺序： | 模块 | 类型 | LoadingPhase | 用途 | |------|------|-------------|------| | **WasmCore** | Runtime | PreDefault | WebAssembly (wasm3) 支持 | | **JsEnv** | Runtime | PreDefault | 核心 V8 嵌入引擎 | | **ParamDefaultValueMetas** | Program | PostConfigInit | UHT 插件，参数默认值 | | **Puerts** | Runtime | PostEngineInit | 高层模块：设置、JsEnv 生命周期、PIE 钩子 | | **DeclarationGenerator** | Editor | Default | 从 UE 反射生成 `*.d.ts` | | **PuertsEditor** | Editor | PostEngineInit | 编辑器集成、TS 编译监听 | ### 依赖链 ``` WasmCore → Core, CoreUObject, Engine JsEnv → Core, CoreUObject, Engine, UMG, ParamDefaultValueMetas, WasmCore, Json Puerts → Core, CoreUObject, Engine, Serialization, OpenSSL, UMG, JsEnv PuertsEditor → Puerts, JsEnv, UnrealEd, LevelEditor, DirectoryWatcher, AssetRegistry DeclarationGenerator → Puerts, JsEnv, UnrealEd ``` JsEnv 链接 V8 静态库（`wee8.lib` / `v8_11.8.172`），也可切换为 QuickJS 或 Node.js 后端。 ## 启动流程 ### 1. V8 Isolate 初始化 `FJsEnvImpl` 构造函数（`JsEnvImpl.cpp:347-646`）： 1. 创建 `v8::Isolate`，分配默认 ArrayBuffer 分配器 2. 创建 `v8::Context` 存入 `DefaultContext` 3. 将 `this` 指针存为 Isolate 数据：`Isolate->SetData(0, static_cast(this))` ### 2. C++ → JS 桥接注册 构造函数注册 C++ 回调为全局 JavaScript 函数： ```cpp MethodBindingHelper<&FJsEnvImpl::EvalScript>::Bind(..., "__tgjsEvalScript", ...); MethodBindingHelper<&FJsEnvImpl::SearchModule>::Bind(..., "__tgjsSearchModule", ...); MethodBindingHelper<&FJsEnvImpl::LoadModule>::Bind(..., "__tgjsLoadModule", ...); MethodBindingHelper<&FJsEnvImpl::FindModule>::Bind(..., "__tgjsFindModule", ...); MethodBindingHelper<&FJsEnvImpl::LoadUEType>::Bind(..., puertsObj, "loadUEType", ...); MethodBindingHelper<&FJsEnvImpl::LoadCppType>::Bind(..., puertsObj, "loadCPPType", ...); MethodBindingHelper<&FJsEnvImpl::NewObjectByClass>::Bind(..., "__tgjsNewObject", ...); MethodBindingHelper<&FJsEnvImpl::MakeUClass>::Bind(..., "__tgjsMakeUClass", ...); MethodBindingHelper<&FJsEnvImpl::Mixin>::Bind(..., "__tgjsMixin", ...); // + setTimeout, setInterval, dumpStatisticsLog, FNameToArrayBuffer 等 ``` ### 3. Bootstrap JS 模块（按顺序执行） ```cpp ExecuteModule("puerts/first_run.js"); // Inspector 存根（可选） ExecuteModule("puerts/polyfill.js"); // JS polyfills（非 NodeJS 模式） ExecuteModule("puerts/log.js"); // console.log → UE_LOG ExecuteModule("puerts/modular.js"); // CommonJS/ESM 模块系统 ExecuteModule("puerts/uelazyload.js"); // UE 类型懒加载 (Proxy) ExecuteModule("puerts/events.js"); // EventEmitter ExecuteModule("puerts/promises.js"); // Promise 支持 ExecuteModule("puerts/argv.js"); // 命令行参数 ExecuteModule("puerts/jit_stub.js"); // JIT 模块存根 ExecuteModule("puerts/hot_reload.js"); // V8 Inspector 热重载 ExecuteModule("puerts/pesaddon.js"); // PESAPI 原生 addon 加载 ``` ### 4. `Start()` 入口 `FJsEnvImpl::Start()` 调用 `require(ModuleName)` 执行用户入口模块。 ## 模块解析系统 ### 核心文件 - `puerts/modular.js` — JS 端 CommonJS/ESM 模块系统 - `JSModuleLoader.h` — C++ `IJSModuleLoader` 接口 - `DefaultJSModuleLoader.cpp` — 文件系统解析实现 ### `genRequire()` 工厂 `modular.js` 实现 Node.js 兼容的 CommonJS 系统： ```javascript // require() 解析流程 1. 尝试 org_require (Node.js 原生，如果使用 Node.js 后端) 2. 检查 buildinModule 缓存 ("ue", "puerts", "cpp") 3. 调用 __tgjsFindModule(moduleName) — 搜索 PUERTS_MODULE 注册的 C++ addon 4. 调用 __tgjsSearchModule(moduleName, requiringDir) — 文件系统搜索（见下） 5. 调用 __tgjsLoadModule(fullPath) — 加载文件 6. CommonJS wrapper 执行: (function(exports, require, module, __filename, __dirname) { ... }) 7. ES 模块 (.mjs/.mbc): 使用 V8 原生 v8::Module API ``` ### 文件系统搜索（`DefaultJSModuleLoader::Search`） 搜索算法： 1. 在 `RequiredDir/RequiredModule` 查找（尝试扩展名：`.js`, `.mjs`, `.cjs`, `.mbc`, `.cbc`, `package.json`, `index.js`） 2. 在 `RequiredDir/node_modules/RequiredModule` 查找 3. 向上遍历目录树，搜索每个父目录的 `node_modules` 4. 回退到 `Content/ScriptRoot/RequiredModule`（默认 `Content/JavaScript/`） 5. 如果 ScriptRoot 不是 `"JavaScript"`，也回退到 `Content/JavaScript/` **注意：搜索范围不包括插件 Content 目录。** ## JsEnv 数据流 ### `puerts/uelazyload.js` — UE 类型懒加载 这是最关键的模块之一： 1. 创建全局 `UE` 对象作为 **Proxy**，访问属性时懒加载 UClass 类型 2. 创建全局 `CPP` 对象用于注册的 C++ 类型 3. 将 `UE` 注册为内置模块：`require('ue')` 返回它 4. 暴露：`NewObject`, `NewStruct`, `FNameLiteral`, `NewArray/Set/Map`, `makeUClass`, `mixin`, `blueprint.tojs/load/unload` 5. 定义 UE 反射常量：`FunctionFlags`, `ClassFlags`, `PropertyFlags` 6. Decorator 存根：`uclass`, `ufunction`, `uproperty`, `uparam` 等 ### `puerts/callable.js`（旧版/替代模式） 使用 `sendRequestSync`（同步 C++ 桥接）通过 JSON 序列化和 Proxy 包装调用 UE 方法。这是旧的 callable 模式。 ### `puerts/hot_reload.js` 使用 V8 Inspector 协议 (`Debugger.setScriptSource`) 在运行时热重载 JS 模块，无需重启游戏。触发 `'HMR.prepare'` 和 `'HMR.finish'` 事件。 ### `puerts/pesaddon.js` 包装 `puerts.load()` 加载原生 `.dll`/`.dylib`/`.so` addon，使用 PESAPI（Portable Embedded Scripting API）。 ## Puerts 模块（`FPuertsModule`） ### 关键文件 - `PuertsModule.h` — `IPuertsModule` 接口 - `PuertsModule.cpp` — 实现 - `PuertsSetting.h` — 设置 UObject ### `StartupModule()` ```cpp void FPuertsModule::StartupModule() { RegisterSettings(); // 从 DefaultPuerts.ini 加载设置 // Editor: 绑定 PIE PreBeginPIE/EndPIE 委托 // 绑定热重载委托 if (Settings.AutoModeEnable) { Enable(); // 创建 JsEnv，注册对象监听器 } } ``` ### `MakeSharedJsEnv()` — JsEnv 工厂 根据 `UPuertsSetting` 创建： - **单一 JsEnv** (`FJsEnv`) — 普通模式 - **JsEnvGroup** (`FJsEnvGroup`) — 多隔离模式（2-9 个实例） 关键设置： - `RootPath` — JS 源码根目录（默认 `"JavaScript"`，相对于 `Content/`） - `AutoModeEnable` — 模块加载时自动启动 - `DebugEnable` / `DebugPort` — V8 Inspector 调试 - `NumberOfJsEnv` — 多隔离模式数量 ### UObject 创建监听 `FPuertsModule` 同时实现 `FUObjectCreateListener`，每个新创建的 `UObject` 触发 `NotifyUObjectCreated()` → `JsEnv->TryBindJs(InObject)`。这就是 Puerts 自动将 TypeScript 行为注入 Blueprint 生成对象的机制。 ## TS → C++ 绑定架构 ### `UTypeScriptGeneratedClass` 和 `UTypeScriptBlueprint` - `UTypeScriptBlueprint` — TypeScript 类的 Blueprint 资产类型 - `UTypeScriptGeneratedClass` — TS 生成的运行时 UClass： - `DynamicInvoker` — `TWeakPtr`，回调 `FJsEnvImpl` - `FunctionToRedirect` — 需要从 C++ 重定向到 JS 的函数名集合 - `HasConstructor` — TS 类是否有 `Constructor` 方法 - `StaticConstructor` — 替换原生 C++ 构造函数 ### `UJSGeneratedFunction` 和 Magic Bytecode `UJSGeneratedFunction` 是动态创建的 `UFunction`，通过 **magic bytecode trick** 重定向到 JS： 1. 在 UFunction 的 `Script` bytecode 中存储自身指针（3 字节 magic marker + 8 字节指针） 2. `execCallJS` 执行时恢复指针 3. 调用 `DynamicInvoker->InvokeJsMethod()` → `FJsEnvImpl::InvokeJsMethod()` 4. `FunctionTranslator->CallJs()` 将所有参数编组到 V8，调用 JS 函数 ### `MakeUClass` / `Mixin` — 运行时类创建 - **`MakeUClass`** (`puerts.makeUClass(ctor)`)：接收 JS 构造函数、原型、类名、方法对象、父 UClass，创建 `UJSGeneratedClass`，遍历父类 `FUNC_BlueprintEvent`，为每个覆盖创建 `UJSGeneratedFunction` - **`Mixin`** (`puerts.blueprint.mixin(to, mixinMethods)`)：接收现有 UClass，添加方法覆盖 ## C++ 调用 TS 的方式 ### 方式 1：`FJsObject`（直接 JS 函数包装器） ```cpp // FJsObject 是 USTRUCT，持有持久化 V8 引用 FJsObject MyFunc; MyFunc.Action(42, TEXT("hello")); // 无返回值 int32 Result = MyFunc.Func(42, TEXT("hello")); // 有返回值 int32 Val = MyObj.Get("someProperty"); // 读取属性 MyObj.Set("someProperty", 42); // 设置属性 ``` 自动使用 `puerts::v8_impl::Converter` 进行 C++ ↔ V8 类型转换。线程安全（`THREAD_SAFE` 模式下使用 `v8::Locker`）。 ### 方式 2：UFUNCTION / BlueprintEvent 覆盖 标准 UE 模式： ```cpp // C++ 中定义 UFUNCTION(BlueprintImplementableEvent) void OnSomethingHappened(int32 Param); // TypeScript 中实现 class MyActor extends UE.Actor { OnSomethingHappened(Param: number): void { // 被 C++ 调用时执行 } } ``` ### 方式 3：委托 ```typescript import { toDelegate, toManualReleaseDelegate } from "puerts"; let d = toDelegate(myObject, myCallback); // 绑定到对象 let d2 = toManualReleaseDelegate(myCallback); // 独立委托 ``` C++ 侧，`FJsEnvImpl` 维护 `DelegateMap` 将委托指针映射到 JS 回调函数。 ### 方式 4：`ITsDynamicInvoker` 接口 - `IDynamicInvoker::InvokeJsMethod` — 从 `UJSGeneratedFunction::execCallJS` 调用 - `IDynamicInvoker::JsConstruct` — 运行 JS 构造函数 - `ITsDynamicInvoker::TsConstruct` — TS 特定构造路径 `FJsEnvImpl` 通过内部类 `DynamicInvokerImpl` 和 `TsDynamicInvokerImpl` 实现这些接口。 ### 方式 5：`PUERTS_MODULE` 宏（Addon 模块系统） C++ 代码注册为 addon 模块： ```cpp // 在任何 C++ 文件中 PUERTS_MODULE(MyPlugin, [](v8::Local Context, v8::Local Exports) { // 注册类、函数等 Exports->Set(...); }); ``` 使用静态自动注册： ```cpp #define PUERTS_MODULE(Name, RegFunc) \ static struct FAutoRegisterFor##Name { \ FAutoRegisterFor##Name() { \ PUERTS_NAMESPACE::RegisterAddon(#Name, (RegFunc)); \ } \ } _AutoRegisterFor##Name ``` JS 端：`require('MyPlugin')` → `FindModule` → 执行注册函数 → 获取 exports。 ## 类型声明文件 位于 `puerts\unreal\Puerts\Typing\`： | 文件 | 内容 | |------|------| | `puerts/index.d.ts` | 核心 Puerts API：`$Ref`, `blueprint`, `toDelegate`, `on/off/emit`, `merge`, `load` | | `ue/puerts.d.ts` | UE 绑定类型：`$Delegate`, `TArray`, `TSet`, `TMap`, `NewObject`, `NewStruct` | | `ue/puerts_decorators.d.ts` | 装饰器：`rpc.flags()`, `edit_on_instance()`, `uclass`, `ufunction` | | `ue/index.d.ts` | 聚合所有声明（通过 `/// `） | `ue.d.ts` 和 `ue_bp.d.ts` 由 `DeclarationGenerator` 模块使用 UE 反射系统自动生成。 ## 架构图 ``` [Game/Editor 启动] │ ▼ FPuertsModule::StartupModule() ├── RegisterSettings() → 读取 DefaultPuerts.ini └── Enable() ├── GUObjectArray::AddUObjectCreateListener(this) // 拦截所有 UObject 创建 └── MakeSharedJsEnv() └── FJsEnv(ScriptRoot) 包装器 └── FJsEnvImpl 构造 ├── v8::Isolate::New() + v8::Context::New() ├── 注册全局 C++ 回调 (__tgjs* + puerts.*) ├── ExecuteModule() ×13 (bootstrap JS 文件) └── 捕获 global.require, global.__reload └── Start(ModuleName) → require(ModuleName) → 用户代码执行 │ ▼ [运行时: UObject 创建（如 Blueprint 实例化）] │ ▼ FPuertsModule::NotifyUObjectCreated() └── JsEnv->TryBindJs(InObject) ├── TypeScriptGeneratedClass? → MakeSureInject (绑定 JS 原型) └── JSGeneratedClass? → JsConstruct (调用 JS 构造函数) [C++ 调用 TS] UFUNCTION(BlueprintEvent) _Implementation → UE VM → execCallJS → DynamicInvoker->InvokeJsMethod() → FJsEnvImpl::InvokeJsMethod() → FunctionTranslator->CallJs() [参数编组] → JS 函数被调用 [TS 调用 C++] require('ue') → Proxy → loadUEType → UETypeToJsClass → DataTransfer::FindOrAddObject new MyActor() → NewObjectByClass → UObject 创建并调用构造函数 actor.K2_SomeMethod() → UFUNCTION → 原生 C++ 代码执行 ``` ## 关键文件索引 | 文件 | 用途 | |------|------| | `unreal/Puerts/Puerts.uplugin` | 插件定义（模块列表、加载阶段） | | `Source/Puerts/Public/PuertsModule.h` | `IPuertsModule` 接口 | | `Source/Puerts/Private/PuertsModule.cpp` | 模块启动/关闭，JsEnv 生命周期，PIE 钩子 | | `Source/JsEnv/Public/JsEnv.h` | `FJsEnv` 公开包装器 | | `Source/JsEnv/Private/JsEnvImpl.h` | `FJsEnvImpl` 完整定义 | | `Source/JsEnv/Private/JsEnvImpl.cpp` | V8 初始化、bootstrap、模块执行、绑定 | | `Source/JsEnv/Public/JSModuleLoader.h` | `IJSModuleLoader` 接口 + `DefaultJSModuleLoader` | | `Source/JsEnv/Private/DefaultJSModuleLoader.cpp` | 文件系统搜索/加载实现 | | `Source/JsEnv/Public/JsObject.h` | `FJsObject` — JS 函数/对象的 C++ 包装器 | | `Source/JsEnv/Public/DataTransfer.h` | `DataTransfer` — C++/JS 类型转换 | | `Source/JsEnv/Public/DynamicInvoker.h` | `IDynamicInvoker` 接口 | | `Source/JsEnv/Public/TsDynamicInvoker.h` | `ITsDynamicInvoker` 接口 | | `Source/JsEnv/Public/TypeScriptGeneratedClass.h` | `UTypeScriptGeneratedClass` | | `Source/JsEnv/Private/JSGeneratedClass.h` | `UJSGeneratedClass` | | `Source/JsEnv/Private/JSGeneratedFunction.h` | `UJSGeneratedFunction` (magic bytecode) | | `Source/JsEnv/Private/FunctionTranslator.h` | `FFunctionTranslator` — C++/JS 参数编组 | | `Source/JsEnv/Public/JSClassRegister.h` | `JSClassDefinition`, `PUERTS_MODULE` 宏 | | `Source/JsEnv/Public/JsEnvGroup.h` | `FJsEnvGroup` — 多隔离模式 | | `Content/JavaScript/puerts/modular.js` | JS 端 CommonJS/ESM 模块系统 | | `Content/JavaScript/puerts/uelazyload.js` | UE 类型懒加载, makeUClass, mixin | | `Content/JavaScript/puerts/callable.js` | 替代 Proxy callable 模式 | | `Content/JavaScript/puerts/hot_reload.js` | V8 Inspector 热重载 | | `Content/JavaScript/puerts/pesaddon.js` | PESAPI 原生 addon 加载器 |