# Spigradle

Spigradle is an intelligent Gradle plugin designed to streamline the development of Minecraft server plugins for Spigot, Paper, Purpur, Bungeecord, and NukkitX platforms. It automates the generation of plugin descriptor files (plugin.yml, bungee.yml, nukkit.yml), provides automatic main class detection using ASM bytecode analysis, and offers convenient shortcuts for managing dependencies and repositories commonly used in Minecraft plugin development.

The plugin provides a comprehensive development workflow including local debugging capabilities with automatic server downloads, plugin dependency management, and IDE integration for IntelliJ IDEA. It supports both Groovy and Kotlin DSL configurations, making it accessible to developers using either Gradle scripting language. The plugin requires Gradle 8.0+ and Java 17, and is built using Kotlin 2.0.21, leveraging ASM 9.9 for bytecode analysis to detect main plugin classes automatically.

## APIs and Key Functions

### Plugin Application - Spigot Plugin

Apply the Spigradle plugin to enable Spigot/Paper plugin development features including plugin.yml generation and debug capabilities.

```groovy
plugins {
    id 'java'
    id 'io.typst.spigradle' version '3.7.3'
}

group 'org.sample'
version '1.0.0'

repositories {
    mavenCentral()
    spigotmc()
    papermc()
}

dependencies {
    compileOnly paper('1.21.8')
}

spigot {
    depends 'ProtocolLib'
    softDepends 'Vault'
    apiVersion '1.21'
    commands {
        register('mycmd') {
            aliases 'cmd', 'mycommand'
            description 'My custom command'
            permission 'myplugin.command'
            usage '/<command> [args]'
        }
    }
}

debugSpigot {
    version.set("1.21.8")
    eula.set(true)
}
```

### Plugin Application - Bungeecord Plugin

Apply the Bungeecord variant for developing BungeeCord proxy plugins with bungee.yml generation.

```groovy
plugins {
    id 'java'
    id 'io.typst.spigradle.bungee' version '3.7.3'
}

group 'org.example'
version '1.0.0'

repositories {
    mavenCentral()
    sonatype()
}

dependencies {
    compileOnly bungeecord('1.21-R0.4')
}

bungee {
    author 'YourName'
    depends 'LuckPerms'
}
```

### Plugin Application - NukkitX Plugin

Apply the Nukkit variant for developing NukkitX (Bedrock Edition) server plugins.

```groovy
plugins {
    id 'java'
    id 'io.typst.spigradle.nukkit' version '3.7.3'
}

repositories {
    mavenCentral()
}

dependencies {
    compileOnly nukkit('1.0')
}

nukkit {
    author 'YourName'
    description 'My Nukkit plugin'
}
```

### Kotlin DSL Configuration

Configure Spigot plugins using Kotlin DSL with type-safe builders and property assignments.

```kotlin
import io.typst.spigradle.spigot.*

plugins {
    kotlin("jvm") version "2.0.21"
    id("io.typst.spigradle") version "3.7.3"
}

repositories {
    mavenCentral()
    spigotmc()
    papermc()
}

dependencies {
    implementation(kotlin("stdlib"))
    compileOnly(paper("1.21.8"))
}

spigot {
    authors = listOf("Developer1", "Developer2")
    depends = listOf("ProtocolLib", "Vault")
    softDepends = listOf("WorldEdit")
    apiVersion = "1.21"
    load = Load.STARTUP

    commands {
        register("give") {
            aliases = listOf("giv", "i")
            description = "Give items to players"
            permission = "myplugin.give"
            permissionMessage = "You don't have permission!"
            usage = "/<command> <player> <item> [amount]"
        }
    }

    permissions {
        register("myplugin.give") {
            description = "Allows giving items"
            default = "op"
        }
        register("myplugin.*") {
            description = "All permissions"
            default = "false"
            children = mapOf(
                "myplugin.give" to true,
                "myplugin.take" to true
            )
        }
    }
}

debugSpigot {
    version.set("1.21.8")
    eula.set(true)
    downloadSoftDepends.set(true)
    jvmArgs.add("-Xmx2G")
    programArgs.add("--nogui")
}
```

### Repository Shortcuts

Use predefined repository shortcuts to access common Minecraft plugin repositories.

```groovy
repositories {
    mavenCentral()
    spigotmc()      // https://hub.spigotmc.org/nexus/content/repositories/snapshots/
    papermc()       // https://repo.papermc.io/repository/maven-public/
    purpurmc()      // https://repo.purpurmc.org/snapshots (for Purpur)
    jitpack()       // https://jitpack.io (for Vault)
    protocolLib()   // https://repo.dmulloy2.net/nexus/repository/public/
    enginehub()     // https://maven.enginehub.org/repo/ (WorldGuard, WorldEdit)
    codemc()        // https://repo.codemc.org/repository/maven-public/ (BStats)
    essentialsX()   // https://repo.essentialsx.net/releases/ (EssentialsX)
    enderzone()     // Alias for essentialsX()
    frostcast()     // https://ci.frostcast.net/plugin/repository/everything (BanManager)
    minecraftLibraries() // https://libraries.minecraft.net (Brigadier - for Bungee)
    sonatype()      // https://oss.sonatype.org/content/repositories/snapshots/
}
```

### Dependency Shortcuts

Use dependency shortcuts to include common Minecraft plugin dependencies with default or custom versions.

```groovy
dependencies {
    // Core APIs
    compileOnly spigot('1.21.8')           // org.spigotmc:spigot-api:1.21.8-R0.1-SNAPSHOT
    compileOnly paper('1.21.8')            // io.papermc.paper:paper-api:1.21.8-R0.1-SNAPSHOT
    compileOnly purpur('1.21.8')           // org.purpurmc.purpur:purpur-api:1.21.8-R0.1-SNAPSHOT
    compileOnly bungeecord('1.21-R0.4')    // net.md-5:bungeecord-api:1.21-R0.4
    compileOnly bukkit('1.21.8')           // org.bukkit:bukkit:1.21.8-R0.1-SNAPSHOT

    // Popular plugins
    compileOnly protocolLib('5.4.0')       // net.dmulloy2:ProtocolLib:5.4.0
    compileOnly vault()                    // com.github.MilkBowl:VaultAPI:1.7
    compileOnly luckperms('5.5')           // net.luckperms:api:5.5
    compileOnly worldedit('7.3.15')        // com.sk89q.worldedit:worldedit-bukkit:7.3.15
    compileOnly worldguard('7.0.14')       // com.sk89q.worldguard:worldguard-bukkit:7.0.14
    compileOnly essentialsX('2.21.1')      // net.essentialsx:EssentialsX:2.21.1
    compileOnly banManager('7.7.0')        // me.confuser.banmanager:BanManagerBukkit:7.7.0-SNAPSHOT
    compileOnly commandHelper('3.3.4')     // com.sk89q:commandhelper:3.3.4-SNAPSHOT

    // Utilities
    compileOnly lombok('1.18.38')          // org.projectlombok:lombok:1.18.38
    implementation bStats('3.0.2')         // org.bstats:bstats-bukkit:3.0.2

    // Brigadier for Bungee
    compileOnly brigadier('1.0.18')        // com.mojang:brigadier:1.0.18

    // Testing - MockBukkit format: mockBukkit(spigotVersion, mockBukkitVersion)
    // spigotVersion is major.minor format like "1.21", defaults to "1.15"
    // mockBukkitVersion defaults to "0.3.0"
    testImplementation mockBukkit('1.21', '3.133.0') // com.github.seeseemelk:MockBukkit-v1.21:3.133.0-SNAPSHOT
}
```

### Runtime Libraries Configuration

Specify runtime libraries that will be loaded by Spigot 1.17+ without shading, reducing plugin size.

```groovy
spigot {
    // Libraries will be downloaded by Spigot at runtime
    libraries = [
        'com.squareup.okhttp3:okhttp:4.9.0',
        'com.google.code.gson:gson:2.8.9',
        'org.apache.commons:commons-lang3:3.12.0'
    ]
}
```

```kotlin
spigot {
    // Kotlin DSL with type-safe configuration
    libraries = configurations.implementation.get().dependencies.map {
        "${it.group}:${it.name}:${it.version}"
    }
}
```

### Debug Task Configuration

Configure and run local debug servers with automatic plugin deployment and server downloads.

```groovy
debugSpigot {
    version.set("1.21.8")
    eula.set(true)                        // Auto-accept EULA
    downloadSoftDepends.set(true)          // Download soft dependencies
    jvmArgs.add("-Xmx2G")                  // Custom JVM arguments
    jvmArgs.add("-XX:+UseG1GC")
    programArgs.add("--nogui")             // Server arguments
}

// Run the debug server
// gradle debugProject
```

```bash
# Run the debug task
./gradlew debugMyPlugin

# The debug server will be located at:
# .gradle/spigradle-debug/paper/

# Clean debug directory
./gradlew cleanDebugMyPlugin

# Clean global Paper cache
./gradlew cleanCachePaper
```

### Permission Configuration

Define plugin permissions with hierarchical structures and default access levels.

```groovy
spigot {
    permissions {
        'myplugin.admin' {
            description 'Administrator permissions'
            defaults 'op'
        }
        'myplugin.user' {
            description 'Basic user permissions'
            defaults 'true'
        }
        'myplugin.*' {
            description 'All plugin permissions'
            defaults 'false'
            children = [
                'myplugin.admin': true,
                'myplugin.user': true,
                'myplugin.command.give': true
            ]
        }
    }
}
```

### Command Registration

Register plugin commands with aliases, permissions, and usage information in the plugin.yml.

```groovy
spigot {
    commands {
        register('teleport') {
            aliases 'tp', 'tele'
            description 'Teleport to a location'
            permission 'myplugin.teleport'
            permissionMessage 'You need myplugin.teleport permission'
            usage '/<command> <x> <y> <z> [world]'
        }
        register('home') {
            aliases 'h'
            description 'Teleport to home'
            usage '/<command> [set|delete]'
        }
    }
}
```

### Plugin Metadata Configuration

Configure plugin metadata that will be written to plugin.yml with automatic defaults.

```groovy
spigot {
    name 'MyAwesomePlugin'                 // Defaults to project.name
    version '2.0.0'                        // Defaults to project.version
    description 'An awesome Minecraft plugin'
    website 'https://example.com'
    authors 'Developer1', 'Developer2'
    apiVersion '1.21'                      // Target API version
    load STARTUP                           // or POST_WORLD
    prefix 'MyPlugin'                      // Console prefix
    depends 'Vault', 'ProtocolLib'         // Required dependencies
    softDepends 'WorldEdit', 'WorldGuard'  // Optional dependencies
    loadBefore 'SomeOtherPlugin'           // Load order control
}
```

### Main Class Override

Override automatic main class detection by explicitly specifying the plugin main class.

```groovy
spigot {
    main 'com.example.myplugin.CustomMainClass'
}
```

```kotlin
spigot {
    main.set("com.example.myplugin.CustomMainClass")
}
```

### Gradle Task Execution

Execute Spigradle tasks to generate descriptor files, detect main classes, and run debug servers.

```bash
# Generate plugin.yml
./gradlew generatePluginYaml

# Detect main class
./gradlew detectSpigotMain

# Build and run debug server
./gradlew debugMyPlugin

# Build plugin JAR
./gradlew jar

# The plugin.yml will be automatically generated in:
# build/resources/main/plugin.yml

# Main class detection result stored in:
# build/spigradle/spigot_main
```

## Summary

Spigradle serves as a comprehensive Gradle plugin for Minecraft server plugin development, supporting Spigot, Paper, Purpur, Bungeecord, and NukkitX platforms. Its primary use cases include automating plugin.yml/bungee.yml/nukkit.yml generation with intelligent main class detection via ASM 9.9 bytecode analysis, providing shortcuts for 20+ common Minecraft dependencies (Vault, ProtocolLib, WorldEdit, LuckPerms, EssentialsX, BanManager, etc.), and enabling rapid local testing with automatic Paper/Spigot server downloads and plugin deployment. The plugin integrates seamlessly with IntelliJ IDEA through the gradle-idea-ext plugin, generating run configurations for debugging, and supports Spigot 1.17+ runtime library loading to reduce plugin JAR sizes.

Integration patterns follow standard Gradle conventions with minimal configuration required - developers simply apply the plugin, configure repositories and dependencies using provided shortcuts, and customize the spigot/bungee/nukkit extension blocks as needed. The plugin automatically hooks into the build lifecycle to generate descriptor files before JAR assembly, performs main class detection using ASM bytecode analysis, and creates debug tasks that download Paper/Spigot servers, copy artifacts, prepare dependencies, and launch configured debug environments. Both Groovy and Kotlin DSL are fully supported with identical functionality, making Spigradle adaptable to any team's preferred Gradle scripting language.