Overview - Refinery WIKI

RefineryCore is the foundation plugin behind every Refinery Minecraft project. It isn’t a gameplay plugin on its own — it’s a library of small, focused APIs (commands, GUIs, configuration, databases, scoreboards, and more) that other plugins like RefineryCombat, StaffHunt, and Monarchs build on top of, so those plugins don’t each reinvent the same plumbing.

RefineryCore targets PaperMC and compiles against the plain paper-api (no NMS), meaning a single build loads on any Paper version from 1.20 onward through the latest 1.21.x.

Why a core plugin?

Without a shared core, every Refinery plugin would independently hand-roll:

A reflection-based command framework (or repeat boilerplate CommandExecutor classes)
A GUI click-handling listener
A YAML config mapper
A cooldown tracker
A per-player scoreboard manager
A database connection pool

RefineryCore centralizes all of it behind clean, annotation-driven or fluent-builder APIs, so downstream plugins only depend on xyz.refineryteam.refinerycore and get all of the above for free.

Package layout

All public API lives under xyz.refineryteam.refinerycore.api, split by concern:

Package	Purpose
`api.command`	Annotation-driven command framework (subcommands, cooldowns, tab-completion)
`api.config`	Annotation-driven YAML configuration mapping
`api.gui`	Inventory GUI framework (slot items/actions, layouts, pagination)
`api.interaction`	Confirmation GUIs, chat prompts, anvil text-input prompts
`api.item`	Fluent `ItemStack` builder
`api.minimessage`	MiniMessage formatting helper
`api.event`	Cross-plugin pub/sub event bus
`api.cooldown`	Generic cooldown tracker
`api.scheduler`	Folia-safe scheduler wrapper
`api.scoreboard`	Per-player sidebar scoreboard manager
`api.version`	Version-capability abstraction (avoids raw version string checks)
`api.database`	Persistent SQL storage (MySQL, MariaDB, PostgreSQL, SQLite, H2) with a repository layer
`api.storage`	Non-persistent, in-memory key-value storage with optional TTL
`api.plugin`	`RefineryPluginImplementation` — the interface your plugin’s main class implements
`api.listener`	`RefineryListener<T>` — a small base class for typed Bukkit listeners

The plugin main class

Every Refinery plugin’s main class implements RefineryPluginImplementation (rather than extending some shared abstract plugin class), which is what wires in the command registry, MiniMessage-based logging, and server-version detection as default interface methods:

RefineryCorePlugin.java

public final class RefineryCorePlugin extends JavaPlugin implements RefineryPluginImplementation {

    @Getter
    private static RefineryCorePlugin instance;

    public RefineryCorePlugin() {
        instance = this;
    }

    @Override
    public void onLoad() {
        saveDefaultConfig();
    }

    @Override
    public void onEnable() {
        getPluginManager().registerEvents(new GUIHandlerListener(this), this);
        getCommandRegistry().register(new RefineryDefaultCommand(this));
    }
}

RefineryPluginImplementation gives your plugin, for free:

reload() — reloads the Bukkit config by default; override for custom reload logic
getConsoleSender() / logMessage(String) — sends MiniMessage-formatted console output
getPluginManager() — shorthand for Bukkit.getPluginManager()
getCommandRegistry() — a per-plugin-class CommandRegistry singleton
getServerImplementation() — the resolved ServerImplementation for the running server

Where to go next

If you’re building a plugin on top of RefineryCore, a typical order to read the docs in:

Installation — add RefineryCore as a dependency
Commands — register your plugin’s commands
Configuration — map a YAML config to a Java class
GUI Framework — build inventory menus
Database and Temporary Storage — persist and cache data

​Why a core plugin?

​Package layout

​The plugin main class

​Where to go next

Why a core plugin?

Package layout

The plugin main class

Where to go next