Use VSCode to debug cocos2d-x JSB programs

Hi guys, i have finished writing a debugger for VSCode to debug cocos2d-x JSB programs. It is availabe since Cocos2d-x v3.11.

The debugger supports:

  • set breakpoints
  • step over, step in, step out
  • show context variables
  • show stack frames
  • evaluate expression in the Debug Console

Please refer to VSCode debugging documentation for more detail information and usage.

Environment setup

  • Install VSCode, v.0.10.8+ is required.
  • Download, and upzip it to:
    • Windows %USERPROFILE%\.vscode\extensions
    • Mac $HOME/.vscode/extensions
    • Linux $HOME/.vscode/extensions
  • cocos2d-x(latest codes from cocos2d-x repo is commended)
    • If your cocos2d-x version is v3.10 or lower, you should:
      • replace cocos/scripting/js-bindings/script/debugger with corresponding contents from cocos2d-x github
      • replace cocos/scripting/js-bindings/script/jsb_debugger.js with corresponding file from cocos2d-x github
      • change cocos/scripting/js-bindings/manual/ScriptingCore.cpp as did in this commit did
      • change templates/cocos2dx_files.json as this commit did
    • If you use cocos2d-x git repo, then you should synchronize to latest codes.
    • You need to create a new project to test, or you should do changes for cocos/scripting/js-bindings/script/debugger, cocos/scripting/js-bindings/script/jsb_debugger.js, cocos/scripting/js-bindings/manual/ScriptingCore.cpp as mentioned above in your project_root/frameworks/cocos2d-x.

You should re-launch VSCode after upzip

I only tried on Mac now, other platforms can work in theory because VSCode is cross-platform.


Currently VSCode can only attach to cocos2d-x JSB program to debug. Which means it can not pause on entry. We will improve it in future.


First you should run cocos2d-x JSB program, then use VSCode to attach it to the debugger.

Run cocos2dx JSB programs

If you don’t know how to run cocos2d-x JSB program, you can refer to this document.

VSCode attach to cocos2d-x JSB program

  • lauch VSCode and open the folder of your project(for example cocos2d-x/tests/js-tests)

  • click on the Debugging icon in the View Bar on the side of VSCode


  • set up launch configuration

    • If you want to debug on iOS devices, you should:
      • connect iOS device to Mac via USB cable
      • run cocos2d-x JSB program on iOS devices
      • use ip address the iOS device to fill the address section in launch.json
    • If you want to debug on Android devices, you should:
      • connect Android devices with PC via USB cable
      • run cocos2d-x JSB program on Android devices
      • use adb to forward tcp
      adb forward tcp:5086 tcp:5086
  • start debugging


For more detailed information please refer to VSCode debugging documentation.

I appreciate if you can try it and give some feedback.



This is great !
is there any plan to connect this debugger to the new Cocos Creator ?
so we can combine the work flow of cocos creator and JSB development ?

@Meir_yanovich Yep, it is in plan after the debugger is stable.


Looks very promising, debugging jsb on native was a painful experience until now. I’m definitely going to try this out.

@araker Thanks and you are appreciated if you can give some feedback.

Update: update Environment setup section to add requirements for cocos2d-x.

Good job, @zhangxm! I’m very excited with these new tools, because you are focusing on productivity.

@patriciog Thanks. You are appreciated to have a try and give some feedback.

Hi sir @zhangxm
can you make a detailed steps on how do we install this?

@eydamson Could you tell me which part were you confused?

@zhangxm about applying the patches…
what do you mean by that sir?
should i leave as it is my cocos2d installed which is 3.10 already?

@eydamson Got it. I will complete it. Sorry about it.

1 Like

@eydamson I have updated the content, could you please take a look? Thanks.

1 Like

thanks sir… very readable il try it out…

@eydamson Thanks.

I tried but no success, vscode running but no log in console and can’t set break point, and after change code in cocos2d-x framework, now firefox can’t remote debug :(, Can you create a video instruction about this, i think it very useful and easier to follow, thank :smiley:

I’m trying this in an existing v3.10 project, but I’m getting build errors.

So I’ve changed cocos/scripting/js-bindings/script/debugger, cocos/scripting/js-bindings/script/jsb_debugger.js, cocos/scripting/js-bindings/manual/ScriptingCore.cpp.

Then I get these build errors. I’ve tried to replace ScriptingCore.h from your repo, only resulting in other errors. What else can I try?