Introduction to the Build Process and FAQ

• General build processing
• Build processing for each platform

Due to the adjustment of the build mechanism in v3.0, the build process of different platforms is injected into the Build panel in the form of build plugins, each participating in the build process. The build options specific to each platform are displayed in the Build panel in the form of expanded options. Developers can make custom build options appear in the Build panel via the build plugin.

The general Build process of Cocos Creator mainly includes the following contents:

1. Initialization of build options
2. Build data organization
3. Write the built resources to the file system
4. Organize settings.json/config.json data
5. UUID compression and file writing in config.json

This step is mainly for initializing the primal options passed to the build during the build to build internal options, completing the format conversion of some of the build options, initialize project configuration, initialize the asset data of the build asset database, and check the latest asset information and classify it.

Build data organization

When building, the editor will first sort out the current scenes involved in the build and assets in all Bundles folders and then search for their dependent assets through engine deserialization, and recursively find a list of all the assets that need to be packaged. After the asset list is summarized, the assets will be classified according to the Bundle configuration, and script compiling tasks, image compression tasks, and json grouping information will be collected.

Writing the built assets to the file system

The built assets will be packaged into assets/[Bundle name] under the corresponding platform release package directory according to the configuration of the Asset Bundle after the build is completed. The directory structure is as follows:

For more information about Asset Bundle configuration, building, file description, etc., please refer to the documentation.

After organizing the basic build tasks, the build will loop through all the Bundles, executing the asset packaging tasks that each Bundle needs to handle in turn to generate these Bundle asset packages.

Each Bundle goes through the following asset handling process:

• Script Building: scripts within the editor are divided into plug-in scripts and non-plugin scripts, with different rules for handling different kinds.

  • Plug-in scripts: directly copy the source files according to the original directory structure to the src directory under the release package directory generated after the build, the plug-in script does not support any script form that needs to be compiled, such as TypeScript or JavaScript (ES6). The asset information of the plug-in script will be written into the jsList array in settings.

  • Non-plugin scripts: packaged into project.js and placed in the corresponding src directory. Checking the sourceMap option will generate the corresponding .map file, and determine whether the script is compressed according to the debug option.

• Auto Atlas Processing: queries the Auto Atlas asset list within the project, packaging the SpriteFrame small images under the atlas into a large image, generating serialized files, etc. according to the configuration of the Auto Atlas resource. This step will also modify the json grouping information, asset grouping information, and add texture compression tasks.

• Texture Compression: according to the organized image compression task, the image assets are compressed and written into the build folder.

• Engine Script Compilation: according to the configuration in Main Menu -> Project Settings -> Feature Cropping, remove the unused engine modules and pack them into the cocos-js directory. Checking the option in the Build panel will generate the corresponding .map file, and determine whether the script is compressed according to the debug option.

  The main steps of engine compilation include:

  • Get engine module information in project settings.

  • If compilation is needed, execute the task of packaging the engine, then copy the compiled js file and save the engine’s cache judgment information file.

    When compiling the engine, can be viewed:

    Regarding the reuse rules of engine files, it is necessary to elaborate:
    The packaged engine file will be placed in the editor’s global temporary directory (use Build.globalTempDir to look up the cache address during the build process). The cache file is stored as the name according to the hash value generated by the parameters that will affect the engine compilation.

    As long as any relevant engine build parameters are changed, the engine will be recompiled. Parameters that specifically affect the use of the build engine cache are:

    • includeModules: engine module settings
    • sourceMaps: whether to enable sourceMaps
    • platform: build platform
    • Engine modification time
    • Whether to check the Separate Engine in the Build panel (only WeChat Mini Game)
    • Use engine path, engine version number

• JSON build: When serializing JSON, it will be merged and written into the file system (in the folder assets/xxxBundle/import) according to the JSON grouping and the Bundle to which it belongs. If it is in release mode, it will also compress the UUID in the serialized JSON.

• Common Asset Copy: Some raw assets will be directly copied from the library to the built folder assets/xxxBundle/native.

• md5 processing: Add the .md5 suffix to all the assets, project scripts and engine files in the assets folder, and organize the data to be recorded in the settings.json.

• application.js template file generation: dynamically generates the application.js file according to user options and generate it to the release package directory src generated after the build.

Organizing settings.json/config.json and configuring JSON data

It is mainly to prepare the necessary configuration information for the game launch based on the asset data compiled previously.

settings.json

settings.json records the basic configuration information of the whole game package, which will directly affect the initialization of the game package.

The description of the settings.json configuration is as follows:

config.json

Each Bundle asset package has a config.json, which records basic information such as assets and scripts for the entire Bundle, which will directly affect the loading of the Bundle package.

The description of the configuration is as follows:

The structure here only lists the structure of settings.json and config.json in a general sense. In fact, these parameters will vary after different platform builds.

Before generating the config.json file, the UUID information in the file will be compressed according to whether it is in release mode or not, understanding this rule will be helpful to find the location of the file after the asset is built.

The UUIDs used in the Bundle will be sorted during the build, and those that appear twice or more will be stored in the uuids array, and the location of the previously used UUID will be replaced with the index.

All types that appear twice and more are also stored in the types array, and the previously used position is replaced with the index.

Build assets

This step generates project asset files other than scripts, since scripts are compiled and processed separately as special files. The assets are re-serialized after deserialization is performed during the packaging process to reduce the package size after packaging. Multiple serialized JSONs are combined into a single file based on the JSON grouping information collated from the previous data, e.g. the serialized files of the texture asset are all packaged into a single JSON file.

Compilation/generation process of each platform

The build process of all platforms that require support for separate compilation and generation have been split. Some developers may wonder why the current mini game platform has a new Make button. In fact this part of the logic has always existed before, but it is merged in the build process and cannot be controlled separately.

The build of the editor is similar to the function of an export game package for the corresponding platform, which is mainly to complete the interface of the engine to each platform and the compatibility of the basic format of the game package, which does not mean that all the work is completed. Each platform usually has its own compilation process, such as the compilation and upload function of the developer tools that come with the WeChat Mini Game platform, and the compilation, running and debugging functions of the relevant IDE for each native platform. If the developer needs to customize the packaging process for a specific platform, the editor needs to support the process of splitting in order to better access.

The entire build process is in a single worker, to view the log information of the build process or view the complete call stack when an error occurs, click on the main menu, then select Developer -> Open Build DevTools. In fact, a lot of log information will be output when building, but in order not to interfere with users, by default only error and important information will be printed to the editor’s Console panel, and the log information in the devtools is the most complete.

Note: before building please make sure that the scene participating in the building can be previewed normally. Loss of assets in some scenes or other script problems can be exposed during the preview stage. Building under the condition that the preview is normal can save time and troubleshoot better.

Asset loading 404 errors

In case of a 404 error, please copy the UUID in the log that reported the error resource loss and search for the corresponding resource in Assets panel to check whether the resources that the resource depends on are normal. Resource loading 404 errors usually occur under the following situations:

1. Resources that are not placed in the Bundle are dynamically loaded in the script.

   • Reason: Through the above introduction, we know that only the resources and their dependent resources in the Bundle directory, as well as the resources and their dependent resources participating in the build scene will be packaged into the final build folder, and only the resource URL directly put into the Bundle folder will be written to the config.json. If a resource is used in the script but the resource is not placed in any Bundle directory, a 404 error will appear when it is loaded.

   • Solution: Move the used resources to the Bundle folder.

2. There is a problem importing the loaded resource, and the data cannot be generated normally to the library

   • Reason: All the original data is obtained by reading the asset files in the library during the build. If the import fails, the correct corresponding asset information will not be obtained.

   • Solution: Find the corresponding asset through Assets panel, right-click, and select Reimport Asset in the menu.

3. Asset Loss

   • Reason: As mentioned in the previous construction process, asset construction will go through the reverse sequence to find dependent assets, and the most frequent problem is that the dependent assets are accidentally during the project iteration process delete and cause asset loss. The loss of these assets may not usually be noticed, but once the build is performed, it will be exposed.

Script asset loading error

As mentioned in the previous section of Building Data Sorting, the script environment needs to be configured when building. If the error message is related to the script, please refer to the error content to modify the script. If it is unknown which script is reporting the error, find the UUID of the corresponding script in the error message call stack, and then find the location in the Assets panel.

The Auto Atlas will print out the UUID information of the original small image and the synthesized large image during the build process, which can be found in the build devtools, and then use the UUID of the composite large image found to generate the XXXBundle/native after packaging. You can view it in the directory. If there are too many combined images, open the build log file and search for the UUID.

How to decompress UUIDs

In release mode, the packaged asset JSON file and the UUID in config.json are compressed and need to be unzipped to find the corresponding assets in the original project. There are some built-in tools and methods in the build process. On the global variable Build, directly click Developer -> Build DevTools in the main menu, the original UUID can be queried in the console by entering the following command:

Engine compilation failed

If the engine fails to compile, please check if the installation package is complete, if the modified built-in engine code is correct, and if you are using a custom engine, if the path is correct, etc.

Other errors