如何对 Cocos Creator 引擎做底层修改

面向有前端背景的开发者，讲解 Cocos Creator 3.x 的引擎定制化开发路径。

---

概述

当你需要制作商业游戏时，对引擎进行底层修改（引擎定制）是迈向高阶开发的必经之路。它能让你：

• 摆脱引擎默认功能的限制
• 引入特殊的第三方 SDK
• 优化引擎的核心性能

Cocos Creator 3.x 的底层修改分为两个维度：

定制维度	适用场景
项目级原生代码定制	接入 SDK、修改平台特性
引擎源码级深度定制	魔改渲染管线、物理系统、核心 Bug

---

一、项目级原生代码定制

适用场景：接入原生平台 SDK（广告、支付、统计）、修改平台配置。

目录结构

构建原生项目（Android/iOS/Windows）时，native 目录结构如下：

native/
├── engine/
│   ├── common/           # 所有平台共用的 C++ 代码
│   ├── android/          # Android 平台代码（Java + C++）
│   ├── ios/              # iOS 平台代码（Objective-C + C++）
│   └── ...               # 其他平台
└── build/                # 构建产物（勿直接修改，会被覆盖）

操作指南

添加 C++ / Objective-C 文件

需要在对应的 CMakeLists.txt 中注册源文件：

# 公共 C++ 文件
list(APPEND CC_COMMON_SOURCES
    your_file.cpp
)

# 平台专属文件
list(APPEND CC_PROJ_SOURCES
    platform_specific.cpp
)

添加 Java 文件

Java 采用包路径管理，直接在 native/engine/android 对应目录下增删文件即可，无需额外配置。

引入第三方库

1. 将 C++/OC 编写的 SDK 放入 native 目录
2. 修改对应平台的 CMakeLists.txt 进行链接

注意

Objective-C 库只能放在平台专属目录（如 ios），不能放在 common 中。

---

二、引擎源码级深度定制

适用场景：修改核心渲染管线、物理系统、修复引擎底层 Bug。

Cocos Creator 3.x 引擎由两部分组成：

组成	技术栈	修改后生效方式
cocos-engine	TypeScript	菜单 开发者 -> 编译引擎
engine-native	C++	重新执行「构建并编译」

定制工作流

┌─────────────────────────────────────────────┐
│  1. 获取引擎源码                              │
│     Cocos Dashboard → 引擎版本 → 在资源管理器中显示 │
│     → 拷贝 engine 到项目根目录 custom-engine    │
├─────────────────────────────────────────────┤
│  2. 关联自定义引擎                            │
│     偏好设置 → 引擎管理器 → 取消「使用内置引擎」   │
│     → 指向 custom-engine 目录                  │
├─────────────────────────────────────────────┤
│  3. 修改与编译                                │
│     TS 代码 → 开发者菜单编译                   │
│     C++ 代码 → 重新构建项目                     │
└─────────────────────────────────────────────┘

详细步骤

1. 获取源码 在 Cocos Dashboard 中找到当前项目使用的引擎版本，点击「在资源管理器中显示」，将 engine 目录拷贝到项目根目录下的 custom-engine 文件夹。

2. 关联自定义引擎 打开 偏好设置 (Preferences) → 引擎管理器 (Engine Manager)，取消勾选「使用内置引擎」，路径指向 custom-engine。

3. 修改与编译

   修改内容	生效方式
   TS 部分	菜单 开发者 -> 编译引擎
   C++ 部分	重新「构建并编译」项目

---

三、进阶调试：像开发前端一样调试引擎源码

调试 TypeScript 引擎源码

1. 在项目根目录新建 scripting 文件夹
2. 将自定义引擎目录软链接或拷贝进去
3. 菜单 开发者 -> Visual Studio Code 工作流 -> 添加 Chrome debug 配置
4. VSCode 中按 F5 启动调试
5. 单步调试（F11）进入引擎 API 时，VSCode 会跳转到本地引擎源码

调试 C++ 引擎源码

目标平台	调试工具
Android	Android Studio
iOS	Xcode

打开 build 目录下的原生工程，即可像调试普通原生 App 一样断点调试 engine-native。

---

特别提示：Cocos 4 全面开源

Cocos 4 已宣布全面开源，采用 MIT 许可证。你可以：

• 自由修改引擎的任何组件
• 基于它创建全新的引擎
• 进行二次打包和深度二次开发

建议

底层修改是一把双刃剑。它能带来极致的性能和定制化能力，但也会增加后续引擎版本升级的合并成本。

建议先从项目级原生代码定制入手，只有在确实无法满足需求时，再谨慎地对引擎核心源码进行「微创手术」。