CocosCreator3.8 Research Notes (5) CocosCreator Script Description and Usage (Part 2)

In Cocos Creator, script code files are divided into modules and plug-ins:

• The module is generally the script of the project, including the code, engine modules, and third-party modules created in the project .

• The plug-in script refers to the plug-in imported from the Cocos Creator property inspector, which generally imports a third-party import library file. Currently, Cocos Creator only supports javaScript script plug-ins. Cocos Creator will insert some code into the content of the plug-in script to adapt to Creator, and will shield the global variables model, exports, and define.

The previous article mainly introduced the script module, and interested friends can check it out: CocosCreator3.8 Research Notes (4) CocosCreator Script Description and Use (Part 1)

This article mainly introduces the use and precautions of plug-in scripts in CocosCreator.

1. Import the plug-in script

When a script resource is imported into the resource manager and imported as a plug-in is set in the Property Inspector , the script resource is called a plug-in script .

Plug-in scripts are usually used to introduce third-party libraries. Currently, only JavaScript plug-in scripts are supported.

2. Simulate global variables

Many third-party JavaScript libraries provide library functions in the form of global variables. These libraries often write global variables window, global, selfand this.

However, these global variables are not necessarily cross-platform. For convenience, Creator provides the option to simulate global variables when importing plug-in scripts .

When enabled, Creator will insert the necessary code to emulate these global variables, similar to:

(function() {
    const window = globalThis;
    const global = globalThis;
    const self = globalThis;

    (function() {
        /* 原始代码 */
    }).call(this);

}).call(this);

3. Control plug-in scripts to execute in certain environments

options	Influence platform	Remark
Allow web platform to load	Browser, web page preview, editor	Enabled by default, when disabled, it will be disabled together with allowing the editor to load
Allow editor to load	editor	It is disabled by default. If other common scripts in the editor depend on the current script during loading, you need to manually enable this option. After it is enabled, local variables that are not declared in any function in the script will not be exposed as global variables, so global variables need to be window.abc = 0defined in the way to take effect.
Allow Native platform to load	Native platform, simulator preview	Enabled by default

In the import inspector, developers can specify dependencies to ensure the execution order of scripts.

4. Precautions when using plug-in scripts

• When the JavaScript script is imported as a plug-in, Creator will not modify the content of the plug-in script, but may insert some codes to adapt to Creator, and Creator will shield global variables module, exports, define.

• The plug-in script will be copied to the build directory almost intact, and the availability and cross-platform performance of the plug-in script are not guaranteed by Creator.

  For example: Many npm modules are directly or indirectly dependent node.js, so native or web platforms cannot be used.

  For example: A large number of front-end plug-ins, jQuery, etc. are used in web pages, which need to rely on the browser's DOM API, which cannot be used on native platforms.

• Plug-in scripts and non-plug-in scripts cannot interact in the form of import, and generally communicate through global variables.

  For example: developers know that the plug-in target platform actually supports CommonJS, and they cannot force its use through relative paths in non-plugin scripts require.

• Use global variables carefully. When you want to use global variables, you should know what you are doing. It is not recommended to abuse global variables. Even if you want to use them, it is best to ensure that global variables are read- only .

• When adding global variables, do not have the same name as the existing global variables in the system.

• You can freely encapsulate or extend the Cocos Creator engine in plug-in scripts, but this may increase communication costs and make scripts difficult to reuse.