Installation

Requirements

• OptimalLibrary - required. It is a separate, free plugin that provides the shared runtime (text, menus, storage, economy hooks and more). OptimalAuctions will not enable without it.
• Paper or Folia (or a Paper fork). Spigot is not supported.
• Minecraft 1.21.11, 26.1.1, 26.1.2, 26.2 or 26.3.
• Java 21 for 1.21.11, Java 25 for the 26.x versions. Check with java -version.
• At least one economy for the currencies you keep enabled (see below).

Soft dependencies (all optional, install the ones your currencies use):

• Vault plus an economy plugin (EssentialsX, OptimalEssentials, CMI, …) - for Type: VAULT currencies. The shipped money currency uses it.
• PlayerPoints - for Type: PLAYER_POINTS currencies.
• RivalCredits - for Type: RIVAL_CREDITS currencies.
• OptimalGens - for OPTIMALGENS_<currency> currencies. The shipped tokens and gems currencies use it.
• OptimalMobcoins - for the OPTIMALMOBCOINS_MOBCOINS currency.
• PlaceholderAPI - registers the %optimalauctions_...% placeholders and resolves %...% from other plugins inside messages and menus.

The shipped default currency is gems

When /ah hand or /ah all is used without a currency, the listing goes into the first enabled file in currencies/ by file name. With the shipped files that is gems.yml, an OptimalGens currency. If you don’t run OptimalGens, set Enabled: false in gems.yml and tokens.yml (or delete them) so money becomes the default. See currencies.

Steps

1. Confirm java -version matches your server version (see above).
2. Stop the server.
3. Drop OptimalLibrary.jar and OptimalAuctions.jar into plugins/.
4. Add the economy plugins your currencies need, and (optionally) PlaceholderAPI.jar.
5. Start the server. The plugin generates its files and prints a startup banner with the number of listings, currencies and categories loaded.
6. Run /plugins: both OptimalLibrary and OptimalAuctions should be green.
7. Check the console for a line saying a currency is unavailable. That currency’s economy plugin is missing; listings in it cannot be created or bought until it is installed.

First start needs internet

OptimalLibrary downloads its database drivers (SQLite, MySQL, HikariCP) and XSeries through Paper’s library loader the first time it starts, so the first launch needs internet access and may take a few extra seconds.

Generated files

plugins/OptimalAuctions/
├─ config.yml               # settings, listing lore, prompts and sounds
├─ categories.yml           # browse categories and their item rules
├─ messages.yml             # every message
├─ currencies/
│  ├─ gems.yml              # OptimalGens gems
│  ├─ money.yml             # Vault money
│  └─ tokens.yml            # OptimalGens tokens
├─ guis/
│  ├─ main-menu.yml         # the /ah board
│  ├─ listings-menu.yml     # the player's own active listings
│  ├─ expired-menu.yml      # the player's expired listings
│  ├─ category-menu.yml     # category picker and search button
│  ├─ purchase-menu.yml     # the buy screen
│  ├─ history-menu.yml      # /ahadmin history
│  └─ removal-menu.yml      # /ahadmin remove and /ahadmin open <player>
└─ data/
   └─ data.db               # SQLite data (do not edit by hand)

config.yml, messages.yml and the menu files use the shipped file as a base, so a key you remove falls back to its default. Missing messages are written back into messages.yml on load. A menu file you delete from guis/ is written back on the next start.

The currencies/ folder is only created when it does not exist. A currency file you delete stays deleted, so you can remove the shipped currencies you don’t use.

Storage

Everything lives in one database: SQLite at data/data.db by default, or MySQL when Settings.Storage.Type is MYSQL (see config.yml).

• auction_listings holds every live listing (active and expired) and the sale history. Every partial purchase writes its own sale row, so a listing sold in five chunks produces five history entries. A live listing’s row is deleted once it is sold out, cancelled or collected.
• auction_payouts holds seller payouts and refunds that could not be paid yet, per player and currency. They are paid out three seconds after the player joins, as long as that currency is available.
• Live listings are loaded into memory at startup. Changes are written in the background as they happen, and pending writes are flushed when the server stops.
• Items are stored with their full data (names, lore, enchantments, components).

Storage changes need a restart

The database connection is opened at startup. /ahadmin reload does not switch between SQLite and MySQL or change MySQL credentials; restart the server instead. Existing data is not copied between the two.

Continue to Selling & Buying, or read the Information overview first.