Setup Project (Spigot)

Starting a Project

Since Fairy requires Gradle as build tool to work, You will first need to create a new Gradle Project.

Normally your IDE should including something to create a fresh new Gradle Project, But if you don't, you can check Gradle's official documentation on how to build a fresh gradle project.

For beginners: Fairy Bukkit Template

To use this, please make sure you have a minimum of these qualifications:

• Understanding of Git (What is git?)
• Understanding of Gradle (What is Gradle?)

To proceed, please head to the official Fairy bukkit template repository and follow these instructions:

For experienced users: Gradle Plugin

After having a fresh Gradle project, you will need to configure Fairy gradle plugin

Adding Fairy plugin to your project build.gradle file:

plugins {
    id "java" // Java is necessary plugin since it's java project, add it if you don't have it yet
    id "io.fairyproject" version "VERSION"
}

io.fairyproject is the plugin tag for gradle portal, VERSION should be replaced as the latest version you found from above.

Configuring

After setting up gradle plugin, now we want to configure the plugin to fit your plugin structure.

If you are using InteliJ, Before configuring, reload Gradle would be suggested. Since InteliJ caches plugin data, and requires reload so InteliJ can read our plugins.

Adding an extension into your build.gradle file:

fairy {
}

This is the extension that includes most of fairy details, Now you can add properties into it.

Property	Required	Description
name	✅	The name of the plugin/application.
mainPackage	✅	The main package of the plugin/application. It should normal matching to your main package in the project.
version	✅	The version of this plugin/application.
description	❌	The description of this plugin/application.
authors	❌	The list of authors of this plugin/application.
fairyPlatforms	❌	The list of platforms that this plugin/application will be included. Uses platform("PLATFORM") to add specific platforms. (ex: platform("bukkit")) By default if no input this will be Bukkit platform.
fairyModules	❌	The list of modules that this plugin/application will be included. Uses module("MODULE", "VERSION") to add specific modules. (ex: module("discord", "0.0.1b11"))

Important note about adding modules

Before adding a new module, check the Versioning and get the latest version of the module first

Gradle plugin will always recognize your module input based on platforms. for example you write discord, it will search from YOUR_PLATFORM-discord to module.discord, and when it found an available module, it will uses it. So you do not need any prefix, just write the name of the module.

Don't know what to write? it's fine. for now we only need the 3 main thing to be in the extension. Here is an example:

fairy {
    name = "examplePlugin"
    mainPackage = "io.fairyproject.examplePlugin"
    version = "1.0.0"
}

name and version should be pretty self-explanatory. for mainPackage it should be the name of your main package in your plugin/application, it will be used for relocating fairy stuffs.

Main Class

Writing a main class is simple. Create a class where you want the main class to be

Extend from io.fairyproject.plugin.Plugin (io.fairyproject.app.Application if you are using app-platform).

And it's done! you can write a simple hello world but overwriting onPluginEnable()!

package io.fairyproject.examplePlugin;

import io.fairyproject.plugin.Plugin;

public class ExamplePlugin extends Plugin {

    @Override
    public void onPluginEnable() {
        System.out.println("Hello World!");
    }
    
}

Important note for Main Class

A project shouldn't contains more than 1 class that extends Plugin or Application.

Build

Finally, to build the plugin/application we can simply do ./gradlew build (or gradle build button in InteliJ) to build the jar. After completed, you should be able to find the jar in build/libs/ folder, and the jar name should ends with -all. The jar will be the actual result jar that you should use.

And... that's all! you build a plugin with Fairy!

Side note for Build

If you are building for Bukkit platform, there is no need for extra plugin.yml creation. Fairy Gradle plugin will generate it all for you based on the information you provided in gradle extension.