Reading Stacktraces and debugging Plugins (#187)

Author: olijeffers0n

config/sidebar.paper.ts

@@ -120,6 +120,19 @@ const paper: SidebarsConfig = {
             "dev/api/custom-inventory-holder",
           ],
         },
+        {
+          type: "category",
+          label: "Miscellaneous",
+          collapsed: true,
+          link: {
+            type: "doc",
+            id: "dev/misc/README",
+          },
+          items: [
+            "dev/misc/reading-stacktraces",
+            "dev/misc/debugging",
+          ],
+        },
       ],
     },
   ],

docs/paper/dev/misc/README.mdx

@@ -0,0 +1,10 @@
+import DocCardList from "@theme/DocCardList";
+import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
+
+# Miscellaneous Development Guides
+
+These guides are for helping developers with parts of the development process that don't fit into the other categories.
+
+---
+
+<DocCardList items={useCurrentSidebarCategory().items} />

docs/paper/dev/misc/assets/add_breakpoints.png

@@ -0,0 +1,92 @@
+---
+slug: /dev/debugging
+---
+
+# Debugging your plugin
+
+Debugging your plugin is vital to being able to fix bugs and issues in your plugin. This page will cover some of the most common debugging techniques.
+
+### Printing to the console
+
+One of the most common debugging techniques is to print to the console. This is likely something you've done before, as it's very simple. 
+This has a few downsides, though. It can be hard to find the print statements in the console, and it can be hard to remove them all when you're done debugging. Most notably, you have to recompile your plugin and restart the server to add or remove debugging.
+
+When debugging, you can use `System.out.println("");` to print to the console. It is recommended to use your plugin's logger instead though, 
+as it will be easier to know which plugin the log has come from. This can be done simply with:
+
+```java
+plugin.getComponentLogger().debug(Component.text("SuperDuperBad Thing has happened"));
+```
+
+:::note[Logger Levels]
+
+In some consoles, using the `warning` level will print the message in different colours.
+This can be useful for finding your print statements in the console.
+
+:::
+
+### Using a remote debugger
+
+A debugger is a tool that allows you to pause your code at a certain point and inspect the values of variables.
+This can be very useful for finding out why your code isn't working as expected and also for finding out where your code is going wrong.
+
+#### Setting up the debugger
+
+To use a debugger, you need to set up your IDE to use it. This is different for each IDE, but for the sake of this guide, we will be using IntelliJ IDEA.
+
+To set up a debugger in IntelliJ, you need to create a new run configuration.
+You can do this by clicking the dropdown next to the run button and clicking `Edit Configurations...`:
+
+![](./assets/config_dropdown.png)
+
+Then, click the `+` button in the top left and select `Remote JVM Debug`. You can then name the configuration whatever you want, and click `Apply`:
+
+![](./assets/config_add.png)
+
+Finally, copy the command line arguments from the window, and paste these into your server's startup script.
+These will go after the `java` command and before `-jar`. Once you have done this, you can click `OK`. For example:
+
+```bash
+java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar paper-1.20.1.jar nogui
+```
+
+Once your server is running, you can use the bug icon in the top right to connect your debugger to the server:
+
+![](./assets/debugger_connect.png)
+
+#### Using the debugger
+
+Let's say we have this code:
+
+```java
+@EventHandler
+public void onPlayerMove(PlayerMoveEvent event) {
+    Player player = event.getPlayer();
+    Location location = player.getLocation();
+    
+    if (location.getWorld() == null)
+        return;
+
+    if (location.getWorld().getEnvironment() == World.Environment.NETHER) {
+        player.sendMessage("You are in the nether!");
+    }
+}
+```
+
+You can add a breakpoint to the line by clicking on the line number:
+
+![](./assets/add_breakpoints.png)
+
+This will pause the code when it reaches that line. You can then use the debugger to inspect the values of variables:
+
+![](./assets/debugger_use.png)
+
+You can inspect the values of each of the variables in the current scope. 
+You can also use the buttons in the top to step from one breakpoint to the next.
+If needed, you can also use the text box at the top to evaluate expressions for debugging purposes.
+
+### Using direct debugging
+
+Direct debugging will allow you to run the server directly from your IDE, and will allow you to use breakpoints and step through your code.
+We can achieve this by using [JPenilla's Gradle plugin](https://github.com/jpenilla/run-task) to run the server directly from the IDE.
+See [here](https://github.com/jpenilla/run-task#basic-usage) for instructions on how to set up the plugin.

docs/paper/dev/misc/assets/config_add.png

@@ -0,0 +1,66 @@
+---
+slug: /dev/reading-stacktraces
+---
+
+# Reading Stacktraces
+
+## What is a stacktrace?
+In Java, a stacktrace shows the call stack of a thread. The call stack is the path of execution that led to the current point in the program.
+Usually, the stacktrace will be printed to the console when an exception is not handled correctly.
+
+Stacktraces are a useful tool for debugging your code. They show you the exact line of code that caused an error, and the 
+line of code that called that line of code, and so on. This is useful because it allows you to see the exact path of execution that led to the error.
+
+### Example:
+
+Here is an example of a stacktrace which has been caused due to a `NullPointerException`:
+
+```
+[15:20:42 ERROR]: Could not pass event PluginEnableEvent to TestPlugin v1.0
+java.lang.NullPointerException: Cannot invoke "Object.toString()" because "player" is null
+        at io.papermc.testplugin.TestPlugin.onPluginEnable(TestPlugin.java:23) ~[TestPlugin-1.0-SNAPSHOT.jar:?]
+        at com.destroystokyo.paper.event.executor.asm.generated.GeneratedEventExecutor1.execute(Unknown Source) ~[?:?]
+        at org.bukkit.plugin.EventExecutor$2.execute(EventExecutor.java:77) ~[paper-api-1.20.1-R0.1-SNAPSHOT.jar:?]
+        at co.aikar.timings.TimedEventExecutor.execute(TimedEventExecutor.java:81) ~[paper-api-1.20.1-R0.1-SNAPSHOT.jar:git-Paper-49]
+        at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:70) ~[paper-api-1.20.1-R0.1-SNAPSHOT.jar:?]
+        at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-1.20.1.jar:git-Paper-49]
+        at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:126) ~[paper-1.20.1.jar:git-Paper-49]
+        at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:615) ~[paper-api-1.20.1-R0.1-SNAPSHOT.jar:?]
+        at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-1.20.1.jar:git-Paper-49]
+        at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-1.20.1.jar:git-Paper-49]
+        at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-1.20.1-R0.1-SNAPSHOT.jar:?]
+        at org.bukkit.craftbukkit.v1_20_R1.CraftServer.enablePlugin(CraftServer.java:636) ~[paper-1.20.1.jar:git-Paper-49]
+        at org.bukkit.craftbukkit.v1_20_R1.CraftServer.enablePlugins(CraftServer.java:547) ~[paper-1.20.1.jar:git-Paper-49]
+        at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:636) ~[paper-1.20.1.jar:git-Paper-49]
+        at net.minecraft.server.MinecraftServer.loadLevel(MinecraftServer.java:435) ~[paper-1.20.1.jar:git-Paper-49]
+        at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:308) ~[paper-1.20.1.jar:git-Paper-49]
+        at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1101) ~[paper-1.20.1.jar:git-Paper-49]
+        at net.minecraft.server.MinecraftServer.lambda$spin$0(MinecraftServer.java:318) ~[paper-1.20.1.jar:git-Paper-49]
+        at java.lang.Thread.run(Thread.java:833) ~[?:?]
+```
+
+-   Firstly, we can see that this certain error occurred when the `PluginEnableEvent` was being handled by the `TestPlugin`.
+
+-   Then we can see on the second line, the cause of the exception:
+    > `java.lang.NullPointerException: Cannot invoke "Object.toString()" because "null" is null`
+
+    This tells us that the exception was caused by a `NullPointerException`, 
+    and that the exception was caused because we tried to call the `toString()` method on a null "player" object.
+
+-   From here, as we work down the stacktrace, we can see the exact path of execution that led to the error. In this case, 
+    the next line of the stacktrace is:
+    > `at io.papermc.testplugin.TestPlugin.onPluginEnable(TestPlugin.java:23) ~[TestPlugin-1.0-SNAPSHOT.jar:?]`
+    
+    Which tells us that the error was thrown at line 23 of `TestPlugin.java`.
+
+-   You can continue to work down the stacktrace, and see the exact path of execution that led to the error. In this case,
+    it is server internals, so we can generally ignore it.
+
+## Omitted Stacktraces
+
+In JDK 5, the JVM started to omit stacktraces for certain exceptions. This was common when the JVM had optimised the code,
+and you could get `NullPointerException`s without a stacktrace. In order to fix this, you can pass the `-XX:-OmitStackTraceInFastThrow` flag to the JVM:
+
+```bash
+java -XX:-OmitStackTraceInFastThrow -jar paper.jar
+```