Developers Manual > Cocos2d-x > Cocos2d-console



cocos2d-console is a command line tool for cocos2d-x & cocos2d-js. It contains several commands for developers to create, compile, run the -x or -js projects.
The cocos2d-console is implemented by Python. You can use it in Windows, Mac or Linux.


  • Python 2.7 is required (Now only support version 2.7).
  • Required by iOS & Mac:
    • XCode
  • Required by android:
  • Required by win32:
    • Visual Studio
  • Required by linux:
    • Please run the build/ in cocos2d-x or cocos2d-js to install the dependencies.

Setup Environment

Run the in the root directory of cocos2d-x or cocos2d-js.
If you are developing games for android, you should input the Android SDK, Android NDK & Apache Ant path when the setup is running.


Use the command line like this:cocos [command] [arguments]
Available commands:


There are depend relationship between commands. Two rules about dependencies:

  • The dependent commands will be invoked first.
  • If command A depend on command B. When you are using command A, the arguments you used will be passed to command B.

For example: Command run depends on command deploy, and deploy depends on compile.

  • The command order is compile->deploy->run.
  • You can use command run like this: cocos run -p android --ndk-mode release
    (-p is available argument of run, --ndk-mode is available argument of compile)

How to add command

  1. Edit bin/cocos2d.ini, and add the class name of your new plugin there. For example:

  2. Create a file called in the plugins folder.
    A new, empty plugin, would look like the code shown below:

    import cocos
    # Plugins should be a subclass of CCPlugin
    class CCPluginCustom(cocos.CCPlugin):   
        # in default category
        def plugin_category():
            return ""
        def plugin_name():
            return "custom"
        def brief_description():
            return "A custom plugin"                
        def run(self, argv, dependencies):
            print "plugin called!"
            print argv
  3. Check the added command. The output of cocos -h will show the available commands:

    available commands
    The result of run the command cocos custom -p android will look like this:

    run custom

Add custom steps during compiling

When cocos compile is running, some events will be dispatched to the custom python scripts. You can use this function by these steps:

  1. Define your custom script in .cocos-project.json in the root of your project. like this:

    "custom_step_script": "./",

    The key must be custom_step_script. The value can be absolute or relative path.

  2. Define a method named handle_event in your custom script like this:

    # event is the event name which pre-defined in cocos command.
    # target_platform is the target platform which you are compiling for.
    # args is more arguments of event.
    def handle_event(event, target_platform, args):
      print("event is %s" % event)
      print("target_platform is %s" % target_platform)
      print("args is %s" % args)

Then your custom script will be invoked when you are compiling your project by cocos compile.

Here are the pre-defined events:

event support platforms special arguments
pre-build all platforms ---
post-build all platforms ---
pre-ndk-build android ---
post-ndk-build android ---
pre-copy-assets android assets-dir : The path of assets directory
post-copy-assets android assets-dir : The path of assets directory
pre-ant-build android ---
post-ant-build android ---

All events arguments will contains:

  • project-path : The path of project root directory.
  • platform-project-path : The path of current compiling platform directory.
  • build-mode : The value of parameter -m. It's release or debug
  • output-dir : The path of output directory.
  • ndk-build-mode : The value of parameter --ndk-mode. It's release or debug or none. (This argument is only available when target platform is android).

Advanced Features


The code repository of cocos2d-console is on github: console repository
You can fork this github repository, add your contribution, then send a pull request to us.

available_cmds.jpg (54.9 kB), 2014-06-16 02:39

run_custom.jpg (19.7 kB), 2014-06-16 02:39

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.