Skip to main content

Debug

Introduction​

This page explains how to debug the Lasers-Enigma plugin using IntelliJ, covering both local and remote debugging. The project provides shared run configurations that handle most of the setup automatically.

Prerequisites: Make sure you have completed the Setup development environment guide first. The shared run configurations and debug-friendly server patches are created during that setup.

Local Debugging​

Local debugging lets you build the plugin and run a Minecraft server in debug mode directly from IntelliJ. This is the recommended approach for day-to-day development.

Using the shared run configurations​

The project includes ready-to-use run configurations in the .run/ directory, automatically detected by IntelliJ:

ConfigurationDescription
🎮 latestBuilds the plugin, then starts run/latest/server.jar
🎮 le-playBuilds the plugin, then starts run/le-play/server.jar
🎮 1.20.4Builds the plugin, then starts run/1.20.4/server.jar
🎮 1.19.4Builds the plugin, then starts run/1.19.4/server.jar

Each configuration automatically:

  • Runs the Gradle build task before launch (builds and deploys the plugin JAR to the server's plugins/ folder)
  • Starts the server with -Dlog4j.configurationFile=log4j2.xml for trace-level plugin logging
  • Allocates -Xms2G -Xmx2G of memory
  • Runs in nogui mode

Start debugging​

  1. Select one of the 🎮 configurations from the run configuration dropdown in IntelliJ.
  2. Click Debug (the bug icon, or Shift+F9) instead of Run.
  3. IntelliJ builds the plugin, starts the server in debug mode, and attaches automatically.
  4. Place breakpoints in your plugin code — when execution reaches a breakpoint, the server thread pauses and you can inspect variables, evaluate expressions, and step through the code.

Tip: Since these are JAR Application configurations launched via IntelliJ's Debug button, the debugger is attached directly — no separate remote debug connection is needed.

Preventing crashes during debugging​

When paused on a breakpoint, the server's watchdog may force a shutdown after a timeout.

If you used ./gradlew setupDevEnvironment (or patchServerConfigs), this is already handled: max-tick-time is set to -1 in spigot.yml for all run/ servers. Otherwise, manually set in spigot.yml:

settings:
  max-tick-time:
    tile: -1
    entity: -1

Remember to revert these changes for production servers.

By default, the Minecraft client disconnects after 30 seconds of inactivity. To prevent this during debugging, install the TimeOutOut mod on your client.

Remote Debugging​

Remote debugging connects IntelliJ to a Minecraft server running on a separate machine (e.g. the LE Play server hosted on Pterodactyl).

Generate the remote debug run configuration​

The project provides a Gradle task that generates the 🔌 remote debug LE Play IntelliJ run configuration.

1. Configure your host​

Add the remote server's IP address to your personal Gradle properties file (~/.gradle/gradle.properties):

## Remote debug host (required)
## Find the IP in the "address" field in the Pterodactyl panel sidebar:
## https://panel.skytale.fr/server/5bcf33bc
remoteDebugHost=<server-ip-address>

## Remote debug port (optional, defaults to 25566)
## remoteDebugPort=25566

See Setup development environment — Configure API tokens for the full list of properties.

2. Generate the configuration​

./gradlew generateRemoteDebugConfig

This creates .run/remote debug LE Play.run.xml (git-ignored since it contains the server IP). IntelliJ picks it up automatically.

3. Configure the server for remote debugging​

Edit the startup command for remote debugging in the Pterodactyl admin panel: Pterodactyl panel > Admin > Servers > LE - Play > Startup. If you do not have admin access, ask a server administrator to do this for you (e.g. bZx_ or the_nt).

Then add this to the Java options (after the existing -Xms and -Xmx parameters):

-Xdebug -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:25566

Full startup command example:

java -Xms128M -XX:MaxRAMPercentage=95.0 -Xdebug -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:25566 -Dterminal.jline=false -Dterminal.ansi=true -jar {{SERVER_JARFILE}}

Normally, the server have both 25566 and 9191 ports opened so you can use both. 25565 is used for Minecraft itself.

Optional: avoid timeouts during debugging​

See chapter Preventing crashes during debugging for local debugging. The same applies to remote debugging: set max-tick-time for tile and entity to -1 in the server's spigot.yml to prevent watchdog shutdowns when paused on breakpoints.

Then restart the server to apply the changes.

3. Connect​

  1. Make sure the remote server is running.
  2. Select 🔌 remote debug LE Play from the run configuration dropdown.
  3. Click Debug (Shift+F9).
  4. IntelliJ connects to the remote JVM. Place breakpoints and debug as usual.

4. Deactivate remote debugging​

When you're done, remove the -Xdebug -agentlib:jdwp=... part from the server startup command java options to prevent unauthorized access.

If you also modified max-tick-time in spigot.yml, remember to revert those changes for production.

Restart the server to apply the changes.

Need Help?​

If you have any questions or need further assistance, feel free to join our Discord Server.