### Complete Paperweight Patcher Configuration Example

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-patcher-extension.md

A comprehensive example demonstrating the setup of the Paperweight Patcher plugin. It includes enabling Git file patches, patch filtering, and configuring multiple upstreams with specific patch directories.

```kotlin
plugins {
    id("io.papermc.paperweight.patcher") version "1.x.x"
}

paperweight {
    // Use standard unified diff format for patches
    gitFilePatches.set(false)
    
    // Filter patches to only modified files
    filterPatches.set(true)
    
    // Configure upstreams
    upstreams {
        // Quick setup for Paper upstream
        paper {
            ref.set("main")
            
            patchDir("server") {
                upstreamPath.set("paper-server")
                patchesDir.set(layout.projectDirectory.dir("patches/server"))
            }
            
            patchDir("api") {
                upstreamPath.set("paper-api")
                patchesDir.set(layout.projectDirectory.dir("patches/api"))
            }
        }
        
        // Custom upstream
        register("custom") {
            repo.set("https://github.com/custom/repo.git")
            ref.set("develop")
            
            patchDir("server") {
                upstreamPath.set("custom-server")
                patchesDir.set(layout.projectDirectory.dir("custom/patches"))
            }
        }
    }
}
```

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

### Complete Paperweight Userdev Dependencies Example

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev-dependencies-extension.md

Shows a comprehensive example of setting up plugins and dependencies for a Paperweight userdev project. Includes simple and custom Paper dev bundles, and Paper API declarations.

```kotlin
plugins {
    `java-library`
    id("io.papermc.paperweight.userdev") version "1.x.x"
}

dependencies {
    // Simple Paper dev bundle
    paperweight.paperDevBundle("1.20.1")
    
    // With custom configuration
    paperweight.paperDevBundle("1.20.1") {
        isTransitive = false
    }
    
    // Folia alternative
    // paperweight.foliaDevBundle("1.0")
    
    // Paper API
    compileOnly("io.papermc.paper:paper-api:1.20.1-R0.1-SNAPSHOT")
    
    // Testing
    testImplementation("junit:junit:4.13.2")
}
```

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

### Initial Setup: Download Dev Bundle

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev.md

Run this command the first time to download and decompress the development bundle, which includes Minecraft source and libraries.

```bash
# Run first time to download and decompress dev bundle
./gradlew compileJava
```

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

### Publishing with MOJANG_PRODUCTION

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/reobf-artifact-configuration.md

Example of publishing artifacts using the MOJANG_PRODUCTION configuration, including both the Mojang-mapped main artifact and the obfuscated reobf artifact.

```kotlin
publishing {
    publications {
        create<MavenPublication>("mavenJava") {
            // Automatically publishes myplugin-1.0.jar (Mojang-mapped)
            from(components["java"])
            
            // Also publish obfuscated version
            artifact(tasks.named("reobfJar")) {
                classifier = "reobf"
            }
        }
    }
}
```

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

### javaLauncher

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev-extension.md

Specifies the Java launcher to be used for the userdev setup pipeline, defaulting to the system's default Java launcher.

```APIDOC
## javaLauncher

### Description
Configures the Java launcher utilized by the userdev setup pipeline, such as tasks for decompilation. It defaults to the Java launcher detected from the system's Java toolchain.

### Type
`Property<JavaLauncher>`

### Default
System default Java launcher

### Usage
Override the default to specify a particular Java version for setup tasks, which can be crucial for compatibility with different Minecraft versions.

### Example
```kotlin
paperweight {
    javaLauncher.set(
        javaToolchains.launcherFor {
            languageVersion.set(JavaLanguageVersion.of(17))
        }
    )
}
```
```

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

### Configure a Spigot Fork

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/fork-config.md

Example of configuring a Spigot fork, setting the Minecraft version, upstream repository, and a specific patch directory for server modifications.

```kotlin
paperweight {
    minecraftVersion.set("1.20.1")
    
    forks {
        register("spigot") {
            upstream {
                repo.set("https://github.com/PaperMC/Spigot.git")
                ref.set("main")
                
                patchDir("server") {
                    upstreamPath.set("Spigot-Server")
                    patchesDir.set(layout.projectDirectory.dir("spigot-server/patches"))
                }
            }
        }
    }
}
```

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

### Example build.gradle.kts Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev.md

Configure your build.gradle.kts file to use the Paperweight Userdev plugin. This includes applying the plugin, specifying dependencies, and configuring Paperweight settings.

```kotlin
plugins {
    `java-library`
    id("io.papermc.paperweight.userdev") version "1.x.x"
}

dependencies {
    paperweight.paperDevBundle("1.20.1")
    
    compileOnly("io.papermc.paper:paper-api:1.20.1-R0.1-SNAPSHOT")
}

paperweight {
    injectPaperRepository.set(true)
    applyJunitExclusionRule.set(true)
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.MOJANG_PRODUCTION)
}

tasks.build {
    dependsOn("reobfJar")
}
```

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

### Full Upstream Configuration Example

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/upstream-config.md

Demonstrates a complete configuration for an upstream repository, including defining patch directories with their respective upstream paths, local patch locations, and exclusion patterns.

```kotlin
forks {
    register("spigot") {
        upstream {
            repo.set(github("PaperMC", "Spigot"))
            ref.set("main")
            
            patchDir("server") {
                upstreamPath.set("Spigot-Server")
                patchesDir.set(layout.projectDirectory.dir("spigot-server/patches"))
                excludes.add("*.gradle")
            }
            
            patchDir("api") {
                upstreamPath.set("Spigot-API")
                patchesDir.set(layout.projectDirectory.dir("spigot-api/patches"))
            }
        }
    }
}
```

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

### Publishing with REOBF_PRODUCTION

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/reobf-artifact-configuration.md

Example of publishing artifacts using the REOBF_PRODUCTION configuration, publishing the obfuscated JAR as the main artifact and a Mojang-mapped JAR as the dev artifact.

```kotlin
publishing {
    publications {
        create<MavenPublication>("mavenJava") {
            // Main artifact is obfuscated
            artifact(tasks.named("jar")) {
                // jar task is configured with classifier "obfuscated"
            }
            
            // Dev artifact for development
            artifact(tasks.named("jar")) {
                classifier = "dev"
            }
        }
    }
}
```

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

### PaperExtension Configuration Example

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paper-extension.md

This snippet shows how to configure the PaperExtension within a Gradle build script. It demonstrates setting the root directory, though other paths typically derive automatically.

```kotlin
paperweight {
    paper {
        // Customize root directory if not at project root
        rootDirectory.set(project.rootProject.layout.projectDirectory)
        
        // All other paths derive from rootDirectory and paperServerDir
        // No need to configure unless you have a custom structure
    }
}
```

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

### Configure Paperweight Patcher Plugin

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-patcher.md

Example of how to apply and configure the io.papermc.paperweight.patcher plugin in a build.gradle.kts file. This includes setting up upstream repositories and patch directories.

```kotlin
plugins {
    id("io.papermc.paperweight.patcher") version "1.x.x"
}

paperweight {
    upstreams {
        register("paper") {
            repo.set("https://github.com/PaperMC/Paper.git")
            ref.set("main")
            
            patchDir("server") {
                upstreamPath.set("paper-server")
                patchesDir.set(layout.projectDirectory.dir("patches/server"))
            }
        }
    }
}
```

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

### Configure Upstreams with PaperweightPatcher

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-patcher.md

Configure upstream repositories and patch directories using the paperweight extension. This example registers the 'paper' upstream.

```kotlin
paperweight {
    upstreams {
        register("paper") {
            repo.set("https://github.com/PaperMC/Paper.git")
            ref.set("main")
            
            patchDir("server") {
                patchesDir.set(layout.projectDirectory.dir("paper-server/patches"))
            }
        }
    }
}
```

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

### Custom ReobfArtifactConfiguration Implementation

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/reobf-artifact-configuration.md

Example of creating a custom ReobfArtifactConfiguration to define source JARs, output JAR paths, and classifiers for other JAR tasks.

```kotlin
val customConfig = ReobfArtifactConfiguration { project, reobfJar ->
    // Configure which jar task feeds into reobfJar
    val sourceJar = project.tasks.named<Jar>("sourcesJar")
    
    // Set reobfJar inputs
    reobfJar {
        inputJar.set(sourceJar.flatMap { it.archiveFile })
        outputJar.set(
            project.layout.buildDirectory.file(
                "libs/my-custom-reobf-${project.version}.jar"
            )
        )
    }
    
    // Optionally set classifiers on other jars
    project.tasks.named<Jar>("jar") {
        archiveClassifier.set("custom-dev")
    }
}

paperweight {
    reobfArtifactConfiguration.set(customConfig)
}
```

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

### Publish Paperweight to Maven Local

Source: https://github.com/papermc/paperweight/blob/main/readme.md

Installs the paperweight Gradle plugin to your local Maven repository. Ensure you have a local Maven repository set up.

```bash
./gradlew publishToMavenLocal
```

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

### Plugin Development Setup

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/README.md

Set up your project for plugin development using Paperweight. This snippet applies the userdev plugin and adds the Paper development bundle dependency.

```kotlin
plugins {
    id("io.papermc.paperweight.userdev") version "1.x.x"
}

dependencies {
    paperweight.paperDevBundle("1.20.1")
}
```

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

### Format Project with Ktlint

Source: https://github.com/papermc/paperweight/blob/main/readme.md

Applies the ktlint formatter to reformat the entire project according to the defined style guide. This task should be run before committing code.

```bash
./gradlew format
```

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

### Development-Focused Reobf Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/reobf-artifact-configuration.md

Use this configuration to publish Mojang-mapped artifacts for IDE use and obfuscated artifacts for runtime. This setup is ideal for a development environment.

```kotlin
paperweight {
    // Publish Mojang-mapped for IDE, obfuscated for runtime
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.MOJANG_PRODUCTION)
}

publishing {
    publications {
        create<MavenPublication>("dev") {
            from(components["java"])
        }
    }
}
```

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

### Configure Multiple Upstreams for Fork Chains

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

Set up Paperweight to manage multiple upstream repositories, allowing for the creation of forks of forks. This example demonstrates defining both the primary Paper upstream and a custom fork upstream with their respective patch directories.

```kotlin
paperweight {
    upstreams {
        // Define Paper (upstream)
        register("paper") {
            repo.set("https://github.com/PaperMC/Paper.git")
            ref.set("main")
            
            patchDir("server") {
                upstreamPath.set("paper-server")
                patchesDir.set(file("patches/paper-server"))
            }
        }
        
        // Fork of Paper
        register("custom") {
            repo.set("https://github.com/custom/fork.git")
            ref.set("main")
            
            patchDir("server") {
                upstreamPath.set("custom-server")
                patchesDir.set(file("patches/custom-server"))
            }
        }
    }
}
```

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

### Configure Java Launcher for UserDev Pipeline

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev-extension.md

Set the Java launcher for the userdev setup pipeline, such as decompilation. Defaults to the system default Java. Override to use a specific Java version.

```kotlin
val javaLauncher: Property<JavaLauncher>
```

```kotlin
paperweight {
    javaLauncher.set(
        javaToolchains.launcherFor {
            languageVersion.set(JavaLanguageVersion.of(17))
        }
    )
}
```

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

### Set Reobf Artifact Configuration in Build Script

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/reobf-artifact-configuration.md

Example of how to set the reobfArtifactConfiguration in a Gradle build script using the MOJANG_PRODUCTION preset.

```kotlin
paperweight {
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.MOJANG_PRODUCTION)
}
```

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

### Configure Upstreams

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-patcher-extension.md

Container of upstream configurations. Define one or more upstream projects (e.g., Paper, Spigot, custom forks). This example registers both 'paper' and 'spigot' upstreams.

```kotlin
paperweight {
    upstreams {
        register("paper") {
            repo.set("https://github.com/PaperMC/Paper.git")
            ref.set("main")
        }
        
        register("spigot") {
            repo.set("https://github.com/PaperMC/Spigot.git")
            ref.set("main")
        }
    }
}
```

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

### Using archivesName in ReobfArtifactConfiguration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/reobf-artifact-configuration.md

Example demonstrating the use of the archivesName helper method within a ReobfArtifactConfiguration to dynamically set the output JAR name.

```kotlin
val customConfig = ReobfArtifactConfiguration { project, reobfJar ->
    val baseName = archivesName(project)
    
    reobfJar {
        outputJar.set(
            project.layout.buildDirectory.file(
                baseName.map { "libs/$it-${project.version}.jar" }
            )
        )
    }
}
```

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

### Registering and Configuring RemapJar Task

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/remap-jar-task.md

Example of how to register and configure the RemapJar task in a Gradle build script. It specifies input and output JARs, namespaces, and dependencies for remapping.

```kotlin
tasks.register<RemapJar>("myRemapTask") {
    inputJar.set(file("build/libs/input.jar"))
    mappingsFile.set(file("mappings.tiny"))
    fromNamespace.set("intermediary")
    toNamespace.set("named")
    remapClasspath.from(configurations.named("minecraft"))
    remapper.from(configurations.named("remapper"))
    outputJar.set(file("build/libs/output.jar"))
}
```

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

### Download File with Hash Verification

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/download-service.md

Example of downloading a file using DownloadService, including optional SHA256 hash verification. Ensure the Hash object is correctly instantiated with the algorithm and expected hash value.

```kotlin
val service = project.download
val hash = Hash(HashAlgorithm.SHA256, "abc123...")

service.download(
    source = "https://launcher.mojang.com/v1/objects/வுகளை",
    target = project.layout.buildDirectory.file("downloads/file.jar"),
    hash = hash
)
```

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

### Configure RemapJar Task

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/errors.md

Example of configuring the `RemapJar` task in Gradle. Ensures input and output JAR paths are different to prevent overwriting the source file.

```gradle
reobfJar {
    inputJar.set(tasks.named("jar").flatMap { it.archiveFile })
    outputJar.set(layout.buildDirectory.file("libs/${archivesName}-reobf.jar"))
    // ✓ Correct: input and output differ
}
```

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

### Configure Java Launcher for Paperweight

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

If Paperweight runs out of memory during setup (decompilation or remapping), configure the Java launcher to use a higher memory limit. Alternatively, adjust JVM arguments for the `RemapJar` task.

```kotlin
paperweight {
    javaLauncher.set(
        javaToolchains.launcherFor {
            languageVersion.set(JavaLanguageVersion.of(17))
        }
    )
}

// Or adjust JVM args (for RemapJar):
tasks.named<RemapJar>("reobfJar") {
    jvmArgs.set(listOf("-Xmx4G"))  // Increase from default 1G
}
```

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

### Paperweight Dev Bundle Setup

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

Use these Gradle configurations to include Paperweight's development bundles in your project. Specify the Paper version or use version catalog references.

```kotlin
paperweight.paperDevBundle("1.20.1")
```

```kotlin
paperweight.foliaDevBundle("1.0")
```

```kotlin
paperweight.devBundle("com.example", "1.0")
```

```kotlin
paperweight.paperDevBundle(libs.versions.paperVersion)
```

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

### Minimal build.gradle.kts for Paperweight User Development

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

Configure your build.gradle.kts to use the paperweight-userdev plugin, add the Paper dev bundle, and specify the Paper API dependency. This setup provides access to Minecraft source code and Mojang-mapped names.

```kotlin
plugins {
    `java-library`
    id("io.papermc.paperweight.userdev") version "1.x.x"
}

dependencies {
    // Add Paper's dev bundle (Minecraft with Mojang mappings)
    paperweight.paperDevBundle("1.20.1")
    
    // Paper API for plugins
    compileOnly("io.papermc.paper:paper-api:1.20.1-R0.1-SNAPSHOT")
}

paperweight {
    // Use Mojang-mapped JAR as main artifact
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.MOJANG_PRODUCTION)
}
```

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

### Configure Paper Dev Bundle

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/errors.md

Example of how to add a Paperweight dev bundle dependency in Gradle. Ensure the Paper repository is configured and the specified version exists.

```gradle
dependencies {
    paperweight.paperDevBundle("1.20.1")
}
```

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

### Publish Plugin with Obfuscated and Development JARs

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

Configure Paperweight to publish both an obfuscated JAR for server use and a Mojang-mapped JAR for development. This setup ensures the main artifact is obfuscated, while a secondary artifact provides development mappings.

```kotlin
paperweight {
    // Obfuscated JAR is the main publication
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.REOBF_PRODUCTION)
}

publishing {
    repositories {
        maven("https://your-repo.com/repository/releases/")
    }
    
    publications {
        create<MavenPublication>("maven") {
            from(components["java"])
            
            // Main publication is obfuscated JAR
            // plugin-1.0.jar -> obfuscated (for server use)
            
            // Also publish development version
            artifact(tasks.named("jar")) {
                classifier = "dev"
                // plugin-1.0-dev.jar -> Mojang-mapped (for development)
            }
        }
    }
}
```

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

### Set Main Class

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-core-extension.md

Configure the main entry point class for the bundled server JAR. Defaults to org.bukkit.craftbukkit.Main.

```kotlin
paperweight {
    mainClass.set("org.bukkit.craftbukkit.Main")
}
```

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

### Register and Use Download Service in Plugin

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/download-service.md

Demonstrates how to register the DownloadService as a shared service and use it within a Gradle task to download a file with hash verification. Ensure the DownloadService and related types are available in your project.

```kotlin
class MyPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        target.gradle.sharedServices.registerIfAbsent(
            "myDownloadService",
            DownloadService::class
        ) {
            parameters.projectPath.set(target.projectDir)
        }
        
        target.tasks.register("downloadFile") {
            doLast {
                val service = target.download
                service.download(
                    "https://example.com/file.jar",
                    target.layout.buildDirectory.file("file.jar"),
                    Hash(HashAlgorithm.SHA256, "expected_hash_here")
                )
            }
        }
    }
}
```

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

### Minimal build.gradle.kts for Building Paper from Source

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

Use this minimal build.gradle.kts file when building Paper from source with the paperweight-core plugin. Ensure the minecraftVersion is set correctly.

```kotlin
plugins {
    `java-library`
    id("io.papermc.paperweight.core") version "1.x.x"
}

paperweight {
    minecraftVersion.set("1.20.1")
}
```

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

### Configure Vanilla JAR Includes

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-core-extension.md

Define glob patterns for classes to include from the vanilla Minecraft JAR. Defaults to common Paperweight inclusions.

```kotlin
paperweight {
    vanillaJarIncludes.set(listOf(
        "/*.class",
        "/net/minecraft/**",
        "/com/mojang/**"
    ))
}
```

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

### Server-Ready Reobf Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/reobf-artifact-configuration.md

Configure Paperweight to produce the main artifact required by servers. This ensures the output is correctly obfuscated for production server environments.

```kotlin
paperweight {
    // Main artifact is what the server needs
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.REOBF_PRODUCTION)
}

tasks.build {
    dependsOn("reobfJar")
}
```

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

### Download from Project-Relative File URL

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/download-service.md

Downloads a file using a path relative to the project root, prefixed with `file://project/`. The project root directory is automatically substituted.

```kotlin
// Project-relative file path
download(
    source = "file://project/build/libs/paper.jar",
    target = "build/libs/paper.jar"
)
```

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

### Complete Paperweight UserDev Plugin Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev-extension.md

This snippet shows a comprehensive Gradle build script configuration using the Paperweight UserDev plugin. It includes setting up Java library, applying the plugin, defining dependencies like Paper's dev bundle and API, and configuring Paperweight-specific options such as injecting the Paper repository, applying JUnit exclusion, setting the reobfuscation artifact configuration, and specifying the Java launcher version. It also demonstrates how to ensure the `reobfJar` task runs on build and how to create a custom task to check the Minecraft development version.

```kotlin
plugins {
    `java-library`
    id("io.papermc.paperweight.userdev") version "1.x.x"
}

group = "com.example"
version = "1.0"

dependencies {
    // Add Paper's dev bundle
    paperweight.paperDevBundle("1.20.1")
    
    // Paper API for plugins
    compileOnly("io.papermc.paper:paper-api:1.20.1-R0.1-SNAPSHOT")
    
    // Testing
    testImplementation("org.junit.jupiter:junit-jupiter:5.9.2")
}

paperweight {
    // Use Paper's maven repository for dev bundles
    injectPaperRepository.set(true)
    
    // Prevent junit conflicts with json-simple
    applyJunitExclusionRule.set(true)
    
    // Obfuscated JAR as the main production artifact
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.REOBF_PRODUCTION)
    
    // Use Java 17 for decompilation (if needed for newer Minecraft)
    javaLauncher.set(
        javaToolchains.launcherFor {
            languageVersion.set(JavaLanguageVersion.of(17))
        }
    )
}

tasks {
    // Ensure reobfJar runs on build
    build {
        dependsOn("reobfJar")
    }
    
    // Custom task to check Minecraft version
    register("checkMinecraft") {
        doLast {
            println("Development version: ${paperweight.minecraftVersion.get()}")
        }
    }
}
```

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

### Registering a Fork

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/fork-config.md

Demonstrates how to register a new fork configuration within the Paperweight extension.

```APIDOC
## Registering a Fork

Register a fork in `PaperweightCoreExtension.forks`:

```kotlin
paperweight {
    forks {
        register("myFork") {
            // ForkConfig properties
        }
    }
}
```

Access via name:

```kotlin
val myFork = paperweight.forks.named("myFork")
```
```

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

### Register Fork Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-core-extension.md

Create fork configurations for Paper forks like Spigot or Bukkit using the `forks` container.

```kotlin
paperweight {
    forks {
        register("spigot") {
            // fork configuration
        }
    }
}
```

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

### Manual Paperweight Development Bundle Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev-dependencies-extension.md

Demonstrates how to manually configure the paperweightDevelopmentBundle in a Gradle build script. Use this for custom configurations.

```kotlin
configurations {
    paperweightDevelopmentBundle {
        // Custom configuration if needed
    }
}
```

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

### Configure Paper Paths

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-core-extension.md

Set Paper-specific path configurations, such as the root directory and the paper-server directory.

```kotlin
paperweight {
    paper {
        rootDirectory.set(project.rootProject.layout.projectDirectory)
        paperServerDir.set(project.rootProject.layout.projectDirectory.dir("paper-server"))
    }
}
```

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

### Dual Publication Reobf Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/reobf-artifact-configuration.md

Set up dual publications for both server-ready (obfuscated) and development (Mojang-mapped) artifacts. This configuration allows for a single build to satisfy both runtime and IDE requirements.

```kotlin
paperweight {
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.REOBF_PRODUCTION)
}

publishing {
    publications {
        create<MavenPublication>("main") {
            from(components["java"])
            // Publishes obfuscated jar-1.0.jar
        }
        create<MavenPublication>("dev") {
            artifact(tasks.named("jar")) {
                classifier = "dev"
            }
            // Publishes jar-1.0-dev.jar
        }
    }
}
```

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

### Configure Server Dependency Configurations

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev-extension.md

Specify configurations to add the Minecraft server dependency to. Defaults to compileOnly and testImplementation. Useful for adding to other configurations like testRuntimeClasspath.

```kotlin
val addServerDependencyTo: SetProperty<Configuration>
```

```kotlin
paperweight {
    addServerDependencyTo.add(configurations.named("testRuntime"))
}
```

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

### Registering Upstream in ForkConfig

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/upstream-config.md

Demonstrates how to configure an upstream repository and reference within a fork registration in Paperweight Core.

```kotlin
forks {
    register("myFork") {
        upstream {
            repo.set("https://github.com/owner/repo.git")
            ref.set("main")
        }
    }
}
```

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

### JVM Arguments for Remapping

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/remap-jar-task.md

Configures JVM arguments passed to the tiny-remapper subprocess. The default allocates 1GB of heap memory. Increase this for large JAR files.

```kotlin
@get:Internal
abstract val jvmArgs: ListProperty<String>
```

```kotlin
jvmArgs.set(listOf("-Xmx4G", "-XX:+UseG1GC"))
```

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

### Configure IDE and Git Hook for Ktlint

Source: https://github.com/papermc/paperweight/blob/main/readme.md

Applies ktlint style settings to your IDE and sets up a git pre-commit hook to automatically format code before each commit. Recommended for consistent code style.

```bash
./gradlew ktlintApplyToIdea addKtlintFormatGitPreCommitHook
```

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

### DownloadService Parameters Interface

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/download-service.md

Defines the parameters for the DownloadService, including the project path for file://project URLs.

```kotlin
interface Params : BuildServiceParameters {
    val projectPath: DirectoryProperty
}
```

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

### Common Gradle Tasks for Building Paper

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

These are common Gradle tasks for building a Paper server JAR, creating a distribution JAR, and cleaning the build cache.

```bash
./gradlew build              # Build Paper server JAR
./gradlew paperclipJar       # Create distribution JAR
./gradlew cleanCache         # Clear build cache
```

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

### Common Gradle Tasks for Paperweight Development

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

Execute these Gradle tasks to compile your plugin with Minecraft sources, build the plugin JAR, generate an obfuscated distribution JAR, and manage local caches.

```bash
./gradlew compileJava       # Compile with Minecraft sources
./gradlew build             # Build plugin JAR
./gradlew reobfJar          # Create obfuscated distribution JAR
./gradlew cleanCache        # Clear local cache
./gradlew cleanAllPaperweightUserdevCaches  # Clear all caches
```

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

### Configure Paperweight Core Extension

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-core-extension.md

Use this block in your build.gradle.kts to configure the PaperweightCore plugin. Set the Minecraft version to be built.

```kotlin
paperweight {
    minecraftVersion.set("1.20.1")
    // ... other properties
}
```

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

### Construct GitHub URL

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/upstream-config.md

Use the `github` convenience method to generate a GitHub repository URL.

```kotlin
fun github(owner: String, repo: String): String = "https://github.com/$owner/$repo.git"
```

```kotlin
upstream {
    repo.set(github("PaperMC", "Paper"))
}
```

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

### Download from Absolute File URL

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/download-service.md

Downloads a file using an absolute path specified in a file URL. Ensure the path is correct and accessible.

```kotlin
// Absolute file path
download(
    source = "file:///tmp/file.jar",
    target = "build/libs/file.jar"
)
```

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

### Build PaperweightCore

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/README.md

Use this snippet to configure your project to build PaperweightCore. Specify the desired Minecraft version.

```kotlin
plugins {
    id("io.papermc.paperweight.core") version "1.x.x"
}

paperweight {
    minecraftVersion.set("1.20.1")
}
```

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

### Testing: Run Tests

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev.md

Executes tests using a Mojang-mapped Minecraft server. Ensure your tests are configured to run with the correct mappings.

```bash
# Run tests with Mojang-mapped Minecraft server
./gradlew test
```

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

### Download Method

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/download-service.md

Downloads a file from a specified source to a target location, with optional hash verification. This method is managed by Gradle and should be accessed via the injected service instance.

```APIDOC
## download(source: Any, target: Any, hash: Hash? = null)

### Description
Download a file from source to target location with optional hash verification.

### Method Signature
`fun download(source: Any, target: Any, hash: Hash? = null)`

### Parameters
#### Path Parameters
- **source** (Any) - Required - Source URL or path (String, URL, or File)
- **target** (Any) - Required - Target file location (String, Path, or File)
- **hash** (Hash) - Optional - Expected file hash for verification

### Behavior
- Downloads from HTTP/HTTPS with 5-minute timeouts
- Supports If-Modified-Since and ETag headers for conditional downloads
- Verifies file hash if provided
- Retries once if hash validation fails
- Handles file:// and file://project:// URLs
- Caches ETags locally for efficient updates

### Throws
- `PaperweightException` if download fails after retries or hash validation fails

### Example
```kotlin
val service = project.download
val hash = Hash(HashAlgorithm.SHA256, "abc123...")

service.download(
    source = "https://launcher.mojang.com/v1/objects/...",
    target = project.layout.buildDirectory.file("downloads/file.jar"),
    hash = hash
)
```
```

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

### Add Dev Bundle from Version Catalog Provider

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev-dependencies-extension.md

This snippet shows how to add a development bundle dependency using a provider from your version catalog, typically defined in libs.versions.toml.

```kotlin
// With libs.versions.toml:
// [libraries]
// paperDevBundle = "io.papermc.paper:dev-bundle:1.20.1"

dependencies {
    paperweight.devBundle(libs.paperDevBundle)
}
```

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

### github(owner: String, repo: String): String

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/upstream-config.md

Convenience method to construct GitHub URLs for repositories.

```APIDOC
## github(owner: String, repo: String): String

### Description
Convenience method to construct GitHub URLs.

### Parameters
#### Path Parameters
- **owner** (String) - Required - GitHub organization or user
- **repo** (String) - Required - Repository name

### Returns
Fully-formed GitHub clone URL
```

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

### Generated Documentation Directory Structure

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/INDEX.md

This snippet shows the expected directory structure for generated documentation files within the Paperweight project. It includes the main index file, reference documents for types, configuration, and errors, as well as API reference files.

```text
output/
├── INDEX.md                    # This file
├── types.md                    # Type reference
├── configuration.md            # Configuration reference
├── errors.md                   # Error reference
└── api-reference/
    ├── paperweight-core.md
    ├── paperweight-core-extension.md
    ├── paper-extension.md
    ├── fork-config.md
    ├── upstream-config.md
    ├── paperweight-patcher.md
    ├── paperweight-patcher-extension.md
    ├── paperweight-userdev.md
    ├── paperweight-userdev-extension.md
    ├── paperweight-userdev-dependencies-extension.md
    ├── download-service.md
    ├── remap-jar-task.md
    └── reobf-artifact-configuration.md
```

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

### Registering Upstream in PatcherExtension

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/upstream-config.md

Shows how to register an upstream configuration, like 'paper', within the Paperweight Patcher Extension.

```kotlin
upstreams {
    register("paper") {
        repo.set("https://github.com/PaperMC/Paper.git")
        ref.set("main")
    }
}
```

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

### Minimal build.gradle.kts for Custom Paper Fork

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

This minimal build.gradle.kts configures the paperweight-patcher plugin for creating a custom Paper fork. It specifies the upstream repository and reference, and the directory for patches.

```kotlin
plugins {
    `java-library`
    id("io.papermc.paperweight.patcher") version "1.x.x"
}

paperweight {
    upstreams {
        register("paper") {
            repo.set("https://github.com/PaperMC/Paper.git")
            ref.set("main")
            
            patchDir("server") {
                upstreamPath.set("paper-server")
                patchesDir.set(file("patches/server"))
            }
        }
    }
}
```

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

### Enable Git File Patches

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-patcher-extension.md

When `true`, patches are stored in unified diff format (Git-style). When `false`, uses custom Paperweight patch format. Use this to configure the patch format.

```kotlin
paperweight {
    gitFilePatches.set(true)
}
```

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

### Configure PaperweightCore Extension

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-core.md

Configure the PaperweightCore plugin by setting essential properties like the Minecraft version, main class, and the bundler JAR name within the `paperweight` extension block.

```kotlin
paperweight {
    minecraftVersion.set("1.20.1")
    mainClass.set("org.bukkit.craftbukkit.Main")
    bundlerJarName.set("paper")
}
```

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

### Create Paper Forks

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/README.md

Configure your project to create Paper forks by specifying upstream repositories and references. This snippet registers the 'paper' upstream.

```kotlin
plugins {
    id("io.papermc.paperweight.patcher") version "1.x.x"
}

paperweight {
    upstreams {
        register("paper") {
            repo.set("https://github.com/PaperMC/Paper.git")
            ref.set("main")
        }
    }
}
```

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

### Download from HTTP/HTTPS URL

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/download-service.md

Use this snippet to download files from HTTP or HTTPS URLs. It supports connection pooling, proxies via system properties, a 5-minute timeout, and automatic retries for transient failures.

```kotlin
download(
    source = "https://repo.papermc.io/repository/maven-public/io/papermc/paper/1.20.1/paper-1.20.1.jar",
    target = "build/libs/paper.jar"
)
```

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

### Configure PaperweightCore Plugin

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/configuration.md

Configure the PaperweightCore plugin in your `build.gradle.kts` file. Set the Minecraft version and main class for your project.

```kotlin
plugins {
    id("io.papermc.paperweight.core") version "1.x.x"
}

paperweight {
    minecraftVersion.set("1.20.1")
    mainClass.set("org.bukkit.craftbukkit.Main")
    // ... other options
}
```

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

### Configure Paperweight Patcher

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/configuration.md

Configure the Paperweight Patcher extension in your `build.gradle.kts` file. Set properties like `gitFilePatches` and `filterPatches`, and define upstreams.

```kotlin
plugins {
    id("io.papermc.paperweight.patcher") version "1.x.x"
}

paperweight {
    gitFilePatches.set(false)
    filterPatches.set(true)
    
    upstreams {
        register("paper") {
            repo.set("https://github.com/PaperMC/Paper.git")
            ref.set("main")
        }
    }
}
```

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

### Configure RemapJar Task for Paperweight

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/QUICK_START.md

If the `RemapJar` task fails, ensure `remapClasspath` includes all dependencies and that the mappings file is in the correct format with valid namespaces. Specify the `fromNamespace` and `toNamespace` if necessary.

```kotlin
tasks.named<RemapJar>("reobfJar") {
    // Ensure all transitive dependencies are included
    remapClasspath.from(
        configurations.named("runtimeClasspath"),
        configurations.named("compileClasspath")
    )
    
    // Verify mappings file exists
    mappingsFile.set(file("mappings.tiny"))
    
    // Check namespace names match mappings file
    fromNamespace.set("named")
    toNamespace.set("obfuscated")
}
```

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

### Add Paperweight Dev Bundles to Dependencies

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev.md

Use the dependencies helper to add Paperweight development bundles for specific Minecraft versions. This allows access to Paper's development environment.

```kotlin
dependencies {
    paperweight.paperDevBundle("1.20.1")
    // or
    paperweight.foliaDevBundle("1.0")
}
```

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

### DirectoryPatchSet Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/upstream-config.md

Defines the configuration for applying multiple patches within a directory. Use this for managing patches across a directory structure.

```kotlin
abstract class DirectoryPatchSet : Named {
    override fun getName(): String = setName
    abstract val upstreamPath: Property<String>
    abstract val excludes: SetProperty<String>
    abstract val outputDir: DirectoryProperty
    abstract val patchesDir: DirectoryProperty
    val rejectsDir: DirectoryProperty
    val filePatchDir: DirectoryProperty
    val featurePatchDir: DirectoryProperty
}
```

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

### Development: Build Plugin JAR

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev.md

Builds the plugin JAR with full Minecraft source access and Mojang names. The `compileJava` task automatically uses the Mojang-mapped server.

```bash
# Code with full Minecraft source access and Mojang names
# compileJava uses Mojang-mapped server automatically

# Build plugin JAR (Mojang-mapped)
./gradlew build
```

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

### Configure Paperweight Userdev

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/configuration.md

Configure the Paperweight Userdev extension in your `build.gradle.kts` file. Options include injecting the Paper repository, applying JUnit exclusion rules, and setting the reobfuscation artifact configuration.

```kotlin
plugins {
    id("io.papermc.paperweight.userdev") version "1.x.x"
}

paperweight {
    injectPaperRepository.set(true)
    applyJunitExclusionRule.set(true)
    reobfArtifactConfiguration.set(ReobfArtifactConfiguration.MOJANG_PRODUCTION)
}
```

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

### Register a Custom Fork Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/configuration.md

Register a custom fork configuration named 'myFork' within the `paperweight` extension. Specify the Git repository and reference for the fork.

```kotlin
paperweight {
    forks {
        register("myFork") {
            upstream {
                repo.set("https://github.com/owner/repo.git")
                ref.set("main")
            }
        }
    }
}
```

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

### Configure Paper Repository Injection

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev-extension.md

Set whether to automatically inject the Paper maven repository. Defaults to true, enabling resolution of Paper development bundles without manual configuration.

```kotlin
val injectPaperRepository: Property<Boolean>
```

```kotlin
paperweight {
    injectPaperRepository.set(true)
}
```

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

### PaperweightCoreExtension Configuration

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-core-extension.md

The PaperweightCoreExtension provides several properties to configure the build process. These include setting the Minecraft version, specifying the manifest URL, defining the main class, naming the bundled JAR, setting the Mache repository, controlling Git file patches and patch filtering, and including specific classes from the vanilla JAR.

```APIDOC
## PaperweightCoreExtension Properties

### minecraftVersion

**Description**: The Minecraft version to build (e.g., "1.20.1"). This property is required.

**Type**: `Property<String>`

**Example**:
```kotlin
paperweight {
    minecraftVersion.set("1.20.1")
}
```

### minecraftManifestUrl

**Description**: URL to Minecraft version manifest. Override to use a custom manifest source.

**Type**: `Property<String>`

**Default**: `https://launcher.mojang.com/v1/objects/35139deedbd5182953cf128461496bec1d88f13a/version_manifest.json`

### mainClass

**Description**: Main entry point class for the bundled server JAR.

**Type**: `Property<String>`

**Default**: `org.bukkit.craftbukkit.Main`

**Example**:
```kotlin
paperweight {
    mainClass.set("org.bukkit.craftbukkit.Main")
}
```

### bundlerJarName

**Description**: Name used for the bundled Paperclip JAR file.

**Type**: `Property<String>`

**Default**: `paper`

### macheRepo

**Description**: Maven repository URL for Mache artifacts.

**Type**: `Property<String>`

**Default**: `https://repo.papermc.io/repository/maven-public/`

### gitFilePatches

**Description**: Whether to use Git format for file patches instead of unified diff.

**Type**: `Property<Boolean>`

**Default**: `false`

### filterPatches

**Description**: Whether to filter patches to only include changed files.

**Type**: `Property<Boolean>`

**Default**: `true`

### vanillaJarIncludes

**Description**: Glob patterns for classes to include from vanilla Minecraft JAR.

**Type**: `ListProperty<String>`

**Default**: `["/*.class", "/net/minecraft/**", "/com/mojang/math/**"]`

**Example**:
```kotlin
paperweight {
    vanillaJarIncludes.set(listOf(
        "/*.class",
        "/net/minecraft/**",
        "/com/mojang/**"
    ))
}
```

### paper

**Description**: Paper-specific path configuration. Configure Paper paths using the `paper` block.

**Type**: `PaperExtension`

**Example**:
```kotlin
paperweight {
    paper {
        rootDirectory.set(project.rootProject.layout.projectDirectory)
        paperServerDir.set(project.rootProject.layout.projectDirectory.dir("paper-server"))
    }
}
```

### forks

**Description**: Container for Fork configurations. Create fork configurations for Paper forks (e.g., Spigot, Bukkit).

**Type**: `NamedDomainObjectContainer<ForkConfig>`

**Example**:
```kotlin
paperweight {
    forks {
        register("spigot") {
            // fork configuration
        }
    }
}
```

### activeFork

**Description**: The currently active fork configuration.

**Type**: `Property<ForkConfig>`

### updatingMinecraft

**Description**: Configuration for Minecraft version updates. Configure when updating Minecraft versions.

**Type**: `UpdatingMinecraftExtension`

**Example**:
```kotlin
paperweight {
    updatingMinecraft {
        oldPaperCommit.set("abc123def456")
    }
}
```
```

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

### Configure PaperweightUser Extension

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-userdev.md

Configure the PaperweightUser extension to customize plugin behavior, such as injecting the Paper repository and applying JUnit exclusion rules.

```kotlin
paperweight {
    injectPaperRepository.set(true)
    applyJunitExclusionRule.set(true)
}
```

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

### Run Apply All Patches Task

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-patcher.md

Execute the `applyAllPatches` Gradle task to apply patches from both the patcher project and the downstream project. This is equivalent to running `apply<Upstream>Patches` and then re-invoking Gradle.

```bash
./gradlew applyAllPatches
```

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

### Clean Caches and Rebuild with Gradle

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/errors.md

When significant dependency or configuration changes occur, clean the Gradle cache and rebuild the project. This helps resolve issues caused by stale cache data.

```bash
./gradlew cleanCache
./gradlew build
```

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

### Register Paper Upstream with Patch Directories

Source: https://github.com/papermc/paperweight/blob/main/_autodocs/api-reference/paperweight-patcher-extension.md

Convenience method to register the 'paper' upstream with proper defaults. Automatically sets the repository URL and allows configuring patch directories for different modules like 'server' and 'api'.

```kotlin
paperweight {
    upstreams {
        paper {
            ref.set("main")
            
            patchDir("server") {
                upstreamPath.set("paper-server")
                patchesDir.set(layout.projectDirectory.dir("patches/server"))
            }
        }
    }
}
```