Build Mini Games With Cocos
This guide is for developers who already build games with Cocos and want to adapt their project to run as a TikTok mini game. You will still develop gameplay mechanics, UI, resource loading, save data, monetization logic, and server-side integrations within your Cocos project. TikTok does not inject game logic or an iOS or Android SDK into your project after the build is completed.
The Cocos integration path is to generate a mini game-like base output from Cocos first, then adapt the entry file, package structure, resource loading, platform configuration, platform capability calls, and validation flow for TikTok mini games. After the Cocos-specific adaptation is complete, DevTool debugging, TikTok app real-device preview, upload, review, release, and live operations follow the same process as other engines.
Technical overview
You can understand Cocos integration as one continuous path: the Cocos project produces the base mini game output, the TikTok adaptation makes that output loadable by TikTok's mini game runtime, and platform capability integration connects login, advertising, payment, sharing, revisit entries, and other capabilities to real game flows.
Role | Responsible for: | Not responsible for: |
Cocos project | Gameplay, UI, resources, scenes, business code, platform capability entry points, and local development validation | Providing real TikTok login, ads, payment, or review environment |
Game server | Exchanging login code for user identity, saving data, rewards, order verification, entitlement maintenance, and failure recovery | Maintaining app secrets, order verification, and trusted reward logic in the TikTok app |
TikTok runtime | Loading the mini game package inside TikTok app and providing the real platform runtime | Building game logic for you or injecting game code after build |
DevTool | Importing packages, viewing logs, running previews, code pre-check, upload, and preview build testing | Replacing validation inside TikTok app runtime on real devices |
If your project is just an ordinary web page or HTML5 (H5) page, you must reorganize it into a Cocos game project or a stable mini game build before proceeding with adaptation. The build artifacts of ordinary web pages cannot be directly submitted as a TikTok mini game package.
Integration process
Step 1: Prepare your account and project
Before adapting your Cocos project, first confirm both platform-side preparations and the game project status. Do not wait until the package is generated to prepare accounts, test permissions, compliance materials, or app information.
Preparation checklist | Completion criteria |
The Cocos project runs properly | The game can enter the main gameplay in Cocos Creator or local development environment, without missing basic resources or startup errors. |
Platform-side preparation has begun | TikTok for Developers account, organization, test users, business verification, compliance tasks, and mini game app creation have clear owners and status. |
App information is recorded | App ID, client key, target regions, test users, base library version, and required configuration are ready. |
The scope of capabilities for the first version has been confirmed | You know whether the first playable version needs login, ads, payment, share, home screen shortcut, revisit from profile, or UI adaptation. |
DevTool validation path is ready | The team knows how to use DevTool to import packages, preview, scan on real devices, view logs, run code pre-check, and upload. |
Step 2: Build the base output from Cocos Creator
After developing the game in Cocos Creator, generate the base mini game output first. The exact output files depend on your Cocos Creator version and project configuration, but you should be able to identify the entry file, engine scripts, game scripts, resource directories, and project configuration.
Output | Pay attention to: | Completion criteria |
Entry file | Game launch entry, engine initialization entry, and initial scene loading entry. | TikTok mini game runtime can launch games from the package entry point, instead of relying on the regular web HTML entry. |
Script file | Scripts run by the Cocos engine, game business scripts, and scripts that must be loaded in the initial package. | The scripts required for the initial startup are accessible within the main package, with a clear loading sequence. |
Resource directory | Scenes, images, audio, fonts, configurations, asset bundles, or remote resource configurations. | The resource paths required for the initial scenario and core processes are correct, and the case, relative paths and remote addresses will not become invalid in the real device environment. |
Project configuration | Orientation, resolution, adaptation mode, base library, package structure, subpackage, and remote resource configuration. | The configuration is consistent with that of the target TikTok mini game app, target region and initial version capabilities. |
Do not treat build as a stage where TikTok injects the SDK after your game is built. Platform capability code, resource organization, and business logic should already be prepared inside the Cocos project. Build produces the package that you will continue to adapt and validate for TikTok.
Step 3: Adapt the output to TikTok mini game runtime
If Cocos does not provide a dedicated TikTok mini game build target, use a Cocos build output that is closer to a mini game runtime as the base output, then adapt the package structure, entry, resource loading, platform configuration, and platform API calls according to TikTok mini game requirements. The goal is not to reuse another platform's capabilities, but to complete adaptation and validation in the TikTok environment.
Item | What to do | Completion criteria |
Entry file | Make sure the TikTok loading entry points to the correct game startup logic. | The game can start in DevTool without being blocked at entry, engine initialization, or first scene loading. |
Package structure | Keep files required by Cocos runtime and remove platform-specific or irrelevant outputs that do not belong to TikTok. | The package structure is clear, with no obvious unrelated files, wrong configuration, or cross-platform leftovers before uploading. |
Resource loading | Check local resources, remote resources, asset bundle, fonts, audio, and configuration paths. | Resources load correctly in DevTool and real-device preview, including path case, CDN domains, and cache strategy. |
Subpackage configuration | Move resources that are not required for first screen or startup into suitable subpackages. | Startup resources are available in the main package, non-first-screen resources can be loaded on demand, and package size meets limits. |
Platform configuration | Replace configuration with the target TikTok mini game app information, base library version, and required settings. | Package configuration matches the target app, target regions, test users, and release plan. |
Keep TikTok-specific adaptation in Cocos project configuration or repeatable build scripts whenever possible. Do not rely on one-off manual edits, because entry files, resource paths, subpackage configuration, or platform capability calls may be overwritten after the next build.
Step 4: Integrate TikTok platform capabilities
Platform capability integration in a Cocos project should follow your game business flow. Do not pick APIs and test them in isolation. Decide what the first playable version must achieve, then integrate the corresponding capabilities.
Capability | When to integrate | Check inside the Cocos project |
Login | When the game needs accounts, save data, rewards, leaderboards, server sessions, or entitlement verification. | The login entry is connected to the correct game flow, and the temporary code is sent to game server for user identity exchange. |
In-App Ads (IAAs) | When the game needs rewarded video, interstitial ads, or other ad monetization. | Ad entry, reward grant, cancel, failure, timeout, and no-fill branches all have UI and business handling. |
In-App Purchases (IAPs) | When the game needs order creation, payment, delivery, and order verification. | Order creation, payment result, delivery, order verification, and failure recovery are aligned with game server. |
Sharing, home screen shortcut, and revisit from profile | When the game needs growth, social distribution, or revisit entries. | Entry position, reward rules, return state, and fallback handling are designed. |
UI adaptation | When the game needs to support different devices, safe areas, orientation, or display issues. | Cocos canvas, adaptation strategy, button hit areas, and safe area behavior are validated on real devices. |
Some capabilities require game server participation, such as login, payment, rewards, order verification, and entitlement maintenance. The client starts the call, displays state, and handles callbacks. User identity, trusted order status, and entitlement delivery should be confirmed on the server.
Step 5: Validate inside the Cocos project
Before entering DevTool, make sure the game itself and platform capability entry points work inside your Cocos project. Local simulation is a development practice. It helps you build UI, reward flows, state transitions, and failure branches, but it does not prove that real TikTok platform capabilities are available.
- Confirm the game is playable, including first scene, core gameplay, resource loading, and basic UI.
- Confirm login, IAAs, IAPs, sharing, and other capabilities are connected to the correct game flows.
- Confirm success, failure, cancel, timeout, no-fill, payment failure, and server failure branches are handled.
- Confirm game server test environment, integration APIs, and failure recovery can support the first version.
- Record Cocos version, build configuration, resource strategy, first-version capability scope, and test users.
Step 6: Debug in DevTool, then preview on a real device
Using DevTool and using a real device to preview on the TikTok app validate different things. Do not treat them as the same environment.
Environment | Main validation: | Cannot prove: |
Local development environment | Game logic, UI, resource organization, and development-stage business branches. | Real TikTok login, IAAs, IAPs, client version, account region, or review policy. |
DevTool | Package import, basic running, logs, package check, code pre-check, upload flow, and platform preview. | TikTok app runtime validation on real devices. |
TikTok app real-device preview | Runtime loading, device behavior, account status, regional behavior, and platform capability behavior. | Production users, retention, monetization, or quality monitoring after release. |
- Generate the TikTok mini game package and import it into DevTool.
- Confirm the package can start in DevTool and logs do not show obvious entry, resource, or configuration errors.
- Run code pre-check and package check, and fix blocking issues first.
- Use test users to run real-device preview in the TikTok app.
- Validate login, IAAs, IAPs, sharing, revisit entries, resource loading, and performance on real devices.
- Record package version, Cocos version, DevTool version, TikTok app version, device, region, and test user.
Step 7: Complete the pre-upload checklist
Before submitting for review, do not only confirm that the game can start. Confirm the final package, platform configuration, compliance materials, and test information all meet upload and review requirements.
Checklist item | Completion criteria |
Package structure | Entry files, engine scripts, game scripts, resource directories, configuration files, and subpackage structure are clear. |
Package size limits | Total package, main package, subpackages, and independent subpackages meet current platform limits. |
Resource loading | First scene, core gameplay, ad assets, payment-related resources, and remote resources load in real-device preview. |
Platform capabilities | Login, IAAs, IAPs, sharing, home screen shortcut, revisit from profile, and UI adaptation required by the first version have been validated against business goals. |
Game server | User identity exchange, rewards, order verification, entitlement maintenance, and failure recovery work in the test environment. |
Compliance materials | Privacy Policy, Terms of Service, target regions, industry qualification, data compliance, and monetization configuration meet review requirements. |
Test information | Test users, target regions, device information, reproduction steps, logs, and screenshots can be provided to the support team. |
