@puerts/cli

开箱即用的 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 重开一次
  • 下载 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
• 允许不安全代码（Blittables 需要用到）
  • UnityEditor菜单 -> Editor -> Project Settings -> Player -> Other Settings -> Allow 'unsafe' Code
• 使用 Puerts 生成关联 Code
  • UnityEditor菜单 -> PuerTS -> Clear Generated Code
  • UnityEditor菜单 -> PuerTS -> Generated Code
  • UnityEditor菜单 -> PuerTS -> Generated index.d.ts (global.CS style)
• 编译 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 处于卡死等待状态）
• Vscode 连接调试服务
  • Vscode 打开该 Unity项目工程，并在对应的代码中标记好断点位置
  • Vscode 点击左侧 Side栏 -> 运行和调试 -> 启动调试（Puerts 字样前小三角图标）

Vscode 需要安装 Debugger for Unity 扩展

参与开发

参与改进本工具或二次开发本请阅读 Developer Guide。

补充说明

• 建议使用 PuerTS_Nodejs 运行时，因为可以直接使用 Node 现成的模块
  • 注意：引入 node_modules、node 自带模块，请使用 require 方法引入
    • PuerTS目前未实现完整 import 支持，import 目前只支持本地模块
    • 项目要兼容 Web、微信小游戏，使用 Node 模块需要自行处理好兼容
• 着色器对 WebGL 做兼容支持
• 不建议直接使用引擎自带资源，例如：Shader.Find("Particles/Standard Unlit")
• 引入相对模块请以 ./、../ 开头，否则编译器可能无法找到模块

项目发起者

Tencent @zombieyang、4399 Game @sbfkcel

相关项目及资料

• Puerts
• puerts_unity_demo
• puerts_unity_webgl_demo
• minigame-unity-webgl-transform
• 微信小游戏开发者文档-快速上手
• Unity WebGL 微信小游戏适配