You can find me on YouTube, X, and Bluesky. If you appreciate my work, consider buying me a coffee!

Debug Godot Engine with VSCode tasks.json and launch.json

Use these configurations if you want to debug your Godot Engine projects with VSCode.

The .vscode folder

Create a folder named '.vscode' at the root of your project (e.g. the Godot Engine master branch root folder). It's a folder that contains VSCode specific files that can define a number of different settings. In this case we'll use 'tasks.json' and 'launch.json' to simplify our Godot Engine debugging workflow. Create these two files inside the '.vscode' folder.

tasks.json

With this file you can automate a variety of tasks. Basically this is stuff most of the time you can execute from the command line.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build_debug",
            "type": "shell",
            "command": "scons",
            "args": ["target=editor", "dev_mode=yes", "dev_build=yes"],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "build_release",
            "type": "shell",
            "command": "scons",
            "group": {
                "kind": "build"
            }
        },
        {
            "label": "regenerate_xml",
            "type": "shell",
            "command": "./bin/your.godot.executable",
            "args": ["--doctool"],
            "group": {
                "kind": "build"
            }
        }
    ]
}

Check this Godot doc page to learn more about scons arguments you may want to use.

If you want to execute one of these tasks:

Press CTRL+SHIFT+P in VSCode;
Write 'Run Build Task';
Select the task you want to launch.

launch.json

A launch.json file is used to configure the debugger in Visual Studio Code.

A couple of premises

When you launch Godot, it opens the 'Project Manager' window. Chances are you wanted to debug the editor, but if you now open the project you wanted to test (at least on Windows), a new process will be created, and the debugger will lose its connection (since it was attached to the 'Project Manager' instance). What you want to do is define a test project of yours directly as an argument of the launch configuration, so that Godot opens that project directly, avoiding the issue presented earlier.

Code

We'll define three configurations:

Build and Launch Godot (Debug)
Launch Godot (Debug)
Attach to Godot (Debug)

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Build and Launch Godot (Debug)",
            "type": "cppvsdbg", // Change this to your debugger of choise.
            "request": "launch",
            "program": "${workspaceFolder}/bin/your.godot.executable",
            // Open the project specified in the path directly.
            "args": ["--editor", "--path", "path/to/your/test/project"],
            "preLaunchTask": "build_debug",
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "externalConsole": false
        },
        {
            "name": "Launch Godot (Debug)",
            "type": "cppvsdbg", // Change this to your debugger of choise.
            "request": "launch",
            "program": "${workspaceFolder}/bin/your.godot.executable",
            // Open the project specified in the path directly.
            "args": ["--editor", "--path", "path/to/your/test/project"],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "externalConsole": false
        },
        {
            "name": "Attach to Godot (Debug)",
            "type": "cppvsdbg", // Change this to your debugger of choise.
            "request": "attach",
            "processId": "${command:pickProcess}"
        }
    ]
}

Once we have defined these configurations, we can use them through the 'Run and Debug' tab in VSCode (CTRL+SHIFT+D).

Usage suggestions

Attach to Godot (Debug) is probably the most flexible way to attach the debugger to the Godot instance, since you don't need to hard-code a project path in the 'launch.json' configuration. Launch the debugging command from the 'Run and Debug' tab and start writing 'Godot' to find the running instance of Godot Engine you want to attach to.

GreenCrowDev/debug_godot_engine_vscode_tasks_launch.md