Debugging Setup

This section explains how to set up a VS Code project for debugging your script using the Minecraft Bedrock Debugger extension and System Template Esbuild.

Warning

This guide assumes you have already read the Basic Workflow section and are using the recommended setup.

Enabling Source Maps

System Tempalte Esbuild makes it easy to compile files for Minecraft and create the source map at the same time. All you need to do is enable the sourcemap option and specify the working_dir path in the filter settings.

Example configuration:

{
    "filter": "system_template_esbuild",
    "settings": {
        "sourcemap": true,
        "working_dir": "debug/script"
    }
}

How it works?:

The compiled JavaScript file is placed in BP/scripts/main.js (default output location).
The source map is stored in debug/script/.
The working_dir path is relative to the root of your Regolith project.
The sourcemap option is required for the Minecraft Bedrock Debugger to map TypeScript code correctly. Without it, debugging will be much harder since only compiled JavaScript will be available.

System Template Esbuild always compiles main.ts from its working directory, producing a main.js file in the same directory. After compilation, main.js is copied to the path specified in the outfile setting.

With the configuration above, running Regolith will automatically create the debug/script directory. This is where we can connect the Minecraft Bedrock Debugger extension to debug our script.

Setting Up a VS Code Debugging Workspace

To streamline debugging, create a new VS Code workspace that includes the debug directory. If your workspace is located in the root of the Regolith project, it might look like this:

{
    "folders": [
        {
            "path": "debug"
        },
        {
            "path": "local_modules"
        }
    ],
    "settings": {
        "workbench.colorTheme": "Tomorrow Night Blue"
    }
}

The key feature here is the addition of the debug folder to the workspace. Everything else is optional. The local_modules folder is a place where you can put your local npm modules. The change of the color theme lets you visually distinguish between the workspace you’re working in and the one you’re using for debugging.

Configuring the Debugger

After setting up the workspace, you have to also add the configuration for the debugger. Add launch.json, tasks.json and prepare_debug.bat to the .vscode folder inside debug directory.

Your project structure should look like this:

📁 debug
    📁 .vscode
        📄 launch.json
        📄 tasks.json
        📄 prepare_debug.bat
    📁 script
📁 local_modules

And the contents of the files is shown below.

launch.json:

{
    "version": "0.3.0",
    "configurations": [
        {
            "type": "minecraft-js",
            "request": "attach",
            "name": "Debug with Minecraft",
            "mode": "listen",
            "preLaunchTask": "Build For Debugging",
            "targetModuleUuid": "653126c0-89a0-4fc4-9e08-c84aada2c604",
            "localRoot": "${workspaceFolder}/script/",
            "sourceMapRoot": "${workspaceFolder}/script/",
            "port": 19144
        }
    ]
}

tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build For Debugging",
            "command": "call .vscode/prepare_debug.bat",
            "type": "shell",
            "options": {
                "shell": {
                    "executable": "cmd.exe",
                    "args": ["/d", "/c"]
                }
            },
            "problemMatcher": ["$tsc"],
            "presentation": {
                "reveal": "always"
            },
            "group": "test"
        }
    ]
}

prepare_debug.bat:

powershell CheckNetIsolation.exe LoopbackExempt -a -p=S-1-15-2-1958404141-86561845-1752920682-3514627264-368642714-62675701-733520436
powershell CheckNetIsolation.exe LoopbackExempt -a -p=S-1-15-2-424268864-5579737-879501358-346833251-474568803-887069379-4040235476

Note

This setup is based on a tutorial from the official Minecraft documentation. If anything is unclear, refer to the original guide.

Running the Debugger

Once everything is set up:

Run Regolith to compile the files.
Open your debugging workspace in VS Code.
Press F5 to start the debugger.
Open the Minecraft world with your pack enabled.
Run the following command in Minecraft to connect the debugger:
```
/script debugger connect
```

Note

You may need to enable Developer Mode in Windows to allow the debugger to function correctly.