WebGPU 渲染模式
功能简介
WebGPU 是 W3C 制定的下一代 Web 图形 API 标准,旨在替代 WebGL,提供更接近现代图形硬件底层的能力。团结引擎支持在小游戏平台和 Web 平台上启用 WebGPU 图形 API,解锁 Compute Shader、VFX、Indirect Draw 等原生级渲染特性。
性能收益
相较于 WebGL 2.0,WebGPU 提供以下增强能力:
- •Compute Shader:支持在 GPU 上进行并行数据计算,适用于复杂的模拟或特效处理。
- •VFX:可用于实现更复杂、运行更高效的视觉特效。
- •Indirect Draw:可实现更高效的渲染调用调度,减少 CPU 开销。
- •Storage Texture:支持在 Shader 中直接读写纹理数据。
- •纹理格式扩展:支持 BGRA8、纹理压缩格式(BC / ETC2 / ASTC)等更多原生纹理格式。
前提条件
以下条件需要同时满足:
项目 | 最低版本或要求 | 说明 |
团结引擎 | 1.11.0 | 从该版本开始可在小游戏 Graphics APIs 中选择 WebGPU。 |
TTSDK | 6.9.6 | TTSDK 6.9.6 对应 UnityPlugin 4.44.0,提供 WebGPU 打包适配。 |
UnityPlugin | ≥ 4.44.0 | 检查最终 game.json 中 plugins.UnityPlugin.version;TTSDK 6.9.6 默认对应 4.44.0。 |
抖音客户端 | 41.1.0 | iOS 和 Android 均需使用 41.1.0 或更高版本。 |
包体格式 | 新包体格式 | WebGPU 不支持旧包体格式。 |
开放范围说明
WebGPU 能力可能按平台策略逐步开放。版本与产物配置满足要求后,仍应以手机端运行日志为最终判断依据。
接入流程
升级开发环境
- 1.安装团结引擎 1.11.0 或更高版本。
- 2.在项目中安装 TTSDK 6.9.6 或更高版本。TTSDK 6.9.6 对应 UnityPlugin 4.44.0;最终包体声明的 UnityPlugin 版本必须 大于或等于 4.44.0。
- 3.确认“抖音小游戏”为当前活跃的小游戏子平台。
- 4.确认项目使用新包体格式。
在团结引擎中启用 WebGPU
- 1.打开项目的 Project Settings。
- 2.进入小游戏对应的 Player / Other Settings。
- 3.在 Graphics APIs 中添加 WebGPU,保留 WebGL2 作为回退项,并将 WebGPU 排在 WebGL2 之前。
- 4.保存设置,按正常流程使用 TTSDK 构建抖音小游戏。
TTSDK 会读取团结引擎的 Graphics APIs 配置,并自动生成 WebGPU 运行所需的小游戏配置。请通过引擎和 TTSDK 重新构建,不要直接修改产物中的关键字段。
Graphics APIs 的顺序会影响实际选择的图形后端
希望优先使用 WebGPU 时,应将 WebGPU 放在回退项之前。
检查最终 game.json
构建完成后,在小游戏工程根目录打开 game.json,确认以下关键字段存在。示例按 TTSDK 6.9.6 / UnityPlugin 4.44.0;其余字段保留构建产物中的内容:
{ "plugins": { "UnityPlugin": { "version": "4.44.0", "provider": "tt674511f8f84ea91612" } }, "enableIOSHighPerformanceModePlus": true, "enableAndroidPipelineMode": true, "graphicsDeviceType": ["WebGPU", "OpenGLES3"] }
- •graphicsDeviceType 必须包含 WebGPU。
- •enableIOSHighPerformanceModePlus 应为 true。
- •enableAndroidPipelineMode 应为 true。
- •plugins.UnityPlugin.version 必须 大于或等于 4.44.0。TTSDK 6.9.6 默认对应 4.44.0;若使用更高版本的 UnityPlugin,检查最终产物中的实际版本号。
这一检查只能证明包体声明了 WebGPU
游戏是否实际进入 WebGPU 环境,还需要继续检查手机端 vConsole 日志。
通过 vConsole 确认运行环境
方法一:查看平台启动日志
- 1.在满足版本要求的 iOS 或 Android 手机上打开调试功能。
- 2.启动小游戏并打开 vConsole。
- 3.完全退出后重新启动小游戏,查看启动早期日志。
- 4.按平台搜索下表中的日志关键字。
平台 | 成功日志 | 判断方式 |
Android | enable WebGPU in remotekrypton mode result: true | 末尾为 true 或 1,表示启用成功。 |
iOS | enable WebGPU in wkkrypton mode result: true | 末尾为 true 或 1,表示启用成功。 |
如果日志末尾为 false 或 0,表示本次启动未启用 WebGPU。如果没有找到对应日志,也不能判定为已启用。
方法二:在游戏内手动打印 GPU 对象
在小游戏的实际 JavaScript 运行环境中手动添加以下打印,重新构建并启动游戏,在手机端 vConsole 查看输出:
console.log('[WebGPU] navigator.gpu:', globalThis.navigator.gpu);
- •输出为 undefined:当前游戏运行环境未提供 GPU 对象,不能使用该对象创建 WebGPU 图形设备。
- •输出为 GPU 对象(不是 undefined):当前运行环境提供了 WebGPU 接口,继续检查下面的引擎图形后端日志。
GPU 对象存在,仍需确认引擎实际使用了 WebGPU
globalThis.navigator.gpu 不是 undefined,只能说明环境提供了该接口。引擎可能受 Graphics APIs 顺序或初始化结果影响而使 用其他图形后端;实际使用情况以引擎启动日志为准。
方法三:对比引擎图形后端日志
在 vConsole 的引擎启动日志中,结合 CreateRealGfxDevice 后续的图形设备信息判断实际后端。下列两张图分别展示游戏使用 WebGPU 和 WebGL2 的情况:
完成验证
同时完成以下三项检查,才表示 WebGPU 接入并实际生效:
- 1.最终 game.json 的 plugins.UnityPlugin.version ≥ 4.44.0,graphicsDeviceType 包含 WebGPU,且两个平台运行模式开关为 true;保留回退项时,WebGPU 的顺序应在其之前。
- 2.目标手机的 vConsole 中出现对应平台的 WebGPU 成功日志,结果为 true 或 1;游戏内手动打印 globalThis.navigator.gpu 为 GPU 对象,而非 undefined。
- 3.引擎启动日志出现 WebGPUGfxDevice 等 WebGPU 图形设备信 息,确认游戏实际使用 WebGPU。若出现 Creating WebGL 2.0 context. 等日志,则本次启动使用的是 WebGL2。
FAQ
Q1. game.json 已包含 WebGPU,但没有成功日志
A1. 依次检查:
- 1.抖音客户端是否为 41.1.0 或更高版本。
- 2.小游戏基础库是否为 4.38.0.0 或更高版本。
- 3.TTSDK 是否为 6.9.6 或更高版本,最终 game.json 中 plugins.UnityPlugin.version 是否 大于或等于 4.44.0(TTSDK 6.9.6 默认对应 4.44.0)。
- 4.团结引擎是否为 1.11.0 或更高版本。
- 5.是否使用新包体格式 ,并确认手机运行的是最新上传的包体。
- 6.完全退出小游戏后重新进入,再查看启动早期日志。
如果以上条件均满足但仍未启用,请记录 AppID、平台、客户端版本、基础库版本、TTSDK 版本、UnityPlugin 版本、GPU 对象打印结果和完整启动日志(包括引擎图形后端日志),并联系平台技术支持。
Q2. 可以直接修改 game.json 启用 WebGPU 吗
A2. 不建议。应在团结引擎的 Graphics APIs 中启用 WebGPU,再由 TTSDK 生成最终产物。直接修改 game.json 可能造成产物配置与引擎实际编译后端不一致。
Q3. 如何切回非 WebGPU 版本
A3. 从团结引擎的 Graphics APIs 中移除 WebGPU,并使用 TTSDK 重新构建。构建后再次检查 game.json,确认 graphicsDeviceType 不再包含 WebGPU。
联系我们
如有任何问题请咨询平台对接人
