Skip to content

spigot_plugin.md

Latest commit

 

History

History
524 lines (353 loc) · 15.4 KB

spigot_plugin.md

File metadata and controls

524 lines (353 loc) · 15.4 KB

Spigot plugin

The Spigot plugin provides you to:

  • Generate 'plugin.yml' with less configuration.

  • Shortcuts for dependency and repository.

  • Tasks for run server with your plugin for debug.

Table of contents

Requirements

The plugin requires Gradle 5.4.2+, recommends the latest.

To update your gradle wrapper:

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

Usage

Full Example Here

Groovy DSL

plugins {
    id 'kr.entree.spigradle' version '2.4.5'
}

Kotlin DSL

plugins {
    id("kr.entree.spigradle") version "2.4.5"
}
Groovy Legacy 
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath 'kr.entree:spigradle:2.4.5'
    }
}

apply plugin: 'kr.entree.spigradle'
Kotlin Legacy 
buildscript {
    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("kr.entree:spigradle:2.4.5")
    }
}

apply(plugin = "kr.entree.spigradle")

Description file generation

The plugin.yml file will be generated by task generateSpigotDescription based on the configuration of spigot, included into output jars automatically.

Basically the properties 'main', 'name' and 'version' defaults to auto-detected main, project.name, project.version respectively. So if we create a simple plugin that just needs those properties, we don't need any configuration. Only pay attention to your unique implementation.

You can configure all properties of plugin.yml in spigot {} block.

Main class detection

The plugin automatically finds the main class extends JavaPlugin, and set the 'main' property to the class found.

You may present the main class using @SpigotMain or @PluginMain:

import kr.entree.spigradle.annotations.SpigotPlugin;

@SpigotPlugin
public class SamplePlugin extends JavaPlugin { }
@SpigotPlugin
class SamplePlugin : JavaPlugin()

Debug your plugin

Run your plugin with just execute single gradle task.

The debugSpigot performs to build Spigot using BuildTools, copy it with your plugins into the default path debug/spigot/server.jar, and run it.

The debugPaper performs to download Paperclip, copy it with your plugins into the same path debug/spigot/server.jar, and run it.

These tasks copy your plugin and its dependency plugins.

You can pass (jvm)arguments:

spigot {
    debug {
        args '--nojline', '--max-players', '100'
        jvmArgs '-Xmx16G'
        serverPort 25564
    }
}

This affects both tasks debugSpigot, debugPaper, also to IDEA RunConfigurations RunSpigot, RunPaper.

More information: Tasks

Exclusion

If you want to exclude some plugins, this is an example,

Kotlin:

tasks {
    prepareSpigotPlugins {
        exclude("**/worldedit*.jar")
        exclude("**/worldguard*.jar")
    }
}

Groovy:

prepareSpigotPlugins {
    exclude '**/worldedit*.jar' // or exclude 'worldedit*.jar'?
    exclude '**/worldguard*.jar'
}

Then WorldEdit and WorldGuard will be excluded by the prepareSpigotPlugins which a Copy task, you can use all the Copy features.

Configuration

spigot - SpigotExtension

The description of your plugin for a plugin.yml.

The 'main' property will be set to the class auto-detected or presented by @kr.entree.spigradle.annotations.SpigotMain.

About the plugin.yml, See plugin-yml wiki

Groovy Example 
spigot {
    authors 'Me'
    depends 'ProtocolLib', 'Vault'
    softDepends 'WorldEdit'
    apiVersion '1.15'
    load STARTUP
    commands {
        give {
            aliases 'giv', 'i'
            description 'Give command.'
            permission 'test.foo'
            permissionMessage 'You do not have the permission!'
            usage '/<command> [item] [amount]'
        }
    }
    permissions {
        'test.foo' {
            description 'Allows foo command'
            defaults 'true'
        }
        'test.*' {
            description 'Wildcard permission'
            defaults 'op'
            children = ['test.foo': true]
        }
    }
}
Kotlin Example 
spigot {
    authors = listOf("Me")
    depends = listOf("ProtocolLib")
    softDepends = listOf("WorldEdit")
    apiVersion = "1.15"
    load = Load.STARTUP
    commands {
        create("give") {
            aliases = listOf("i")
            description = "Give command."
            permission = "test.foo"
            permissionMessage = "You do not have permission!"
            usage = "/<command> [test|stop]"
        }
    }
    permissions {
        create("test.foo") {
            description = "Allows foo command"
            defaults = "true"
        }
        create("test.*") {
            description = "Wildcard permission"
            defaults = "op"
            children = mapOf("test.foo" to true)
        }
    }
}

Without type-safe accessors:

configure<SpigotExtension> {
    authors = listOf("Me")  
    // ...
}

Tasks

All tasks supports UP-TO-DATE check.

Configuration Guide

Groovy:

runSpigot {
    jvmArgs('-Xmx8G')
}

Kotlin with type-safe accessors:

tasks {
    runSpigot {
        jvmArgs("-Xmx8G")
    }
}

Kotlin without type-safe accessors:

tasks {
    named<JavaExec>("runSpigot") {
        jvmArgs("-Xmx8G")
    }
}

Kotlin with property delegation

tasks {
    val runSpigot by existing(JavaExec::clas) {
        jvmArgs("-Xmx8G")
    }
    // Do something with 'runSpigot'
}

detectSpigotMain - SubclassDetection

Finds the main class extends org.bukkit.plugin.java.JavaPlugin.

generateSpigotDescription - YamlGenerate

Depends on: detectSpigotMain

Generates the description file 'plugin.yml'.

debugSpigot

Depends on: prepareSpigotPlugins, prepareSpigot, runSpigot

Builds Spigot and runs it with your plugin and dependency plugins.

debugPaper

Depends on: prepareSpigotPlugins, downloadPaper, runSpigot

Runs Paper with your plugin and dependency plugins.

prepareSpigotPlugins - Copy

Depends on: build

Copies project plugin jar and its dependency plugins into the server plugins directory.

prepareSpigot - Copy

Depends on: downloadSpigotBuildTools, buildSpigot

Prepares Spigot for ready to run.

runSpigot - JavaExec

*Depends on: acceptSpigotEula, configSpigot

Just runs the server jar at configured path even there's no executable file.

NOTE: Use debugSpigot or debugPaper instead of runSpigot if you need prepare process like download server jar, copy plugins.

downloadSpigotBuildTools - Download

Downloads Spigot BuildTools.

buildSpigot - JavaExec

Builds Spigot using BuildTools.

acceptSpigotEula

Accepts the Mojang EULA, used in runSpigot task and IDEA RunConfiguration.

configSpigot

Configure the spigot.yml, used to set settings.restart-on-crash to false as default.

downloadPaper - Download

Downloads Paperclip.

cleanSpigotBuild

Deletes all build outputs created by Spigot BuildTools.

cleanDebug

Deletes all server files.

Why not spigot-annotations?

@Plugin(name = "SamplePlugin", version = "1.0-SNAPSHOT")
@Commands(@Command(name = "foo", desc = "Foo command", aliases = ["foobar", "fubar"], permission = "test.foo", permissionMessage = "You do not have permission!", usage = "/<command> [test|stop]"))
@Permission(name = "test.foo", desc = "Allows foo command", defaultValue = PermissionDefault.OP)
class SamplePlugin : JavaPlugin()

If you use Gradle, the following reasons why no spigot-annotations:

  1. Duplicate information of the name and version, these already provided in build.gradle and settings.gradle.
  2. The Annotation doesn't suit for providing complex information like commands and permissions.
  3. Using Gradle, we can configure all things programmatically.

Replacement on build.gradle:

spigot {
    // The 'name' and 'version' will be set to project.version and project.name, 
    // But we may set those manually.
    name = 'Manual name'
    version = 'Manual version'
    commands {
        foo {
            aliases = ['foobar', 'fubar']
            description = 'Foo command'
            permission = 'test.foo'
            permissionMessage = 'You do not have permission!'
            usage = '/<command> [test|stop]'
        }
    }
    permissions {
        'test.foo' {
            description = 'Allows foo command'
            defaults = 'op'
        }
    }
}

Testing with MockBukkit

With Spigradle 1.3.0+, you can use the MockBukkit without any special code.

If you use less than 1.3.0, add it in build.gradle:

task copyPluginYaml(type: Copy, dependsOn: spigotPluginYaml) {
    from(new File(spigotPluginYaml.temporaryDir, 'plugin.yml'))
    into(sourceSets.test.output.resourcesDir)
}

tasks.test.dependsOn(copyPluginYaml)

Migration Tips

2.x <- 1.x

  • The task spigotPluginYaml renamed to generateSpigotDescription
  • The annotation @Plugin repackaged to @kr.entree.spigradle.annotations.Plugin.

Templates

spigot-plugin-template by @Silthus

BukkitJavaGradle by @portlek

See also