Native Plugins

Notice: Native plugin support for 3.6.2 is broken, please upgrade to 3.6.3 or later.

Native Plugins are part of the editor plugins. By calling JSB interfaces (e.g. export with sebind) through native plugins, developers can extend the ability of JS scripts to call C++ interfaces, which can be very beneficial for solving script performance bottles and reusing existing codebases. As the engine is upgraded in the future, the native plugins will open up more features.

Cooperation with existing Editor Extensions

Native plugins can exist independently of editor extensions, and users can use native plug-ins by copying them to the specified directory.

At the same time, native plugins complement the existing editor extension system, extending the game’s runtime capabilities. Developers use the ability of editor extensions to manage native plugins, such as download/switch/version upgrade, etc.

Installing Dependencies

In a few environments without Cocos Creator installed, NodeJS version 8.0 or higher is required to support plugin configuration parsing. You can set the environment variable PATH, or specify it by setting the NODE_EXECUTABLE variable in CMakeLists.txt.

Or set the environment variable NODE_EXECUTABLE to the full path to node. Starting with 3.6.2, if CMake still does not locate NodeJS, you can set NODE_EXECUTABLE directly in native/engine/common/localCfg.cmake.

Example of the plugin’s directory structure

  1. ├── cc_plugin.json
  2. ├── android
  3. │ ├── arm64-v8a
  4. │ ├── armeabi-v7a
  5. │ ├── x86
  6. │ └─ x86_64
  7. ├─ ios
  8. │ ├── include
  9. │ └── lib
  10. ├─ mac
  11. │ ├── include
  12. │ └── lib
  13. └─ windows
  14.     ├─ include
  15.     └── lib

The file cc_plugin.json provides the information necessary to load the plugin, and is the identifier of the native plugin. Each supported native platform corresponds to a directory that contains at least one <PackageName>-Config.cmake file. The build system will use CMake’s find_package mechanism to locate or link to the required library files.

If there are cross-platform source files or CMake configurations in the plugin, these files can be merged into the top-level directory. For example: example project

Description file cc_plugin.json format

  1. {
  2.     "name": string;             // required: plugin name
  3.     "version": string;          // required: plugin version
  4.     "engine-version":string;    // mandatory: the range of the corresponding engine version
  5.     "author": string;           // required: the author of the plugin
  6.     "description": string;      // required: description of the plugin
  7.     "platforms":string[];       // optional: list of supported platforms, all native platforms are supported by default if not filled. Including windows, android, mac, ios
  8.     "disabled":true;            // optional: Disable plugins on all platforms
  9.     "disable-by-platforms":string[];    // optional: Disable plugins for the specified platform
  10.     "modules": [{        // mandatory: the libraries included in the plugin, 
  11.         "target":string;                // mandatory: the name of the corresponding `find_package`, consistent with the first parameter of `CC_PLUGIN_ENTRY`
  12.         "depends": string|string[];     // optional: depends on other module names 
  13.         "platforms":string[];           // optional: re-qualify the supported native platforms
  14.     }]
  15. }

engine-version can specify a version range and exclude specific versions, for example:

  1. "engine-version": ">=3.3 <= 3.6.0 !3.5.2 || 4.x"

Example file

Example of description file cc_plugin.json

  1. {
  2.     "name": "hello-cocos-demo",
  3.     "version": "0.1.0",
  4.     "author": "demo group",
  5.     "engine-version":">=3.6.0",
  6.     "description": "demo project",
  7.     "modules":[
  8.         {
  9.             "target": "hello_cocos_glue"
  10.         }
  11.     ],
  12.     "platforms":[ "windows", "android", "mac", "iOS" ]
  13. }

Installing Native Plugins

Developers can download and enable editor extensions from the Store that contain native plugins, and complete the installation of the plugins into the extensions directory. You can also get the plugin archive from the forums and manually extract it to the native/ directory or its subdirectories.

If you want to disable the plugin, or disable it only in a special platform, you can change the relevant fields(disabled and disable-by-platforms) in cc_plugin.json.

Note: Native plugins require CMake 3.12+, Android projects need to specify cmake version to 3.18.1.

Creating native plugins

Cocos native projects are managed using CMake. Simply put, a native plugin is a search directory for find_package on specific platform.

As long as the directory matches the cmake find_package search rules, the plugin will load correctly, regardless of whether it is source code or precompiled libraries. Therefore, the development process of a native plugin is the process of providing the cmake configuration and related resources, and writing cc_plugin.json.

See Cocos Native Plugin Quick Tutorial to learn more about native plugins.