weaver-userdev

Note

This guide assumes you are able to use a Gradle wrapper of some capacity, either Gradle Kotlin DSL or Gradle Groovy DSL. We do not include guides for accesing internals on Maven. However, should you wish to access Canvas’ internals with Maven, there are community made plugins available.

This page focuses on teaching you how to access internals through the weaver-userdev Gradle plugin. But given that paperweight-userdev also allows you to access internals, we provide guides for using it too.

You might also find some additional resources, going more in-depth on the PaperMC Userdev Docs.

What is weaver, and how does it differ from paperweight?

weaver is a custom fork of paperweight used for Canvas build tooling. It includes 3 modules, but only one of them matters here, namely weaver-userdev. The main difference between the paperweight userdev plugin and ours is that weaver has some DSL extensions that make using Canvas dev bundles more easy.

What are dev bundle’s?

Dev bundles are maven artifacts, containing patches to the Minecraft source, which are applied during the build process, and API. This means that they are a fully functional way to access Minecraft internals, without having to worry about EULA or license restrictions.

Is This Important to You?

Accessing server internals is not necessary for majority of Canvas plugins. Using the Canvas API or the one of the APIs of our upstream projects (i.e. Paper or Folia) is always preferrable when it can be used.

In some situations, the Canvas API may not be enough and you may need to access server internals directly.

Getting Started

Danger

The Canvas API should always be preferred over internals. Minecraft and Canvas internals change very frequently and your plugin is likely to break upon every new Minecraft release. If your code can be written using Canvas’ API, use the API!

If you’re not sure whether your plugin requires access to Minecraft internals, join our Discord! We’re happy to give feedback and help you where we can.

If you’ve concluded that your project has to rely on internals, this guide is here to assist you in configuring your Gradle build script, so that you can build against them.

Prerequisites

Tip

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

Gradle 9.+

For this guide, we’ll be using gradle 9.+. If your Gradle wrapper version starts with the number 9, you’re good to go and you can skip this part!

macOS & Linux Windows

# First, check your Gradle version
./gradlew --version

# Run this if your Gradle wrapper is using an older version
./gradlew wrapper --gradle-version latest

# First, check your Gradle version
gradlew --version

# Run this if your Gradle wrapper is using an older version
gradlew wrapper --gradle-version latest

Setup using weaver-userdev

This portion will show you how to add weaver-userdev and the Canvas dev bundle to your Gradle project.

In your settings.gradle.kts or settings.gradle file…

settings.gradle.kts

pluginManagement {
    repositories {
        gradlePluginPortal()
        maven("https://maven.canvasmc.io/releases")
    }
}

In your build.gradle.kts or build.gradle file…

build.gradle.kts

plugins {
    id("io.canvasmc.weaver.userdev") version "2.3.12"
}

dependencies {
    // Other dependencies...
    paperweight.canvasDevBundle("1.21.11-R0.1-SNAPSHOT")
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(21))
}

Setup using paperweight-userdev

Note

This is an alternative method for adding Canvas dev bundles to your Gradle project. paperweight-userdev is not developed, nor maintained by CanvasMC. weaver-userdev should always be preferred!

build.gradle.kts

plugins {
    id("io.papermc.paperweight.userdev") version "2.0.0-beta.19"
}

repositories {
    // Other respositories...
    maven("https://maven.canvasmc.io/snapshots")
}

dependencies {
    // Other dependencies...
    paperweight.devBundle("io.canvasmc.canvas", "1.21.11-R0.1-SNAPSHOT")
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(21))
}

After completing all of the above steps, you will have successfully attached Minecraft internals to your project!