Installation

Requirements

• Java 21+ - required. The plugin is compiled to Java 21 bytecode; on Java 17 or older it fails with UnsupportedClassVersionError. Check with java -version.
• Paper / Folia (or a Paper fork). Spigot is not supported. api-version is 1.20.
• Minecraft 1.20+, tested on 1.21.11. The server must run Java 21.
• An economy for the market and cases - the market and case pricing need a currency provider. Pick one with Settings.Economy: Vault (with a Vault economy), PlayerPoints, or RivalCredits. Without one, buying is disabled.

Optional soft dependencies (hooked only if installed):

• PlaceholderAPI - required to expose the cosmetic placeholders an external chat/nametag plugin reads. Cosmetics do not render themselves - see Information.
• Vault / PlayerPoints / RivalCredits - the market/case currency provider.
• DecentHolograms - floating text above placed case blocks. Without it, cases still work; only the holograms are disabled.

Steps

1. Confirm java -version reports 21 or higher.
2. Stop the server.
3. Drop OptimalCosmetics.jar into plugins/.
4. (Recommended) Add PlaceholderAPI.jar, your economy plugin, and optionally DecentHolograms.jar.
5. Start the server. The plugin generates its files and prints a startup banner.
6. Run /plugins - OptimalCosmetics should be green.

sqlite-jdbc, XSeries and mysql-connector-java download automatically on first startup via Paper’s library loader, so the first launch needs internet access and may take a few extra seconds.

Generated files

plugins/OptimalCosmetics/
├─ config.yml               # global settings, market, economy, rarities, menus theming
├─ messages.yml             # every message
├─ locations.yml            # placed case blocks (written by the plugin, do not edit by hand)
├─ cosmetics/               # one file per type, each holding many cosmetics
│  ├─ chat-colors.yml
│  ├─ tags.yml
│  ├─ name-paints.yml
│  ├─ glow.yml
│  ├─ tab-icons.yml
│  ├─ join-messages.yml
│  └─ leave-messages.yml
├─ cases/
│  └─ secret.yml            # example case (crate)
├─ guis/
│  ├─ cosmetics-menu.yml    # the /cosmetics menu
│  ├─ equip-menu.yml        # equip / unequip / sell confirmation
│  ├─ cosmetics-market.yml  # the /cosmetics market menu
│  ├─ market-confirm.yml    # market purchase confirmation
│  └─ case-confirm.yml      # case opening confirmation
└─ data/
   └─ data.db               # SQLite player data (do not edit by hand)

A few example cosmetics ship in each cosmetics/*.yml file so the menu is populated on first run. Add your own by adding sections to those files - see Creating Cosmetics.

Storage

Player data (owned cosmetics, equipped cosmetics, market listings, case winners) is stored in SQLite by default at data/data.db. To share data across a network - so equips and ownership sync between gamemodes - set Settings.Database: "MySQL" and fill in the MySQL section of config.yml. Both backends use the same schema; SQLite runs in WAL mode.

Continue to Creating Cosmetics, or read the Information overview first.