Solved - How to use NMS with Paper? (2025)

All guides on this seem outdated, on Spigot, or not explained enough for my small brain.

I know I have to add the Paper Server into my dependencies but I don't know where to go past that.

Use paperweight-userdev from https://github.com/PaperMC/paperweight for Mojang mappings.
template: https://github.com/PaperMC/paperweight-test-plugin

I hate to gatekeep, but if learning from the example github is too hard, then you will likely struggle with the compatibility issues that arise from using NMS.

It's going to get a ton easier with the Mojang Mappings, but I still wouldn't recommend it unless you only plan on supporting a single version at a time, (until you understand exactly what's going on)

Nevermind, misread the post.
Still may apply to some people interested in NMS or who use maven

I know this was marked as solved but questions like this come up a lot.
Hopefully this helps explains some things.

First you'll need to install the latest remapped jar to your local repository I use buildtools for this.
you can create a simple script to automate the update process:

java -jar buildtools.jar --remappedread -p "press any key to exit"

This will contain the (for development purposes only) remapped (vanilla + spigot) jar where using mojang mappings the method names, classes and packages (but not fields) have been de-obfuscated.

now that the latest remapped spigot jar has been installed we'll need to head over to our maven project and install the special source plugin

The job of the special source plugin is to take your code (compiled against the remapped jar) and refactor it so that when we install it to a non-remapped server all of the methods and fields will line up.

For instance, if the code you compiled invoked net.minecraft.somepackage.SomeClass.someMethod() It wouldn't find any of that in the non-remapped server because net.minecraft.somepackage.SomeClass.someMethod() would have been obfuscated to something like abc.a()

An example configuration of special source:

<!-- Special Source --><plugin> <groupId>net.md-5</groupId> <artifactId>specialsource-maven-plugin</artifactId> <version>1.2.2</version> <executions> <execution> <phase>package</phase> <goals> <goal>remap</goal> </goals> <id>remap-obf</id> <configuration> <srgIn>org.spigotmc:minecraft-server:1.18.1-R0.1-SNAPSHOT:txt:maps-mojang</srgIn> <reverse>true</reverse> <remappedDependencies>org.spigotmc:spigot:1.18.1-R0.1-SNAPSHOT:jar:remapped-mojang</remappedDependencies> <remappedArtifactAttached>true</remappedArtifactAttached> <remappedClassifierName>remapped-obf</remappedClassifierName> </configuration> </execution> <execution> <phase>package</phase> <goals> <goal>remap</goal> </goals> <id>remap-spigot</id> <configuration> <inputFile>${project.build.directory}/${project.artifactId}-${project.version}-remapped-obf.jar</inputFile> <srgIn>org.spigotmc:minecraft-server:1.18.1-R0.1-SNAPSHOT:csrg:maps-spigot</srgIn> <remappedDependencies>org.spigotmc:spigot:1.18.1-R0.1-SNAPSHOT:jar:remapped-obf</remappedDependencies> </configuration> </execution> </executions></plugin>

After this you'll need to add the remapped jar to your dependencies:

<!-- Spigot --><dependency> <groupId>org.spigotmc</groupId> <artifactId>spigot</artifactId> <version>1.18.1-R0.1-SNAPSHOT</version> <classifier>remapped-mojang</classifier> <scope>provided</scope></dependency>

A quick note on the output binaries:
You'll see 3 new files something.jar something-remapped.jar and something-remapped-obf.jar
The one you'll want to use will be something.jar This will be your fully re-obfuscated jar compatible with non-remapped servers.

Some pitfalls:

• If maven can't find the remapped jar make sure that the maven install being used by buildtools is pointing to the same local repository that you are trying to get it from.
• If you also use reflection in your project you may find in some conditions the code isn't obfuscated properly, for example:
  getClass("net.minecraft.world.entity." + entityClassName) isn't reobfuscated properly because the value is decided at runtime.
• I'll think of something else?

Hope this helps some people.

Sorry to revive this thread again, but I've finally got around to using the test plugin and I cloned the test plugin repo and it was going well, however, in usage, I got errors stating "Invalid plugin.yml". I put my plugin.yml in the usual spot for other plugins "src/main/resources", removed the plugin to auto-create a plugin.yml, even tried letting the plugin make one itself but every time I got an error. The only differences between this plugin and my other working one is that this one is gradle, the other is maven, and (somehow) the project keeps forcing separate modules for main and test instead of using one for the entire plugin (which worked for my other one).

@Tau your method worked, but it overrode a lot of paper methods that I have been using, which was the main point of using the paper, and created this weird mix between paper and spigot that I feel would make it more difficult especially using the docs and other people's answers.

Vizzoid said:

Sorry to revive this thread again, but I've finally got around to using the test plugin and I cloned the test plugin repo and it was going well, however, in usage, I got errors stating "Invalid plugin.yml". I put my plugin.yml in the usual spot for other plugins "src/main/resources", removed the plugin to auto-create a plugin.yml, even tried letting the plugin make one itself but every time I got an error. The only differences between this plugin and my other working one is that this one is gradle, the other is maven, and (somehow) the project keeps forcing separate modules for main and test instead of using one for the entire plugin (which worked for my other one).

@Tau your method worked, but it overrode a lot of paper methods that I have been using, which was the main point of using the paper, and created this weird mix between paper and spigot that I feel would make it more difficult especially using the docs and other people's answers.

Click to expand...

Yes as i stated in my post I misread your thread.

Does the jarfile contain the plugin.yml at all if you open it with a program such as 7zip?
My thought is you might be relying on the maven-resources plugin to do some placeholder replacement that isn't being done now.

By "no, there isn't" are you referring to the lack of a plugin.yml in the final jar? If not:
If you inspect the compiled jar does the ${project.version} get replaced properly?

Otherwise I wouldn't be able to help you as i'm not much of a gradle person.

Yes, there is no plugin.yml.

This is confusing, this setup works perfectly fine until I run it on the paperweight plugin, I'm not quite sure what could be wrong.

Command? I didn't know I needed a command... I've been creating artifacts and building them...

Vizzoid said:

Command? I didn't know I needed a command... I've been creating artifacts and building them...

Click to expand...

or, rather: what are you clicking to build it? (screenshot is fine). Additionally, what jar are you looking at? as in where is it being output to/what is it named.

Apologies for the confusion.

I created an artifact on Intellij:

^^ I set the output directory straight to the plugins folder so I didn't have to move it, and the jar compiles fine (Only missing plugin.yml, but if I manually add it then it works fine)

Yeah, that makes sense. By doing that you are completely bypassing paperweight and Gradle, as well as not including your plugin.yml. I don't think that specific configuration would have worked normally either, but I'm not too familiar with the built-in build configs.

What you'll want to do is navigate to where it says "Gradle" on the right side of your screen, and then select paperweight -> reobfJar. Then double click or right click -> Run. The jar will then be located in build/libs/. For distribution (running on spigot mapped servers) you'll want to select the jar without dev in the name.