paper-nms-maven-plugin

A maven plugin for using NMS on Paper with Mojang mappings.

This plugin will both create the mapped paper dependency and install it to your local repository, and remap your artifact back to spigot mappings.

[!NOTE] This is an unofficial plugin. You probably want to use Gradle and the officially supported paperweight-userdev plugin instead. Do not ask PaperMC for support regarding this plugin. Instead, direct message alvinn8 on discord and I will try to help you.

Usage (IntelliJ)

1. Add .paper-nms to your .gitignore.

2. Add the plugin and its repository to your pom.xml:

<pluginRepositories>
    ...
    <pluginRepository>
        <id>bytecode.space</id>
        <url>https://repo.bytecode.space/repository/maven-public/</url>
    </pluginRepository>
    ...
</pluginRepositories>

<build>
    <plugins>
        ...
        <plugin>
            <groupId>ca.bkaw</groupId>
            <artifactId>paper-nms-maven-plugin</artifactId>
            <version>1.5</version>
        </plugin>
        ...
    </plugins>
</build>

1. Add the mojang mapped dependency to your pom.xml.

<dependency>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms</artifactId>
    <version>[26.1.2.build.1, 26.1.2.build.9999)</version>
    <scope>provided</scope>
</dependency>

• For snapshot versions, specify the version as 1.21.8-R0.1-SNAPSHOT.
• To use a specific build, specify the version as 26.1.2.build.70-stable.
• If you want to use the latest build for 26.1.2, you can use a version range like [26.1.2.build.1, 26.1.2.build.9999) to always use the latest build of 26.1.2.

• If you want to use the latest build of the latest version (not recommended because Minecraft may have breaking changes) you can use a range without an upper bound such as [26.1.2,) to always use the latest build of 26.1.2 or higher.

• Reload the project.

A Cannot resolve ca.bkaw:paper-nms:version message is expected.

1. To create the missing dependency, run init. For arrow (4), double-click paper-nms:init to run it.

2. Wait for init to finish and a BUILD SUCCESS message should appear. The paper-nms dependency should now exist.

3. Done! Your project should now have a Mojang mapped paper dependency.

Usage on versions before Paper 1.20.5 / Spigot support

Before Paper 1.20.5 the runtime mappings were Spigot mappings on Paper servers. To use NMS on versions before Paper 1.20.5, you must configure paper-nms-maven-plugin to remap your plugin back to Spigot mappings.

If you are using 1.21 and need to support Spigot servers, you also need to remap to Spigot mappings.

To remap your plugin back to Spigot mappings, add the following to your pom.xml:

 <plugin>
     <groupId>ca.bkaw</groupId>
     <artifactId>paper-nms-maven-plugin</artifactId>
     <version>1.5</version>
+    <executions>
+        <execution>
+            <phase>process-classes</phase>
+            <goals>
+                <goal>remap</goal>
+            </goals>
+        </execution>
+    </executions>
 </plugin>
 ```

## Usage with paper forks
You can specify a custom dev bundle to use NMS with paper forks.

This is done by configuring the plugin as follows.
```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>...</version>
    <executions>...</executions>
    <configuration>
        <devBundle>

            <id>forktest-nms</id>

            <repository>
                <id>myrepo</id>
                <url>https://repo.example.com/repository/maven-public/</url>
            </repository>

            <artifact>
                <groupId>com.example.paperfork</groupId>
                <artifactId>dev-bundle</artifactId>
            </artifact>
        </devBundle>
    </configuration>
</plugin>
...
<dependencies>
    <dependency>

        <groupId>ca.bkaw.nms</groupId>
        <artifactId>forktest-nms</artifactId> 
        <version>[26.1.2.build.1, 26.1.2.build.9999)</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

The version you specify for the forktest-nms dependency will be the version of the dev-bundle used. You may use ranges or exact versions to specify the version as explained in the previous section.

Run paper-nms:init. The paper-nms-maven-plugin will download the dev bundle from the specified repository and generate the dependency.

The repository can be omitted and the dev bundle will be fetched from maven local.

It is also possible to omit the url from the repository tag if you already have defined a repository with the same id in the repositories tag of your pom.xml.

If the repository requires authentication, prefer specifying the id of the repository and define the repository in the repositories tag of your pom.xml.

Usage with NMS modules that depend on each other

If you have multiple modules that use NMS that depend on each other and that will be shaded into one jar, the plugin needs to be configured in a different way.

[!NOTE] This only applies if you have multiple NMS modules that depend on each other and that will shade each other. And only applies if you use remapping (before version 1.20.5 or for Spigot support).

Let's say you have two modules, api and plugin. Both of these modules use NMS. api has an interface that uses NMS types, and plugin implements this interface. The plugin module shades the api module.

To use the plugin with this setup it needs to remap the resulting shaded jar file instead of remapping classes.

1. In the api module, remove the executions part of the plugin configuration so that it doesn't remap that module.
2. In the plugin module, change the remap goal to run during the package phase instead of process-classes, and make sure the paper-nms-maven-plugin is located after the maven-shade-plugin.

This way the plugin will remap the jar file after it has been shaded, and all shaded dependencies will also be remapped.

See issue #16 (Closed) for more information.

Troubleshooting: remap failed: Duplicate key

Delete the file .paper-nms/classes.json and try again.

Issues

Only works for 1.17 and higher

On some older spigot versions, mappings use a package rename to avoid having to retype net/minecraft/server for every class mapping. See issue #2.

In the future all versions down to 1.14.4 should be supportable as there are Mojang mappings available since then.

Disclaimer

You probably want to use Gradle and paperweight-userdev instead.

Please bear the licence of the Mojang mappings in mind.

Not affiliated with Minecraft, Mojang or Microsoft.

Not affiliated with Paper or PaperMC.

Not affiliated with Maven or The Apache Software Foundation.