Plugin Script

In the Assets, select any of the script, you can see such a settings interface in the Properties, we can set whether the script is "Import As Plugin" here.

• For Component script, data logic, the default is to cancel this option, such a script is referred to as Normal Script.
• For third-party script, or the underlying plugin, it may be necessary to select the option, such a script is referred to as Plugin Script.

This option is only related to the script, specific aspects of the impact, most people only need a simple understanding

When the "Import As Plugin" is checked, it is possible to further set up where the plugin script will take effect in Properties:

Script loading order

The script loading order is as follows:

1. Cocos2d engine
2. Plugin Script (if there are multiple, they are loaded in alphabetical order according to the path in the project)
3. Normal Script (only one file after packing, the internal scripts will be initialized in the order of require dependencies)

Target platform compatibility

After the project is published, the plugin will be loaded directly by the target platform, so please check the plugin compatibility with the target platform, or the plugin may not run.

• The target platform does not provide native Node.js support

  For example, many npm modules depend directly or indirectly on Node.js, which can not be used when they are published to a native or web.

• Plugins that rely on the DOM API will not be able to publish to native platforms

  Web pages can use a lot of front-end plugins, such as jQuery, but they may depend on the browser's DOM API. Plugins that rely on these APIs can not be used in native platforms.

Precautions

• If the plugin contains multiple scripts, you need to merge all the scripts used by the plugin into a single js file

  Take Async (https://github.com/caolan/async) as an example, this library contains a lot of fragmented source files, if you put all the source files into the project, each source file must be set "Import As Plugin" once, and Creator can not guarantee the load order between these source files, it is easy to report errors. So we have to find the pre-compiled single script provided by plugin author, such as async.js or async.min.js. Such a file can be loaded directly by the browser, do not need to do additional compilation operations, generally can be put directly into Creator. If the plugin author does not provide a packaged version, usually also shows how to compile the browser executable script in the document, according to the operation just fine.

• If the plugin also depends on other plugins, you also need to merge multiple plugins into a single js file

  In the example of protobuf.js, this library also depends on bytebuffer.js, but the plugin author does not provide an integrated standalone version. We can first download the two files protobuf.js and bytebuffer.js which compiled from the two libraries, and then use the text editor or a command-line tool like cat to concat these two scripts into a new script protobuf_all.js. Then you can use this protobuf_all.js directly in Creator.

• Does not support plugins to actively load other scripts

  To lzma plugin, for example, the default lzma.js script provided by this plugin will load another worker script through the browser's Worker, which is not currently supported by Creator. The solution is to use lzma_worker.js alone. Others like the use of document.createElement("script") self-loading dependencies plugins, also need to do a similar process to import into Creator.

Global variable

Since all Plugin Scripts are guaranteed to be loaded before Normal Scripts, you can use this feature to declare some special global variables in addition to being used to load the plugin.

You can add such a script in the project, and set the "Import As Plugin":

/* globals.js */

// Defines the default value for new components
window.DEFAULT_IP = "192.168.1.1";

// Define the component switch
window.ENABLE_NET_DEBUGGER = true;

// Define engine API abbreviations (only for constructors)
window.V2 = cc.Vec2;

Then you can use them directly in any Normal script, such as using global variables like DEFAULT_IP when declaring class:

/* network.js */

cc.Class({
    extends: cc.Component,
    properties: {
        ip: {
            default: DEFAULT_IP
        }
    }
});

/* network_debugger.js */

if (ENABLE_NET_DEBUGGER) {
    // This component takes effect when ENABLE_NET_DEBUGGER
    cc.Class({
        extends: cc.Component,
        properties: {
            location: {
                default: new V2(100, 200)
            }
        },
        update: function () {
            ...
        },
    });
}
else {
    // Otherwise this component does nothing
    cc.Class({
        extends: cc.Component,
        start: function () {
            // Remove the component after it starts
            this.destroy();
        }
    });
}

In this case, the variables in globals.js has been used since scripts such as network.js and network_debugger.js are loaded. So if the globals.js is not a plugin script, each script that might use those global variables should declare require("globals"); at the top, to ensure that globals.js is loaded first.

But if a global variable itself is to be initialize in the component's onLoad, it is recommended to use window.foo = bar to declare the global variables directly in the onLoad of a Normal Script, do not need to use the Plugin Script, see Access by using global variable.

Please note that when the game is running away from the editor, the plugin script will run directly on the global scope. Local variables within the script that are not in any function will be exposed as global variables. Be careful to cause global variables to pollute.

You should use global variable with care and understanding, we do not recommend using it, you had better keep them readonly if really need to do that.
Please avoid name duplication with exists global variables in the system.
You can freely encapsulate or extend the Cocos2d engine in Plugin Scripts, but this will increase team communication costs, making scripts difficult to reuse.