Engine Customization Workflow

The game engine in Cocos Creator has three parts: JavaScript engine with ECS (entity-component system), Cocos2d-x (custom version of Cocos2d-x) and adapters. They are all open sourced on GitHub:

There are three adapters:

If you want to customize engine, we recommend that you follow the fork workflow thru GitHub. Please read GitHub help: Fork A Repo to learn the details.

1 Customize JavaScript Engine

If your concern is only Web based games, or what you want to change in the engine is not native API, related (for example UI and animation components), you just need to follow the workflow here:

1.1 Get JavaScript Engine Repository

If you only need to make some adjustments based on the current version, Then you can modify it based on the builtin engine of Cocos Creator. Click Open App in the upper right corner of the Creator Editor, and then copy the builtin engine directory to another local paths.

If you want to get the latest version that is currently under development, you need to first fork or clone the original version of the JavaScript engine from github. You have to make sure the repo is at the corresponding branch. For example to customize engine for Cocos Creator v1.6.2 you'd need to checkout v1.6 branch; for Cocos Creator v1.7.1 you'd need to checkout v1.7 branch. Once cloning is completed, go to the repo's folder in command-line shell.

1.2 Install NPM Dependencies

npm and gulp are core components for engine building. These need to be installed. Example:

# Enter the engine path in the command line
cd /Users/yufang/engine
# Install the gulp build tool
npm install -g gulp
# Install dependent modules
npm install

1.3 Change and Build

Now you can do whatever you want to do with the engine, once you finished:

# build engine
gulp build

This command will generate a bin folder in the engine directory and compile the engine source into the bin directory.

1.4 Use customized engine in Cocos Creator

Use the Custom Engine tab of the Project -> Project Settings panel to set the path to your customized JavaScript engine.

2 Customize Cocos2d-x Engine

If you need to customize the engine functionality associated with the native platform. Besides updating JavaScript engine (so that your change can work with component system) you may also need to synchronize your change to the customized Cocos2d-x engine of Cocos Creator.

2.1 Get the Cocos2d-x Engine

If you only need to make some adjustments based on the current version, Then you can modify it based on the builtin Cocos2d-x engine of Cocos Creator. Same as get JavaScript engine: click Open App in the upper right corner of the Creator Editor, and then copy the builtin cocos2d-x directory to another local paths.

If you want to get the latest version that is currently under development, you need to download it from the github repo specified above. please make sure you get the cocos2d-x-lite engine repo from the link on top of this article. Same as JavaScript engine, you need to make sure cocos2d-x-lite repo is on correct branch. For Cocos Creator v1.6.2 please checkout v1.6 branch.

2.2 Initialize

Once cloned, enter the Cocos2d-x-lite engine folder and run:

# Enter the Cocos2d-x engine path from the command line
cd /Users/yufang/cocos2d-x-lite
# Install NPM dependencies
npm install
# Initialize repo
gulp init
  • If you get an error like the one below, please download the zip file manually. The reason for the error is that the version of a library that your python ships with is too low, but it is not very easy to upgrade. The simpler method is to download the zip file and manually put it under the Cocos2d-x engine repo and rename it to v3-deps-54.zip (you do not need to unzip the zip file.) and rerun gulp init again.
> ==> Ready to download 'v3-deps-54.zip' from
> 'https://github.com/cocos-creator/cocos2d-x-lite-external/archive/v3-deps-54.zip'
> Traceback (most recent call last):
> ...
> URLError: <urlopen error [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590)>
  • If you get an error like the one below, please manually download the zip file. Manually put it in the Cocos2d-x engine repository under the tools/cocos2d-console directory and rename it to creator-console-2.zip (without unzipping the zip file), and rerun gulp init again.
> ==> Ready to download 'creator-console-2.zip' from
> 'https://github.com/cocos2d/console-binary/archive/creator-console-2.zip'
> Traceback (most recent call last):
> ...
> URLError: <urlopen error [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590)>

2.3 Configure Custom Engine in Cocos Creator

Use the Custom Engine tab of the Project -> Project Settings panel to set the path to your customized cocos2d-x-lite engine.

2.4 Build from Source

Next, you can start working on updating code for Cocos2d-x-lite. If you want to use source code in your built project you can just choose default or link template in Build panel and compile from the source, no extra command line work needed.

2.5 Build simulator

To generate simulator to preview your changes:

# use cocos console to generate simulator
gulp gen-simulator
gulp update-simulator-config

Attention: If you need to debug your customized simulator on macOS, you must sign the Xcode project first. See Build simulator for details.

3 Customize adapter

Cocos Creator in order to achieve cross-platform, in the JavaScript layer needs to do a number of different platform adaptation work. These efforts include:

  • Suitable for different platforms with BOM and DOM running environment
  • Some engine-level adaptation

The current adaptation layer consists of three parts:

  • jsb-adapter: Suitable for native platforms
  • weapp-adapter: Suitable for Wechat Mini Games
  • qqplay-adapter: Suitable for QQ Play

3.1 Get adapter

If you only need to make some adjustments based on the current version, Then you can modify it based on the builtin adapter engine of Cocos Creator. Same as get JavaScript engine: click Open App in the upper right corner of the Creator Editor, and the jsb-adapter, weapp-adapter, and qqplay-adapter directories can be found within the resources/builtin directory.

If you want to get the latest version of the official developing, you need to download it from the github repo specified above, Then replace it with the resources/builtin directory of the program installation path. Same as JavaScript engine, you need to make sure adapter repo is on correct branch.

3.2 Customize jsb-adapter

In the jsb-adapter directory, the following two directory structures are included:

  • builtin:Adapt the runtime of the native platform
  • engine:Adapt some APIs of the engine level

The builtin section also includes a number of related JSB interfaces, such as openGL, audioEngine, in addition to adapting the BOM and DOM runtime environment.

3.2.1 Customize and compile builtin

Customization of the engine section only requires modification of the code.
Customization of the builtin section requires installing the dependencies first, please execute them on the command line:

cd jsb-adapter/builtin
npm install

Next, you can customize the code in the builtin section. After the modification is complete, continue to execute it on the command line:

# jsb-adapter/builtin 目录下
gulp

When the command completes, a new jsb-builtin.js file is generated in the jsb-adapter/builtin/dist directory.

After customizing the jsb-adapter, the editor will copy the jsb-builtin.js file and the engine directory together to the jsb-adapter folder in the project when you build the native platform in the Build panel.

3.3 Customize weapp-adapter and qqplay-adapter

The adaptation layer code for the Wechat Mini Games and QQ Play is located in the weapp-adapter and qqplay-adapter in the resources/builtin directory.

  • The customization of this part of the code does not require any compilation operations.
  • Engine-level adaptation work, please complete in the appropriate engine directory.

4 JSB Workflow (JavaScript Binding)

If you need to modify the JavaScript interface provided by the Cocos2d-x engine, you should complete the JSB binding.

Creator >= 1.7, please refer to:

Creator <= 1.6, please refer to:

results matching ""

    No results matching ""