Puerts-Unreal引擎TypeScript开发深度解析

Puerts-Unreal引擎TypeScript开发深度解析

【免费下载链接】puerts PUER(普洱) Typescript. Let's write your game in UE or Unity with TypeScript. 项目地址: https://gitcode.com/GitHub_Trending/pu/puerts

一、Puerts核心概念与架构设计

Puerts-Unreal的核心价值在于为Unreal Engine提供了完整的TypeScript/JavaScript运行时环境，使开发者能够使用脚本语言进行游戏开发。其架构设计遵循了"不重造轮子"的原则，而是作为桥梁连接现有引擎功能。

1.1 虚拟机环境本质

Puerts在UE引擎中创建的JavaScript虚拟机环境，其能力边界由宿主(引擎)提供的API决定：

1. 反射API全支持：所有UE反射系统暴露的C++类和蓝图接口，均可直接在TypeScript中调用
2. 扩展绑定机制：对于非反射API，提供模板绑定技术实现静态调用
3. 双向调用体系：支持脚本调用引擎，也支持引擎回调脚本

与浏览器环境(DOM API)和Node.js环境(I/O API)类似，Puerts环境的核心能力围绕游戏开发需求构建。

二、虚拟机管理与生命周期

2.1 FJsEnv核心类

puerts::FJsEnv类代表一个独立的JavaScript虚拟机实例，其生命周期管理遵循RAII原则：

// 典型用法示例
UCLASS()
class MYPROJECT_API UCustomGameInstance : public UGameInstance {
    TSharedPtr<puerts::FJsEnv> JsEnv;
    
    virtual void OnStart() override {
        JsEnv = MakeShared<puerts::FJsEnv>();
        TArray<TPair<FString, UObject*>> Args;
        Args.Add(TPair<FString, UObject*>("GameInstance", this));
        JsEnv->Start("Main", Args); // 启动入口脚本
    }
    
    virtual void Shutdown() override {
        JsEnv.Reset(); // 显式释放资源
    }
};

关键设计要点：

• 多虚拟机隔离：每个FJsEnv实例相互独立，类似多个Node.js进程
• 资源目录：默认脚本根目录为Content/JavaScript，可通过构造函数配置
• 参数传递：启动时可传入UE对象供脚本访问

2.2 脚本端参数获取

TypeScript中通过argv访问启动参数：

import * as UE from 'ue'
import {argv} from 'puerts';

const gameInstance = argv.getByName("GameInstance") as UE.GameInstance;
const world = gameInstance.GetWorld();

三、引擎交互技术详解

3.1 反射API调用规范

UE反射系统支持的API调用规则：

1. 类型名称转换：

   • C++类去除前缀（FVector → Vector，AActor → Actor）
   • 蓝图类保持原名

2. 声明文件支持：

   • 自动生成的.d.ts文件提供完整类型提示
   • IDE智能补全提升开发效率

3. 调用示例：

const actor = world.SpawnActor(
    UE.Actor.StaticClass(), 
    new UE.Transform(
        new UE.Vector(0, 0, 0), 
        UE.Rotator.ZeroRotator, 
        new UE.Vector(1, 1, 1)
    )
);

3.2 非反射API集成方案

对于未通过反射暴露的C++ API，Puerts提供两种解决方案：

1. 反射封装：将目标API包装成反射类
2. 模板绑定：通过声明模板实现直接绑定（高性能）

四、高级特性与应用场景

4.1 蓝图Mixin技术

Mixin模式允许将TypeScript逻辑"混入"到现有蓝图类：

• 实现原理：运行时动态扩展蓝图功能
• 典型应用：
  • 为已有蓝图添加脚本逻辑
  • 实现多继承效果
  • 热修复现有功能

4.2 引擎类继承系统

通过特殊声明语法，TypeScript类可被UE编辑器识别为原生类：

class MyComponent extends UE.ActorComponent {
    // 可被蓝图调用的方法
    UFUNCTION(BlueprintCallable)
    MyMethod(): void {
        // 脚本逻辑
    }
}

性能警示：此功能会产生跨语言调用开销，建议仅用于：

• 新旧系统过渡层
• 有限边界接口
• 非性能敏感逻辑

五、架构选型指南

5.1 技术方案对比

特性	FJsEnv直接使用	蓝图Mixin	继承引擎类
性能开销	低	中	高
编辑器集成度	无	部分	完整
适用阶段	新项目	过渡期	旧项目改造
脚本控制力	完全	部分	受限

5.2 最佳实践建议

1. 新项目架构：以FJsEnv为主，最小化跨语言调用
2. 现有项目改造：边界使用继承系统，核心逻辑保持原生
3. 性能敏感路径：避免在每帧调用的函数中使用继承系统
4. 调试策略：结合SourceMap实现TypeScript源码级调试

通过理解Puerts的多层架构设计，开发者可以根据项目需求选择合适的技术组合，在开发效率与运行时性能间取得平衡。

【免费下载链接】puerts PUER(普洱) Typescript. Let's write your game in UE or Unity with TypeScript. 项目地址: https://gitcode.com/GitHub_Trending/pu/puerts