\
mcfunction-debugger is a debugger for Minecraft's *.mcfunction files that does not require any Minecraft mods.
This project has reached a minimum-viable product level of quality. It offers a command line interface but does not integrate with an editor. We already started implementing the Debug Adapter Protocol to provide an extension for Visual Studio Code which will also include additional features like stepping through the code and showing current scoreboard values, but this will take some time.
You can debug any datapack with the following five steps:
# breakpoint lines in your *.mcfunction files/function debug:<your_namespace>/<your_function>/function debug:uninstallA more detailed description can be found here.
Precompiled binaries are available under releases.
We recommend saving the mcfunction-debugger binary to Minecraft's saves directory for ease of use.
On Windows this is located at %APPDATA%\.minecraft\saves.
mcfunction-debugger is written in Rust so to build it from source you need to install Rust.
You can then install it from crates.io by running:
cargo install mcfunction-debugger
Or from GitHub by running:
cargo install --git https://github.com/vanilla-technologies/mcfunction-debugger.git
To uninstall run:
cargo uninstall mcfunction-debugger
These features are planned, but not yet implemented:
commands.json file for newer or older versions of Minecraft #42gametime while suspended #18load.json and tick.json #8result/success of a function command with execute store #11randomTickSpeed to 0 while suspended #14Unfortunately a program can always behave slightly differently when being debugged. Here are some problems you might encounter with mcfunction-debugger.
In a Minecraft function you can kill an entity and then continue using it. For example, consider the following datapack:
example:sacrifice_pig:
summon pig ~ ~ ~ {Tags: [sacrifice]}
execute as @e[type=pig,tag=sacrifice] run function example:perform_necromancy
example:perform_necromancy:
say I am still alive
function example:kill_me
say I am dead inside
example:kill_me:
kill @s
After the function example:kill_me is executed the pig is dead, yet it speaks to us from the other side.
This cannot be handled by the debugger.
If you try to debug the function example:sacrifice_pig it will crash:
[Pig] I am still alive
Selected entity was killed!
Start a new debugging session with '/function debug:<your_namespace>/<your_function>'
Executed 145 commands from function 'debug:example/sacrifice_pig'
By default Minecraft only executes up to 65536 commands per tick.
Since the debug datapack needs to run many commands in addition to the commands of your datapack, you might hit this limit when debugging a very large datapack.
You can tell by looking at how many commands where executed from the function.
When you see something like:
Executed 65536 commands from function 'debug:resume'
You should stop the debug session with /function debug:stop and add more breakpoints to avoid running so many commands at once or increase the command limit with:
/gamerule maxCommandChainLength 2147483647
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, if 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 teleport command or by going through a portal).