How to Decompile and Recompile a Minecraft Plugin: A Developer’s Guide #

Minecraft plugins are distributed as .jar files, which are essentially compressed archives containing compiled Java bytecode. Sometimes you may need to modify an existing plugin for debugging, learning purposes, or making custom changes. This guide will walk you through the process of decompiling a Minecraft plugin, making modifications, and recompiling it back into a working .jar file.

What You’ll Need #

Before we begin, you’ll need:

• Java Development Kit (JDK) 17 or higher
• CFR decompiler (available at CFR Releases)
• Basic knowledge of Java programming
• The plugin .jar file you want to modify

Step 1: Decompiling the Plugin #

A .jar file is essentially an archive (like a .zip file) containing compiled Java bytecode. To make this code readable and editable, we need to decompile it back to Java source code.

Use the following command to decompile the plugin:

java -jar cfr.jar YourPlugin.jar --outputdir out

CFR is a mature and reliable Java decompiler that converts JVM bytecode back into readable Java source code. The --outputdir out parameter tells CFR to place all decompiled files in an out directory.

Step 2: Setting Up the Build Environment #

Create a build directory structure for compiling your modified code:

mkdir -p build/classes

This directory will store the compiled .class files before we package them back into the .jar.

Step 3: Handling Dependencies #

Most Minecraft plugins depend on external libraries, such as:

• Paper MC API
• Spigot API
• Other plugin APIs
• Third-party libraries

You’ll need to download these dependencies manually and place them in a lib folder. I found the following websites useful for downloading paper dependencies:

• phoenix616.dev

Important Note: If the original plugin is digitally signed, you’ll see signature files in the META-INF directory (files ending with .SF or .RSA). Since we’re modifying the plugin, these signatures will become invalid. You have two options:

1. Remove the signature files from META-INF
2. Re-sign the jar after modification (advanced topic)

In our case, the plugin is fortunately not signed.

Step 4: Making Your Changes #

Navigate to the out directory and locate the Java files you want to modify. Edit them using your preferred text editor or IDE. Make sure to:

• Maintain proper Java syntax
• Keep package declarations intact
• Preserve import statements unless you’re removing unused dependencies

Step 5: Recompiling Modified Files #

Compile your modified Java files back to bytecode:

javac --release 17 \
  -cp "YourPlugin.jar:lib/*" \
  -d build/classes \
  out/net/yourplugin/package/YourModifiedFile.java

Explanation of parameters:

• --release 17: Ensures compatibility with Java 17
• -cp: Specifies the classpath (original jar + dependencies)
• -d build/classes: Output directory for compiled classes
• The final parameter is the path to your modified Java file(s)

Step 6: Updating the JAR File #

Now we need to replace the old compiled class with our new one inside the original .jar file:

jar uf YourPlugin.jar -C build/classes net/yourplugin/package/YourModifiedFile.class

The uf flags mean:

• u: Update existing jar file
• f: Specify jar file name

Step 7: Testing Your Modified Plugin #

1. Copy your modified plugin to your Minecraft server’s plugins directory
2. Start your server and check the console for any errors
3. Test the plugin functionality to ensure your changes work as expected

Important Considerations #

• Legal and Ethical: Only modify plugins you have permission to alter
• Backups: Always keep a backup of the original plugin
• Version Compatibility: Ensure your modifications are compatible with your Minecraft server version
• Testing: Thoroughly test your changes in a development environment before deploying to production

Troubleshooting Common Issues #

• ClassNotFoundException: Check that all dependencies are in the classpath
• Compilation Errors: Verify that you haven’t introduced syntax errors during editing
• Plugin Won’t Load: Check server logs for specific error messages

Conclusion #

Decompiling and recompiling Minecraft plugins can be a valuable skill for developers who want to understand how plugins work, fix bugs, or add custom features. Remember to always respect the original author’s work and licensing terms when modifying plugins.

With your newly recompiled plugin, you now have a customized version that meets your specific needs. Happy hacking!