Engine Customization Workflow
- Cocos2d-x-lite engine：https://github.com/cocos-creator/cocos2d-x-lite
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.
In addition, depending on the different version of Creator, you have to make sure the engine repo is at the corresponding branch. For example:
- master/develop branch: Branch used for current latest version
- vX.Y-release branch: The branch that corresponds to the x.y version
- vX.Y branch: Same as the vX.Y-release branch, mainly used for example projects
- next branch: Branch for large refactoring, if are document and API repo, then used for version 2.0
It is generally recommended to use the same version of the vX.Y-release branch as the Creator used, and if it is not found, use the master branch.
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:
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.
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
Note: If a
gulp build --max-old-space-size=8192
1.4 Use customized engine in Cocos Creator
2 Customize Cocos2d-x-lite Engine
2.1 Get the Cocos2d-x-lite Engine
Once cloned or downloaded, enter the Cocos2d-x-lite engine folder and run:
# Enter the Cocos2d-x-lite 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-lite engine repo and rename it to
v3-deps-54.zip(you do not need to unzip the zip file.) and rerun
> ==> 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-lite engine repository under the
tools/cocos2d-consoledirectory and rename it to
creator-console-2.zip(without unzipping the zip file), and rerun
> ==> 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)>
If you get an error like the one below, it's usually because the Cocos2d-x-lite engine folder was downloaded, not cloned from GitHub. You can execute
git initand then rerun
fatal: not a git repository (or any of the parent directories): .git
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
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
- Suitable for different platforms with BOM and DOM running environment
- Some engine-level adaptation
The current adaptation layer consists of two parts:
jsb-adapter: Suitable for native platforms
mini-game-adapters: Suitable for Mini Games
3.1 Get adapter
adapters directories can be found within the
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
3.2 Customize jsb-adapter
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
builtin section also includes a number of related JSB interfaces, such as openGL, audioEngine, in addition to adapting the BOM and DOM runtime environment.
We made some adjustments and optimizations in different versions of Creator. Please reference to the different guide below according to the current Creator version you are using.
3.2.1 Customization before Creator v2.0.5
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:
# Enter the jsb-adapter/builtin engine path from the command line cd jsb-adapter/builtin # Install the gulp build tool npm install -g gulp # Install dependent modules 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:
# in jsb-adapter/builtin folder gulp
When the command completes, a new
jsb-builtin.js file is generated in the
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.2.2 Customization on Creator v2.0.5 and v2.0.6
First of all, you should install the dependencies. Please execute them on the command line:
# Enter the jsb-adapter engine path from the command line cd jsb-adapter/ # Install the gulp build tool npm install -g gulp # Install dependent modules npm install
Next, you can customize the code in jsb-adapter . After the modification is complete, continue to execute it on the command line:
# in jsb-adapter folder gulp
gulp command will pack all the code in bultin into file
jsb-builtin.js, and translate code in engine from ES6 to ES5. All the target files are put into the dist folder.
After customizing the
jsb-adapter, the editor will copy files in dist folder to the jsb-adapter folder in the project when you build the native platform in the Build panel.
3.2.3 Customization after Creator v2.0.7 (v2.0.7 included)
After Creator v2.0.7, Jsb-adapter abandoned the cumbersome manual compilation operation. You can directly modify the source code in directories builtin and engine. When the modification is complete, open the editor and the editor will automatically compile this part of the source code at startup.
3.3 Customize Mini Games adapter
The adaptation layer code for the Mini Games is located in the
adapters in the
- 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.
If you want to learn more about mini game adapter, please refer to Mini Game Documentation for details.
Creator >= 1.7, please refer to:
Creator <= 1.6, please refer to: