BukkitGradle

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

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• 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

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

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

<details> <summary>Using snapshots</summary>

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"
}

</details>

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][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][issue].

License

MIT (c) 2020 EndlessCode Group