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.

Setting up cocos

it is a good idea to run /setup.py to properly setup your PATH. Doing so ensures that you can run Cocos2d-x and its related tools. Example:

# Option 1
> ./setup.py

# Option 2
> python setup.py

On OS X, 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 cocos

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 OS X run source ~/.bash_profile after updating your PATH or specify the full path to \tools\cocos2d-console\bin.

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>

Examples:

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>

Examples:

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\MyGamein

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.

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>

Examples:

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>

Examples:

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.

Creating pre-built libraries to use instead of source code.

Cocos2d-x is available to use as both source code and pre-built libraries. Using the source allows developers to see under the hood what the engine is doing. Using the source increases compilation time. To decrease compilation time, by a great deal, you can create pre-built libraries from the source. These are static libraries you can add to your project to use Cocos2d-x. Compiling the pre-built libraries with the cocos tool is easy. Examples:

# remove the 'prebuilt' folder
# without the -m flag, this builds for release mode
# generates libraries for every platform
cocos gen-libs -c

# remove the 'prebuilt' folder
# without the -m flag, this builds for release mode
# generates libraries for just ios
cocos gen-libs -c -p ios

# remove the 'prebuilt' folder
# without the -m flag, this builds for release mode
# generates libraries for just ios and android
cocos gen-libs -c -p ios -p android

# remove the 'prebuilt' folder
# with the -m flag, this builds for debug
# generates libraries for just ios and android
cocos gen-libs -c -p ios -m debug

You can run cocos gen-libs --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, including VR and 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 VR

VR is easily added to your project! Every VR project needs vrsdkbase, it takes care of setting up your project to use VR. It is easy to import:

$ cocos package import -v -b vrsdkbase --anysdk

If you are using a supported VR SDK make sure to import it. Examples:

# add the GearVR package
$ cocos package import -v -b gearvr --anysdk

# add the Deepoon VR package
$ cocos package import -v -b deepoon --anysdk

# add the Google VR package
$ cocos package import -v -b gvr --anysdk

# add the Oculus VR package
$ cocos package import -v -b oculus --anysdk

For more information, please see our chapter on VR.

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.