Skip to content

NMSMapper

A Gradle plugin 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

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
buildscript {
    repositories {
        maven {
            url 'https://repo.screamingsandals.org/repository/maven-public'
        }
    }
    dependencies {
        // make sure you have the latest version
        classpath 'org.screamingsandals.nms:NMSMapper:1.1.1'
    }
}

apply plugin: 'org.screamingsandals.nms'

Examples

Basic setup

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
/* 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.

    /*
     * 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
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
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.

You can also specify an another NMS class as a parameter without requesting it, in this case you will have to add a prefix: &

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

    reqClass('net.minecraft.world.entity.decoration.ArmorStand')
        .reqConstructor('&net.minecraft.world.level.Level', double, double, double)
        .reqMethod('setSmall', boolean)
}
However, the accessor for Level will be generated anyways.

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
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

Compatibility

Versions lower than 1.9.4 are not supported and will not work!

1
./gradlew generateNmsConfig -PminecraftVersion=<version>

Last update: 2022-01-18
Back to top