Native Platform Secondary Development Guide

Native Platform Secondary Development Guide

If you need to integrate third-party SDK libraries or modify, add or remove C++, Objective-C, or Java code files, the following information can help you do it faster.

Native Project Directories

When you click the Build button, three native platform-related folders are generated.

There is 3 directories related to native project.

Common Directory

Location: native/engine/common

This directory is used to store common content such as engine library configurations and some third-party libraries that are used by all platforms.

The code in this directory is mostly written in C/C++.

Native Platforms Directories

Location: native/engine/<current_build_platform>

This directory is used to store platform-specific content. For example:

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

win64 is used for Windows, and win32 is no longer supported. Only win64 applications are supported for release by Cocos Creator.

Project Directory

Location: build/<current_build_platform>

This directory contains the final generated native projects used for compilation, debugging, and publishing. For example:

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

During each build, the engine combines the common directory, the native platform directory, and the resources and scripts from the Cocos Creator project to generate the project directory.

The code and related configurations in the project directory reference the files in the corresponding native platform directory and the common directory. If you make changes to the corresponding parts in the IDE, the files in the referenced directories will be modified accordingly.

Note: The native/engine/ios/info.plist and native/engine/mac/info.plist files copied due to the mechanism of CMake. If you want to modify info.plist, please be cautious.

The project directory contains the following contents:

assets: data A symbolic link to the data directory, used for compatibility across platforms.
data: The contents generated from the resources and scripts in the Cocos Creator project.
proj: The native platform project for the current build, used for compilation, debugging, and publishing in the corresponding platform’s IDE (e.g., Xcode, Android Studio).
cocos.compile.config.json: The build options configuration used for this build.

Native Project Customization

Sometimes, due to project requirements, we may need to modify, add, or remove native platform-related source code files, integrate third-party SDKs, or modify project configurations. These tasks are referred to as project customization development.

Below, we will categorize different scenarios and explain how to perform the operations.

Modifying Engine Code

Please refer to the Engine Customization Workflow。

Modifying Project Code

If you need to modify project-related code, simply locate the corresponding files and make the necessary changes. Once modified, you can compile the project without any additional configuration.

Adding/Removing Code Files

Adding or removing code files involves modifying the build configuration, which may differ for different programming languages and platforms. Let’s categorize them as follows.

Adding/Removing C++ Files

If you need to add or remove project-related C++ files, you need to modify the corresponding CMakeLists.txt file.

If the C++ files to be added or removed are in the native/engine/common/ directory, you need to modify native/engine/common/CMakeLists.txt.

list(APPEND CC_COMMON_SOURCES
    ${CMAKE_CURRENT_LIST_DIR}/Classes/Game.h
    ${CMAKE_CURRENT_LIST_DIR}/Classes/Game.cpp
)

As shown in the code above, find the corresponding location and add or remove your own source code.

If the code files to be added or removed are platform-specific C++ files, you need to modify native/engine/<platform_name>/CMakeLists.txt. Refer to the code below:

include(${CC_PROJECT_DIR}/../common/CMakeLists.txt)
//Add your own C++ files here
list(APPEND CC_PROJ_SOURCES
    ${CMAKE_CURRENT_LIST_DIR}/MyTest2.hpp
    ${CMAKE_CURRENT_LIST_DIR}/MyTest2.cpp
)

Adding/Removing Objective-C Files

The management of Objective-C files in the iOS/macOS native projects generated by Cocos Creator is exactly the same as for C++. Please refer to the previous content.

Adding/Removing Java Files

Java is based on a path-based package management mechanism, so adding or removing Java files does not require any special handling.

Integrating C++/OC Libraries

If the library you want to integrate is written in C++ or Objective-C, place the SDK in the native/engine/common/ or native/engine/<platform_name>/ directory depending on the situation, and modify the corresponding CMakeLists.txt in the respective directory.

Libraries written by Objective-C should only be placed in the platform-specific directory and should not be placed in native/engine/common/, as it may cause compilation errors on other native platforms.

Most C++ SDKs provide their own CMakeLists.txt, so you can integrate them by including the files.

For CMake configuration, you can refer to the existing CMakeLists.txt in the project for modification. For more details on using CMake, you can refer to Introduce to CMake Usage.

Integrating Jar Libraries

If the library you want to integrate is written by Java and specific to the Android platform, simply place it in the corresponding native/engine/android/ directory and configure native/android/build.gradle.

Interacting with Native

For newly created native methods or newly integrated native SDKs that you want to export for use in script code, you can use the following approaches.

Using JsbBridge

If you need to call simple and infrequent functions, you can use the JsbBridge mechanism for communication.

Using JSB Auto Binding

For frequent C++ function calls or batch C++ API exports to the script layer, it is recommended to use the JSB Automatic Binding) mechanism for script-native interaction.

Using Reflection

Communication based on the reflection mechanism in Java and Objective-C can also be used for convenient script-native interaction. However, due to stricter review rules on iOS, there is a risk of review failure when using reflection mechanisms on iOS.

Source Code Version Control

If your team uses source code version control software for collaborative work, the native/ directory should be included in the version control.

All project customization work should be done in the / directory as much as possible, so that the build/ directory can be deleted at any time and does not need to be included in the source code version control.

For special project requirements that cannot be achieved within the native/ directory, modifications to the content under the build/ directory are required. In this case, the corresponding folders should be included in version control based on the requirements.