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.gui.preset`, `api.gui.animation`, `api.gui.pagination`	Ready-made picker/text-input GUIs, live collection binding, menu animation
`api.interaction`	Confirmation GUIs, chat prompts, anvil text-input prompts
`api.item`	Fluent `ItemStack` builder and Base64 item serialization
`api.minimessage`	MiniMessage formatting helper
`api.text`	Shared PlaceholderAPI-style placeholder registry
`api.i18n`	Per-player-locale messages from `lang/*.yml` files
`api.event`	Cross-plugin pub/sub event bus
`api.cooldown`	Generic cooldown tracker (in-memory and persistent)
`api.scheduler`	Folia-safe scheduler wrapper and fluent task chaining
`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.crash`	Pattern-matched crash reports with human-readable help lines
`api.http`	Minimal async HTTP client with retries and backoff
`api.time`, `api.inventory`, `api.messaging`	Duration formatting/parsing, inventory snapshots, proxy messaging
`api.plugin`	`RefineryPlugin` base class and `RefineryPluginImplementation` interface
`api.listener`	`RefineryListener<T>` — a small base class for typed Bukkit listeners

The plugin main class

Your plugin can either extend RefineryPlugin, which initializes a CrashHandler and exposes the configuration registry, or implement RefineryPluginImplementation directly for the lighter interface-only approach. The interface provides the command registry, MiniMessage-based logging, and server-version detection as default methods:

RefineryCorePlugin.java

public final class RefineryCorePlugin extends RefineryPlugin {

    @Getter
    private static RefineryCorePlugin instance;

    public RefineryCorePlugin() {
        instance = this;
    }

    @Override
    public void onLoad() {
        super.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

RefineryPlugin additionally provides:

getCrashHandler() — a plugin-bound CrashHandler
getConfigurationRegistry() — the shared RefineryConfigurationRegistry
initializeConfiguration(configuration) — saves a configuration’s defaults, registers it, and returns the same instance
reloadPlugin() — reloads the Bukkit config and all configurations registered for the plugin

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
Crash Reporting, Localization, and Utilities — polish the rest

​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