Mcfunction-Debugger is a debugger for Minecraft's mcfunction files that does not require any Minecraft mods.
Features related to the underlying debugger implementation used by this Visual Studio Code extension can be found here.
Execute mcfunction Files
You can execute any mcfunction file of a datapack in your Minecraft world directly from Visual Studio Code.
The function will be executed with a
Suspend execution at any point by setting breakpoints.
Syntax highlighting in this screenshot was provided by Data-pack Helper Plus.
Step through your Program
Starting from a breakpoint you can execute your program line by line.
The entire stacktrace (including file, line and column number) can be viewed and navigated.
The scores of the
View Position and Rotation in Minecraft
While suspended, the current position and rotation are displayed with particles in Minecraft.
You can teleport yourself to this position and rotation by executing the following command:
Missing and Invalid Functions
Both Minecraft and Mcfunction-Debugger completely skip the execution of functions that are missing or contain an invalid command. This means that breakpoints in an invalid function will be ignored. To highlight this fact Mcfunction-Debugger writes to the debug console whenever a function call is skipped.
To connect to Minecraft Mcfunction-Debugger uses Minect to create a connection building in Minecraft the first time you debug a program. To uninstall Minect in Minecraft execute:
There are three main options you can change in the debug configuration (in
This is the mcfunction file you want to debug.
The initial debug configuration uses
This is the directory containing the Minecraft world the debugger should connect to.
For single player this is typically a directory within the saves directory:
For servers it is specified in
This is the path to Minecraft's log file.
For single player this is typically at these locations:
For servers it is at
The debugger requires a running instance of Minecraft Java Edition (both singleplayer and server mode are supported).
When using singleplayer, make sure the game is not paused.
This happens when moving the Minecraft window to the the background or pressing
This extension contributes the following settings:
Here are some of the most important features that are planned, but not yet implemented:
Visual Studio Code Extension
After Cancelling a Launch the Setup Notification is not Shown Again
The first time you start debugging a function, the debugger shows a notification with instructions to execute
Unfortunately a program can always behave slightly differently when being debugged. Here are some problems you might encounter with Mcfunction-Debugger.
Calling Functions in Other Datapacks is not Supported Yet
Currently Mcfunction-Debugger only considers the datapack that contains the debugged function (see #9). This means that calls to functions in other datapacks will be skipped as if the function was missing.
To work around this limitation you can merge all datapacks into one big datapack before debugging.
Operating on Dead Entities
In a Minecraft function you can kill an entity and then continue using it. For example, consider the following datapack:
After the function
Hitting the Maximum Command Chain Length
By default Minecraft only executes up to 65536 commands per tick. Since the debugger needs to run many commands in addition to the commands of your datapack, you might hit this limit when debugging a very large datapack. When this happens the debug session will be left in an undefined state. If there are no schedules, the development tool will wait indefinitely and you will have to manually terminate the debug session. If there are upcoming schedules they may crash the debug session or exhibit unexpected behaviour.
To avoid hitting the command limit you can add more breakpoints, step through the function line by line, or increase the command limit:
If a chunk that contains an entity required for debugging is unloaded, while a function is suspended on a breakpoint, the debug session will crash, when you try to resume the execution.
This can for example happen if you go far away or if the function operates in a chunk that is only loaded temporarily (for instance by a