原生插件
注意:对 3.6.2 的原生插件支持有问题,请升级到 3.6.3 或更高版本。
原生插件是编辑器插件的一部分。开发者通过原生插件调用脚本绑定接口(如 sebind)可以扩展 JS 脚本调用 C++ 的接口的能力,对解决脚本的性能瓶颈和复用现有代码库都非常有利。
和现有插件系统的关系
原生插件能独立于编辑器插件存在,用户通过拷贝到指定目录就可以使用原生插件。
同时,原生插件也作为现有编辑器插件系统的补充,扩展游戏运行时的能力。利用编辑插件的能力实现对原生插件管理, 如:下载/开关/版本升级等功能。
插件的结构
每个插件的根目录下都有一个插件的描述文件 cc_plugin.json
,这是一个标准的 JSON 文件。
在构建原生工程的时候,构建系统会从工程的 extensions
和 native
目录中去递归查找这所有的 cc_plugin.json
文件,以定位原生插件。一旦在目录中找到 cc_plugins.json
,就不会再查找子目录中的内容。
安装依赖
在少数未安装编辑器的环境下,需要安装 NodeJS 8.0 以上的版本,以支持插件配置解析。开发者可以将 NodeJS 并设置环境变量 PATH
,也可以在 CMakeLists.txt
中通过设置 NODE_EXECUTABLE
指定。
也可以设置环境变量 NODE_EXECUTABLE
为 node 的完整路径。3.6.2 开始,如果 CMake 仍然定位不到 nodejs,可以在 native/engine/common/localCfg.cmake
中直接设置 NODE_EXECUTABLE
。
目录结构示例
├── cc_plugin.json
├── android
│ ├── arm64-v8a
│ ├── armeabi-v7a
│ ├── x86
│ └── x86_64
├── ios
│ ├── include
│ └── lib
├── mac
│ ├── include
│ └── lib
└── windows
├── include
└── lib
文件 cc_plugin.json
是提供了加载插件所必须的信息,是原生插件的标识。每一个支持的原生平台对应一个目录,目录中至少包含一个 <PackageName>-Config.cmake
文件。构建系统会子使用 CMake 的 find_package
机制定位或链接到所需的库文件。
如果插件中存在可跨平台的源文件或 CMake 配置, 可以将这些文件合并到顶层目录。详情请参考 示例工程。
描述文件 cc_plugin.json
格式
{
"name": string; // 必填:插件名称
"version": string; // 必填:插件版本
"engine-version":string; // 必填:对应引擎版本的区间
"author": string; // 必填:插件作者
"description": string; // 必填:插件描述
"platforms":string[]; // 可选:支持的平台列表,不填默认支持所有原生平台。包括 windows, android, mac, ios
"disabled":true; // 可选:禁用插件
"disable-by-platforms":string[]; //可选:指定平台禁用插件
"modules": [{ // 必填:插件包含的库,
"target":string; // 必填:对应 `find_package` 名称,需和 `CC_PLUGIN_ENTRY` 的首参数保持一致
"depends": string|string[]; // 可选:依赖其他 module 名称
"platforms":string[]; // 可选:重新限定支持的原生平台
}]
}
engine-version
可以指定版区间和排除指定版本,代码示例如下:
"engine-version": ">=3.3 <= 3.6.0 !3.5.2|| 4.x"
文件示例
{
"name":"hello-cocos-demo",
"version":"0.1.0",
"author":"demo group",
"engine-version":">=3.6.0",
"description": "demo project",
"modules":[
{
"target":"hello_cocos_glue"
}
],
"platforms":["windows", "android", "mac", "iOS"]
}
安装原生插件
开发者可以从 Store 下载并启用包含原生插件的编辑器扩展,同时完成插件的安装到 extensions
目录。也可以从论坛获取插件压缩包,手动解压到 native/
目录或其子目录。
如果想关闭插件,或者仅在特地平台关闭,可以修改 cc_plugin.json 中的 disabled
和 disable-by-platforms
字段。
注意:原生插件要求 CMake 为 3.12+,Android 需要 指定 CMake 版本 为 3.18.1. 其他平台使用编辑器内建的 CMake,可不必指定版本号。
创建原生插件
Cocos 原生工程使用 CMake 管理,原生插件会通过 find_package 的搜索路径/目录来进行管理,因此只要目录符合 CMake find_package 的搜索规则,插件就能正确加载。所以,原生插件的开发过程,就是提供 CMake 配置和相关的资源,以及编写 cc_plugin.json 的过程。相关示例请参考 原生插件构建工程示例。