Spigradle

An intelligent Gradle plugin for developing plugins for Spigot, BungeeCord, and NukkitX.

Migration Guide | Chatbot Q&A | Samples

Features

• Auto-generate plugin.yml with main class detection
• Debug task with server download and IDEA integration
• Repository and dependency shortcuts

Quick Start

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
    versionCatalogs {
        // apply the version catalog to use the new dependency shortcut
        create("spigots") {
            from("io.typst:spigot-catalog:1.0.0")
            // if you need to override the version:
            // version("spigot-api", "1.21.10-R0.1-SNAPSHOT")
            // to see the catalog declaration, double tab shift in IDE, search spigot-catalog
        }
        create("commons") {
            from("io.typst:common-catalog:1.1.0")
        }
    }
}

// ...

build.gradle.kts

plugins {
    java
    alias(spigots.plugins.spigot)
    alias(commons.plugins.ideaExt) // optional, allows Spigradle generates Run Configurations for debug
}

repositories {
    mavenCentral()
    spigotRepos {
        spigotmc()
        jitpack() // for vault
    }
}

dependencies {
    compileOnly(spigots.paper.api)
    compileOnly(spigots.protocolLib)
    compileOnly(spigots.vault) {
        isTransitive = false
    }
}

spigot {
    depend = listOf("ProtocolLib", "Vault")
    apiVersion = "1.21"
}

debugSpigot { // extension for debugProjectName task
    version = "1.21.8"
    eula = true
}

Table of contents

• Plugins
• Requirements
• Main Class Detection
• Repositories
• Dependencies
• All docs
• Supporters

Plugins

• Spigot: id 'io.typst.spigradle.spigot' - Documentation
• BungeeCord: id 'io.typst.spigradle.bungee' - Documentation
• NukkitX: id 'io.typst.spigradle.nukkit' - Documentation

Requirements

All the plugins require Gradle 9.0+, the latest version is recommended.

To update your gradle wrapper:

gradlew wrapper --gradle-version 9.2.1 --distribution-type all

Main Class Detection

Spigradle automatically detects your plugin's main class using bytecode analysis with ASM (a Java bytecode manipulation framework). This eliminates the need to manually specify the main class in your build configuration.

How it works

The detection process follows these steps:

1. Bytecode Scanning: Scans all compiled .class files using ASM's ClassReader

• Uses optimized flags (SKIP_CODE, SKIP_DEBUG, SKIP_FRAMES) for faster processing
• Only extracts class metadata (name, superclass, access modifiers)

2. Class Hierarchy Building: For each class file, extracts:

• Class name (e.g., com/example/MyPlugin)
• Superclass name (e.g., org/bukkit/plugin/java/JavaPlugin)
• Access modifiers (public, abstract, final, etc.)

3. Detection Context: All discovered classes are registered in a directed graph structure

• Maintains class inheritance relationships
• Enables efficient traversal of the class hierarchy

4. Main Class Resolution: Traverses the inheritance graph to find a valid main class:

• Must be a non-abstract, public class
• Must directly or indirectly extend/implement the platform-specific base class
• Prefers direct subclasses over deeper inheritance levels

5. Result Integration: The detected class name is automatically set as the main property in:

• plugin.yml for Spigot/Nukkit
• bungee.yml for BungeeCord

Platform-specific detection targets

Key features

• Automatic: No manual configuration required in most cases
• Incremental: Only scans changed .class files for faster builds
• Gradle-native: Fully integrated with Gradle's incremental compilation
• Smart: Understands complex inheritance hierarchies

Manual override

If you need to manually specify the main class (e.g., multiple valid candidates), you can override the detection:

Groovy:

spigot {
    main = 'com.example.MyCustomMain'
}

Kotlin:

spigot {
    main = "com.example.MyCustomMain"
}

Technical details

For a contributor, internal usage:

• Implementation: SubclassDetection task
• Detection framework: io.typst.spigradle.detection package
  • ClassDefinition - Represents class metadata
  • DetectionContext - Manages detection state and class graph
  • DirectedGraph - Graph utilities for class hierarchy traversal
• Bytecode library: ASM

Repositories

Spigradle provides convenient shortcuts for adding Maven repositories commonly used in Minecraft plugin development. These repository shortcuts can be used in both Groovy and Kotlin DSL.

Relations column indicates which popular plugins/libraries are hosted in each repository.

Repository shortcuts

Repository shortcuts are now available via platform-specific blocks: spigotRepos {}, bungeeRepos {}, nukkitRepos {}.

Spigot repositories (via spigotRepos {})

Bungee repositories (via bungeeRepos {})

Nukkit repositories (via nukkitRepos {})

Common repositories (via Repositories)

Groovy usage

repositories {
    mavenCentral()
    spigotRepos {
        papermc()
        protocolLib()
    }
}

Kotlin usage

repositories {
    mavenCentral()
    spigotRepos {
        papermc()
        protocolLib()
    }
}

Dependencies

Spigradle provides shortcuts for common Minecraft plugin dependencies. Each shortcut automatically resolves the correct Maven coordinates and uses a sensible default version (which you can override).

Important: Make sure to add the corresponding repository (see Repositories) before using these dependencies. The "Official repository" column indicates which repository function provides access to each dependency.

Dependency shortcuts

Dependencies are now available via Version Catalogs. See Quick Start for setup.

Groovy usage

dependencies {
    compileOnly spigots.spigot.api
}

Kotlin usage

dependencies {
    compileOnly(spigots.spigot.api)
}

All docs

• Spigot Plugin
• Bungeecord Plugin
• Nukkit Plugin
• Multi-Module Projects Guide

Supporters