ProgrammingGuide > Lua > Use Cocos Code IDE to Debug a Lua Game

Use Cocos Code IDE to Debug a Lua Game

version: Cocos2d-x v3.x, Code IDE 1.x
update: Updated almost 3 years ago

Cocos Code IDE is tool that can debug a lua script,it has windows and mac version. You can debug Windows and Android lua games through the windows version and you can debug Mac, iOS and android lua games through the Mac version. Now we will demonstrate how to use Cocos Code IDE to debug a lua game based on the mac version. The process of the windows version is almost the same.


If you have been not installed the Cocos Code IDE,you can refer to Cocos Code IDE Installation.

Cocos Code IDE Configuration

Basic Settings

Click Cocos Code IDE/Preferences to open the configuration dialog,then select the Cocos/Lua to set the directory of cocos2d-x v3.x in the Lua Frameworks:

Additional Settings

You should set directory of some compliling tools about android if you need to replace the Android runtime which Cocos Code IDE provided. Click Cocos Code IDE/Preferences then pitch on Cocos to configurate the directory of related tools:

Debug a Lua Game

  1. Create a new Cocos Lua Project by the right click menu in the Lua Projects Explorer

  1. Select src/GameScene.lua and open it,then toggle breakpoint by right click menu or double click

3.Click debug button on toolbar

4.Trigger the breakpoint,select "Yes" to open Debug Perspective,and you will find many useful debug views like Call stacks, Variables and Breakpoints,etc.

5.Use Step over, Step into, Step out in the tool bar to debug

Code Hot Updating when Debugging

We could realize the hot updating of lua code when debugging by the Cocos Code IDE.

If you want to change the moving path of dog int the src/GameScene.lua, you can modify the "tick()" function to control the dog's position

local function tick()
    if spriteDog.isPaused then return end
        local x, y = spriteDog:getPosition()
        if x > self.origin.x + self.visibleSize.width then
            x = self.origin.x
            x = x + 1


Modify the implementation of function, for example, change the value 1 to 10 and save your change. Then you will find that you have improved the speed of SpriteDog without restarting the app!

How to Debug on the Other Target Platforms

The above example is executed on the Mac platform because of the default configuration of Cocos Code IDE.If you debug on the other target platforms you should modify Debug Configurations.

  1. Click Debug Configurations button on the toolbar to open Debug Configurations dialog

  1. Select the CocosLuaGame item,then to configure

Debug on the iOS Simulator

  1. Check iOS Simulator radio button

  2. Choose a runtime app

  3. Click the Debug button,IDE will auto-install chosen runtime app and start
    runtime to debug

Debug on an iOS Device

1.You need a runtime IPA, you can build a custom runtime IPA by Cocos Code IDE, then install runtime IPA
to iOS device.

  • Click Build Runtime on the toolbars

  • Click Yes button on the pop-up Cocos dialog

  • Click Generate button to Generate Create Native Source Wizard

  • Click Close button to finish Create Native Source Wizard

  • Click Build Runtime on the toolbars to open Runtime Builder Wizard dialog

  • Check Build iOS Device Runtime and click Generate button to generate

  • Click Close button when Finished dialog pop up

  1. Click Debug Configuration,then check Remote Debug radio button on the Debug Configuration dialog
  2. Select iOS platform
  3. Fill IP address of your device into the Target IP and Fill the IP address that your PC used on the Host IP(Make sure that the Target IP and Host IP can access each other)
  4. Click 'Debug' button to begin to debug

Debug on Android Device by ADB Mode

  1. Prebuild Runtimelua.apk by Build Runtime like first of Debug on the iOS Device
  2. Check Android ADB Mode radio button
  3. Choose a runtime apk
  4. Click the Debug button
  5. IDE will auto-install the chosen runtime apk and start to debug

Debug on Android Device by WLAN

  1. Install runtime apk to your device manually. It is placed in CocosLuaGame/runtime/android.
  2. Start runtime on device manually
  3. Click Debug Configuration,then check Remote Debug radio button on the Debug Configuration dialog
  4. Fill IP address of your device into the Target IP and Fill the IP address that your PC used on the Host IP(Make sure that the Target IP and Host IP can access each other)
  5. Click 'Debug' button to begin to debug

lua_configure_build_runtime_first.png (19.2 kB), 2014-12-03 07:19

lua_configure_iOS_simulator.png (110.8 kB), 2014-12-03 07:19

lua_configure_build_runtime.png (13.6 kB), 2014-12-03 07:19

lua_configure_runtime_builder_wizard.png (53.6 kB), 2014-12-03 07:19

lua_configure_creat_native_source_wizard.png (61.5 kB), 2014-12-03 07:19

lua_configure_runtime_select_iOS_device.png (460.7 kB), 2014-12-03 07:19

lua_configure_finish_create_native_source_wizard.png (40.3 kB), 2014-12-03 07:19

lua_confirm_perspective.png (288.5 kB), 2014-12-03 07:19

lua_create_project.png (43.8 kB), 2014-12-03 07:19

lua_debug_android_adb_mode.png (37.4 kB), 2014-12-03 07:19

cocos_preferences.png (87.4 kB), 2014-12-03 07:19

lua_debug_button.png (17.6 kB), 2014-12-03 07:19

lua_anroid_device_remote_setting.png (27.6 kB), 2014-12-03 07:19

lua_debug_configure_dialog.png (111.5 kB), 2014-12-03 07:19

lua_cocos_preferences.png (47.2 kB), 2014-12-03 07:19

lua_iOS_device_remote_setting.png (26.9 kB), 2014-12-03 07:19

lua_step_debug.png (5.2 kB), 2014-12-03 07:19

lua_config_button.png (18.8 kB), 2014-12-03 07:19

lua_configure_finish_iOS_device.png (34.3 kB), 2014-12-03 07:19

lua_toggle_breakpoint.png (1.1 MB), 2014-12-03 07:19

lua_configure_build_runtime_first.png (19.2 kB), 2014-12-03 07:19

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