Extending Build Process

    1. Click Project -> New Build Extension in the menu bar of the editor, and select Global/Project to create a build extension package.

      • If selecting Global, the build extension will be applied to all Cocos Creator projects. The path of Global is:

        • Windows: %USERPROFILE%\.CocosCreator\extensions

        • macOS: $HOME/.CocosCreator/extensions

      • If selecting Project, this will apply the build extension to the specified Cocos Creator project. The path of Project is:

        • $Your project address/extensions

    2. After the build extension is created, notice the generation path of the plugin in the Console. Click on the path to open the build extension package in the file manager of the operating system.

    3. Before enabling the build extension, execute npm install in the directory to install some dependent @types modules to compile normally. The interface definition that comes with the editor has been generated under the @types folder in the root directory. Developer -> Export.d.ts from the menu bar of the editor shows the latest interface definitions.

    4. Click Extension -> Extension Manager in the menu bar of the editor to open the Extension Manager panel. Then select the Project/Global tab in the Extension Manager, and click the Refresh Icon button to see the build extension just added. Then click the Enable button on the right to run the plug-in normally.

      enable-plugin

    5. After the build extension is enabled, open the Build panel, notice the expansion bar of the build extension plugin. Click Build to join the build process.

    6. To modify the content of the built extension, directly modify the build extension package under the extensions directory, review the readme.md file in the build extension package directory for details. Find the corresponding build extension in the Extension Manager, and click the Reload icon button. The extension in the editor will re-run with the latest code and files.

      reload

    To extend the build function of the plug-in, add the builder field to the contributions in package.json, and the relative path configuration of the corresponding module can be passed to the specified platform in the field.

    Example package.json:

    The plugin entry configuration code example is shown below:

    1. // builder.ts
    3. // Allow external developers to replace parts of the build asset handler module. Please refer to the "Custom Texture Compression Processing" section below for details.
    4. export const assetHandlers: string = './asset-handlers';
    6. export const configs: IConfigs = {
    7.     'web-mobile': {
    8.         hooks: './hooks',
    9.         options: {
    10.             remoteAddress: {
    11.                 label: 'i18n:xxx',
    12.                 render: {
    13.                     ui: 'ui-input',
    14.                     attributes: {
    15.                         placeholder: 'Enter remote address...',
    16.                     },
    17.                 },
    18.                 // Validation rules, there are currently several commonly used validation rules built in, and the rules that need to be customized can be configured in the "verifyRuleMap" field
    19.                 verifyRules: ['require', 'http'],
    20.             },
    21.             enterCocos: {
    22.                     label: 'i18n:cocos-build-template.options.enterCocos',
    23.                     description: 'i18n:cocos-build-template.options.enterCocos',
    24.                     render: {
    25.                         // Please click "Developer -> UI Components" in the menu bar of the editor to view a list of all supported UI components.
    26.                         ui: 'ui-input',
    27.                         attributes: {
    28.                             placeholder: 'i18n:cocos-build-template.options.enterCocos',
    29.                         },
    30.                     },
    31.                     verifyRules: ['ruleTest']
    33.             },
    34.             verifyRuleMap: {
    35.                 ruleTest: {
    36.                     message: 'i18n:cocos-build-template.ruleTest_msg',
    37.                     func(val, option) {
    38.                         if (val === 'cocos') {
    39.                             return true;
    40.                         }
    41.                         return false;
    42.                     }
    43.                 }
    44.             }
    45.         },
    46. };

    1. The environment variables in different processes will be different. The start script will be loaded by the rendering process and the main process at the same time, do not use the editor interface that only exists in a single process in the start script.

    2. There are two ways to configure the key of config:

      • One is for a single platform configuration, and the key is filled in as platform plugin name (available in the editor menu bar Extensions -> Extension Manager -> Internal to view the platform plug-in name).

      • One is the configuration for all platforms, the key is filled in as *. These two configuration methods are mutually exclusive, please do not use them in the same build extension package.

    Start script interface definition

    The detailed interface definition is described as follows:

    1. declare type IConfigs = Record<Platform | '*', IPlatformConfig>;
    2. declare interface IBuildPlugin {
    3.     hooks?: string; // Storage path of hook function
    4.     options?: IDisplayOptions; // Platform parameter configuration that needs to be injected
    5.     verifyRuleMap?: IVerificationRuleMap; // Register parameter verification rule function
    6. }
    7. declare type IDisplayOptions = Record<string, IConfigItem>;
    8. declare interface IConfigItem {
    9.     // The default value, the registered default value will be in the "options.[platform].xxx" field in the plugin configuration
    10.     default?: any;
    12.     render: ?{
    13.         // The rules for rendering UI components are consistent with the unified rules at "ui-prop". Only configurations with UI properties specified will be displayed on the Build panel
    14.         ui?: string;
    15.         // The configuration parameters passed to the UI component
    16.         attributes?: IUiOptions;
    17.     };
    19.     label?: string;
    21.     // A brief description of the setting, which will be displayed on the title when the mouse hovers over the configuration name.
    22.     description?: string;
    24.     // Type of configuration
    25.     type?: 'array' | 'object';
    28.     itemConfigs?: Record<string, IConfigItem> | IConfigItem[];
    29. }
    31. declare interface IUiOptions extends IOptionsBase {
    32.     // Validation rules array, build provides some basic rules, and you can also specify new validation rules through “verifyRuleMap”. Only when pass in “require” will be a valueless checksum, otherwise only when there is a value.
    33.     verifyRules?: string[];
    34. }
    36. declare interface IUiOptions extends IOptionsBase {
    37.     class?: string | string[]; // The name of the style that needs to be set on the current "ui-prop"
    38. }

    For the interface definition of IOptionsBase please refer to .

    In the script module defined by the hooks field in the entry configuration, hook functions can be written that build the life cycle. In different hook functions, the data received will be different. All hook functions run in the build process, and the engine method can be used directly in the build process.

    The relationship between the public hook function and the life cycle of the build can be seen in the following figure:

    The rough interface definition of hook function is as follows:

    A simple example:

    1. export function onBeforeBuild(options) {
    2.     // Todo some thing...
    3. }
    4. export async function onBeforeCompressSettings(options, result) {
    5.     // Todo some thing...
    6. }

    The assetHandler path configuration specified in the start script configuration above allows external developers to register some asset handling functions to replace the engine’s handler module when building partial assets. Currently only texture compression handler registration is available.

    Creator provides its own compression tools to handle compressed texture assets at build time, but does not focus on image compression because it needs to be compatible with different user environments and usually the compression tools are chosen to work on most computers rather than the most efficient ones. Therefore, Creator has opened up a plug-in mechanism in v3.4, which allows users to directly register compression processing functions for the corresponding texture assets, which will be called at the appropriate processing time when building.

    The specific steps are as follows:

    1. In the start script, write the relative path of the assetHandlers module script:

      1.  export const assetHandlers = './asset-handlers';

    2. In the assetHandlers script module, the compressTextures function has been opened up for developers to write the corresponding handler function directly in compressTextures, which will be called during the texture compression phase of the build.

      When there are multiple plugins registered with texture compression handler functions, they are executed in the order in which the plugins are started. If the previous plugin processes all the texture compression tasks, the subsequent plugins registered with the handler functions will not receive the tasks.

      The code example is as follows:

    When the build extension plugin is involved in the build process, the associated code runs in the following three processes:

    • Main Process: executes the start script and its dependent assets.
    • Rendering Process: executes some of the fields registered in the start script to the Build panel.
    • Build Process: executes the script defined in the hooks field of the start script.

    Main Process (Start Script)

    The main process mainly executes the start script used in the build extension plugin to participate in the build process (the script specified in the builder field), and the plugin’s own start script (the script specified in the main field).

    When the code running in the main process is modified, the plugin must be restarted and then the process to be updated must be refreshed (this will be optimized later to try to solve the code update problem with a single restart, but refreshing is still the most thorough reloading method). The main process currently does not have a more appropriate debugging method, you can use the command line to open the editor to view the main process code log to assist debugging:

    1. // Mac
    2. /Applications/CocosCreator/Creator/3.0.0/CocosCreator.app/Contents/MacOS/CocosCreator --project projectPath
    4. // Windows
    5. ... \CocosCreator.exe --project projectPath

    The start script of the build extension plugin has some fields that are registered to the Build panel, such as the display configuration of options, the panel field, and the panel script itself, which is loaded and executed in the render process. The rendering process is actually the window’s own execution process. Open the DevTools to debug the dom elements, styles, scripts, etc. on the Build panel.

    If the code registered to the Build panel is modified, refresh the panel without restarting the plugin.

    • Open the DevTools for the rendering process of the Build panel

      Click on the Build panel and press the shortcut Ctrl + Shift + I (Windows) or Command + Option + I (Mac) to open the DevTools for the Build panel.

    • How to reload (refresh) the panel

      Press Ctrl/Command + R after clicking on the Build panel or the DevTool in the Build panel.

    Build Process (hooks Script)

    The actual execution phase of the build is a separate worker process, ensuring that even if an abnormal crash occurs, it will not affect the normal use of other windows. The scripts defined in the hooks field of the start script are also loaded and executed in this separate worker process.

    If only the script defined in the hook field is modified, the build process can be refreshed without restarting the plugin. To do this, press Ctrl/Command + R after opening the build DevTools, as in the Build panel above.

    Opening the DevTools for the build process

    This includes the following three ways:

    1. Click the Open Build DevTools button at the top right of the build task window in the Build panel.

      dev_tools

    2. Click Developers -> Open Build DevTools in the main editor menu to open it.

    3. In any plugin code or in the console, execute the following code: