### Standard Paper Setup Configuration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Configure the plugin and add the Paper NMS dependency for a standard setup.

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

<!-- Add Paper NMS dependency -->
<dependency>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms</artifactId>
    <version>1.21.8-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>
```

--------------------------------

### init()

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Initializes the Paper-NMS environment by creating a Mojang-mapped Paper dependency and installing it into the local Maven repository. This method handles the core setup process, including directory creation, dev bundle download or manual mapping, and server JAR mapping.

```APIDOC
## init()

### Description
Initializes the paper-nms environment. Creates a Mojang-mapped Paper dependency and installs it to the local repository.

### Method
void

### Throws
- `MojoExecutionException` — if an unexpected error occurs
- `MojoFailureException` — if the initialization cannot proceed
```

--------------------------------

### Configure InitMojo in pom.xml

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/InitMojo.md

Example of how to configure the paper-nms-maven-plugin in your pom.xml to use the 'init' goal. This setup ensures the plugin is available for execution.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
</plugin>
```

--------------------------------

### Initialize Paper-NMS Environment

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Initializes the Paper-NMS environment by creating a Mojang-mapped Paper dependency and installing it to the local repository. This method handles the creation of cache directories, downloading dev bundles, mapping server JARs, and installing them.

```java
public void init() throws MojoExecutionException, MojoFailureException
```

--------------------------------

### Paper 1.20.5+ Setup (Mojang Mappings)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Configure the plugin for Paper 1.20.5+ using Mojang mappings without Spigot remapping. Includes manifest entry for paperweight detection.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <!-- No executions - no remapping needed -->
</plugin>

<!-- Also add this to manifest for paperweight detection -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.4.1</version>
    <configuration>
        <archive>
            <manifestEntries>
                <paperweight-mappings-namespace>mojang</paperweight-mappings-namespace>
            </manifestEntries>
        </archive>
    </configuration>
</plugin>
```

--------------------------------

### Install Mapped Server JAR to Maven Repository

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Installs the mapped server JAR to the local Maven repository with a generated POM file. This method is used to make the processed server JAR available as a Maven dependency.

```java
public void installToMavenRepo(String gameVersion, List<String> dependencyCoordinates, 
                              List<String> dependencyManagementCoordinates, Path mappedServerPath, 
                              Path pomPath) throws MojoExecutionException
```

--------------------------------

### Example Usage of DevBundle.Repository

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/types.md

Instantiates a Repository object with a specific ID and URL. This is useful for configuring custom Maven repositories.

```java
Repository repo = new Repository("papermc", "https://repo.papermc.io/repository/maven-public/");
```

--------------------------------

### Example Usage of DevBundle

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/types.md

Instantiates a DevBundle object with a custom ID, repository, and artifact. This allows for flexible configuration of development bundles.

```java
DevBundle bundle = new DevBundle(
    "custom-nms",
    new Repository("custom-repo", "https://repo.example.com/maven"),
    new Artifact("com.example", "dev-bundle", "${gameVersion}")
);
```

--------------------------------

### Checking Plugin Version Details

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

This command retrieves detailed information about the installed Paper NMS Maven Plugin.

```bash
mvn help:describe -Dplugin=ca.bkaw:paper-nms-maven-plugin -Ddetail
```

--------------------------------

### installToMavenRepo()

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Installs the mapped server JAR to the local Maven repository with a generated POM. This allows the server JAR to be managed as a Maven dependency.

```APIDOC
## installToMavenRepo()

### Description
Installs the mapped server JAR to the local Maven repository with a generated POM.

### Method
public void

### Parameters
#### Path Parameters
- **gameVersion** (String) - Required - The Minecraft version (used in artifact coordinates)
- **dependencyCoordinates** (List<String>) - Required - Runtime dependencies to include in POM
- **dependencyManagementCoordinates** (List<String>) - Required - Dependency management entries to include
- **mappedServerPath** (Path) - Required - Path to the mapped server JAR
- **pomPath** (Path) - Required - Where to write the generated POM before installation

### Throws
- `MojoExecutionException` — if POM generation or artifact installation fails
```

--------------------------------

### Example Usage of DevBundle.Artifact

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/types.md

Instantiates an Artifact object with Maven coordinates. The `${gameVersion}` placeholder is used for the version, which is replaced at runtime.

```java
Artifact artifact = new Artifact(
    "io.papermc.paper",
    "dev-bundle",
    "${gameVersion}"
);
```

--------------------------------

### Usage Example for isAlreadyRemapped

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/RemappedClasses.md

Demonstrates how to use the `isAlreadyRemapped` method to conditionally remap a class file. If the class has not been remapped or has changed, it proceeds with remapping and updates the tracking state.

```java
if (!remappedClasses.isAlreadyRemapped(classPath)) {
    // Remap this class
    Files.write(classPath, remappedBytes);
    remappedClasses.markAsRemappedNow(classPath);
}
```

--------------------------------

### Add Plugin Repository and Paper NMS Maven Plugin

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/README.md

Configure your pom.xml to include the necessary plugin repository and the paper-nms-maven-plugin. This setup is required for the plugin to function.

```xml
<pluginRepositories>
    ...
    <pluginRepository>
        <id>bytecode.space</id>
        <url>https://repo.bytecode.space/repository/maven-public/</url>
    </pluginRepository>
    ...
</pluginRepositories>

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

--------------------------------

### Default Paper Dev Bundle Configuration in POM

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/DevBundle.md

Example of how to configure the paper-nms-maven-plugin in pom.xml to use the default Paper dev bundle. No specific DevBundle configuration is needed.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <!-- No configuration - uses default Paper dev bundle -->
</plugin>
```

--------------------------------

### Paper NMS Dependency Configuration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/InitMojo.md

Example of how to declare the Paper NMS dependency in your pom.xml. This is typically required for projects using Paper NMS.

```xml
<dependency>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms</artifactId>
    <version>1.21.8-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>
```

--------------------------------

### Paper NMS Maven Plugin Configuration (No Remapping Needed)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/RemapMojo.md

Example XML configuration for the paper-nms-maven-plugin where the 'executions' section is omitted. This indicates that remapping is not required, typically for newer Paper versions (1.20.5+) that handle Mojang mappings natively.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <!-- No executions section - no remapping needed -->
</plugin>
```

--------------------------------

### Get Dev Bundle Repositories

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Retrieves the Maven repositories configured for searching the dev bundle. Returns an empty list if no custom repositories are set.

```java
public List<ArtifactRepository> getDevBundleRepositories() throws MojoExecutionException
```

--------------------------------

### Get Minecraft Game Version

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Extracts the Minecraft game version from project dependencies. Throws MojoFailureException if the NMS dependency is not found.

```java
public String getGameVersion() throws MojoFailureException
```

--------------------------------

### Get Cache Directory Path

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Retrieves the path to the cache directory, typically '.paper-nms', located in the project's parent or root.

```java
public Path getCacheDirectory()
```

--------------------------------

### RemappedClasses Constructor

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/RemappedClasses.md

Initializes a RemappedClasses tracker. It loads existing remapping state from a JSON file if it exists, or starts with an empty tracking map. The classesFolder path is used for relative path conversion.

```java
public RemappedClasses(Path jsonFile, Path classesFolder) throws IOException
```

--------------------------------

### Initialize Dev Bundle Configuration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Sets up the dev bundle configuration with default values if it's not already configured.

```java
public void createDevBundleConfiguration()
```

--------------------------------

### Initialize and Use RemappedClasses Tracker

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/RemappedClasses.md

Demonstrates how to create a RemappedClasses tracker, process classes for remapping, and save the tracker's state for subsequent builds. Ensure the cache directory and classes path are correctly configured.

```java
RemappedClasses remappedClasses = new RemappedClasses(
    cacheDirectory.resolve(RemappedClasses.FILE_NAME),
    classesPath
);

remapper.apply((name, bytes) -> {
    try {
        Path path = classesPath.resolve(name + ".class");
        if (!remappedClasses.isAlreadyRemapped(path)) {
            // Class needs remapping
            Files.write(path, bytes);
            remappedClasses.markAsRemappedNow(path);
        }
    } catch (IOException e) {
        throw new UncheckedIOException("Failed to write class " + name, e);
    }
});

remappedClasses.save();
```

--------------------------------

### Download File (Basic)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads a file from a given URL to a specified local path. Throws MojoExecutionException on failure.

```java
public void downloadFile(String url, Path path) throws MojoExecutionException
```

--------------------------------

### Run InitMojo Goal

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/InitMojo.md

Command to execute the 'init' goal of the paper-nms-maven-plugin from the command line. This triggers the initialization process.

```bash
mvn paper-nms:init
```

--------------------------------

### Manual Init Goal Execution

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Manually configure the 'init' goal to run during the 'initialize' phase. This is an alternative to using the default execution.

```xml
<execution>
    <phase>initialize</phase>
    <goals>
        <goal>init</goal>
    </goals>
</execution>
```

--------------------------------

### Get NMS Group ID

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Returns the Maven group ID for the NMS dependency, which varies based on the dev bundle configuration.

```java
public String getNmsGroupId()
```

--------------------------------

### Verifying Plugin Configuration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Run this command to check the plugin's remap goal while skipping tests, useful for configuration verification.

```bash
mvn paper-nms:remap -DskipTests
```

--------------------------------

### Plugin Declaration with Configuration and Executions

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Includes placeholders for both plugin configuration and execution phases within the pom.xml.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <configuration>
        <!-- Configuration options here -->
    </configuration>
    <executions>
        <!-- Execution phases here -->
    </executions>
</plugin>
```

--------------------------------

### File Organization Structure

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/OVERVIEW.md

Illustrates the directory structure of the paper-nms-maven-plugin project, including source code, Maven configuration, and documentation files.

```text
paper-nms-maven-plugin/
├── src/main/java/ca/bkaw/papernmsmavenplugin/
│   ├── InitMojo.java              (init goal entry point)
│   ├── RemapMojo.java             (remap goal entry point)
│   ├── MojoBase.java              (shared implementation)
│   ├── DevBundle.java             (configuration)
│   └── RemappedClasses.java       (incremental tracking)
├── pom.xml                         (Maven configuration)
└── README.md                       (User guide)
```

--------------------------------

### createDevBundleConfiguration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Initializes the dev bundle configuration with default values if it has not been set. This ensures that a default dev bundle is used if none is explicitly provided.

```APIDOC
## createDevBundleConfiguration()

### Description
Initializes the dev bundle configuration by setting the `devBundle` field to `DevBundle.PAPER_DEV_BUNDLE` if the field is currently null or its ID is null. This method ensures a default dev bundle is available if not explicitly configured.

### Method
public void createDevBundleConfiguration()

### Parameters
None

### Return Type
void
```

--------------------------------

### Custom Dev Bundle Configuration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/InitMojo.md

Optional configuration for the InitMojo to specify a custom dev bundle. This allows using a non-standard or locally hosted dev bundle artifact.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <configuration>
        <devBundle>
            <id>custom-nms</id>
            <repository>
                <id>custom-repo</id>
                <url>https://repo.example.com/maven</url>
            </repository>
            <artifact>
                <groupId>com.example</groupId>
                <artifactId>dev-bundle</artifactId>
                <version>${gameVersion}</version>
            </artifact>
        </devBundle>
    </configuration>
</plugin>
```

--------------------------------

### Init Goal Execution Configuration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Configure the 'init' goal to run during the 'initialize' phase, creating a Mojang-mapped Paper dependency. This can also be triggered manually via 'mvn paper-nms:init'.

```xml
<execution>
    <id>init</id>
    <phase>initialize</phase>
    <goals>
        <goal>init</goal>
    </goals>
</execution>
```

--------------------------------

### Custom Repository Configuration with URL

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Specify a custom Maven repository for downloading the dev bundle, including its ID and URL. Ensure the repository ID matches one in your project's <repositories> section.

```xml
<repository>
    <id>custom-repo</id>
    <url>https://repo.example.com/repository/maven-public/</url>
</repository>
```

--------------------------------

### resolveDevBundle(String gameVersion)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Attempts to resolve and download the development bundle for the specified Minecraft game version. Returns the path to the downloaded bundle if successful, otherwise returns null.

```APIDOC
## resolveDevBundle(String gameVersion)

### Description
Resolves and downloads the dev bundle for the specified game version.

### Method
Path | null

### Parameters
#### Path Parameters
- **gameVersion** (`String`) - The Minecraft version

### Return Type
`Path` | `null` — Path to the downloaded dev bundle, or null if not found

### Throws
- `MojoExecutionException` — if artifact resolution fails unexpectedly
```

--------------------------------

### Custom Dev Bundle Configuration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/OVERVIEW.md

Configure a custom development bundle for the paper-nms-maven-plugin, including repository and artifact details.

```xml
<configuration>
    <devBundle>
        <id>bundle-id</id>
        <repository>
            <id>repo-id</id>
            <url>https://repo.example.com</url>
        </repository>
        <artifact>
            <groupId>com.example</groupId>
            <artifactId>dev-bundle</artifactId>
            <version>${gameVersion}</version>
        </artifact>
    </devBundle>
</configuration>
```

--------------------------------

### Add Plugin Repository

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/OVERVIEW.md

Configure your Maven project to use the Bytecode Space repository for the paper-nms-maven-plugin.

```xml
<pluginRepositories>
    <pluginRepository>
        <id>bytecode.space</id>
        <url>https://repo.bytecode.space/repository/maven-public/</url>
    </pluginRepository>
</pluginRepositories>
```

--------------------------------

### Enabling Debug Logging

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Execute these commands with the -X flag to enable detailed debug logging for plugin goals.

```bash
mvn -X paper-nms:init
mvn -X paper-nms:remap
```

--------------------------------

### Catching MojoExecutionException in Java

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Demonstrates how to catch a MojoExecutionException, typically thrown for runtime errors like file I/O or network failures during plugin execution.

```java
try {
    mojoBase.downloadFile(url, path, expectedSha1);
} catch (MojoExecutionException e) {
    getLog().error("Download failed", e);
}
```

--------------------------------

### Download Spigot Mappings

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads Spigot class and member mappings from the Spigot build data repository for a given Minecraft version. Ensure the paths for saving the mappings are provided.

```java
public void downloadSpigotMappings(Path spigotClassMappingsPath, Path spigotMemberMappingsPath, 
                                   String gameVersion) throws MojoExecutionException
```

--------------------------------

### Custom Paper Fork with Existing Repository Reference

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Configure a custom Paper fork using a dev bundle, referencing an existing repository definition by ID. The repository URL is omitted as it's defined elsewhere.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <configuration>
        <devBundle>
            <id>my-fork-nms</id>
            <repository>
                <id>my-custom-repo</id>
                <!-- URL omitted - uses <repositories> definition -->
            </repository>
            <artifact>
                <groupId>com.example.fork</groupId>
                <artifactId>dev-bundle</artifactId>
                <version>${gameVersion}</version>
            </artifact>
        </devBundle>
    </configuration>
</plugin>

<!-- Repository defined once in <repositories> -->
<repositories>
    <repository>
        <id>my-custom-repo</id>
        <url>https://repo.example.com/maven</url>
    </repository>
</repositories>
```

--------------------------------

### downloadSpigotMappings

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads Spigot class and member mappings from the Spigot build data repository. It requires paths for saving the mappings and the Minecraft game version.

```APIDOC
## downloadSpigotMappings()

### Description
Downloads Spigot class and member mappings from the Spigot build data repository.

### Method
Not specified (likely Java method call)

### Parameters
#### Path Parameters
- **spigotClassMappingsPath** (`Path`) - Required - Where to save class mappings (CSRG format)
- **spigotMemberMappingsPath** (`Path`) - Required - Where to save member mappings (CSRG format)
- **gameVersion** (`String`) - Required - The Minecraft version

### Return Type
`void`

### Throws
- `MojoExecutionException` — if download fails

### Details
Member mappings may not exist for newer versions. If downloaded file is HTML (redirected to login), deletes the member mappings file.
```

--------------------------------

### Configure Custom Dev Bundle

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/DevBundle.md

Use this snippet to specify a custom dev bundle with its own repository. The artifact details and repository URL are explicitly defined.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <configuration>
        <devBundle>
            <id>custom-fork-nms</id>
            <repository>
                <id>custom-repo</id>
                <url>https://repo.example.com/maven</url>
            </repository>
            <artifact>
                <groupId>com.example.fork</groupId>
                <artifactId>dev-bundle</artifactId>
                <version>${gameVersion}</version>
                <!-- classifier is optional, null by default -->
            </artifact>
        </devBundle>
    </configuration>
</plugin>
```

--------------------------------

### Configure Paper NMS Maven Plugin to Use Mojang Mappings

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Configure the plugin to use Mojang mappings only when Spigot is not yet released or if Spigot support is not required. This prevents errors related to missing dev bundles.

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <configuration>
        <archive>
            <manifestEntries>
                <paperweight-mappings-namespace>mojang</paperweight-mappings-namespace>
            </manifestEntries>
        </archive>
    </configuration>
</plugin>
```

--------------------------------

### Remap Goal Execution Configuration (package)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Configure the 'remap' goal to run during the 'package' phase for remapping after JAR creation. This is an alternative to the default 'process-classes' phase.

```xml
<execution>
    <phase>package</phase>
    <goals>
        <goal>remap</goal>
    </goals>
</execution>
```

--------------------------------

### Configure Custom Dev Bundle for Paper Forks

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/README.md

Use this configuration to specify a custom dev bundle for NMS with Paper forks. The plugin downloads the dev bundle from the specified repository and generates the dependency.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>...</version>
    <executions>...</executions>
    <configuration>
        <devBundle>
            <!-- The artifact id of the resulting dependency -->
            <id>forktest-nms</id>
            <!-- The repository to download the dev-bundle from -->
            <repository>
                <id>myrepo</id>
                <url>https://repo.example.com/repository/maven-public/</url>
            </repository>
            <!-- The artifact to download -->
            <artifact>
                <groupId>com.example.paperfork</groupId>
                <artifactId>dev-bundle</artifactId>
                <version>${gameVersion}</version>
                <!-- ${gameVersion} will be replaced with the game version to use.
                     paper-nms-maven-plugin will take care of the '-R0.1-SNAPSHOT' suffix handling. -->
            </artifact>
        </devBundle>
    </configuration>
</plugin>
...
```

--------------------------------

### downloadFile (URL, Path, SHA1)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads a file from a URL to a specified path and validates its integrity using a SHA-1 hash. If the hash does not match, an exception is thrown.

```APIDOC
## downloadFile(String url, Path path, String sha1)

### Description
Downloads a file from the specified URL to the given destination path and performs a SHA-1 hash validation. After downloading, it computes the file's SHA-1 hash and compares it against the provided expected hash. If they do not match, a `MojoExecutionException` is thrown, detailing both the expected and computed hashes.

### Method
public void downloadFile(String url, Path path, String sha1) throws MojoExecutionException

### Parameters
#### Path Parameters
- **url** (String) - Required - The URL of the file to download.
- **path** (Path) - Required - The local file path where the downloaded file will be saved.
- **sha1** (String) - Required - The expected SHA-1 hash of the file in hexadecimal format.

### Return Type
void

### Throws
MojoExecutionException - If the download fails or if the computed SHA-1 hash does not match the expected hash.
```

--------------------------------

### downloadMojangMappings

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads Mojang mappings from the official launcher metadata. It requires a path to save the mappings and the Minecraft game version.

```APIDOC
## downloadMojangMappings()

### Description
Downloads Mojang mappings from the official launcher metadata.

### Method
Not specified (likely Java method call)

### Parameters
#### Path Parameters
- **mojangMappingsPath** (`Path`) - Required - Where to save the ProGuard format mappings
- **gameVersion** (`String`) - Required - The Minecraft version

### Return Type
`void`

### Throws
- `MojoExecutionException` — if download or JSON parsing fails
- `MojoFailureException` — if the game version is not found in the manifest

### Details
Fetches from https://launchermeta.mojang.com/mc/game/version_manifest_v2.json, then downloads server_mappings from the version-specific metadata.
```

--------------------------------

### downloadFile (URL, Path)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads a file from a given URL to a specified local path. This operation can throw an exception if the download process fails.

```APIDOC
## downloadFile(String url, Path path)

### Description
Downloads a file from the specified URL to the given destination path. This method is used for basic file downloads without integrity checks.

### Method
public void downloadFile(String url, Path path) throws MojoExecutionException

### Parameters
#### Path Parameters
- **url** (String) - Required - The URL of the file to download.
- **path** (Path) - Required - The local file path where the downloaded file will be saved.

### Return Type
void

### Throws
MojoExecutionException - If an error occurs during the download process.
```

--------------------------------

### RemappedClasses Constructor

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/RemappedClasses.md

Creates a RemappedClasses tracker, loading existing remapping state from disk if available. It initializes the tracker with paths to the JSON metadata file and the classes directory.

```APIDOC
## RemappedClasses(Path jsonFile, Path classesFolder)

### Description
Creates a RemappedClasses tracker, loading existing remapping state from disk if available. The classesFolder path is used to convert absolute class paths to relative paths for storage.

### Parameters
#### Path Parameters
- **jsonFile** (Path) - Required - Path to the JSON file storing remapping metadata (typically `.paper-nms/classes.json`)
- **classesFolder** (Path) - Required - Path to the target/classes directory containing compiled class files

### Return Type
`RemappedClasses` instance

### Throws
- `IOException` — if the JSON file cannot be read (only thrown if file exists; missing file is acceptable)
```

--------------------------------

### Set Java Version for Paper NMS Init

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Temporarily set the project's Java version to 21 (or a compatible version) in the pom.xml to resolve 'Failed to extract the server jar' errors. This is only required for the paper-nms:init goal.

```xml
<properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <!-- Temporary for init goal -->
</properties>
```

--------------------------------

### Custom Development Bundle Configuration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Configure a custom development bundle by specifying its repository and artifact coordinates. This replaces the default Paper dev bundle.

```xml
<devBundle>
    <id>custom-fork-nms</id>
    <repository>
        <id>custom-repo</id>
        <url>https://repo.example.com/maven</url>
    </repository>
    <artifact>
        <groupId>com.example.fork</groupId>
        <artifactId>dev-bundle</artifactId>
        <version>${gameVersion}</version>
        <classifier>optional</classifier>
    </artifact>
</devBundle>
```

--------------------------------

### Basic Plugin Declaration

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Declare the paper-nms-maven-plugin in your pom.xml. Configuration options are placed within the <configuration> element.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <!-- Configuration goes here -->
</plugin>
```

--------------------------------

### Recovering from File I/O Errors

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Use these commands to clear the cache and reinitialize the plugin when file I/O errors occur.

```bash
rm -rf .paper-nms
mvn clean
mvn paper-nms:init
```

--------------------------------

### Remap Goal Execution Configuration (process-classes)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Configure the 'remap' goal to run during the 'process-classes' phase for remapping classes after compilation, ensuring Spigot compatibility. This is the typical configuration.

```xml
<execution>
    <phase>process-classes</phase>
    <goals>
        <goal>remap</goal>
    </goals>
</execution>
```

--------------------------------

### Manually Run Remap Goal

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Manually trigger the remap goal using Maven commands if automatic execution is not configured or not running.

```bash
mvn process-classes
# or
mvn paper-nms:remap
```

--------------------------------

### MojoExecutionException: Download failed, sha1 hash mismatch

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Details the error message when a downloaded file's SHA1 hash does not match the expected value, indicating corruption or an incorrect file. This snippet shows the typical exception format.

```text
MojoExecutionException: Download failed, sha1 hash of downloaded file did not match. 
Expected: {expected} Found: {actual} for file {filename}
```

--------------------------------

### Reference Existing Repository for Dev Bundle

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/DevBundle.md

This snippet shows how to reference an existing repository by its ID. The plugin will look for the repository definition in your project's repositories, omitting the need to repeat the URL.

```xml
<plugin>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms-maven-plugin</artifactId>
    <version>1.4.11</version>
    <configuration>
        <devBundle>
            <id>my-fork-nms</id>
            <repository>
                <id>my-repo</id>
                <!-- URL omitted - uses the repository definition from <repositories> -->
            </repository>
            <artifact>
                <groupId>com.example</groupId>
                <artifactId>dev-bundle</artifactId>
                <version>${gameVersion}</version>
            </artifact>
        </devBundle>
    </configuration>
</plugin>

<!-- Repository definition referenced by ID -->
<repositories>
    <repository>
        <id>my-repo</id>
        <url>https://repo.example.com/maven</url>
    </repository>
</repositories>
```

--------------------------------

### Download File with SHA-1 Validation

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads a file and validates its integrity using a provided SHA-1 hash. Throws MojoExecutionException if the download fails or the hash does not match.

```java
public void downloadFile(String url, Path path, String sha1) throws MojoExecutionException
```

--------------------------------

### Configure Paper NMS Maven Plugin

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/OVERVIEW.md

Integrate the paper-nms-maven-plugin into your Maven project's build configuration.

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

--------------------------------

### Download Mojang Mappings

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads Mojang mappings in ProGuard format for a specific Minecraft version. It fetches data from Mojang's launcher metadata and saves the mappings to the specified path.

```java
public void downloadMojangMappings(Path mojangMappingsPath, String gameVersion) 
    throws MojoFailureException, MojoExecutionException
```

--------------------------------

### mapPaperJar()

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Maps a Paper server JAR from Spigot to Mojang mappings. This method is a convenience wrapper around `mapJar` for Paper JARs.

```APIDOC
## mapPaperJar()

### Description
Maps a Paper server JAR from Spigot to Mojang mappings.

### Method
public void

### Parameters
#### Path Parameters
- **mappingsPath** (Path) - Required - Path to spigot→mojang mappings
- **paperPath** (Path) - Required - Input Paper JAR
- **mappedPaperPath** (Path) - Required - Output Mojang-mapped Paper JAR

### Throws
- `MojoExecutionException` — if mapping fails
```

--------------------------------

### Execute Method Signature

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/InitMojo.md

The signature for the execute method of InitMojo. This is the entry point invoked by Maven when the 'init' goal is run.

```java
@Override
public void execute() throws MojoExecutionException, MojoFailureException
```

--------------------------------

### execute()

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/RemapMojo.md

Executes the remapping process for compiled classes or JAR artifacts. This is the entry point called by Maven to perform the remapping based on the plugin's configuration.

```APIDOC
## execute()

### Description
Executes the remapping process for compiled classes or JAR artifacts. This is the entry point called by Maven.

### Method
`execute()`

### Parameters
None

### Throws
- `MojoExecutionException` — if an unexpected error occurs during remapping
- `MojoFailureException` — if remapping fails due to configuration or compatibility issues
```

--------------------------------

### Remapped Classes JSON Format

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/RemappedClasses.md

Illustrates the JSON format used for storing remapping metadata. Keys are relative paths to class files, and values are their last-modified timestamps in milliseconds.

```json
{
  "com/example/MyClass.class": 1717358400000,
  "com/example/Helper.class": 1717358401500
}
```

--------------------------------

### Add .gitignore Entry for Cache Directory

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Add the .paper-nms directory to your .gitignore file to prevent caching artifacts from being committed.

```text
.paper-nms
```

--------------------------------

### extractDevBundle(Path paperclipPath, Path mappingsPath, Path devBundlePath, List<String> dependencyCoordinates, List<String> dependencyManagementCoordinates, String gameVersion)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Extracts necessary files and metadata from the development bundle ZIP archive. This method populates provided lists with runtime dependencies and dependency management entries, and handles different dev bundle data versions.

```APIDOC
## extractDevBundle(Path paperclipPath, Path mappingsPath, Path devBundlePath, List<String> dependencyCoordinates, List<String> dependencyManagementCoordinates, String gameVersion)

### Description
Extracts files and metadata from the dev bundle ZIP.

### Method
void

### Parameters
#### Path Parameters
- **paperclipPath** (`Path`) - Where to extract the mapped paperclip JAR
- **mappingsPath** (`Path`) - Where to extract the mappings
- **devBundlePath** (`Path`) - Path to the dev bundle ZIP file
- **dependencyCoordinates** (`List<String>`) - Mutable list populated with runtime dependencies
- **dependencyManagementCoordinates** (`List<String>`) - Mutable list populated with dependency management entries
- **gameVersion** (`String`) - The Minecraft game version

### Throws
- `MojoExecutionException` — if extraction fails
- `MojoFailureException` — if data version is unsupported
```

--------------------------------

### Referencing Existing Repository

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/configuration.md

Configure the dev bundle to use an existing Maven repository defined in your project's POM. The URL can be omitted if the repository ID is already declared.

```xml
<repository>
    <id>existing-repo-id</id>
    <!-- URL omitted - uses definition from <repositories> -->
</repository>
```

--------------------------------

### InitMojo Class Definition

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/InitMojo.md

Defines the InitMojo class, which extends MojoBase and is annotated to be a Maven plugin goal named 'init' that executes during the 'INITIALIZE' lifecycle phase.

```java
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;

@Mojo(name = "init", defaultPhase = LifecyclePhase.INITIALIZE)
public class InitMojo extends MojoBase {
    @Override
    public void execute() throws MojoExecutionException, MojoFailureException {
        // Actual execution logic is in MojoBase.init()
    }
}
```

--------------------------------

### Create Dev Bundle Artifact

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Constructs a Maven artifact object for the dev bundle, with coordinates derived from the dev bundle settings. Requires the Minecraft game version as input.

```java
public Artifact getDevBundleArtifact(CharSequence gameVersion)
```

--------------------------------

### DevBundle Parameterized Constructor

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/DevBundle.md

A constructor for DevBundle that accepts all necessary parameters for initialization. Use this to set the bundle identifier, repository, and artifact coordinates.

```java
public DevBundle(String id, Repository repository, Artifact artifact)
```

--------------------------------

### Map Paper Server JAR

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Maps a Paper server JAR from Spigot to Mojang mappings. This is a convenience wrapper around `mapJar` specifically for Paper JARs, including error handling for known conflicts.

```java
public void mapPaperJar(Path mappingsPath, Path paperPath, Path mappedPaperPath) 
    throws MojoExecutionException
```

--------------------------------

### mapJar()

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Remaps a JAR file using tiny-remapper. This is a core utility for transforming JAR contents based on provided mappings.

```APIDOC
## mapJar()

### Description
Remaps a JAR file using tiny-remapper.

### Method
public void

### Parameters
#### Path Parameters
- **in** (Path) - Required - Input JAR path
- **out** (Path) - Required - Output JAR path
- **mappingsPath** (Path) - Required - Path to tiny format mappings
- **mappingFrom** (String) - Required - Source mapping namespace
- **mappingTo** (String) - Required - Target mapping namespace
- **classPath** (Path...) - Optional - Variable arguments for classpath entries

### Throws
- `IOException` — if JAR processing fails
- `URISyntaxException` — if URI construction fails
```

--------------------------------

### Repository Parameterized Constructor

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/DevBundle.md

A constructor for the Repository class that takes the repository ID and URL as arguments. Use this to define a specific Maven repository.

```java
public Repository(String id, String url)
```

--------------------------------

### Exported Remap Goal

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/OVERVIEW.md

Command to remap compiled code from Mojang mappings to Spigot mappings.

```bash
mvn paper-nms:remap
```

--------------------------------

### getDevBundleRepositories()

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Retrieves the list of Maven repositories that will be searched for the development bundle. Returns an empty list if no custom repositories are configured.

```APIDOC
## getDevBundleRepositories()

### Description
Returns the Maven repositories to search for the dev bundle.

### Method
List<ArtifactRepository>

### Return Type
`List<ArtifactRepository>` — List of repositories, empty if no custom repository configured

### Throws
- `MojoExecutionException` — if a configured repository cannot be found
```

--------------------------------

### Repository Default Constructor

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/DevBundle.md

The no-argument constructor for the Repository class. Initializes a Repository object with default null values.

```java
public Repository()
```

--------------------------------

### downloadPaper

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads the latest Paper build for the specified game version. It requires the game version and a path to save the paperclip JAR.

```APIDOC
## downloadPaper()

### Description
Downloads the latest Paper build for the specified game version.

### Method
Not specified (likely Java method call)

### Parameters
#### Path Parameters
- **gameVersion** (`String`) - Required - The Minecraft version
- **paperclipPath** (`Path`) - Required - Where to save the paperclip JAR

### Return Type
`void`

### Throws
- `MojoExecutionException` — if API call or download fails

### Details
Fetches from https://api.papermc.io/v2/projects/paper/versions/{version}, finds the highest build number, and downloads that build.
```

--------------------------------

### getGameVersion

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Extracts and returns the Minecraft game version from the project's dependencies. It identifies the NMS dependency and derives the version, throwing an exception if the dependency is not found.

```APIDOC
## getGameVersion()

### Description
Extracts the Minecraft game version by searching for a dependency matching the NMS group ID and the dev bundle's artifact ID. It then removes the `-SNAPSHOT` suffix from the version string to provide a clean game version.

### Method
public String getGameVersion() throws MojoFailureException

### Parameters
None

### Return Type
String - The Minecraft game version (e.g., "1.21.8").

### Throws
MojoFailureException - If the NMS dependency cannot be found in the project.
```

--------------------------------

### DevBundle Default Constructor

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/DevBundle.md

Provides a no-argument constructor for the DevBundle class. Fields are initialized to null and require manual or Maven configuration.

```java
public DevBundle()
```

--------------------------------

### Catching MojoFailureException in Java

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Shows how to catch a MojoFailureException, which indicates a logical or configuration failure preventing plugin execution, such as missing required configuration.

```java
try {
    String version = mojoBase.getGameVersion();
} catch (MojoFailureException e) {
    getLog().error("Configuration error", e);
}
```

--------------------------------

### PAPER_DEV_BUNDLE Static Constant

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/DevBundle.md

Represents the default Paper development bundle. It is used when no custom dev bundle configuration is provided in the plugin settings.

```java
public static final DevBundle PAPER_DEV_BUNDLE
```

--------------------------------

### Maven Plugin Definition and Dependency

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/README.md

Defines the paper-nms-maven-plugin in the Maven build and specifies the necessary Paper NMS dependency. This is typically placed within the <build><plugins> section of your pom.xml.

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

<!-- Dependency -->
<dependency>
    <groupId>ca.bkaw</groupId>
    <artifactId>paper-nms</artifactId>
    <version>1.21.8-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>
```

--------------------------------

### MojoFailureException: Version not found

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Shows the error message when a specified Minecraft version cannot be found in the Mojang launcher manifest, often due to typos or unreleased versions. This snippet shows the typical exception format.

```text
MojoFailureException: The version "{version}" was not found.
```

--------------------------------

### Resolve Dev Bundle

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Resolves and downloads the dev bundle for a given Minecraft game version. Returns the path to the downloaded bundle or null if it's not found. Throws an exception if artifact resolution fails.

```java
@Nullable
public Path resolveDevBundle(String gameVersion) throws MojoExecutionException
```

--------------------------------

### Download Latest Paper JAR

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Downloads the latest Paper build for a specified Minecraft game version. The JAR will be saved to the provided path. This method fetches information from the PaperMC API.

```java
public void downloadPaper(String gameVersion, Path paperclipPath) throws MojoExecutionException
```

--------------------------------

### MojoExecutionException: Failed to download file

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

Represents the error message for a failed file download, often caused by network issues or an invalid URL. This snippet shows the typical exception format.

```text
MojoExecutionException: Failed to download {filename}
```

--------------------------------

### resolveGradleModuleMetadata(Artifact artifact)

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Resolves the Gradle module metadata file (.module) for a given artifact. Returns the path to the metadata file if found, otherwise returns null.

```APIDOC
## resolveGradleModuleMetadata(Artifact artifact)

### Description
Resolves Gradle module metadata (.module file) for an artifact.

### Method
Path | null

### Parameters
#### Path Parameters
- **artifact** (`Artifact`) - The artifact to find metadata for

### Return Type
`Path` | `null` — Path to the metadata file, or null if not found

### Throws
- `MojoExecutionException` — if repository lookup fails
```

--------------------------------

### save

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/RemappedClasses.md

Persists the current remapping state, including all tracked class files and their last-modified timestamps, to the designated JSON file on disk. This ensures the state is available for future incremental builds.

```APIDOC
## save()

### Description
Persists the remapping state to disk in JSON format. Writes all tracked class paths and their last-modified times to the JSON file. Paths are converted from absolute to relative (relative to the classes folder) for portability.

### Parameters
None

### Return Type
`void`

### Throws
- `IOException` — if the JSON file cannot be written

### JSON Format Example
```json
{
  "com/example/MyClass.class": 1717358400000,
  "com/example/Helper.class": 1717358401500
}
```
```

--------------------------------

### mergeMappings

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Merges Spigot and Mojang mappings to create bidirectional mappings. It takes input paths for Spigot and Mojang mappings and output paths for the merged mappings.

```APIDOC
## mergeMappings()

### Description
Merges Spigot and Mojang mappings to create bidirectional mappings.

### Method
Not specified (likely Java method call)

### Parameters
#### Path Parameters
- **spigotClassMappingsPath** (`Path`) - Required - Input Spigot class mappings (CSRG)
- **spigotMemberMappingsPath** (`Path`) - Required - Input Spigot member mappings (CSRG)
- **mojangMappingsPath** (`Path`) - Required - Input Mojang mappings (ProGuard)
- **outputPath** (`Path`) - Required - Output spigot→mojang mappings (Tiny)
- **outputMojangPath** (`Path`) - Required - Output mojang→obfuscated mappings (Tiny)
- **outputSpigotPath** (`Path`) - Required - Output obfuscated→spigot mappings (Tiny)

### Return Type
`void`

### Throws
- `MojoExecutionException` — if reading, writing, or fixing mappings fails

### Details
Reads mappings, reverses them, merges them, applies fixes, then writes in Tiny v2 format. Deletes input files after successful merge.
```

--------------------------------

### DevBundle.Repository Class Definition

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/types.md

Defines the structure for configuring a Maven repository. Use this to specify the ID and URL for a repository containing a dev bundle.

```java
public static class Repository {
    public String id;
    public String url;
    
    public Repository(String id, String url)
    public Repository()
}
```

--------------------------------

### Preventing Duplicate Key Error

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/errors.md

This command sequence helps prevent duplicate key errors by cleaning the cache before rebuilding.

```bash
cd .paper-nms
rm classes.json
cd ..
mvn clean package
```

--------------------------------

### Merge Spigot and Mojang Mappings

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

Merges Spigot and Mojang mappings to create bidirectional mappings in Tiny v2 format. This method requires paths for both input and output mapping files.

```java
public void mergeMappings(Path spigotClassMappingsPath, Path spigotMemberMappingsPath, 
                         Path mojangMappingsPath, Path outputPath, Path outputMojangPath, 
                         Path outputSpigotPath) throws MojoExecutionException
```

--------------------------------

### MojoBase Class Definition

Source: https://github.com/alvinn8/paper-nms-maven-plugin/blob/main/_autodocs/api-reference/MojoBase.md

The abstract base class for Maven Mojos, extending AbstractMojo and providing shared functionality.

```java
public abstract class MojoBase extends AbstractMojo
```