@puerts/cli
v0.3.9
Published
PureTS is a quick scaffold tool, which can be used in the project.
Downloads
79
Readme
开箱即用的 PuerTS 脚手架工具,通过本工具可以将 Puerts 快速接入并应用于项目中。
功能特点:
- 基于 SWC 构建的编译环境,快如闪电
- 无需再手动搭建 Typescript、Webpack 相关编译及打包环境
- 开箱即用的 Souremap、Hot reload、断点调试 等配置集成
- 快速编译 Puerts WebGL 运行时,并能自动完成与Web或微信小游戏项目的对接
- Web、微信小游戏工程拥有编译与预览一体的环境,无需自行再搭建预览环境
现阶段仅支持 Unity 项目,支持 Puerts 2.X的版本正在火速开发中
安装
确保本地已经安装 Node.js 16.15.0+
# 使用npm安装
npm install @puerts/cli -g
# 使用yarn安装
yarn global add @puerts/cli
# 输出版本号,检查是否安装成功
puer -v
注意:以下所有
puer
命令都建议以管理员身份运行
帮助手册
Puerts Cli 自带帮助手册,通过添加 --help
参数来查看每个命令及相关参数的帮助说明。
# 查看当前可用的命令
puer -h
# 查看 build 命令使用参数
puer build -h
# ...
新手教程
- 使用
Unity 2021+ LTS
创建一个3D空项目 - 在项目中添加
Puerts
- 下载 Puerts(建议下载 PuerTS_Nodejs_xxx.tgz 版本,因为开发阶段的 Sourcemap、Hotreload 要用到 Node 的环境)
- 解压并将
Puerts
目录复制到项目的Assets/
目录下,即:Assets/Puerts/
- 注意:由于
Puerts
支持多系统多平台,需要手动指定好哪些文件适用于哪些平台,否则可能运行或编译出现异常,具体操作方法如下:- UnityEditor的资源管理器中找到:
Assets
->Puerts
->Plugins
->xx系统
->xx
直到具体的文件,选中目录下所有文件 - 然后在
Inspector
面板勾选对上的平台并点击Apply
按钮(至少保证当前 Editor 环境有选择对,其它如果不知道则全都不选就好,之后等需要编译对应平台的时候再来这里设置) - 设置完之后,建议关掉 UnityEditor 重开一次
- UnityEditor的资源管理器中找到:
- 下载 PuertsWebGL 并解压
- 在解压目录内找到
package
目录并重命名为PuertsWebGL
- 将重命名好的
PuertsWebGL
目录复制到项目的Assets/
目录下,即:Assets/PuertsWebGL/
- 在项目中添加
微信小游戏转换工具
(无需支持 Web、微信小游戏可以忽略)- 下载微信小游戏转换工具Unity插件
- 双击
minigame.xxx.unitypackage
将插件导入到项目
- 初始化
Puerts
项目- 终端进入到创建好的
Unity项目
目录中 - 终端执行
puer init
初始化一个Puerts
项目
- 终端进入到创建好的
- 将项目色彩空间改为
Gamma
(无需支持 Web、微信小游戏可以忽略)- UnityEditor菜单 ->
Editor
->Project Settings
->Player
->Other Settings
->Color Space
->Gamma
- UnityEditor菜单 ->
- 允许不安全代码(Blittables 需要用到)
- UnityEditor菜单 ->
Editor
->Project Settings
->Player
->Other Settings
->Allow 'unsafe' Code
- UnityEditor菜单 ->
- 使用
Puerts
生成关联Code
- UnityEditor菜单 ->
PuerTS
->Clear Generated Code
- UnityEditor菜单 ->
PuerTS
->Generated Code
- UnityEditor菜单 ->
PuerTS
->Generated index.d.ts (global.CS style)
- UnityEditor菜单 ->
- 编译
Puerts
项目- 终端进入到创建好的
Unity项目
目录中 - 终端执行
puer build
,工具会将项目所有的TS
文件编译为JS
- 终端进入到创建好的
- 预览项目
- 使用
Unity Editor
打开项目 - 双击
Assets/Scenes/App.unity
场景 - 点击
Play
即可看到运行效果
- 使用
- 进入开发模式
- 终端进入到创建好的
Unity项目
目录中 - 终端执行
puer dev
,此时工具会监听项目中的TS
文件是否有修改,如有修改则会实时将其编译为JS
文件 - 默认会启动热重载支持,如果不需要可添加
--reload false
参数来关闭
- 终端进入到创建好的
编译为Web或微信小游戏工程
- 导出 Web 或 微信小游戏工程
- 确保 UnityEditor 有安装 Unity-WebGL-Support
- 确保项目已经有安装
PuertsWebGL
、微信小游戏转换工具
- 切换编译平台为 WebGL,并确保添加需要导出的 Scene
- UnityEditor 打开需要导出的场景
- UnityEditor菜单
File
->Build Settings
->WebGL
->Switch Platform
- UnityEditor菜单
File
->Build Settings
->Add Open Scenes
- UnityEditor菜单
微信小游戏
->转换小游戏
在弹出的转换窗口中填写以下信息- 游戏appid,在微信公众平台中申请
- 小游戏项目名称,随便填写
- 游戏资源CDN,填写
http://localhost:10000
(这也是 cli 工具默认的 Web 项目预览地址,CDN资源也就是这里的资源) - 导出路径,这里建议与
puer.config.js
中的minigameOutputDir
配置项目保持一致puer.config.js
文件在执行puer init
时会自动创建,文件默认位置:项目/TS/puer.config.js
minigameOutputDir
默认为桌面/项目目录名称/
- 点击
导出WEBGL并转换为小游戏(常用按钮)
导出项目- 如果导出遇到错误,请根据 UnityEditor Console 面板中的提示排除故障
- 编译 puerts 运行时并对接
- 终端
cd Unity项目目录
- 终端
puer build --target minigame --browse
- 脚手架会编译
puerts运行时
以及项目中的TS
并自动接好相关入口 - 不出意外终端会输出浏览器预览地址,直接访问即可预览效果
- 如果
puer.config.js
中的minigameOutputDir
配置项与微信小游戏转换工具
导出目录不一致则需要根据提示自行手动接入
- 脚手架会编译
- 终端
建议:微信小程序、小游戏技术生态都是基于Web之上的,所以要先保证浏览器上可正常运行,之后再打开小游戏工程来预览调试
如何断点调试
- 启动调试模式
- UnityEditor 打开
Assets/Screnes/App.unity
场景 - UnityEditor 在
Hierarchy面板
-> 找到Main
节点,勾选Inspector
面板中的Debug
选项 - 播放场景(此时 UnityEditor 处于卡死等待状态)
- UnityEditor 打开
- Vscode 连接调试服务
- Vscode 打开该
Unity项目工程
,并在对应的代码中标记好断点位置 - Vscode 点击左侧
Side栏
->运行和调试
->启动调试(Puerts 字样前小三角图标)
- Vscode 打开该
Vscode 需要安装
Debugger for Unity
扩展
参与开发
参与改进本工具或二次开发本请阅读 Developer Guide。
补充说明
- 建议使用
PuerTS_Nodejs
运行时,因为可以直接使用Node
现成的模块- 注意:引入 node_modules、node 自带模块,请使用
require
方法引入- PuerTS目前未实现完整
import
支持,import
目前只支持本地模块 - 项目要兼容
Web
、微信小游戏
,使用Node
模块需要自行处理好兼容
- PuerTS目前未实现完整
- 注意:引入 node_modules、node 自带模块,请使用
- 着色器对 WebGL 做兼容支持
- 不建议直接使用引擎自带资源,例如:
Shader.Find("Particles/Standard Unlit")
- 引入相对模块请以
./
、../
开头,否则编译器可能无法找到模块
项目发起者
Tencent @zombieyang、4399 Game @sbfkcel