BlueRoseNote/03-UnrealEngine/Gameplay/PuerTS/Puerts Quick Start.md

title, date, excerpt, tags, rating

title	date	excerpt	tags	rating
未命名	2025-07-20 11:39:10			⭐

相关资料

• 官方文档:https://puerts.github.io/docs/puerts/unreal/manual
  • 调试指南:https://puerts.github.io/docs/puerts/unreal/vscode_debug
  • 脚本调用引擎API:https://puerts.github.io/docs/puerts/unreal/script_call_uclass
    • 更多用法可以参考Puerts Demo https://puerts.github.io/docs/puerts/unreal/demos
      • 尤其推荐QuickStart.ts:https://github.com/chexiongsheng/puerts_unreal_demo/blob/master/TypeScript/QuickStart.ts
  • FAQ https://github.com/Tencent/puerts/blob/master/doc/unreal/zhcn/faq.md
• 哪里可以找到答案：
  • https://github.com/Tencent/puerts/issues
  • https://github.com/Tencent/puerts/discussions

QuickStart

Setup

1. 安装Nodejs v22.17.1。
2. 通过安装全局typeScrpit模块。

npm install -g typescript

3. 安装VSCode插件 !

Puerts Project Setup(跳过)

1. 下载Puerts插件:https://github.com/Tencent/puerts/releases
   1. 可选版本有Nodejs（一般情况下使用这个，可使用NPM添加其他的库）、V8（纯净环境）以及Quickjs（包体小，适合手机）
2. 编译插件。
3. 进入插件目录Plugins\Puerts执行node enable_puerts_module.js。
4. 在项目根目录下执行npm init，并且添加。之后重新生成一次VS解决方案并且执行npm install。其中Mocha是必须安装的，否则会出现找到编译后的js文件。

"dependencies": {
	"@types/mocha": "^10.0.10"
 }

5. 打开工程，在引擎中点击 ue.d.ts 。 该功能用于生成项目、引擎符号信息，生成之后就能找到相关符号了。如果想在ts文件中调用新增的蓝图&C++方法，也需要点击ue.d.ts才能找到对应符号。可以阅读该文了解详细信息 https://puerts.github.io/docs/puerts/unreal/script_call_uclass !
6. 在ProjectSettings - Packaging - Additional Not-Asset Directories to Package中添加Content/javaScript。

调试方法

具体可以参考：

• Puerts Inspector指南（一）在UE4和Unity里调试Javascript:https://zhuanlan.zhihu.com/p/359598262

调试器的选择有：

1. 在Chrome输入devtools://devtools/bundled/inspector.html?v8only=true&ws=127.0.0.1:8080。
2. 在Chrome输入chrome://inspect，点击Configure...，输入IP&Port后，点击Inspect。
3. 使用VSCode进行调试。
   1. 在Launch Program处点击add Configuration。
   2. 选择Node.js: Attach。
   3. 设置端口。
   4. 点击绿色箭头即可调试。

以下有2种添加调试入口的方式，一般选择第二种，勾选后启动游戏会处于冻结状态，需要调试器（VSCode、Chrome）连上才能继续运行。如果没有设置好调试器，可以打开Config\DefaultPuerts.ini把WaitDebugger改为False来跳过 添加调试入口方式1：自创建虚拟机模式下调试配置 创建FJsEnv传入调试端口

//8080是调试端口 GameScript = MakeShared<puerts::FJsEnv>(std::make_unique<puerts::DefaultJSModuleLoader>(TEXT("JavaScript")), std::make_shared<puerts::FDefaultLogger>(), 8080);

阻塞等待调试器链接

GameScript = MakeShared<puerts::FJsEnv>(std::make_unique<puerts::DefaultJSModuleLoader>(TEXT("JavaScript")), std::make_shared<puerts::FDefaultLogger>(), 8080);
GameScript->WaitDebugger();
GameScript->Start("QuickStart", Arguments);

添加调试入口方式2：自动绑定模式下调试配置

1. 菜单上选择Edit->ProjectSettings，打开设置页面后在Plugins -> Puerts Setting页面中开启调试以及设置端口。

开发方法

继承引擎类功能

类似c++的继承式开发方法。 https://puerts.github.io/docs/puerts/unreal/uclass_extends

蓝图mixin

一般用于给蓝图添加一些TS逻辑。 https://puerts.github.io/docs/puerts/unreal/mixin

直接运行脚本

通过在c++对应类中（GameMode、GameInstance等）调用执行脚本的函数来调用指定名称的脚本。

GameScript = MakeShared<puerts::FJsEnv>(std::make_unique<puerts::DefaultJSModuleLoader>(TEXT("JavaScript")), std::make_shared<puerts::FDefaultLogger>(), 8080);    
GameScript->Start("QuickStart", Arguments);

可以参考:https://github.com/chexiongsheng/puerts_unreal_demo/blob/master/TypeScript/QuickStart.ts·