Skip to content

NMSMapper

A Java library for generating multi-version NMS accessors.

  • Mappings generated by this library can be browsed here.

Disclaimer

These mappings are provided "AS-IS", with no warranty, so mistakes are possible. We are only solving issues in classes, that we are actively using in ScreamingSandals plugins.
If you want to fix anything, feel free to open a pull request or contact us on our Discord server.
NMSMapper is made for servers! Many client-side mappings are missing.

Warning

Usage of this Gradle plugin requires significant knowledge of Java Reflection!

Usage

Gradle

Compatibility

This project requires Gradle >= 7.0. Maven is not supported. At least JDK 11 is needed for compiling, however the compiled classes use only Java 8 methods.

settings.gradle
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
pluginManagement {
    repositories {
        mavenCentral()
        maven {
            url = "https://repo.screamingsandals.org/public/"
        }

        gradlePluginPortal()
    }
}

rootProject.name = 'YourProject'
build.gradle
1
2
3
plugins {
    id 'org.screamingsandals.nms-mapper' version '1.2.0'
}

Standalone

Download the latest jar file from here and save it in your project.
Create a groovy file (example: nms.groovy). Contents of this file will be similar like when using Gradle, however this time only nmsGen section and its content is present.
Run the generation using:
java -jar nms-mapper-standalone.jar -b nms.groovy

Examples

Basic setup

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
/* First add a new source set. Don't use your main source set for generated stuff. */
sourceSets.main.java.srcDirs = ['src/generated/java', 'src/main/java']

/* All other things will be set inside the nmsGen method. */
nmsGen {
    basePackage = "com.example.nms.accessors" // All generated classes will be in this package.
    sourceSet = "src/generated/java" // All generated classes will be part of this source set.
    minMinecraftVersion = "1.8.8" // Optional, default value is 1.9.4
    maxMinecraftVersion = "1.18.2" // Optional, default value is the last known version

    /*
     * This means that the folder will be cleared before generation. 
     *
     * If this value is false, old no longer used classes won't be removed.
     */
    cleanOnRebuild = true
}

Defining objects for generation

We want to access the net.minecraft.core.Rotations class in our plugin. The following method generates a new class, named RotationsAccessor, which you can use to retrieve the type. 

1
2
3
4
5
nmsGen {
    /* Setup, see chapter before */

    reqClass('net.minecraft.core.Rotations')
}
The generated code looks like this: 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
public class RotationsAccessor {
    public static Class<?> getType() {
        return AccessorUtils.getType(RotationsAccessor.class, mapper -> {
            mapper.map("spigot", "1.9.4", "net.minecraft.server.${V}.Vector3f");
            mapper.map("spigot", "1.17", "net.minecraft.core.Vector3f");
            mapper.map("mcp", "1.9.4", "net.minecraft.util.math.Rotations");
            mapper.map("mcp", "1.17", "net.minecraft.src.C_4709_");
        });
    }  
}
We can see that we got a new static method, named getType(), which returns a class based on the version and platform (Spigot and Forge is supported).

Okay, we have a class. But classes are not all, we also need to access some fields, methods or even constructors. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
nmsGen {
    /* Setup, see chapter before */

    reqClass('net.minecraft.core.Rotations') {
        reqConstructor(float, float, float)
        reqField('x')
        reqField('y')
        reqField('z')
        reqMethod('getX')
        reqMethod('getY')
        reqMethod('getZ')
    }
}

This will generate access methods for one constructor, three fields and three methods. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public class RotationsAccessor {
    public static Class<?> getType() {
    }

    public static Field getFieldX() {
    }

    public static Field getFieldY() {
    }

    public static Field getFieldZ() {
    }

    public static Constructor<?> getConstructor0() {
    }

    public static Method getMethodGetX1() {
    }

    public static Method getMethodGetY1() {
    }

    public static Method getMethodGetZ1() {
    }
}
A generated access method for a field will always be called getField<Name> and will always return Field. A generated access method for a constructor will always be called getConstructor<Index> and will always return Constructor<?>. This index is generated from the specified order in build.gradle.
A generated access method for a method will always be called getMethod<Name><Index> and will always return Method. Here the index is present, because multiple methods can have other parameters, but the same name.

Info

If a class, a field, a method or a constructor is not found, null is returned.

Maybe you are asking: How to define parameters to methods? It's actually pretty easy, and the same applies to constructors: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
nmsGen {
    /* Setup, see chapter before */

    var Level = reqClass('net.minecraft.world.level.Level')

    reqClass('net.minecraft.world.entity.decoration.ArmorStand') {
        reqConstructor(Level, double, double, double)
        reqMethod('setSmall', boolean)
    }
}
Parameters can be classes (e.g. String.class, in groovy you don't have to specify the .class suffix), strings (java.lang.String) or an another requested class (in this example it's Level).

Arrays of requested classes

You can create an array of a requested class by calling .array() on it, useful for defining parameters of a NMS type.

For requested classes you can also use so-called context. That means you don't have to save it to variable, but you can use string prepended with @ 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
nmsGen {
    /* Setup, see chapter before */

    reqClass('net.minecraft.world.level.Level')

    reqClass('net.minecraft.world.entity.decoration.ArmorStand') {
        reqConstructor('@Level', double, double, double)
        reqMethod('setSmall', boolean)
    }
}

Arrays of requested classes in context

You can create an array of a requested class by appending [].

If the class is an enum and we want to retrieve its enum value, we can simply use the reqEnumField method. 

1
2
3
4
5
6
7
nmsGen {
    /* Setup, see chapter before */

    reqClass('net.minecraft.network.protocol.game.ServerboundClientCommandPacket$Action') {
        reqEnumField('PERFORM_RESPAWN')
    }
}
In this case, the getField method will be generated again, however it will return directly the Object instead of Field. 
1
2
public static Object getFieldPERFORM_RESPAWN() {
}

  • For generating accessor classes, you will have to execute the generateNmsComponents task.

Using alternative mappings/custom versions

If you want to use alternative mappings or specific versions for generating accessors, prefix the build.gradle declaration with <mappingtype>: and suffix it with :<version>.
Available mapping types are mojang, searge, spigot, obfuscated. Mojang mappings are used by default (if available).

Generating configurations for new versions

1
./gradlew generateNmsConfig -PminecraftVersion=<version>
Last update: 2022-03-22
Back to top