Skip to content
This repository was archived by the owner on Sep 27, 2023. It is now read-only.

Commit e115beb

Browse files
AdrodocAdrodoc
committed
Fix #16 - Add documentation
1 parent 6ad133a commit e115beb

9 files changed

Lines changed: 425 additions & 37 deletions

File tree

‎README.md‎

Lines changed: 106 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,123 @@
1+
[![Minecraft: Java Edition 1.14.1 - 1.18.1](https://img.shields.io/badge/Minecraft%3A%20Java%20Edition-1.14.1%20--%201.18.1-informational)](https://www.minecraft.net/store/minecraft-java-edition)
2+
![Minecraft: Bedrock Edition unsupported](https://img.shields.io/badge/Minecraft%3A%20Bedrock%20Edition-unsupported-critical)\
3+
[![crates.io](https://img.shields.io/crates/v/mcfunction-debugger)](https://crates.io/crates/mcfunction-debugger)
4+
15
# mcfunction-debugger
26

37
mcfunction-debugger is a debugger for Minecraft's *.mcfunction files that does not require any Minecraft mods.
48

5-
## Debug your datapack in three steps
9+
## Status
10+
11+
This project has reached a minimum-viable product level of quality.
12+
It offers a command line interface but does not integrate with an editor.
13+
We already started implementing the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) to provide an extension for [Visual Studio Code](https://code.visualstudio.com/) which will also include additional features like stepping through the code and showing current scoreboard values, but this will take some time.
14+
15+
## Usage
16+
17+
You can debug any datapack with the following five steps:
618

719
1. Add `# breakpoint` lines in your *.mcfunction files
8-
2. Generate a debug datapack and load it in Minecraft
9-
3. Start debugging any of your functions by executing the command `/function debug:<your_namespace>/<your_function>`
20+
2. Generate a debug datapack
21+
3. Load the debug datapack in Minecraft
22+
4. Start debugging any of your functions with: `/function debug:<your_namespace>/<your_function>`
23+
5. When finished, uninstall the debug datapack with: `/function debug:uninstall`
24+
25+
A more detailed description can be found [here](docs/usage.md).
26+
27+
## Installation
28+
29+
### Using precompiled binaries
30+
31+
Precompiled binaries are available under [releases](https://github.com/vanilla-technologies/mcfunction-debugger/releases).
32+
We recommend saving the `mcfunction-debugger` binary to Minecraft's `saves` directory for ease of use.
33+
On Windows this is located at `%APPDATA%\.minecraft\saves`.
34+
35+
### Installing from source
36+
37+
mcfunction-debugger is written in Rust so to build it from source you need to [install Rust](https://www.rust-lang.org/tools/install).
38+
39+
You can then install it from [crates.io](https://crates.io/crates/mcfunction-debugger) by running:
40+
```
41+
cargo install mcfunction-debugger
42+
```
43+
44+
Or from GitHub by running:
45+
```
46+
cargo install --git https://github.com/vanilla-technologies/mcfunction-debugger.git
47+
```
48+
49+
To uninstall run:
50+
```
51+
cargo uninstall mcfunction-debugger
52+
```
53+
54+
## Planned features
55+
56+
These features are planned, but not yet implemented:
57+
58+
* Support function tags [#12](https://github.com/vanilla-technologies/mcfunction-debugger/issues/12)
59+
* Allow users to supply a `commands.json` file for newer or older versions of Minecraft [#42](https://github.com/vanilla-technologies/mcfunction-debugger/issues/42)
60+
* Freezing the `gametime` while suspended [#18](https://github.com/vanilla-technologies/mcfunction-debugger/issues/18)
61+
* Freezing the age of all entities while suspended (this is currently only done for area_effect_clouds) [#24](https://github.com/vanilla-technologies/mcfunction-debugger/issues/24)
62+
* Support debugging multiple datapacks at once [#9](https://github.com/vanilla-technologies/mcfunction-debugger/issues/9)
63+
* Support debugging `load.json` and `tick.json` [#8](https://github.com/vanilla-technologies/mcfunction-debugger/issues/8)
64+
* Support storing the `result`/`success` of a `function` command with `execute store` [#11](https://github.com/vanilla-technologies/mcfunction-debugger/issues/11)
65+
* Setting `randomTickSpeed` to 0 while suspended [#14](https://github.com/vanilla-technologies/mcfunction-debugger/issues/14)
66+
67+
## Caveats
68+
69+
Unfortunately a program can always behave slightly differently when being debugged.
70+
Here are some problems you might encounter with mcfunction-debugger.
1071

11-
## Generating a debug datapack
72+
### Operating on Dead Entities
1273

13-
Currently it is necessary to [install Rust](https://www.rust-lang.org/tools/install) and clone this reporsitory in order to generate a debug datapack.
14-
Executables for Windows, Linux and Mac will be provided with the first release.
74+
In a Minecraft function you can kill an entity and then continue using it.
75+
For example, consider the following datapack:
1576

16-
Build an executable for Windows with following command:
77+
`example:sacrifice_pig`:
78+
```
79+
summon pig ~ ~ ~ {Tags: [sacrifice]}
80+
execute as @e[type=pig,tag=sacrifice] run function example:perform_necromancy
81+
```
1782

18-
`cargo build --release`
83+
`example:perform_necromancy`:
84+
```
85+
say I am still alive
86+
function example:kill_me
87+
say I am dead inside
88+
```
1989

20-
and run it with
90+
`example:kill_me`:
91+
```
92+
kill @s
93+
```
2194

22-
`mcfunction-debugger [FLAGS] [OPTIONS] --input <DATAPACK> --output <DATAPACK>`
95+
After the function `example:kill_me` is executed the pig is dead, yet it speaks to us from the other side.
96+
This cannot be handled by the debugger.
97+
If you try to debug the function `example:sacrifice_pig` it will crash:
98+
```
99+
[Pig] I am still alive
100+
Selected entity was killed!
101+
Start a new debugging session with '/function debug:<your_namespace>/<your_function>'
102+
Executed 145 commands from function 'debug:example/sacrifice_pig'
103+
```
23104

24-
### Flags
105+
### Hitting the Maximum Command Chain Length
25106

26-
* `shadow`: When this is set to true the generated datapack will additionally contain functions with the same name as the functions in the input datapack.
27-
These functions will simply forward to the appropriate function in the `debug` namespace. When using this make sure to disable the input datapack to avoid name clashes.\
28-
\
29-
This can be helpful when executing a function from a command block, because you don't have to change the function call to debug the function. Note however that calling a debug function inside an execute prevents the debugger to suspend the execute. For example if the command `execute as @e run function my_namespace:my_function` hits a breakpoint in my_function if there is more than one entity my_function will be called again, resulting in an error like: "Cannot start debugging my_namespace:my_function, because a function is already suspended at a breakpoint!".
107+
By default Minecraft only executes up to 65536 commands per tick.
108+
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.
109+
You can tell by looking at how many commands where executed from the function.
110+
When you see something like:
111+
```
112+
Executed 65536 commands from function 'debug:resume'
113+
```
114+
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:
115+
```
116+
/gamerule maxCommandChainLength 2147483647
117+
```
30118

119+
### Chunkloading
31120

32-
### Options
121+
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.
33122

34-
* `input`: The datapack to generate a debug datapack for. This has to be a directory containing a `pack.mcmeta` file.
35-
* `log-level`: The log level can also be configured via the environment variable `LOG_LEVEL`.
36-
* `namespace`: The internal namespace of the generated datapack.\
37-
Default value: `mcfd`.\
38-
The namespace is used for all internal functions in the generated datapack and as a prefix for all scoreboard objectives and tags. By specifying a different namespace with max. 7 characters you can avoid name clashes. The generated functions in the `debug` namespace such as `debug:install` and `debug:resume` are unaffected by this option.
39-
* `output`: The directory that should become the generated debug datapack.
40-
On Windows this is typically a directory in the datapacks directory of your world, for example: \
41-
`%APPDATA%\.minecraft\\saves\\Your-World\\datapacks\\debug-my-datapack`
123+
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).

‎docs/command-line-interface.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
2+
# Command line interface
3+
4+
## Usage
5+
6+
`mcfunction-debugger [FLAGS] [OPTIONS] --input <DATAPACK> --output <DATAPACK>`
7+
8+
## Flags
9+
10+
### --help
11+
12+
Prints help information.
13+
14+
### --shadow
15+
16+
When this is set to true the generated datapack will additionally contain functions with the same name as the functions in the input datapack.
17+
These functions will simply forward to the appropriate function in the `debug` namespace. When using this make sure to disable the input datapack to avoid name clashes.
18+
19+
This can be helpful when executing a function from a command block, because you don't have to change the function call to debug the function.
20+
Note however that calling a debug function inside an execute command prevents the debugger from suspending the execute command.
21+
For example, if the command `execute as @e run function my_namespace:my_function` hits a breakpoint in `my_function` and there is more than one entity, `my_function` will be called again, resulting in an error like: "Cannot start debugging my_namespace:my_function, because a function is already suspended at a breakpoint!".
22+
23+
### --version
24+
25+
Prints version information.
26+
27+
## Options
28+
29+
### --input
30+
31+
The datapack to generate a debug datapack for. This has to be a directory containing a `pack.mcmeta` file, for example:
32+
```
33+
%APPDATA%\.minecraft\saves\Your-World\datapacks\my-datapack
34+
```
35+
36+
### --log-level
37+
38+
The log level can also be configured via the environment variable `LOG_LEVEL`.
39+
40+
### --namespace
41+
42+
The internal namespace of the generated datapack.
43+
44+
Default value: `mcfd`.
45+
46+
The namespace is used for all internal functions in the generated datapack and as a prefix for all scoreboard objectives and tags.
47+
By specifying a different namespace with max. 7 characters you can avoid name clashes.
48+
The generated functions in the `debug` namespace such as `debug:resume` and `debug:uninstall` are unaffected by this option.
49+
50+
### --output
51+
52+
The directory that should become the generated debug datapack.
53+
On Windows this is typically a directory in the datapacks directory of your world, for example:
54+
```
55+
%APPDATA%\.minecraft\saves\Your-World\datapacks\debug-my-datapack
56+
```

‎docs/how-to-open-a-command-line.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# How to Open a Command Line
2+
3+
Opening a command line is different for different operating systems.
4+
5+
## Windows
6+
7+
On Windows the easiest way to open a command line in a directory is:
8+
9+
1. Open the directoy in Windows Explorer.
10+
2. Make sure you didn't select a file or directory.
11+
3. Hold the `Shift` key and right click.
12+
4. From the context menu select: `Open PowerShell here`.
13+
On Windows 7 and below you need to select `Open Command Window here`.
14+
15+
## Linux
16+
17+
On Linux the easiest way to open a command line in a directory is:
18+
19+
1. Open the directoy in your file manager.
20+
2. Right click.
21+
3. From the context menu select: `Open In Terminal`.
22+
23+
## macOS
24+
25+
For macOS you can follow this tutorial: https://ladedu.com/how-to-open-a-terminal-window-at-any-folder-from-finder-in-macos/#How-to-Open-Mac-Terminal-from-Finder-in-the-Folder

0 commit comments

Comments
 (0)