DOCSEARCHbyAlgolia
Submit Docs

paper-nms-maven-plugin

repository·main·Indexed 41 days ago

https://github.com/alvinn8/paper-nms-maven-plugin

A Maven plugin for using Paper NMS (Net Minecraft Server) code with Mojang mappings. It automates the creation of mapped dependencies and provides remapping capabilities to support Spigot or older Paper versions. Features include support for custom dev bundles with Paper forks and specific remapping strategies for shaded NMS modules.

Tokens
1.7K
Snippets
3
Records
5
Agent score
1%

What's inside paper-nms-maven-plugin

  1. Configure remapping for NMS modules that depend on each other

    main

    If you have multiple NMS modules that depend on each other and will be shaded into a single JAR (and you are using remapping), you must change the remapping strategy to avoid issues with shaded dependencies.

    Scenario: Module api uses NMS and provides interfaces. Module plugin implements these and shades api.

    Required Configuration:

    1. In the api module: Remove the <executions> block from the paper-nms-maven-plugin configuration so it does not attempt to remap the individual module.
    2. In the plugin module:
      • Change the remap goal to run during the package phase (instead of process-classes).
      • Ensure the paper-nms-maven-plugin is positioned after the maven-shade-plugin in your <plugins> list.

    This ensures the plugin remaps the final shaded JAR file, including all shaded NMS dependencies.

  2. Install the paper-nms-maven-plugin

    main

    To use Mojang mappings with Paper in a Maven project, follow these steps:

    1. Add .paper-nms to your .gitignore.
    2. Add the bytecode.space plugin repository to your pom.xml.
    3. Add the paper-nms-maven-plugin to your <build><plugins> section.
    4. Add the ca.bkaw:paper-nms dependency to your <dependencies> section with provided scope.
    5. Reload your Maven project (you will see a Cannot resolve ca.bkaw:paper-nms:version error initially).
    6. Run the paper-nms:init goal to generate the missing dependency.

    Dependency Versioning Patterns:

    • Snapshot: Use 1.21.8-R0.1-SNAPSHOT.
    • Specific Build: Use 26.1.2.build.70-stable.
    • Latest build for a specific version: Use a range like [26.1.2.build.1, 26.1.2.build.9999).
    • Latest build of any version (not recommended): Use [26.1.2,).
    <!-- 1. Add Plugin Repository -->
<pluginRepositories>
    <pluginRepository>
        <id>bytecode.space</id>
        <url>https://repo.bytecode.space/repository/maven-public/</url>
    </pluginRepository>
</pluginRepositories>

<!-- 2. Add Plugin -->
<build>
    <plugins>
        <plugin>
            <groupId>ca.bkaw</groupId>
            <artifactId>paper-nms-maven-plugin</artifactId>
            <version>1.5</version>
        </plugin>
    </plugins>
</build>

<!-- 3. Add Dependency -->
<dependencies>
    <dependency>
        <groupId>ca.bkaw</groupId>
        <artifactId>paper-nms</artifactId>
        <version>[26.1.2.build.1, 26.1.2.build.9999)</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

  3. Remap to Spigot mappings for older versions or Spigot support

    main

    By default, the plugin provides Mojang mappings. If you are targeting versions before Paper 1.20.5, or if you are using 1.21 but need to support Spigot servers, you must configure the plugin to remap your artifact back to Spigot mappings.

    To do this, add an execution to the paper-nms-maven-plugin that binds the remap goal to the process-classes phase.

    <plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.5</version>
    <executions>
        <execution>
            <phase>process-classes</phase>
            <goals>
                <goal>remap</goal>
            </goals>
        </execution>
    </executions>
</plugin>

  4. Use custom dev bundles with Paper forks

    main

    To use NMS with a Paper fork, you can configure a custom devBundle. This allows the plugin to download a specific dev-bundle artifact and generate a dependency for it.

    Key Requirements:

    • The resulting dependency will use the group ID ca.bkaw.nms instead of ca.bkaw.
    • The <id> in the <devBundle> configuration must match the <artifactId> used in your <dependencies>.
    • You must run paper-nms:init after configuration.

    Configuration Details:

    • <devBundle><id>: The artifact ID of the resulting dependency.
    • <devBundle><repository>: The repository to download the bundle from. If the repository is already defined in your project's <repositories> section, you can omit the <url> and just provide the <id>.
    • <devBundle><artifact>: The actual artifact to download (contains groupId and artifactId).
    <plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>...</version>
    <executions>...</executions>
    <configuration>
        <devBundle>
            <id>forktest-nms</id>
            <repository>
                <id>myrepo</id>
                <url>https://repo.example.com/repository/maven-public/</url>
            </repository>
            <artifact>
                <groupId>com.example.paperfork</groupId>
                <artifactId>dev-bundle</artifactId>
            </artifact>
        </devBundle>
    </configuration>
</plugin>

<dependencies>
    <dependency>
        <groupId>ca.bkaw.nms</groupId>
        <artifactId>forktest-nms</artifactId>
        <version>[26.1.2.build.1, 26.1.2.build.9999)</version>
        <scope>provided</scope>
    </dependency>
</dependencies>