Unity 插件安装与使用指南

一、当前支持情况

我们提供的 Unity 插件包（下文简称：插件包）支持 Unity 2019 ~ 2022 版本及Unity团结引擎，推荐使用 Unity 2021 及以上版本。该插件支持设置纹理压缩格式为 ASTC，以优化运行时内存表现。

二、插件包安装说明

下载最新版插件包：下载地址
将插件包导入 Unity 工程
成功导入后，Unity 工具栏将出现“联盟快游戏”菜单：

图中填写仅为⽰例，开发者需根据⾃家游戏实际情况填写

三、插件包目录结构

导入插件包后，Assets 目录下将生成 QG-GAME-SDK 目录，结构如下：

QG-GAME-SDK
├── Default         # 工程模板，可自定义 JS 代码，导出时自动复制
├── Editor          # Unity 插件面板，实现导出/调试等功能
├── Runtime         # 提供 C# 接口调用 JS 能力
├── Plugins         # JS 与 C# 的胶水层
└── CHANGELOG       # 版本日志

Runtime/包含一套 C# SDK，详见文档《Unity 游戏适配 C# API》
Editor/ 提供 WebGL 构建、快游戏转换、插件更新提示等能力
Plugins/ 处理 JS 能力封装与调用

四、导出快游戏步骤

前提条件

请确保已安装以下脚手架工具：


npm install -g @quick-game/cli          # 安装联盟脚手架
qg -v                                    # 查看联盟 CLI 版本

npm install -g @vivo-minigame/cli       # 安装 vivo 快游戏脚手架
mg -v                                    # 查看 vivo CLI 版本

步骤一：切换平台为 WebGL

打开 Build Settings，选择 WebGL 并点击 Switch Platform，配置如下：

Code Optimization: Speed
IL2CPP Code Generation: Faster (smaller) builds
Texture Compression：ASTC

Player Settings 设置：

勾选 Strip Engine Code
Managed Stripping Level: High

步骤二：导出为快游戏

顶部菜单点击 联盟快游戏 -> 转换快游戏，打开转换工具面板。

面板说明

基本信息：必填项，包括导出路径等
启动 Loading 配置：
- 背景封面配置：
  - 支持纹理选择或手动输入背景图；
  - 直接在源码中配置 loading（位于 xxx_qg/src/game.js），参考 qg.createCustomizeLoading
- 包体类型配置：支持整包、CDN 配置、分包配置
- Addressable 支持
- 预下载资源列表支持
统一 SDK 配置：
支持账号、支付、广告模块的配置，导出时会自动集成统一客户端 sdk 到游戏中
- 将 appid、appKey、appSecret 等参数配置好，在游戏内调用统一接口即可获取账号/进行支付
- 默认支持 bannerAd、interstitialAd、customAd、rewardedVideoAd；开发者可以将各平台申请的广告位配置进去即可，每个广告类型都可以填写多个广告位；若开发者有不同的需要，可以新增或删除其他广告类型
资源缓存配置：
- 启用缓存：是否启用缓存，建议开启
- CDN 地址：配置需要缓存的 CDN 地址
- 缓存路径：不填写代表所有路径都进行缓存判断。填写时多个时使用英文分号分隔，例如 StreamingAssets;bundles
- Bundle 哈希长度：资源 hash 占多少长度，默认 32 位
- 排除扩展名：不填写代表所有文件都进行缓存判断。填写多个时使用英文分号分隔，例如 .json;.hash
- 额外清理大小：清理缓存时默认额外清理的大小，单位 MB，默认 30MB
调试编译选项：
- WebGL2.0: 支持 webgl2.0 渲染方式
- UnityHeap: 设置预留内存（单位：MB），超休闲游戏 256/中轻度 496/重度游戏 768，需预估游戏最大 UnityHeap 值以防止内存自动扩容带来的峰值尖刺。默认值为 256
- Il2Cpp Optimize Size: 是否启用代码体积优化，勾选时使用 OptimizeSize(默认推荐)，生成代码小 15%左右，取消勾选则使用 OptimizeSpeed。游戏中大量泛型集合的高频访问建议 OptimizeSpeed，在使用 HybridCLR 等第三方组件时只能用 OptimizeSpeed。(Dotnet Runtime 模式下该选项无效)
- Scripts Only Build: 仅构建脚本而不重新打包资源或生成完整 Player 文件，提升打包速度，线上发布不建议使用。
- Profiling Funcs: 调试能够清晰看到调用栈里的函数名称（影响包体积）
- Clean WebGL Build: 清除旧缓存并重新构建
- 打包使用release签名: 自动打包并使用 release 签名，若本地无 release 签名会依据包名自动生成并缓存到 npm 目录

步骤三：构建输出

构建完成后，导出目录结构如下：

.
├── webgl        # Unity 导出的资源与代码
└── webgl_qg     # 快游戏项目目录

五、运行与调试

方法一：工具运行调试

点击 生成并转换
点击 运行，生成二维码，使用调试器扫描二维码进行真机调试

方法二：命令行运行

在 VSCode 中打开 webgl_qg，运行：

qg build（debug包体）/ qg release(release包体)
qg server

方法三：使用 IDE 工具打包调试

详见官方 IDE 打包说明

六、WebGL 构建产物验证

如果快游戏运行异常（报错、黑屏、加载失败），建议先验证 WebGL 产物是否能在本地正常运行。

搭建本地服务验证 WebGL

安装 Node.js（官网下载）
安装 http-server：

npm install -g http-server

启动服务：

cd webgl
http-server

浏览器访问：

http://127.0.0.1:8080

调试控制台查看日志和运行情况