Skip to main content

paperweight-userdev

paperweight is the name of Paper's custom build tooling. The paperweight-userdev Gradle plugin part of that provides access to internal code (also known as NMS) during development.

note

This guide is written using the Gradle Kotlin DSL and assumes you have some basic knowledge of Gradle. If you want to see a fully-functioning plugin that uses paperweight-userdev, check out this example plugin.

Why this is useful​

The Paper server JARs we provide on the downloads page through the API are paperclip JARs. These use Spigot's mappings, which are essentially some type names, but fully obfuscated fields and methods. This can make it hard to work with in a development environment. This plugin lets you use fully deobfuscated types, names, and fields during development, and then remaps your plugin, so it can still be used with the obfuscated server.

1.20.5

As of Minecraft version 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings. See here for more details.

caution

The re-obfuscation does not apply to reflection. Look at something like this library to be able to use non-obfuscated names in reflection.

Adding the plugin​

Add the plugin to your build.gradle.kts file.

plugins {
    id("io.papermc.paperweight.userdev") version "1.7.1" // Check for new versions at https://plugins.gradle.org/plugin/io.papermc.paperweight.userdev
}

The latest version of paperweight-userdev supports dev bundles for Minecraft 1.17.1 and newer, so it's best practice to keep it up to date! Only the latest version of paperweight-userdev is officially supported, and we will ask you to update first if you are having problems with old versions.

Snapshots

paperweight-userdev releases are available through the Gradle Plugin Portal, but if you want to use SNAPSHOT versions, you must add Paper's Maven repository to settings.gradle.kts with:

pluginManagement {
    repositories {
        gradlePluginPortal()
        maven("https://repo.papermc.io/repository/maven-public/")
    }
}

Adding the dev bundle dependency​

If you try to load your Gradle project now, you will receive an error saying you have to declare a dev bundle dependency. You can do that by adding to your dependencies block in your build.gradle.kts file.

tip

You should remove any dependency on the Paper API, as the dev bundle includes that.

Gradle tasks​

reobfJar​

This task creates a plugin JAR that is re-obfuscated to Spigot's runtime mappings. This means it will work on standard Paper servers.

The output will be inside the build/libs folder. The JAR whose filename includes -dev is Mojang-mapped (not re-obfuscated) and will not work on most servers.

Shadow

If you have the shadow Gradle plugin applied in your build script, paperweight-userdev will detect that and use the shaded JAR as the input for the reobfJar task.

The -dev-all.jar file in build/libs is the shaded, but not re-obfuscated JAR.

You can make the reobfJar task run on the default build task with:

tasks.assemble {
    dependsOn(tasks.reobfJar)
}

1.20.5 and beyond​

As of 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings. Additionally, CraftBukkit classes will no longer be relocated into a versioned package. This requires plugins to be deobfuscated before loading when necessary.

Most of this process is done automatically by paperweight but there are some important things to know when using NMS from now on.

Default mappings assumption​

  • By default, all Spigot/Bukkit plugins will be assumed to be Spigot-mapped if they do not specify their mappings namespace in the manifest. Conversely, all Paper plugins will be assumed to be Mojang-mapped if they do not specify their mappings namespace in the manifest.
  • Spigot-mapped plugins will need to be deobfuscated on first load, Mojang-mapped plugins will not.

Mojang mappings​

If you want to map your plugin with Mojang mappings, you need to add the following code to your build script:

note

You only have to change this setting if you are using Bukkit/Spigot plugins. Paper plugins are already assumed to be Mojang-mapped.

build.gradle.kts
paperweight.reobfArtifactConfiguration = io.papermc.paperweight.userdev.ReobfArtifactConfiguration.MOJANG_PRODUCTION

Additionally, you need to remove all dependsOn(reobfJar) lines.

Spigot mappings​

If you are using Paper plugins but want to explicitly use Spigot mappings, you need to change the property to:

build.gradle.kts
paperweight.reobfArtifactConfiguration = io.papermc.paperweight.userdev.ReobfArtifactConfiguration.REOBF_PRODUCTION