原生平台二次开发指南

如果你需要为增加第三方 SDK 库，或者增删 C++，OC，JAVA 代码文件，以下内容可以帮你更好地理解。

原生项目目录

当点击 构建 按钮后，会生成三个原生平台相关的文件夹。

公共目录

公共目录位置：native/engine/common

此目录用于存放共公内容，如引擎库配置，以及一些所有平台都会用上的第三方库。

这个目录下的代码多数是由 C/C++ 编写。

原生平台目录

平台目录名字规则：native/engine/当前构建的平台名称

这个目录用于存放对应平台相关的信息，比如：

  • native/engine/android
  • native/engine/ios
  • native/engine/win64
  • native/engine/mac

win64 用于 windows, 目前已不再支持 win32, 仅支持 win64 应用程序发布。

项目目录

项目目录名字规则：build/当前构建的平台名称

这个目录，包含的是最终生成的原生工程，用于编译、调试和发布。如：

  • build/android
  • build/ios
  • build/windows
  • build/mac

每一次构建时，引擎会将公共目录和原生平台目录，以及 Cocos Creator 项目中的资源、脚本等结合在一起，生成项目目录。

项目目录中的代码和相关配置引用原生平台目录下的文件，在 IDE 中改动对应的部分，平台目录下的文件也会做对就修改。

例外：native/engine/ios/info.plist 与 native/engine/mac/info.plist 文件由于CMake的机制，使用的是复制方式。 如果要对 info.plist 进行修改，则需要注意。

项目目录包含下内容：

  • assets：data 目录的软链，用于兼容各平台
  • data：Cocos Creator 项目中的资源和脚本生成的内容
  • proj：存放当前构建的原生平台工程，可用于对应平台的 IDE（如 Xcode，Android Studio 等） 执行编译、调试和发布。
  • cocos.compile.config.json：本次构建的采用的构建选项配置

原生项目定制开发

因为项目需要，有时候我们需要修改、增删原生平台相关的源代码，或者引入第三方SDK，修改项目配置等。这些工作，我们称为项目定制开发。

下面我们就分类说明，不同情况下的需求，如何操作。

修改引擎代码

请参考 引擎定制工作流程。

修改项目代码

如果需要修改项目相关的代码，只需要找到对应文件进行修改即可，修改完即可编译，不需要额外配置。

增删项目代码文件

增删代码文件，将会涉及到编译配置，而不同的语言和平台有所差异，下面将分类说明。

增删 C++ 文件

如果需要增加和删除项目相关的 C++ 文件，需要做对应的 CMakeList.txt 修改。

如果增删的是 native/engine/common/ 目录下的代码，则需要修改 native/engine/common/CMakeLists.txt

  1. list(APPEND CC_COMMON_SOURCES
  2.     ${CMAKE_CURRENT_LIST_DIR}/Classes/Game.h
  3.     ${CMAKE_CURRENT_LIST_DIR}/Classes/Game.cpp
  4. )

如上面代码所示，找到对应位置，添加或者删除自己的源码即可。

如果增删的是平台相关的 C++ 代码文件，则需要修改 native/engine/平台名称/CMakeLists.txt。参考下面代码：

  1. include(${CC_PROJECT_DIR}/../common/CMakeLists.txt)
  3. //在这个位置添加自己的 C++ 文件
  4. list(APPEND CC_PROJ_SOURCES
  5.     ${CMAKE_CURRENT_LIST_DIR}/MyTest2.hpp
  6.     ${CMAKE_CURRENT_LIST_DIR}/MyTest2.cpp
  7. )

增删 OC 文件

Cocos Creator 生成的 iOS/macOS 原生工程中，Objective-C 文件的管理方式，与 C++ 完全一致，参考上面的内容即可。

增删 Java 文件

Java 语言本身是基于路径的包管理机制，增删 JAVA 文件不需要做特殊处理。

引入第三方 C++/OC 库

如果引入的库是由 C++/OC 编写而成，则根据情况将 SDK 放入 native/engine/common/ 或者 native/engine/平台名称/ 目录下，并修改对应目录下的 CMakeList.txt。

OC 库只能放在平台目录，不能放在 native/engine/common/，否则会导致在其他原生平台出现编译错误。

大部分 C++ SDK 也提供了自己的 CMakeList.txt，直接通过 include 的方式集成就行。

关于 CMake 的配置，可以参考项目中已有的 CMakeList.txt 进行修改。更多关于 CMake 的使用详情，可参考 CMake 使用简介。

引入 Jar 库

如果引入的库是 Android 平台特有的库，直接放到对应的 native/engine/android/ 目录，配置 native/android/build.gradle 即可。

脚本与原生通信

新写的原生方法，或者新引入的原生 SDK，如果想要导出到脚本层使用，可以采用以下几种方案。

使用 JsbBridge

如果需要调用一些简单，非高频的函数，可以使用 JsbBridge 机制进行调用。

JSB 自动绑定

对于需要高频调用，或者批量导出 API 到脚本层的接口，建议使用 JSB 自动绑定 机制实现脚本与原生交互。

基于语言反射机制

基于 Java 和 OC 语言反射机制的通信，也可以很方便实现脚本与原生的交互，但由于 iOS 的审核规则越来越严格，iOS 上使用反射机制有审核失败的风险。

源码版本管理

如果你的团队使用源码版本管理软件进行多人协同工作，native 目录需要全部加入到源码版本管理。

所有的项目定制化工作都应该尽量放到 native 目录，这样 build 目录就可以随时被删除，它不需要加入到源代码版本管理。

对于一些特殊的项目需求，无法在 native 目录下完成，则需要改动 build 目录下的内容，此时应该根据需求将对应的文件夹加入管理。