> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.refineryteam.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> What RefineryCore is, how it's structured, and how other Refinery plugins depend on it.

**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.

<Note>
  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.
</Note>

## 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`](/refinerycore/commands)                  | Annotation-driven command framework (subcommands, cooldowns, tab-completion)            |
| [`api.config`](/refinerycore/configuration)              | Annotation-driven YAML configuration mapping                                            |
| [`api.gui`](/refinerycore/gui)                           | Inventory GUI framework (slot items/actions, layouts, pagination)                       |
| [`api.interaction`](/refinerycore/interaction)           | Confirmation GUIs, chat prompts, anvil text-input prompts                               |
| [`api.item`](/refinerycore/item-and-messages)            | Fluent `ItemStack` builder                                                              |
| [`api.minimessage`](/refinerycore/item-and-messages)     | MiniMessage formatting helper                                                           |
| [`api.event`](/refinerycore/event-bus)                   | Cross-plugin pub/sub event bus                                                          |
| [`api.cooldown`](/refinerycore/cooldowns-and-scheduler)  | Generic cooldown tracker                                                                |
| [`api.scheduler`](/refinerycore/cooldowns-and-scheduler) | Folia-safe scheduler wrapper                                                            |
| [`api.scoreboard`](/refinerycore/scoreboard)             | Per-player sidebar scoreboard manager                                                   |
| [`api.version`](/refinerycore/version-abstraction)       | Version-capability abstraction (avoids raw version string checks)                       |
| [`api.database`](/refinerycore/database)                 | Persistent SQL storage (MySQL, MariaDB, PostgreSQL, SQLite, H2) with a repository layer |
| [`api.storage`](/refinerycore/temporary-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:

```java RefineryCorePlugin.java icon="java" theme={"system"}
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`](/refinerycore/version-abstraction) 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:

1. [Installation](/refinerycore/installation) — add RefineryCore as a dependency
2. [Commands](/refinerycore/commands) — register your plugin's commands
3. [Configuration](/refinerycore/configuration) — map a YAML config to a Java class
4. [GUI Framework](/refinerycore/gui) — build inventory menus
5. [Database](/refinerycore/database) and [Temporary Storage](/refinerycore/temporary-storage) — persist and cache data