引擎定制工作流程

Cocos Creator 拥有两套引擎内核,C++ 内核 和 TypeScript 内核。C++ 内核用于原生平台,TypeScript 内核用于 Web 和小游戏平台。 在引擎内核之上,是用 TypeScript 编写的引擎框架层,用以统一两套内核的差异,让开发更便捷。

engine-core

获取引擎源码

download repo js

1. 进入 Cocos 引擎仓库

Cocos 是一个开源引擎,不同版本的引擎源码可以从 Cocos 引擎官方开源仓库中获取,地址如下:

打开仓库主页,可以看到上图中左侧子图所示的内容,根据需求自行决定使用哪一个版本即可。

2. 选择分支(Branch)

如果是要采用最新的分支,选择上图中间子图所示的 develop 分支即可。

注意:此分支由于是开发中的最新分支,并不确保稳定性。

选择 Tag

如果要采用对应 Cocos Creator 版本的稳定分支,则按上图右侧子图所示,切换到 Tags 标签,并选择对应的版本号。 比如,你所用的 Cocos Creator 为 3.7.3 版本,那么你就选择 3.7.3 即可。

注意:不同的 Cocos Creator 版本,需要对应不同的引擎分支,请确保二者版本匹配。

3. Clone 或者 下载

download-repo

如上图所示,选择了对应的分支或者 Tag 后,就会切换到相应仓库(1)。

点击右边的 代码(2)按钮,会弹出代码下载面板。

你可以 复制仓库链接(3),然后使用 git 工具 clone 到本地,也可以选择 Download ZIP(4) 下载源码的 zip 包到本地并解压即可。

记得在页面右上角给 Cocos 引擎的开源仓库加个星(5),谢谢!

配置环境

1. 引擎源码放到指定目录

根据自身项目需求,从 Cocos 引擎的源码仓库获得引擎源码,放到适合的目录下。

  • 如果自定义引擎仅为某一个项目使用,则建议放入对应的项目目录。
  • 如果多个项目会共享一套自定义引擎,则根据项目管理方案,放到适合的公共目录。

2. 获取 external

Cocos 原生引擎的编译,需要依赖 cocos-engine/native/external 中的库。这些库有几百 MB 大小,所以源码包内默认是没有的,可以通过以下三种方式获取。

第一种方式:通过 git 命令行。

  1. cd cocos-engine/native
  2. git clone https://github.com/cocos/cocos-engine-external external
  3. cd external
  4. git checkout -b branch_name tag
  • branch_name:是新的分支名
  • tag:是第三方库对应的 tag 名字,可以从 cocos-engine/native/external-config.json 里的 checkout 字段获取该值。

示例: 假如我们要使用 3.7.3-1 版本,则可以写成 git checkout -b 3.7.3-1 3.7.3-1

第二种方式:使用引擎自带的脚本下载。

该脚本只会下载某个 tag 对应的第三方库。

  1. cd cocos-engine/native
  2. npm install
  3. gulp init

只要使用的 tag 有变化,就需要重新下载。每次需要下载几百兆的内容。

第三种方式:下载 ZIP 包

如果某些原因不能通过 NodeJS 和 git 命令下载 external 源码包,则可以直接在 cocos-engine-external 仓库页面,按照以下步骤下载。

download-external-zip

  1. 选择对应的分支,需要使用哪一个分支可以从 cocos-engine/native/external-config.json 中的 checkout 字段中查看。
  2. 点击右边的 源代码(Code) 按钮,弹出源码下载页面。
  3. 点击 下载ZIP(Download ZIP) 按钮,下载源码压缩包。
  4. 解压,重命名为 external,并放到 cocos-engine/native 目录下。

注意:external 与 cocos-engine 的版本号要一致,否则可能导致编译失败。

3. 安装编译依赖

编译依赖项需要使用 NodeJS,请确保电脑安装了 NodeJS v12.0 以上版本,如未安装,请前往 https://nodejs.org/ 下载安装。

安装完成后,在自定义引擎根目录,执行以下命令。

  1. # 安装 gulp 构建工具
  2. npm install -g gulp
  3. # 安装依赖的模块
  4. npm install
  5. # 编译一些数据,包括 debug infos 和 .d.ts
  6. gulp build

4. 修改引擎路径

通过 Cocos Creator/File -> 偏好设置引擎管理器 选项卡来设置需要使用的引擎源码路径。需要注意的是 修改引擎路径后需要重启编辑器

custom ts engine

指定 TypeScript 引擎

默认情况下,Use Built-in 会处于选中状态,表示使用的是 Cocos Creator 内置的引擎。 为了使用自定义引擎,我们只需要将选项卡切换到 Use Custom, 并将路径指定为引擎源码根目录即可。

指定原生(C++)引擎

如果需要定制和原生平台相关的引擎功能, 则还需要勾选 Native Module 下的 Use Custom。 会自动识别自定义引擎根目录下的 native 作为路径,不可更改。

配置存储路径

custom-engine-store-path

默认情况下,自定义引擎的修改会保存为全局配置,将影响所有使用当前 Cocos Creator 版本的项目。

将鼠标移动到 Cocos Engine 文字上,文字前方会出现一个设置按钮,点击按钮可以选择存储位置。

重启 Cocos Creator

自定义引擎路径修改完成后,需要重启 Cocos Creator 编辑器才能生效。 直接关闭 Cocos Creator 再次打开,或者点击界面上的 重启(Relaunch) 按钮。

注意:自定义引擎生效后,Cocos Creator 中的场景编辑器也会采用自定义引擎进行渲染。默认情况下采用的是 TypeScript 内核运行,如果要让编辑器也使用原生引擎进行渲染,需要在 偏号设置 -> 实验室 面板下,开启 启用原生引擎加载场景编辑器

use-native-engine-for-editor

修改 TypeScript 引擎

如果您只需要为 Web 和 小游戏平台的游戏定制引擎功能,或只需要修改 TypeScript 层的引擎相关代码(如 UI 系统,动画系统等),那么只需要在修改完成之后在 Cocos Creator 编辑器的菜单栏中点击 开发者 -> 编译引擎 进行编译即可。

build

该命令会在引擎目录下生成一个 bin 文件夹,并将引擎源码编译到这里。

修改原生(C++)引擎

如果需要定制和原生平台相关的引擎功能,除了修改 TypeScript 代码,可能还需要修改 C++ 代码。

为了使原生部分的代码能够正常被编译,需要确保 Native Module 中的 Use Custom 被选中。

在 Cocos Creator 中编译

引擎修改完成后,打开 构建发布 面板,点击构建,构建完成后,点击 编译

在 IDE 中编译

第一次配置完自定义引擎路径后,需要 在构建发布 面板点击 构建 按钮,才会同步相关配置到 IDE(如 Xcode, Android Studio, Visual Studio 等)中。

此时的 IDE 中引用的 Cocos Engine 路径将会是自定义引擎的路径。修改完原生相关代码后,直接使用 IDE 的编译即可。

重新编译原生引擎模拟器

  1. ```bash
  2. cd cocos-engine/native
  3. git clone https://github.com/cocos/cocos-engine-external external --branch tag
  4. ```
  5. `branch_name` 是新的分支名;`tag` 是第三方库对应的 `tag` 名字,可以从 `cocos-engine/native/external-config.json` 里的 `checkout` 字段获取该值。
  • 使用引擎自带的脚本下载。该脚本只会下载某个 tag 对应的第三方库。后续只要使用的 tag 有变化,就需要重新下载。每次需要下载几百兆的内容。

Cocos Creator 提供了基于原生引擎的模拟器预览功能:

custom-native-simulator

自定义 TypeScript 引擎

若使用了自定义 TypeScript 引擎,则这个原生模拟器在启动时,会去加载自定义引擎路径下的自定义引擎路径/native/simulator 的 TS 引擎模块。

首次启动时,需要点击编辑器顶部菜单栏中的 开发者 -> 编译原生模拟器引擎,否则会无法成功加载 TS 引擎模块。

自定义原生引擎

若勾选了自定义原生引擎,在运行模拟器时,Cocos Creator 会启动 自定义引擎路径/native/simulator/ 路径下的模拟器应用程序。

为了避免安装包过大,Cocos Creator 在发布时剔除了原生引擎模拟器相关工程,需要按以下步骤配置环境,重新编译生成,否则无法启动:

CMake 安装与配置

Cocos Creator 在构建、编译、发布应用时,使用的是自带的 CMake,并配置好了路径,不需要再做相关配置。

原生模拟器的编译不属于构建流程,因此需要自己配置 CMake 编译环境。

由于不同的系统平台和系统版本有差异,请参考 CMake 官方文档 安装 CMake 并配置系统环境变量。

编译

CMake 配置完成后在 自定义引擎路径/native 目录下依次执行以下命令:

  1. # 安装依赖的模块
  2. npm install
  3. # 生成原生模拟器相关文件
  4. gulp gen-simulator

编译完成后,会在 自定义引擎路径/native/simulator 路径下生成一个模拟器工程和模拟器可执行文件,便可运行原生模拟器了。

模拟器编译成功后,若后续只改动了 TypeScript 部分,则只需要点击编辑器顶部菜单栏中的 开发者 -> 编译原生模拟器引擎 即可。