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.
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.
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
1.4 Use customized engine in Cocos Creator
Use the Custom Engine tab of the
2 Customize Cocos2d-x Engine
2.1 Get the Cocos2d-x Engine
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
> ==> 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-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)>
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 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
qqplay-adapter 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.
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
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
qqplay-adapter 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.
Creator >= 1.7, please refer to:
Creator <= 1.6, please refer to: