Cocos command-line tool
What is the
cocos command-line tool?
Cocos2d-x comes with a command-line tool called cocos. It is a cross-platform tool that allows you to create new Cocos2d-x applications as well as run them and deploy them. cocos works for all cocos2d-x supported platforms, which include: ios, android, mac, linux, win32, wp8_1, wp10 and web. You don't need to use an IDE unless you want to. It has many options, so let's go through them grouped by function.
it is a good idea to run
# Option 1 > ./setup.py # Option 2 > python setup.py
On macOS, it is also a good idea to add a few lines to your ~/.bash_profile to ensure your character encoding is set to UTF-8. Example:
export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8
After adding these lines, it is necessary to run source ~/.bash_profile or restart your shell.
Testing your path for
It is necessary for cocos to be in your path or to specify the complete path to it when using it. An easy test:
> cocos -v
If you see output like 1.2 you are all set. If you see anything else you need to either add the location to your PATH.
On macOS run source ~/.bash_profile after updating your PATH or
specify the full path to
Creating a new project
To create a new project you use the cocos new command. The command is formatted as:
cocos new <game name> -p <package identifier> -l <language> -d <location>
cocos new MyGame -p com.MyCompany.MyGame -l cpp -d ~/MyCompany cocos new MyGame -p com.MyCompany.MyGame -l lua -d ~/MyCompany cocos new MyGame -p com.MyCompany.MyGame -l js -d ~/MyCompany
In the above examples, a new project is created using the Cocos2d-x source code. If you want to create a new project using the pre-built libraries you need to pass an additional flag of -t binary. Example:
cocos new MyGame -p com.MyCompany.MyGame -l cpp -d ~/MyCompany -t binary
If you haven't generated the pre-built libraries, please see the section below on doing so.
You can run cocos new --help to see even more options as well as platform specific options.
Compiling a project
As you make changes to your code it is necessary to compile it. We all know this has to happen, let's go through it. The command is formatted as:
cocos compile -s <path to your project> -p <platform> -m <mode> -o <output directory>
cocos compile -s ~/MyCompany/MyGame -p ios -m release -o ~/MyCompany/MyGame/bin cocos compile -s ~/MyCompany/MyGame -p android -m release -o ~/MyCompany/MyGame/bin cocos compile -s c:\MyCompany\MyGame -p win32 -m release -o c:\MyCompany\MyGame\bin
There is a lot going on here so let's go over the finer points. -p is the platform you are compiling for. -m is mode, debug or release with the default being debug if this parameter is not specified.
Also, it is important to know that the -s and -o parameters are optional as well as long as you are already in your project's working directory. Taking the example above if you are already in ~/MyCompany/MyGame then the cocos compile command can be shortened:
cocos compile . -p ios -m release
You can also specify an optional parameter -q for quiet. This lessens the output that is outputted to the console. Taking an example from above:
cocos compile -q -s ~/MyCompany/MyGame -p ios -m release -o ~/MyCompany/MyGame/bin
As cocos supports a lot of platforms there are also platform specific options which allow you to fine tune targeting specific SDK versions, signing code, lua options as well as web specific options. You can run cocos compile --help to see all available options broken down by platform.
Android compiling could require specifying an API level.
If you are compiling for Android, the cocos command is flexible and allows developers to compile using specific Android API versions. You may have Android-22 installed on your system (or any other version). You will want to add --ap android-api-version to the end of the cocos command to specify. Example:
cocos compile -p android --ap android-22
You can always check
project.properties to see what api-version is being targetted. For more info, please read out Release Notes.
Running a project
Once you have created a project you can run it right from the command-line. cocos takes care of launching the environment you specify. The command is formatted as:
cocos run -s <path to your project> -p <platform>
cocos run -s ~/MyCompany/MyGame -p ios cocos run -s ~/MyCompany/MyGame -p android cocos run -s c:\MyCompany\MyGame -p win32
You can also specify to run in debug or release mode using the optional -m parameter. Excluding this parameter defaults to debug.
cocos run -s ~/MyCompany/MyGame -p ios -m release
As with the cocos compile command above, it is important to know that the -s and -o parameters are optional as well as long as you are already in your project's working directory. Taking the example above if you are already in ~/MyCompany/MyGame then the cocos run command can be shortened:
cocos run . -p ios -m release
When running for the web there are additional parameters that allow you to specify what web browser you want to run in. You can also specify ip address and port. This, again is done via command-line parameters. Examples, specifying Google Chrome:
cocos run -s ~/MyCompany/MyGame -p web -b /Applications/Google\ Chrome.app cocos run -s ~/MyCompany/MyGame -p web -b C:\Program Files\Google\Chrome\Application\chrome.exe cocos run -s ~/MyCompany/MyGame -p web -b /usr/local/bin/chrome
You can run cocos run --help to see all available options broken down by platform.
Deploy a project
Once you are ready to ship your game cocos provides an easy mechanism for deploying it. Just like with the commands above you specify what want to do. The command is formatted as:
cocos deploy -s <path to your project> -p <platform> -m <mode>
cocos deploy -s ~/MyCompany/MyGame -p ios -m release cocos deploy -s ~/MyCompany/MyGame -p android -m release cocos deploy -s c:\MyCompany\MyGame -p win32 -m release
You can also specify an optional parameter -q for quiet. This reduces the output that is logged to the console. Taking an example from above:
cocos deploy -q -s ~/MyCompany/MyGame -p ios -m release
You can run cocos deploy --help to see all available options broken down by platform.
Installing additional plugins
Using the Cocos Package Manager you can easily add additional functionality to your games, SDKBOX. There are a variety of commands to assist with this. Examples:
# list available packages cocos package list # show all packages imported into your project cocos package info # update installed packages to the latest versions cocos package update
You can run cocos package --help to see all available options broken down by platform.
Installing SDKBOX plugins
SDKBOX plugins can be installed using the Cocos Package Manager. Example:
# install a package, in this example, Facebook cocos package import facebook
Unique command-line options
cocos has a number of unique options you can use to help build your games. To see all of these options, please run cocos --help. Let's us talk about these optios.
|no-apk||compile without building an apk.|
|luacompile||Encrypt the lua scripts in your game. This is invoked once
|gen-simulator||The simulator powers the preview function in Cocos Creator.|
|gen-templates||is used for generating the binary templates you can use to get started on a project that uses the pre-built libraries. Binary templates are required by Cocos Bundle package and also Cocos Creator.|