Mini games on TikTok follow a lightweight game format that runs inside the TikTok client. You can build games with mainstream engines such as Cocos, Unity, and Laya, then export a runtime package through platform-provided engine plugins or mini game publishing capabilities. The package is loaded and executed by the mini game runtime inside the TikTok client, without distributing the game as a standalone app through app stores.

From a project structure perspective, TikTok mini games use a standard mini game package model: game code, engine runtime code, assets, and platform configuration are organized in a required directory structure. Platform capabilities are accessed through runtime built-in APIs or the Unity SDK.

Before you begin

Choose an integration path

Understand key limitations

• Runtime package format: Mini game packages must follow the required directory structure. Native app packages and unadapted WebGL builds are not accepted.
• Platform capabilities: Account, monetization, payment, sharing, user data, and other platform capabilities are accessed through runtime built-in APIs or the Unity SDK. The host does not expose arbitrary native system APIs.
• Package size: Unity projects focus on total project size <= 60 MB. Non-Unity projects must keep total project size <= 30 MB, main package size <= 4 MB, and each independent package <= 4 MB.
• Unity build path: Unity projects are compiled through IL2CPP to WebAssembly. Mono / JIT is not supported.
• Unity runtime requirements: TikTok Android / iOS client version must be >= 43.1.0. Builds with bulk memory enabled do not currently support subpackages. If the Wasm function count is too high, use the Wasm split flow to optimize startup performance.

What this guide covers

This overview focuses on runtime mechanics, engine integration, build outputs, debugging, and upload flow. It does not cover business strategy, operations strategy, or revenue-sharing rules.

Runtime mechanics

How code runs

Game logic runs from the engine build output. The platform runtime loads the package, manages lifecycle events, bridges platform capabilities, forwards rendering commands, and coordinates system resources. Developers do not need to integrate TikTok client capabilities manually, and should not depend on internal host interfaces that are not exposed.

Runtime architecture

TikTok mini games run on top of a native runtime inside the TikTok client. The runtime is organized into four layers:

• Game layer: Developer code and engine logic. Cocos / Laya projects mainly use JS / TS. Unity projects use C# compiled into WebAssembly.
• Platform capability layer: The bridge layer for account, monetization, payment, sharing, lifecycle, storage, network, and other platform capabilities. Cocos / Laya projects call runtime built-in APIs directly. Unity projects call the corresponding capabilities through the TikTok Unity SDK.
• Native runtime: Handles rendering, audio, and system resource management. Rendering commands are sent from the engine layer to the native rendering pipeline.
• Client host: Provides entries, container environment, account, ads, payment, risk control, and distribution flows.

The separation is simple: the game layer focuses on game logic, platform capability calls go through the capability layer, rendering and audio are handled by the native runtime, and entry and host interactions are handled by the TikTok client.

Integrate platform capabilities

Platform capabilities such as login, payment, ads, sharing, storage, and network are integrated in your own engine project source code, not by manually editing the built package. The build step only bundles these capability calls together with your game code into the TikTok mini game package.

• Cocos / Laya projects: Call TikTok mini game runtime built-in APIs directly from TS / JS source code. For example, call TTMinis.game.login, payment, or sharing APIs during game startup, login button handling, or payment flows. Runtime APIs are compatible with namespaces such as TTMinis.game, tt, and wx; for example, TTMinis.game.login is equivalent to tt.login and wx.login. You do not need to integrate SDK source code or manually import SDK files. After build, these calls are bundled into output directories such as src/ and assets/.
• Unity projects: call the TikTok Unity SDK from C# source code. For example, call TT.Login(...) in Start(), login panel button callbacks, or payment pre-check flows. After build, C# code is compiled through IL2CPP into WebAssembly and loaded with the Unity runtime package.

Minimal examples:

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}");
    }
);

Do not directly modify business logic in build output directories such as minigame/ or tt-minigame/. These files will be overwritten by the next build.

What the native runtime changes

• Rendering, audio, and system resource management are handled by the native client runtime, with a performance ceiling close to native apps.
• Build outputs must follow the required package structure. Native app packages and generic WebGL builds cannot be uploaded directly.
• Debugging, preview, and upload are handled through DevTool and @ttmg/cli.

Engines and build outputs

Supported Engines

TikTok mini games uses the standard mini game package model. Developers export a loadable directory through platform plugins or engine mini game publishing capabilities, then debug, preview, and upload it through DevTool / CLI.

Package size and subpackages

Before upload, DevTool runs code pre-checks for total project size, main package size, subpackage configuration, and Unity Wasm startup performance risks. Package size is calculated recursively from the project source root. Irrelevant directories or files such as node_modules, __MACOSX, .DS_Store, and Thumbs.db are ignored.

Subpackages must be configured with the lowercase subpackages field in game.json. The main package is not a separate directory. It is calculated by excluding all subpackage root directories from the whole project:

Main package size = project total size - size of all subpackage root directories in game.json

Regular subpackages are checked for configuration validity and directory existence only. They do not have a per-package size limit. Independent packages are marked with independent: true; for non-Unity games, each independent package is checked by its root directory size.

Cocos / Laya build output

Cocos / Laya projects mainly produce JS / TS code and asset bundles. Their build outputs follow the ByteDance Mini Game package model. Integration usually focuses on mini game export configuration, runtime API adaptation, asset paths, subpackage configuration, and review checks.

A typical package structure looks like this. Exact filenames may vary by engine version and build configuration:

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

Subpackages are declared through the subpackages field in game.json. Main package size is calculated as "project total size - size of all subpackage root directories". Cocos / Laya projects should pay close attention to first-screen resources, duplicated assets, and independent package size.

Use current mainstream stable versions: Cocos Creator 3.x and LayaAir 3.x. Official templates and subpackage details should follow the DevTool debugging guide and engine documentation.

Unity build output

Unity projects are compiled through IL2CPP into WebAssembly and loaded by the TikTok Mini Game native runtime. Developers build with Unity WebGL Build Target and the TikTok Unity plugin. Mono / JIT is not supported.

Install the Unity plugin

Import com.tiktok.minigame@<version>-Release.unitypackage into your Unity project, then start the build from Unity to generate a TikTok Mini Game loadable directory. See the Unity SDK documentation for the latest plugin version and download entry.

Unity limitations

• Client version: TikTok Android / iOS client version must be >= 43.1.0. Lower versions cannot launch Unity packages.
• Package size: Unity total project size must be <= 60 MB. Projects above this limit cannot be uploaded. The size of data and wasm files directly affects first-load time and the delivery experience, so keep assets under control.
• Subpackage capability: The platform supports splitting wasm into main code and sub code through the plugin's built-in wasm split toolchain. Builds with bulk memory enabled do not currently support subpackages.
• Wasm startup performance: When wasmFuncCount >= 80000, DevTool prompts you to enable Wasm code splitting to optimize startup performance. After splitting, verify first-screen loading, core gameplay, asset loading, and stability on real devices.

Directory structure

Unity build output root is tt-minigame/. Key files:

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

Run debugging and upload commands with @ttmg/cli under the tt-minigame/ directory. See the next section.

Development, debugging, and upload

Start DevTool

TikTok Mini Game DevTool is started through the official CLI package @ttmg/cli. Run ttmg dev in the project directory to start the debugging environment and open the visual DevTool interface for local debugging, real-device verification, and platform preview.

Choose a debugging mode

DevTool provides remote debugging, real-device preview, and platform preview:

• Remote debugging: game logic runs in the DevTool debugging environment, while rendering and device events interact with the real-device environment through the debugging channel. JS / TS projects can use Chrome DevTools breakpoints. This mode is suitable for feature development and logic debugging.
• Real-device preview: game code is delivered to the phone, and both logic and rendering run inside the native TikTok client environment. The CLI starts a local static server, and the phone scans a QR code to authenticate and upload code. Unity projects should use real-device preview for feature verification, performance tuning, and final regression.
• Platform preview: the game package is uploaded to the developer portal to generate a persistent preview version. Use TikTok to scan and test it. This mode is suitable for team regression and verification before review submission.

Basic flow

The core flow from project setup to release:

1. Choose an engine and project template, then develop the Cocos / Unity / Laya project.
2. Integrate platform capabilities such as login, payment, ads, sharing, and storage in the engine project source code.
3. Install @ttmg/cli, log in to the developer platform, and add test users.
4. Export a TikTok mini game package through platform plugins or engine mini game publishing capabilities.
5. Run ttmg dev in the package directory, then choose remote debugging or real-device preview.
6. After debugging, upload the package through DevTool and complete platform preview and review submission in the developer portal.

For launch mode, development options, code pre-checks, domain checks, and required capability checks, see the developer debugging guide.

Integration checklist

Before integration, check the following:

• Engine version: confirm that your Cocos / Unity / Laya version is within the recommended range.
• Build path: confirm that your project can export a TikTok Mini Game package through platform plugins or engine mini game publishing capabilities.
• Platform capabilities: list capability call sites such as account, payment, ads, sharing, storage, and network, then integrate TikTok platform capabilities in engine source code. Cocos / Laya projects call runtime built-in APIs directly. Unity projects use the TikTok Unity SDK.
• Package size and assets: check package size limits by project type. Unity projects should focus on total project size, wasm / data file size, and Wasm split prompts. Cocos / Laya projects should focus on total project size, main package size, independent package size, and duplicated assets.
• Subpackage configuration: confirm that game.json uses the lowercase subpackages field, and that each subpackage name and root is non-empty with an existing directory.
• Debugging mode: Cocos / Laya projects can use remote debugging for logic issues. Unity projects should use real-device preview for main verification.
• Review preparation: confirm that domains, required capabilities, privacy compliance, payment, and ads configuration meet platform requirements.

H5 mini games

TikTok mini games previously had an H5-based runtime. Games ran in a Web container, rendering used Canvas / WebGL, and platform capabilities were called through the host bridge.

New integrations should use the current mini game runtime described in this document. The H5 form is included here only as historical context, not as a new integration path.