External code support

Plugin script

When the script resource is imported with import as a plug-in, this script resource is called plug-in script. Plug-in scripts are usually used to import third-party libraries. Currently only supports JavaScript plug-in scripts.

Unlike other scripts in the project, Cocos Creator 3D will not modify the content of the plug-in script, but some code may be inserted to adapt to Creator 3D itself; in particular, Cocos Creator 3D will shield the global variables module, exports, define.

Execution timing

Developers can control whether plug-in scripts are executed in certain environments.

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

Usability and cross-platform

The plug-in script is copied to the build directory almost intact, so the usability and cross-platform of the plug-in script are not guaranteed by Cocos Creator 3D. For example, when plug-in scripts use language features that are not supported by certain platforms, errors will result, especially:

-The target platform does not provide native node.js support
For example, many npm modules directly or indirectly depend on node.js, so they cannot be used after being published to native or web platforms.

-Plugins that rely on the DOM API will not be able to publish to the native platform
A large number of front-end plug-ins can be used in web pages, such as jQuery, but they may depend on the browser's DOM API. Plugins that rely on these APIs cannot be used on the native platform.

Interaction

Plug-in scripts and non-plug-in scripts cannot interact in the form of import. For example, even if the developer knows that their target platform actually supports CommonJS, nor can it be used in a non-plug-in script forcibly through the relative path of require.

Therefore, plug-in scripts generally communicate in the form of global variables (also known as IIFE module format).

Note: Developers should use global variables very carefully. When you want to use global variables, you should be very clear about what you are doing. We do not recommend abusing global variables. Even if you want to use them, it is best to ensure that global variables are read only.

Note: When adding global variables, please be careful not to have the same name with the existing global variables in the system.

Note: Developers can freely encapsulate or extend the Cocos Creator 3D engine in the plug-in script, but this will increase the cost of team communication and make the script difficult to reuse.

Import options

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

However, these global variables are not necessarily cross-platform. For convenience, when importing plug-in scripts, the option Simulate global variables is provided. After opening, Cocos Creator 3D will insert the necessary code to simulate these global variables. Example:

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

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

}).call(this);