Puerts项目：在TypeScript中调用Unreal引擎API的完整指南

Puerts项目：在TypeScript中调用Unreal引擎API的完整指南

puerts PUER(普洱) Typescript. Let's write your game in UE or Unity with TypeScript. 项目地址: https://gitcode.com/gh_mirrors/pu/puerts

前言

Puerts为Unreal引擎提供了强大的TypeScript脚本支持，让开发者能够以更高效、更灵活的方式开发游戏逻辑。本文将详细介绍如何在TypeScript脚本中调用Unreal引擎的各种API，包括UCLASS、UFUNCTION、USTRUCT等核心元素。

基础概念

在Unreal引擎中，所有标记了UCLASS、UPPROPERTY、UFUNCTION、USTRUCT和UENUM的C++/蓝图类都可以直接在TypeScript中访问。需要注意的是：

1. 对于未标记UPPROPERTY或UFUNCTION的成员，需要通过静态绑定的方式声明后才能使用
2. C++类和蓝图类在调用方式上基本一致，主要区别在于生命周期管理

声明文件生成

为了获得更好的开发体验，Puerts提供了自动生成TypeScript声明文件的功能：

1. 通过编辑器UI按钮生成（推荐新手使用）
2. 通过控制台命令Puerts.Gen生成
3. 全量生成命令Puerts.Gen FULL（解决依赖变更问题）

生成的声明文件会包含所有可访问的引擎API，提供完整的代码提示和类型检查。

核心API调用示例

对象构造与成员访问

// 创建对象
let obj = new UE.MainObject();

// 访问和修改属性
console.log("属性值:", obj.MyString);
obj.MyString = "新值";

方法调用

// 简单参数方法
let result = obj.Add(100, 200);

// 复杂类型参数
obj.Bar(new UE.Vector(1, 2, 3));

// 引用参数处理
let vectorRef = $ref(new UE.Vector(1, 2, 3));
obj.Bar2(vectorRef);
let actualVector = $unref(vectorRef);

静态方法与枚举

// 调用静态方法
let name = UE.JSBlueprintFunctionLibrary.GetName();

// 使用枚举
obj.EnumTest(UE.EToTest.V1);

资源加载与管理

蓝图类加载

// 加载蓝图类
let bpClass = UE.Class.Load('/Game/Path/To/Blueprint.Blueprint_C');

// 创建蓝图实例
let actor = world.SpawnActor(bpClass) as UE.MyBlueprint_C;

其他资源加载

// 加载粒子系统
let particle = UE.ParticleSystem.Load("/Game/Effects/PS_Explosion");

// 加载静态网格
let mesh = UE.StaticMesh.Load("/Game/Models/SM_Character");

高级加载方式

// 使用blueprint.load简化访问
blueprint.load(UE.Game.Content.TestEnum.TestEnum);

// 直接访问枚举值
console.log(UE.Game.Content.TestEnum.TestEnum.Red);

// 转换为TS类
let tsClass = blueprint.tojs(someUClass);

容器类型使用

Puerts支持Unreal的主要容器类型：

创建容器

// TArray
let intArray = UE.NewArray(UE.BuiltinInt);
let vectorArray = UE.NewArray(UE.Vector);

// TSet
let stringSet = UE.NewSet(UE.BuiltinString);

// TMap
let scoreMap = UE.NewMap(UE.BuiltinString, UE.BuiltinInt);

容器操作

// 添加元素
intArray.Add(100);
stringSet.Add("Hello");
scoreMap.Add("Player1", 1000);

// 访问元素
let first = intArray.Get(0);
let exists = stringSet.Contains("Hello");
let score = scoreMap.Get("Player1");

二进制数据处理

Puerts提供了ArrayBuffer支持，方便处理网络数据等二进制操作：

读取C++的Buffer

let buffer = obj.ArrayBuffer;
let view = new Uint8Array(buffer);
for (let i = 0; i < view.length; i++) {
    console.log(`字节${i}: ${view[i]}`);
}

传递Buffer到C++

let data = new Uint8Array([0x01, 0x02, 0x03]);
obj.ProcessBinaryData(data);

最佳实践建议

1. 对于频繁使用的蓝图类，建议使用blueprint.load预先加载
2. 注意资源管理，及时调用blueprint.unload释放不再使用的资源
3. 对于性能敏感的操作，考虑使用C++实现并通过绑定暴露给TS
4. 充分利用生成的声明文件提供的类型提示

总结

Puerts为Unreal引擎开发带来了TypeScript的强大能力，通过本文介绍的各种API调用方式，开发者可以灵活地在脚本层实现游戏逻辑，同时保持与引擎底层的高效交互。掌握这些核心技巧将显著提升开发效率和代码质量。

puerts PUER(普洱) Typescript. Let's write your game in UE or Unity with TypeScript. 项目地址: https://gitcode.com/gh_mirrors/pu/puerts