BukkitGradle

Gradle utilities to simplify Bukkit/Spigot plugins writing and debugging.

• Installation
  • Quick Start
• Configuration
• Repositories and Dependencies
• Running Dev server
  • Dev server configuration
• Migration Guide
  • Upgrade from 0.10.x
  • Upgrade from 0.8.x
• License

Features

• Sets up compiler encoding to UTF-8
• Provides short extension functions to add common repositories and dependencies
• Generates plugin.yml from Gradle project information
• Allows running dev server from IDE
• Runs server using jpenilla/run-task

Installation

Note

BukkitGradle requires Gradle 8.0+ to run

plugins {
    id("ru.endlesscode.bukkitgradle") version "1.0.0"
}

BukkitGradle on plugins.gradle.org

Using snapshots

To use snapshots, add jitpack repository to the settings.gradle.kts and specify version develop-SNAPSHOT:

// settings.gradle

pluginManagement {
    repositories {
        gradlePluginPortal()
        maven { setUrl("https://jitpack.io") }
    }
}

rootProject.name = "<your project name>"

// build.gradle

plugins {
    id("ru.endlesscode.bukkitgradle") version "develop-SNAPSHOT"
}

Quick Start

Apply the plugin and configure project's group, description and version. These values will be used to generate the plugin.yml file:

plugins {
    id("ru.endlesscode.bukkitgradle") version "1.0.0"
}

group = "com.example.myplugin"
description = "My first Bukkit plugin built with Gradle"
version = "0.1"

bukkit {
    // Target API version. Will be used both for plugin.yml and for dependencies
    apiVersion = "1.21.5"
}

// Add the necessary API to the project
dependencies {
    compileOnly(paperApi)
    // See the 'Dependencies' section for more info
}

repositories {
    papermc()
}

That's it! During the plugin compilation plugin.yml will be generated with the following content:

api-version: 1.21.5
name: MyPlugin
version: '0.1'
main: com.example.myplugin.MyPlugin
description: My first Bukkit plugin built with Gradle

Note

By default, main class is built by the following pattern: <groupId>.<name>

Next, you might need to configure plugin.yml content or run dev server.

Configuration

The plugin.yml content can be configured using bukkit.plugin { ... } block.

bukkit {
    plugin {
        name = "MyPlugin"
        description = "My amazing plugin"
        main = "com.example.plugin.MyPlugin"
        version = "1.0"
        authors = listOf("osipxd", "contributors")
        depend = listOf("Vault", "Mimic")
    }
}

Repositories and Dependencies

BukkitGradle provides shortcuts to add common repositories and dependencies:

repositories {
    papermc()
}

dependencies {
    compileOnly(paperApi)
}

Repositories

Name	Url
spigot	https://hub.spigotmc.org/nexus/content/repositories/snapshots/
sk98q	https://maven.sk89q.com/repo/
papermc	https://repo.papermc.io/repository/maven-public/
dmulloy2	https://repo.dmulloy2.net/nexus/repository/public/
md5	https://repo.md-5.net/content/groups/public/
jitpack	https://jitpack.io/
placeholderapi	https://repo.extendedclip.com/content/repositories/placeholderapi/
aikar	https://repo.aikar.co/content/groups/aikar/
codemc	https://repo.codemc.org/repository/maven-public/

Dependencies

When adding dependencies, make sure you've added the corresponding repository.

Name	Signature	Official repository
spigot	org.spigotmc:spigot:$apiVersion	mavenLocal()*
spigotApi	org.spigotmc:spigot-api:$apiVersion	spigot()
bukkitApi	org.bukkit:bukkit:$apiVersion	mavenLocal()**
paperApi	io.papermc.paper:paper-api:$apiVersion	papermc()

* Spigot is available in mavenLocal() only if you've built it locally using Spigot BuildTools.
** Bukkit should be built locally. However, some versions are available in spigot() repository.
*** $apiVersion - is ${version}-R0.1-SNAPSHOT (where $version is bukkit.apiVersion).

If you need more shortcuts, file an issue.

Running Dev server

This plugin pre-configures jpenilla/run-task according to the specified configuration. Use :runServer task to run the dev server:

./gradlew runServer

Tip

It is possible to create a run configuration for IDEA by running :buildIdeaRun task. The configuration will be stored in <projectDir>/.run directory so it can be shared through VCS. The directory can be changed by configuring the :buildIdeaRun task:

tasks.buildIdeaRun {
    configurationsDir = file(".idea/runConfigurations")
}

By default, the server will be located at <projectDir>/run but you can change it by providing Gradle property bukkitgradle.server.dir:

# gradle.properties
bukkitgradle.server.dir=build/run

Alternatively, you can configure runServer task:

tasks.runServer {
    runDirectory.set(file("build/run"))
}

Tip

It is possible to configure a server directory shared between multiple projects. Set the bukkitgradle.server.dir property in $HOME/.gradle/gradle.properties.

This file contains local configurations to be used for all Gradle projects. The value specified in project's gradle.properties takes precedence over the global one.

Dev server configuration

Use bukkit.server section to accept EULA and configure the server:

bukkit {
    // INFO: Default values are used here
    server {
        // Server version
        version = "1.21.5" // If not specified, bukkit.apiVersion will be used
        // Accept EULA
        eula = false
        // Set online-mode flag
        onlineMode = false
        // Debug mode (listen to 5005 port)
        debug = true
        // Set default file encoding (flag -Dfile.encoding)
        encoding = "UTF-8"
        // JVM arguments
        javaArgs("-Xmx1G")
        // Bukkit arguments
        bukkitArgs()
    }
}

Note

eula and online-mode options specified in bukkit.server always take precedence over the values specified in eula.txt and server.properties

Migration Guide

Upgrade from 0.10.x

1. Update Gradle to 8.0 or newer (the latest version is recommended):

   ./gradlew wrapper --gradle-version 8.13

2. Replace deprecated and removed APIs:

   bukkit {
   -   meta {
   +   plugin {
           name = "MyPlugin"
   -       url = "https://example.com/"
   +       website = "https://example.com/"
       }
   }

3. Specify bukkit.apiVersion explicitly. Previously it was implicitly set to 1.16.4:

   bukkit {
       apiVersion = "1.21.5"
   }

4. Remove server core selection: bukkit.server.coreType and bukkit.server.setCore(...). Paper is the only supported server core now.

5. If you have plugin.yml, move it's content to bukkit.plugin { ... } block and delete the file.

6. Explicitly add mavenCentral() to the repositories if you're using dependencies from it:

   repositories {
       mavenCentral()
   } 

   Add repositories for Bukkit/Spigot/Paper according to the dependency table.

Upgrade from 0.8.x

1. Use bukkit.apiVersion instead of bukkit.version:

   bukkit {
   -   version = "1.16.4"
   +   apiVersion = "1.16.4"
   }

2. Use build.server block instead of build.run:

   bukkit {
   -   run {
   +   server {
           core = "paper"
       }
   }

3. Update arguments assignment syntax:

   bukkit {
       server {
   -       jvmArgs = "-Xmx2G -Xms512M"
   +       jvmArgs = ["-Xmx2G", "-Xms512M"]
   +       //or jvmArgs("-Xms512M") if you don't want to override defaults
       }
   }

4. Replace removed APIs:

   repositories {
   -   destroystokyo()
   +   papermc()
   
   -   vault()
   +   jitpack()
   }
   
   dependencies {
   -   compileOnly(craftbikkit())
   +   compileOnly(spigot())
   }

5. Remove q and qq functions calls in meta { ... }
6. Check generated plugin.yml contents after build.

If there are any problems, create an issue.

License

MIT (c) 2020 EndlessCode Group