Mcfunction-Debugger

Mcfunction-Debugger is a debugger for Minecraft's mcfunction files that does not require any Minecraft mods.

Contents

1. Quick Start
2. Features
3. Uninstall
4. Debug Configuration
5. Requirements
6. Extension Settings
7. Planned Features
8. Known Issues

Quick Start

1. Install Mcfunction-Debugger from Visual Studio Code Marketplace.
2. Go to "Run and Debug":

• Windows / Linux: Ctrl + Shift + D
• macOS: Cmd + Shift + D

3. Click on "create a launch.json file".
4. Adjust the value of minecraftWorldDir to point to your Minecraft world.
5. Open that world in Minecraft.
6. Open the mcfunction file you want to debug (it must be in a datapack with a pack.mcmeta file).
7. Set a breakpoint at a line with a Minecraft command by clicking left to the line number.
8. Press the key F5 on your keyboard.
9. Execute the command /reload in Minecraft and follow the instructions there.

Features

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 schedule command, so it runs without an @s entity at the world's origin position. To change this, you can create a new function that executes your function as the player or at a different position and debug this new function instead. For example:

execute as @p at @s run function my_namespace:my_function

Breakpoints

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.

View Stacktrace

The entire stacktrace (including file, line and column number) can be viewed and navigated.

View Scores

The scores of the @s entity are displayed when the execution is suspended.

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:

execute as @e[type=area_effect_cloud,tag=mcfd_context,tag=mcfd_current] if score @s mcfd_depth = current mcfd_depth at @s run teleport @p @s

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.

Example:

example:main:

function example:missing
function example:invalid
schedule function example:missing 1t
schedule function example:invalid 1t

example:invalid:

this is an invalid command

Uninstall

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:

function minect:uninstall

Debug Configuration

There are three main options you can change in the debug configuration (in launch.json):

program

This is the mcfunction file you want to debug. The initial debug configuration uses ${file} which refers to the currently opened file when pressing F5. Alternatively you can use ${command:askForFunctionPath} to instruct the debugger to ask you which function to debug. If you always want to debug the same function you can also specify a fixed file path. Use ${workspaceFolder}/... for files in your workspace.

minecraftWorldDir

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:

• Windows: ${userHome}/AppData/Roaming/.minecraft/saves/
• GNU/Linux: ${userHome}/.minecraft/saves/
• Mac: ${userHome}/Library/Application Support/minecraft/saves/

For servers it is specified in server.properties.

minecraftLogFile

This is the path to Minecraft's log file.

For single player this is typically at these locations:

• Windows: ${userHome}/AppData/Roaming/.minecraft/logs/latest.log
• GNU/Linux: ${userHome}/.minecraft/logs/latest.log
• Mac: ${userHome}/Library/Application Support/minecraft/logs/latest.log

For servers it is at logs/latest.log in the server directory.

Requirements

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 Esc to enter the game menu. A paused game will cause the debugger to wait until the game is resumed. To prevent the game from pausing when moving the window to the background, you can open Minecraft's chat by pressing the key T.

Extension Settings

This extension contributes the following settings:

• mcfunctionDebugger.adapter.log.file: Specifies the log file for the debug adapter.
• mcfunctionDebugger.adapter.log.level: Specifies the log level for the debug adapter.

Planned Features

Here are some of the most important features that are planned, but not yet implemented:

• Hot code replacement #70
• Support function tags #12
• Support storing the result/success of a function command with execute store #11
• Freezing the gametime while suspended #18
• Freezing the age of all entities while suspended (this is currently only done for area_effect_clouds) #24
• Setting randomTickSpeed to 0 while suspended #14

Known Issues

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 /reload in Minecraft. If you cancel the connection procedure, this notification is not shown again until you complete a launch sucessfully. Nevertheless you need to execute /reload and follow the instructions in Minecraft to set up a connection initially.

Debugger Core

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:

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. Currently this cannot be handled by the debugger. If you try to debug the function example:sacrifice_pig it will crash:

[Info] Started debugging example:sacrifice_pig
[Pig] I am still alive
[Error] Selected entity was killed!

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:

/gamerule maxCommandChainLength 2147483647

Chunkloading

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 teleport command or by going through a portal).