Publish to Douyin Mini Games

Note: some platforms only have Chinese documentation available when visiting the platform’s website. It may be necessary to use Google Translate in-order to review the documentation.

Douyin Mini Games are developed based on Douyin full products, which do not require users to download. This is a brand-new game type that can be played on tap.

The game submission, review and release process of a mini-game needs to comply with the requirements and standard processes of the Douyin official specification. For specific information, please refer to the links at the end of this document.

Preparation

  1. Download the Douyin DevTools [cn] and install it..

  2. Refer to the Douyin Mini Game Access Guide [cn] to register, login and apply for mini games on the Douyin Developer Platform [cn].

  3. After the application is approved, find the appid in Development Management -> Development Settings of the developer platform.

    appid

Publishing Process

  1. Use Cocos Creator to open the project to be published, open the Build panel from Menu Bar -> Project, select Douyin Mini Game in Platform, fill in the appid, and click Build.

    build

    Click on the Douyin Mini Game below to expand the build options configuration of Douyin Mini Game:

    Douyin options

    For the general build options settings, please refer to General Build Options for details. The Douyin Mini Games specific build options are shown below, please refer to the Build Options section below for the filling rules.

  2. After the relevant parameters of the Build panel are set, click Build button.
    When the build is complete, click the folder icon button below the corresponding build task to open the build release path, notice that a directory bytedance-mini-game (with the same name as the Build Task Name) is generated in the default release path build directory, which already contains the configuration files game.json and project.config.json of the ByteDance Mini Games environment.

    package

  3. Use the Douyin DevTools to open the bytedance-mini-game folder generated by the build, open the Douyin game project and preview the debugging game content. Please refer to the Introduction to Douyin DevTools [cn] for details on how to use the developer tools.

    tool

Build Options

OptionsDescriptionField name (for publishing with command line)
Start Scene Asset BundleIf set, the start scene and its related dependent resources are built into the built-in Asset Bundle — start-scene to speed up the resource loading of the start scene.startSceneAssetBundle
OrientationDevice orientation, it will be written to game.json file.orientation
AppIDThe appid of the Douyin Mini Games, it will be written to project.config.json file.appid
Remote server addressThis option is used to fill in the address of the remote server where the resources are stored. Developers need to manually upload the remote folder from the release package directory to the filled resource server after build.remoteServerAddress
Open data context rootFor access to Open Data Context, please refer to the Open Data Context documentation for details.buildOpenDataContextTemplate
Native PhysX Physics SystemThis option is used to set whether to use the PhysX physics system, please see the Native Physics section below for more details.-

Native Physics

The Douyin platform has always been committed to providing developers with the more powerful performance and basic capabilities. TikTok will provide PhysX native physics interfaces for Douyin mini games in v16.3 and later versions.

Cocos Creator and the Douyin platform have conducted in-depth collaboration, with the experimental feature in v3.2 to support the use of PhysX physics capabilities provided by the Douyin platform in Douyin Mini Games, optimizing the performance of physics calculations, and having a nearly 100% performance improvement compared to Bullet physics:

compare performance

The prerequisite for using native physics is to set Physics System to PhysX in Project -> Project Settings -> Feature Cropping in the Creator main menu bar. Then open the Build panel with the Platform option set to Douyin Mini Game, and see the native physics related configuration options as follows:

PhysX options

OptionsDescriptionField name (for publishing with command line)
Not to pack the built-in PhysX libraryIf checked, the built-in PhysX library files will not be packaged when building, which helps to reduce the package size, but does not support PhysX running on some application platforms of Douyin, such as TikTok (iOS version) and DevTools.
If unchecked, Creator supports PhysX running on the full application platform of Douyin.
physX.notPackPhysXLibs
Multithreading modeIf checked, multithreading mode is enabled.physX.multiThread
Number of sub-threadsThe number of sub-threads when multithreading mode is enabled.physX.subThreadCount
Tolerance of errorsIf this option is enabled, the precision will be lower when using multithreading than single threading.physX.epsilon

Subpackage Loading

The Douyin Mini Game requires a specific version to support the subpackage feature, and the version requirements for the Douyin product are as follows:

ProductAndroidiOS
TikTokv13.6.0v13.7.0
TouTiaov7.9.9v7.9.8

For Douyin DevTools, please use v2.0.6 or above, but below v3.0.0. After updating the DevTools, don’t forget to modify the Debug Base library to 1.88.0 or above in the Douyin DevTools.

Note: if the product version does not support subpackage loading, the engine will load the subpackage as a normal asset bundle.

Ordinary game packages

In the scenario of not configuring sub-packaging, the total size of code packages allowed to be uploaded for each mini-game is capped at 20MB.

Packages after packetization

For games with subpackaging configured, the default limit is:

  • The size of the whole game package (the entire directory of the game package) should not exceed 20MB.
  • The size of a single main package should not exceed 4MB.
  • The size of a single sub-package should not exceed 20MB.

For details, please refer to the Douyin Subpackage Loading Official Documentation [cn]

Asset Management for Douyin Mini Game Environment

In a Douyin Mini Game environment, asset management is the most special part. It differs from the browser in the following four points:

  1. The size of the Douyin Mini Game package cannot exceed 4MB, including all the code and assets. Additional assets must be downloaded via web request.

  2. For files downloaded from a remote server, the Douyin Mini Game environment does not have the browser’s caching and outdated update mechanism.

  3. For the assets in the Douyin Mini Game package, they are not loaded on demand in the mini game environment, but rather all the assets in the package are loaded at once, and then the game page is launched.

  4. You cannot download script files from a remote server.

This brings up two key issues, home page loading speed and remote asset caching and version management. For the home page loading speed, we recommend that developers only save the script file in the Douyin Mini Game package, and all other assets are downloaded from the remote server. As for downloading, caching and version management of remote assets, Cocos Creator has done the job for developers.

Specifically, developers need to do the following:

  1. When building, enable the MD5 Cache in the Build config panel.
  2. Set the Remote service address, and then click Build.
  3. When the build is complete, upload the res folder in the mini game release package to the server.
  4. Delete the res folder inside the local release package.
  5. For the test phase, you may not be able to deploy to the official server, you need to use the local server to test, then open the details page in the WeChat DevTools, check the Does not verify valid domain names, web-view (business domain names), TLS versions and HTTPS certificates option in the Local Settings.

Reference documentation

Note: some platforms only have Chinese documentation available when visiting the platforms website. It may be necessary to use Google Translate in-order to review the documentation.