BukkitGradle

Gradle utilities for easier writing Bukkit plugins.

• Installation
  • First steps
• Configuration
• Repositories and Dependencies
• Running Dev server
  • Dev server configuration
• Migration Guide
  • Upgrade from 0.8.x
• License

Features:

• 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

TODO:

• Add smart dependency system

Installation

BukkitGradle on plugins.gradle.org

Note: Gradle 6.6+ required

With new plugins mechanism

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

With buildscript and apply

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath("gradle.plugin.ru.endlesscode:bukkit-gradle:0.10.1")
  }
}

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

Snapshots

If you want to use snapshots, you can add jitpack repository to settings.gradle and use 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"
}

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 {
    compileOnly(bukkitApi())
    // 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>

Configuration

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 {
        name.set("MyPlugin")
        description.set("My amazing plugin, that doing nothing")
        main.set("com.example.plugin.MyPlugin")
        version.set("1.0")
        url.set("http://www.example.com") // 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
website: http://www.example.com
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
}

Repositories:

Dependencies:

Some dependencies also applies repo needed for them.

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 local.properties file (that was automatically created in project directory on refresh):

# Absolute path to dev server
server.dir=/path/to/buildtools/

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
buildtools.dir=/path/to/buildtools/

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.

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
        javaArgs("-Xmx1G")
        // Bukkit arguments
        bukkitArgs("nogui")
    }
}

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

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 build.run:

   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.

License

MIT (c) 2020 EndlessCode Group