NMS: Use Mojang mappings for your Spigot plugins with Maven

If you need to access NMS classes from inside your Spigot plugin, it is a very good idea to use the so called Mojang mappings.

Disclaimer: This post is obviously written for 1.18.2. If you use another version, you of course have to replace every occurance of “1.18.2” with the version you actually use.

What are Mojang mappings?

Mojang is obfuscating certain method and field names before shipping Minecraft. That means you will have a very bad experience when you want to access NMS in the classic way, because most fields are simply called “a”, “b”, “c”, etc. Fortunately, Mojang decided to release their obfuscation map, which means that you can actually use the same names that the Mojang developers are using.

How to use Mojang mappings

First of all, you have to run BuildTools and tell it to get yourself a nice, fresh compiled spigot version with the Mojang mappings:

java -jar BuildTools.jar --rev 1.18.2 --remapped

It does not matter in which folder you run BuildTools as long as it’s on the same computer that you use to code your plugin. BuildTools will install all dependencies to your local maven repository. You can now adjust your pom.xml to use the Mojang mapped .jar, and to reobfuscate all needed method/class calls at compile time:

    <build>
        <plugins>
            <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.2-R0.1-SNAPSHOT:txt:maps-mojang</srgIn>
                            <reverse>true</reverse>
                            <remappedDependencies>org.spigotmc:spigot:1.18.2-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.2-R0.1-SNAPSHOT:csrg:maps-spigot</srgIn>
                            <remappedDependencies>org.spigotmc:spigot:1.18.2-R0.1-SNAPSHOT:jar:remapped-obf</remappedDependencies>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

    [...]

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

Obviously, you might want to adjust “1.18.2” when you want to use a different spigot version (e.g. change it from “1.18.2” to “1.19.2” in both, your <dependency> section, and in all 4 places it appears in the <plugin> section). You are now fine to go to use Mojang mappings. Maven will automatically “reobfuscate” your code so it’ll be compatible with the actual server software.