This repository has moved to https://codeberg.org/vanilla-technologies/mcfunction-debugger-vscode to avoid GitHubs two factor authentication (2FA) requirement. We believe that Microsofts decision to force all code contributors to use 2FA is very problematic for the following reasons:
- 2FA significantly increases the risk of irreversible account loss. This is very different to 2FA for something like online banking where in the worst case you can contact your bank and verify your identity to regain access. With GitHub however, if you loose your phone and backup codes (both of which is possible), you will never gain access to your account again.
- The decision to require 2FA for every code contributor seems very needless. Yes software supply chain attacks are a thing, but not every code contributor on GitHub is responsible for widely used libraries. It's quite the opposite: most code contributors are not responsible for widely used libraries and their code is reviewed and merged by those that are. Also, the details of the 2FA requirement seem arbitrary. Why for example is email not accepted as a second factor or why can WebAuth only be a second second factor and not a primary second factor? Just to make it really hard to not use a phone for 2FA? It feels like a "trust us, we know what's good for you" attitude from Microsoft and it is scary to think what arbitrary decision could come next.
- Depending on how you use passwords the account security is not necessary improved that much by using 2FA, especially if it is forced onto people that don't want to use it. So why is there no opt out?
- Many other developers publicly stated that they are leaving GitHub because of this, so staying on GitHub would prevent any code contributions from these people. This makes finding good contributors even harder than before. By moving to https://codeberg.org everyone can continue to contribute to this project.
- Unfortunately Microsoft does not allow mail as a second factor and some companies do not allow you to bring your private phone to work or install proprietary software (such authenticators) for security reasons. This means 2FA can actually completely prevent you from logging into the website in some circumstances. This is really sad, because it can make it harder for professional developers at companies that use free and open source software to return something to the community.
- Not everyone owns/can afford a smartphone or dedicated authenticator hardware and Microsoft makes it very inconvenient to use 2FA without that by requiring you to install authenticator software on every development machine. This discourages code contributions from poor people.
2FA is a good technology, but it should be up to repository owners to decide whether it is appropriate for the project at hand. Requiring 2FA for all code contributions, even for code that is reviewed and merged by other people, is completely unnecessary and discourages contributions.
McFunction-Debugger is a debugger for Minecraft's mcfunction files that does not require any Minecraft mods.
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_functionPause the execution at any point by setting breakpoints.
Syntax highlighting in this screenshot was provided by Data-pack Helper Plus.
Starting from a breakpoint you can execute your program line by line.
The scores of the @s entity are displayed when the execution is paused.
When paused, 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:
teleport @s @e[type=area_effect_cloud,tag=mcfd_breakpoint,limit=1]- Install McFunction-Debugger from Visual Studio Code Marketplace.
- Go to "Run and Debug":
- Windows / Linux:
Ctrl + Shift + D - macOS:
Cmd + Shift + D
- Click on "create a launch.json file".
- Adjust the value of
minecraftWorldDirto point to your Minecraft world. - Open that world in Minecraft.
- Open the mcfunction file you want to debug (it must be in a datapack with a
pack.mcmetafile). - Set a breakpoint at a line with a Minecraft command by clicking left to the line number.
- Press the key
F5on your keyboard. - Execute the command
/reloadin Minecraft and follow the instructions there.
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:uninstallThere are three main options you can change in the debug configuration (in launch.json):
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.
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.
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.
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.
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.
These features are planned, but not yet implemented:
- Hot code replacement #70
- Support function tags #12
- Allow users to supply a
commands.jsonfile for newer or older versions of Minecraft #42 - Freezing the
gametimewhile suspended #18 - Freezing the age of all entities while suspended (this is currently only done for area_effect_clouds) #24
- Support debugging multiple datapacks at once #9
- Support debugging
load.jsonandtick.json#8 - Support storing the
result/successof afunctioncommand withexecute store#11 - Setting
randomTickSpeedto 0 while suspended #14
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.
Unfortunately a program can always behave slightly differently when being debugged. Here are some problems you might encounter during debugging 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).