TikTok 上的小游戏采用轻量级游戏格式，运行在 TikTok 客户端内。你可以使用主流引擎（例如 Cocos、Unity 和 Laya）构建游戏，然后通过平台提供的引擎插件或小游戏发布能力导出运行时包。TikTok 客户端内的小游戏运行时会加载并执行运行时包，无需通过应用商店将游戏作为独立应用发布。

从项目结构角度来看，TikTok 小游戏采用标准的小游戏包模型：游戏代码、引擎运行时代码、资产和平台配置，均按要求遵循目录结构。平台能力通过运行时内置 API 或 Unity SDK 进行调用。

#准备工作

#选择集成路径

#了解关键限制

• 运行时包格式：小游戏包必须遵循要求的目录结构。不接受原生应用包和未适配的 WebGL 构建。
• 平台能力：账号、营收、支付、分享、用户数据及其他平台能力通过运行时的内置 API 或 Unity SDK 进行访问。宿主不会暴露任意原生系统 API。
• 包大小：Unity 项目需保持项目总大小 <= 60 MB。非 Unity 项目需保持项目总大小 <= 30 MB，主包大小 <= 4 MB，每个独立包 <= 4 MB。
• Unity 构建路径：Unity 项目通过 IL2CPP 编译为 WebAssembly。不支持 Mono 和 JIT。
• Unity 运行时要求：TikTok Android 或 iOS 客户端版本必须 >= 43.1.0。启用大容量内存的构建当前不支持分包。如果 Wasm 函数数量过多，请使用 Wasm 分割流程优化启动性能。

#本指南涵盖内容

本文重点介绍运行时机制、引擎集成、构建输出、调试与上传流程。不涉及业务策略、运营策略或分成规则。

#运行时机制

#代码如何运行

游戏逻辑基于引擎构建输出运行。平台运行时负责加载包、管理生命周期事件、桥接平台能力、转发渲染指令以及协调系统资源。开发者无需手动集成 TikTok 客户端能力，也不应依赖未暴露的内部宿主接口。

#运行时架构

TikTok 小游戏运行在 TikTok 客户端内的原生运行时。运行时分为四层：

• 游戏层：开发者代码与引擎逻辑。Cocos/Laya 项目主要使用 JS/TS。Unity 项目通过 C# 编译为 WebAssembly。
• 平台能力层：账号、营收、支付、分享、生命周期、存储、网络及其他平台能力的桥接层。Cocos/Laya 项目直接调用运行时内置 API。Unity 项目通过 TikTok Unity SDK 调用对应能力。
• 原生运行时：负责渲染、音频和系统资源管理。渲染指令由引擎层发送到原生渲染管线。
• 客户端宿主：提供入口、容器环境、账号、广告、支付、风控和分发流程。

分层很简单：游戏层专注于游戏逻辑，能力层支持平台能力调用，原生运行时处理渲染和音频，TikTok 客户端处理入口和宿主交互。

#集成平台能力

登录、支付、广告、分享、存储、网络等平台能力需在你自己的引擎项目源代码中集成，而不是通过手动编辑构建包来实现。构建步骤仅将这些能力调用与你的游戏代码一起打包到 TikTok 小游戏包中。

• Cocos/Laya 项目：直接在 TS/JS 源代码中调用 TikTok 小游戏运行时的内置 API。例如，在游戏启动、登录按钮处理或支付流程中调用对应的 TTMinis.game.login、支付或分享 API。运行时 API 兼容 TTMinis.game、tt 和 wx 等命名空间。例如，TTMinis.game.login 等同于 tt.login 和 wx.login。无需集成 SDK 源代码或手动导入 SDK 文件。构建后，相关调用会被打包到 src/ 和 assets/ 等输出目录中。
• Unity 项目：通过 C# 源代码调用 TikTok Unity SDK。例如，在 Start()、登录面板按钮回调或支付预检查流程中调用 TT.Login(...)。构建后，C# 代码通过 IL2CPP 编译为 WebAssembly，并与 Unity 运行时包一起加载。

简单示例：

TTMinis.game.login({
  success: result => {
    const code = result.code;
    // Send code to your backend and exchange it for open_id / session state.
  },
});

using TTSDK;
using UnityEngine;

TT.Login(
    successCallback: code =>
    {
        // Send code to your backend and exchange it for open_id / session state.
    },
    failedCallback: errMsg =>
    {
        Debug.Log($"Login failed: {errMsg}");
    }
);

请勿直接修改 minigame/ 或 tt-minigame/ 等构建输出目录中的业务逻辑。这些文件将在下次构建时被覆盖。

#原生运行时的变化

• 渲染、音频和系统资源管理由原生客户端运行时处理，性能上限接近原生应用。
• 构建输出必须遵循要求的包结构。原生应用包和通用 WebGL 构建无法直接上传。
• 调试、预览和上传通过 DevTool 和 @ttmg/cli 完成。

#引擎与构建输出

#支持的引擎

TikTok 小游戏采用标准小游戏包模型。开发者通过平台插件或引擎小游戏发布能力导出可加载目录，然后通过 DevTool/CLI 进行调试、预览和上传。

#包大小与分包

上传前，DevTool 会对项目总大小、主包大小、分包配置以及 Unity Wasm 启动性能风险进行代码预检查。包大小从项目源代码根目录开始递归计算。无关目录或文件（例如node_modules、__MACOSX、.DS_Store 和 Thumbs.db）会被忽略。

分包必须通过小写的 subpackages 字段在 game.json 中进行配置。主包不是单独目录。主包大小计算方式为：从整个项目中排除所有分包根目录后，再进行计算：

主包大小 = 项目总大小 − game.json 中所有分包根目录的大小

常规分包仅检查配置有效性以及目录是否存在。它们没有单独的包大小限制。独立分包以 independent: true 标记。对于非 Unity 游戏，每个独立分包按其根目录大小进行检查。

#Cocos/Laya 构建输出

Cocos/Laya 项目主要生成 JS/TS 代码和资源包。其构建输出遵循 ByteDance 小游戏包模型。集成流程通常聚焦小游戏导出配置、运行时 API 适配、资源路径、分包配置和审查。

以下为典型包结构。具体文件名取决于引擎版本和构建配置：

minigame/
├── game.js                     # Mini game entry
├── game.json                   # Mini game configuration, including window, network, and subpackage settings
├── project.config.json         # DevTool project configuration
├── adapter-min.js              # Mini game environment adapter, may be split or renamed by engine version
├── main.js                     # Engine bootstrap logic
├── src/                        # Built business code
│   ├── settings.json           # Engine build configuration and asset manifest
│   ├── chunks/                 # Business code chunks, may exist depending on engine version
│   └── ...
├── assets/                     # Engine asset bundles
│   ├── internal/               # Built-in engine assets
│   ├── main/                   # Main asset bundle
│   └── <custom-bundle>/        # Custom asset bundle, can be organized with subpackages
├── subpackages/                # Regular / independent subpackages, if configured
│   └── <subpackage-name>/
└── res/                        # Additional assets, depending on engine and project configuration

分包通过 game.json 中的 subpackages 字段声明。主包大小按“项目总大小 − 所有分包根目录大小”计算。Cocos/Laya 项目需重点关注首屏资源、重复资源和独立分包大小。

请使用当前主流稳定版本：Cocos Creator 3.x 和 LayaAir 3.x。官方模板和分包细节应遵循 DevTool 调试指南及引擎文档。

#Unity 构建输出

Unity 项目通过 IL2CPP 编译为 WebAssembly，并由 TikTok 小游戏原生运行时加载。开发者使用 Unity WebGL Build Target 和 TikTok Unity 插件进行构建。不支持 Mono 和 JIT。

#安装 Unity 插件

将 com.tiktok.minigame@<version>-Release.unitypackage 导入到你的 Unity 项目中，然后从 Unity 启动构建，生成 TikTok 小游戏可加载的目录结构。请参阅 Unity SDK 文档，获取最新插件版本和下载入口。

#Unity 限制

• 客户端版本：TikTok Android/iOS 客户端版本必须 >= 43.1.0。低于此版本无法启动 Unity 包。
• 包大小：Unity 总项目大小必须 <= 60 MB。超过此限制的项目无法上传。数据和 Wasm 文件的大小会直接影响首次加载时间和分发体验，因此请控制资源规模。
• 分包能力：平台支持通过插件内置的 Wasm 分包工具链将 Wasm 拆分为主代码和子代码。启用大容量内存的构建目前不支持分包。
• Wasm 启动性能：当 wasmFuncCount >= 80000 时，DevTool 会提示启用 Wasm 代码拆分，用于优化启动性能。拆分后，请在实际设备上验证首屏加载、核心玩法、资源加载和稳定性。

#目录结构

Unity 构建输出根目录为 tt-minigame/。关键文件：

tt-minigame/
├── data-package/                                       # Resource data
├── images/                                             # Platform assets, such as icons and launch images
├── wasmcode/                                           # Wasm code
│   └── <hash>.webgl.wasm.code.unityweb.wasm.br         # Brotli-compressed wasm binary
├── game.js                                             # Mini game entry
├── game.json                                           # Mini game configuration
├── plugin.js                                           # Plugin entry
├── plugin-config.js                                    # Plugin configuration
├── unity-namespace.js                                  # Unity global namespace bridge
├── webgl-wasm-split.js                                 # Wasm split configuration
├── webgl.framework.js                                  # Unity runtime framework
└── webgl.symbols.json                                  # Debug symbols, may exist in debug builds

在 tt-minigame/ 目录下使用 @ttmg/cli 进行调试和上传命令。请参阅下一节。

#开发、调试和上传

#启动 DevTool

TikTok Mini Game DevTool 通过官方 CLI 包 @ttmg/cli 启动。在项目目录下运行 ttmg dev，启动调试环境并打开可视化 DevTool 界面，用于本地调试、真机验证和平台预览。

#选择调试模式

DevTool 支持远程调试、真机预览和平台预览模式：

• 远程调试：游戏逻辑在 DevTool 调试环境中运行，渲染和设备事件通过调试通道与真机环境进行交互。JS/TS 项目可使用 Chrome DevTools 设置断点。此模式适用于功能开发和逻辑调试。
• 真机预览：游戏代码传送到手机，逻辑和渲染均在原生 TikTok 客户端环境中运行。通过 CLI 启动本地静态服务器，然后使用手机扫描二维码进行认证并上传代码。Unity 项目应使用真机预览模式进行功能验证、性能调优和最终回归测试。
• 平台预览：游戏包上传到开发者门户，生成持久可用的预览版本。使用 TikTok 扫码进行测试。此模式适用于团队回归测试和提交审查前的验证。

#基本流程

项目从搭建到发布的核心流程：

1. 选择引擎和项目模板，然后开发 Cocos/Unity/Laya 项目。
2. 在引擎项目源代码中集成登录、支付、广告、分享、存储等平台能力。
3. 安装 @ttmg/cli，登录开发者平台，并添加测试用户。
4. 通过平台插件或引擎小游戏发布能力导出 TikTok 小游戏包。
5. 在包目录下运行 ttmg dev，然后选择远程调试或真机预览模式。
6. 完成调试后，通过 DevTool 上传包，并在开发者门户完成平台预览和审查提交。

关于启动模式、开发选项、代码预检查、域名检查和必需能力检查，请参阅开发者调试指南。

#集成检查清单

集成前，请检查以下内容：

• 引擎版本：确认你的 Cocos/Unity/Laya 版本可接受。
• 构建路径：确认你的项目可通过平台插件或引擎小游戏发布能力导出 TikTok 小游戏包。
• 平台能力：梳理能力调用点（例如账号、支付、广告、分享、存储和网络），然后在引擎源代码中集成 TikTok 平台能力。Cocos/Laya 项目直接调用运行时内置 API。Unity 项目使用 TikTok Unity SDK。
• 包大小和资产：按项目类型检查包大小限制。Unity 项目需关注项目总大小、Wasm/数据文件大小及 Wasm 分包提示。Cocos/Laya 项目需关注项目总大小、主包大小、独立包大小及重复资源。
• 分包配置：确认 game.json 使用小写 subpackages 字段，并确保每个分包的 name 和 root 非空且对应目录存在。
• 调试模式：Cocos/Laya 项目可用远程调试处理逻辑问题。Unity 项目应使用真机预览模式进行主要验证。
• 审查准备：确认域名、必需能力、隐私合规、支付和广告配置符合平台要求。

#H5 小游戏

TikTok 小游戏曾采用基于 H5 的运行时。游戏运行在 Web 容器中，渲染使用 Canvas/WebGL，平台能力通过宿主桥接层调用。

新集成应使用本文档描述的当前小游戏运行时。H5 形式仅作为历史背景列出，不作为新的集成路径。