Engine Customization Workflow
- Cocos2d-x-lite engine：https://github.com/cocos-creator/cocos2d-x-lite
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 Customized 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 binary library and simulator
- If you want to use a
binarytemplate to build and compile native project (it's much faster since Cocos2d-x code are already compiled), you'll need to run these commands:
# use cocos console to generate prebuilt binary libs gulp gen-libs
- To generate simulator to preview your changes:
# use cocos console to generate simulator gulp sign-simulator gulp gen-simulator gulp update-simulator-config
gulp sign-simulator is a new command since 1.7.0. only need to run on Mac. It can help you to sign the simulator project in
tools/simulator/frameworks/runtime-src/proj.ios_mac/simulator.xcodeproj, so you can debug the simulator on Mac. This command will open the simulator project directly in XCode, and then ask you to manually set the signature and close XCode. If you don't want to sign it, just close XCode directly. You need to rerun this command once the project is changed. See Build simulator for details.
Creator >= 1.7, please refer to:
Creator <= 1.6, please refer to: