Content generated with AI — it may contain mistakes.

ExyliaLib/Getting startedguide

A first plugin

Config, a command, a menu and a database table — end to end, in one file each.

Page 6 of 543 min read

Everything below is real API. It is the shortest path from an empty plugin to one that stores something, shows a menu and can be reloaded.

The build#

ExyliaLib is on the server already, so you compile against it and never ship it:

build.gradle
groovy
repositories {
    maven { url 'https://repo.papermc.io/repository/maven-public/' }
    maven { url 'https://jitpack.io' }
}
 
dependencies {
    compileOnly 'io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT'
    compileOnly 'com.github.DiGround-s.ExyliaLib:ExyliaLib:v1.321.2'
}
plugin.yml
yaml
name: MyPlugin
main: com.example.myplugin.MyPlugin
version: 1.0.0
api-version: '1.21'
depend: [ ExyliaLib ]

The version is the ExyliaLib release tag, v included; use the one the server runs or an older one. Java 21. The plugin's name is also its action namespace below: MyPlugin answers to myplugin:.

The handles#

Each module is reached through a small per-plugin handle, created once in onEnable:

java
private ConfigFile<Settings> settings;
private PluginMenus menus;
private TaskScheduler tasks;
private Reloads reloads;
 
@Override
public void onEnable() {
    menus = Menus.of(this);
    tasks = Tasks.of(this);
    // ...the steps below
}

The configuration#

A YAML file is a Java record. The record is the source of truth; the file is generated from it.

Settings.java
java
public record Settings(
        @Comment("How many kits a player may own.")
        @Key("max-kits")
        int maxKits,
 
        @Comment("Shown above the kit list.")
        String header) {
 
    /** The defaults the file is generated from. */
    public Settings() {
        this(3, "{primary}&lYOUR KITS");
    }
}
java
settings = Configs.define(this, "config", Settings.class).load();
int max = settings.get().maxKits();

get() is a field access, never a re-parse, so reading a value inside a loop costs nothing.

The table#

A record again, annotated with where it lives:

Kit.java
java
@Table("my_kits")
public record Kit(
        @Id(length = 64) String id,
        @Column(length = 36) String owner,
        @Column(length = 128) String name,
        @Column(length = 64) String icon,
        @Column ItemStack[] contents) {
}
java
Repository<Kit> kits = Databases.of(this).repository(Kit.class);
 
kits.find(id).thenAccept(found ->
        tasks.runAtEntity(player, () -> found.ifPresent(kit -> give(player, kit))));

Every call returns a CompletableFuture and none of them blocks. Coming back to Bukkit means coming back through the scheduler — runAtEntity on the player, which on Folia is that player's region thread.

The menu#

The menu is a file, not code:

menus/kits.yml
yaml
title: '{primary}&lKITS {muted}%current_page%/%total_pages%'
size: 54
 
pagination:
  slots: '10-16,19-25,28-34'
  item_template:
    material: "%kit_icon%"
    name: "{warning}&l%kit_name%"
    lore:
      - "{muted}Click to equip"
    actions:
      - "myplugin:equip %kit_id%"
  navigation:
    previous: { slot: 45, material: ARROW, name: "{muted}Back" }
    next:     { slot: 53, material: ARROW, name: "{muted}Next" }
 
filler:
  global:
    material: BLACK_STAINED_GLASS_PANE
    hide_tooltip: true

Loaded once — load compiles and registers it — and opened cheaply:

java
private void loadMenus() {
    menus.unload();
    menus.load("kits", YamlConfiguration.loadConfiguration(
            new File(getDataFolder(), "menus/kits.yml")));
}
 
menus.open(player, "kits");

Filling the list is where your data meets the template:

java
UiSession session = menus.openNow(player, menus.definition("kits").orElseThrow(), Map.of());
 
session.entries(owned.stream()
        .map(kit -> UiEntry.of(kit)
                .with("kit_name", kit.name())
                .with("kit_icon", kit.icon())
                .with("kit_id", kit.id())
                .build())
        .toList());

The action behind the button#

myplugin:equip %kit_id% is an action. Register it once and every menu, item and event boundary can call it:

java
Actions.of(this).registerSync("equip", (context, args) -> {
    Player player = context.player();
    Kit kit = (Kit) context.require(UiKeys.ENTRY);   // the row that was clicked
    give(player, kit);
    return ActionResult.success();
});

The row is carried by the click, so nothing has to work out which kit was drawn where. See Actions.

Reloading#

Declare the steps once and /myplugin reload becomes one call that reports which step failed rather than dying halfway:

java
reloads = Reloads.of(this)
        .step("config", () -> settings.reload())
        .stepAlsoOnLibraryReload("menus", this::loadMenus)   // also when the library's colours change
        .step("kits", () -> kitManager.load());
 
// In the reload command:
reloads.run(sender);   // [MyPlugin] Reloaded 3 steps in 12ms

What you did not have to write#

No inventory listener, no per-player map keyed by UUID, no YAML parsing, no thread juggling around the database, no scoreboard team for a nametag, and no Folia branch anywhere.

Next: Configuration for the file format, or Menus for everything a menu file can say.

Something missing on this page? Tell us on Discord