Developer Guide

Gradle Setup

repositories {
    maven { url 'https://jitpack.io' }
}
dependencies {
    compileOnly 'com.github.xyness:XCore:1.0.0'
}

Addon Structure

addon.yml

name: MyAddon
version: '1.0.0'
author: 'YourName'
main: com.example.myaddon.MyAddonAddon
description: What this addon does
depend: []
soft-depend: []

Main Class

public class MyAddon extends XAddon {

    @Override
    public boolean onEnable() {
        saveDefaultConfig();
        // Register listeners, commands, tables...
        return true;
    }

    @Override
    public void onDisable() { }

    @Override
    public void onReload() { }
}

Available APIs

Method	Description
`api()`	XCore API (database, cache, sync, GUI, vault, web)
`core()`	XCore JavaPlugin instance (for Bukkit registrations)
`scheduler()`	Folia-compatible SchedulerAdapter
`logger()`	Addon-scoped logger
`lang()`	Addon language namespace (MiniMessage)
`guiRegistry()`	GUI definition registry (loaded from YAML)
`getConfig()`	Addon config.yml
`getDataFolder()`	`plugins/XCore/addons/<name>/`

SchedulerAdapter (Folia)

Never use Bukkit.getScheduler(). Use scheduler() for Folia compatibility.

Method	Usage
`runGlobalTask(Runnable)`	Sync main thread
`runGlobalTaskTimer(Runnable, start, period)`	Repeating sync
`runEntityTask(Player, Runnable)`	Entity region thread
`runEntityTaskLater(Player, Runnable, delay)`	Delayed entity task
`runAsyncTask(Runnable)`	Async thread
`runAsyncTaskTimer(Runnable, start, period)`	Repeating async
`runAsyncTaskLater(Runnable, delay)`	Delayed async
`cancelTask(Object)`	Cancel a task handle

For entity teleportation, always use entity.teleportAsync().

GUI Framework

XCore provides a YAML-driven GUI system. Place YAML files in src/main/resources/guis/.

gui-title: "gui-title-key"        # Lang key for inventory title
rows: 6
slots: [0,1,2,...,44]             # Slots for paginated content
slots-sound: "minecraft:ui.button.click"

items:
  BackPage:
    slot: 48
    material: ARROW
    target-title: "previous-title"
    target-lore: "previous-lore"
    target-button-on: "previous-button-on"
    target-button-off: "previous-button-off"
    permission: "myaddon.gui.navigate"
    sound: "minecraft:ui.button.click"
    custom_model_data_value: 0
    item_model_key: "my_pack:my_item"
    actions:
      left:
        - "command:mycommand"
      right:
        - "message:<green>Hello!"

GuiUtils Methods

Method	Description
`createItem(Material, Component, List<Component>)`	Create item with name, lore, all ItemFlags
`createItemFromDef(GuiItem, Component, List<Component>)`	Create from YAML definition (handles heads, model data)
`updateGuiItem(Inventory, slot, Component, List<Component>)`	Update existing item's name/lore in-place
`buildNavLore(LangNamespace, loreKey, offKey, onKey, check, ...)`	Build nav button lore with blink state
`playSound(Player, String)`	Play sound from namespaced key