Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

BukkitGradle Version Build Status license

Gradle utilities for easier writing Bukkit plugins.


  • Automatically applies plugin: java
  • Sets up compiler encoding to UTF-8
  • Sets archivesBaseName to plugin name
  • Supports APIs: Bukkit, CraftBukkit, Spigot, Paper
  • Provides short extension functions to add common repositories and dependencies
  • Generates plugin.yml from Gradle project information
  • Allows running dev server from IDE
  • Supports two cores for dev server: Spigot and Paper
  • Automatically downloads and updates BuildTools or Paperclip
  • Automatically copies your plugin to plugins dir on server running


  • Add smart dependency system


BukkitGradle on

Note: Gradle 6.6+ required

With new plugins mechanism

plugins {
  id("ru.endlesscode.bukkitgradle") version "0.10.1"

With buildscript and apply

buildscript {
  repositories {
  dependencies {

apply(plugin: "ru.endlesscode.bukkitgradle")


If you want to use snapshots, you can add jitpack repository to settings.gradle and use version develop-SNAPSHOT:

// settings.gradle

pluginManagement {
    repositories {
        maven { setUrl("") }
} = "<your project name>"
// build.gradle

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

First steps

Simple build.gradle file that use BukkitGradle:

plugins {
    id("ru.endlesscode.bukkitgradle") version "0.10.1"
// Project information
group = "com.example.myplugin"
description = "My first Bukkit plugin with Gradle"
version = "0.1"

// Let's add needed API to project
dependencies {
    // see section 'Dependencies' for more info

Note: compileOnly - it's like provided scope in Maven. It means that this dependency will not be included to your final jar.

It's enough! Will be hooked the latest version of Bukkit and automatically generated plugin.yml with next content:

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

Note: Main class built by following pattern: <groupId>.<name>


You can configure attributes that will be placed to plugin.yml:

// Override default configurations
bukkit {
    // Version of API (if you will not set this property, will be used latest version at moment of BukkitGradle release)
    apiVersion = "1.15.2"
    // Attributes for plugin.yml
    meta {
        description.set("My amazing plugin, that doing nothing")
        url.set("") // Attribute website
        authors.set(["OsipXD", "Contributors"])

Will be generated plugin.yml file:

name: MyPlugin
description: My amazing plugin, that doing nothing
main: com.example.plugin.MyPlugin
version: 1.0
api-version: 1.15
authors: [OsipXD, Contributors]

If you want to add unsupported by BukkitGradle attributes, like a depend, commands etc. Create plugin.yml file and put custom attributes there.

Repositories and Dependencies

BukkitGradle provides short extension-functions to add common repositories and dependencies. There are list of its.

Usage example:

repositories {
    spigot() // Adds spigot repo

dependencies {
    compileOnly(paperApi()) // Adds paper-api dependency


Name Url


Some dependencies also applies repo needed for them.

Name Signature Applies repo
spigot org.spigotmc:spigot:$apiVersion mavenLocal
spigotApi org.spigotmc:spigot-api:$apiVersion spigot
bukkitApi org.bukkit:bukkit:$apiVersion spigot
paperApi com.destroystokyo.paper:paper-api:$apiVersion destroystokyo

Note: $apiVersion - is ${version}-R0.1-SNAPSHOT (where $version is bukkit.version)

If you need more extension-functions, create issue.

Running Dev server

Before running server you should configure dev server location.

You can define it in file (that was automatically created in project directory on refresh):

# Absolute path to dev server

If you use Spigot (see bukkit.server.core) you also should specify BuildTools location. For Paper no additional actions needed.

# Absolute path to directory that contains BuildTools.jar

If there no BuildTools.jar it will be automatically downloaded.

Tip: you can define it globally, for all projects that uses BukkitGradle. Specify environment variables BUKKIT_DEV_SERVER_HOME and BUKKIT_BUILDTOOLS_HOME.

On IntelliJ IDEA

Run :buildIdeaRun task. Run Configuration will be added to your IDE. It will be automatically refreshed when you change server configurations.

Run Configuration

On other IDEs

Run :runServer task.

Dev server configuration

To accept EULA and change settings use bukkit.server section:

bukkit {
    // INFO: Here used default values
    server {
        // Core type. It can be 'spigot' or 'paper'
        core = "spigot"
        // Server version
        version = "1.16.4" // If not specified, apiVersion will be used
        // Accept EULA
        eula = false
        // Set online-mode flag
        onlineMode = false
        // Debug mode (listen 5005 port, if you use running from IDEA this option will be ignored)
        debug = true
        // Set server encoding (flag -Dfile.encoding)
        encoding = "UTF-8"
        // JVM arguments
        // Bukkit arguments

EULA and online-mode settings in build.gradle always rewrites settings in eula.txt and

Migration Guide

Upgrade from 0.8.x

  1. Update gradle to 6.6 or newer:
    $ ./gradlew wrapper --gradle-version 6.7.1
  2. Use syntax .set in bukkit.meta instead of =:
    bukkit {
        meta {
    -        desctiption = "My plugin's description"
    +        description.set("My plugin's description")
  3. Use bukkit.apiVersion instead of bukkit.version:
    bukkit {
    -   version = "1.16.4"
    +   apiVersion = "1.16.4"
  4. Use build.server block instead of
    bukkit {
    -   run {
    +   server {
            core = "paper"
  5. Update arguments assignment syntax:
    bukkit {
        server {
    -       jvmArgs = "-Xmx2G -Xms512M"
    +       jvmArgs = ["-Xmx2G", "-Xms512M"]
    +       //or jvmArgs("-Xms512M") if you don't want to override defaults
  6. Replace removed APIs:
    repositories {
    -   destroystokyo()
    +   papermc()
    -   vault()
    +   jitpack()
    dependencies {
    -   compileOnly(craftbikkit())
    +   compileOnly(spigot())
  7. Remove q and qq functions calls in meta { ... }
  8. Check generated plugin.yml contents after build.

If there are any problems, create an issue.


MIT (c) 2020 EndlessCode Group