Installation

Requirements

• OptimalLibrary - required. It is a separate, free plugin that provides the shared runtime (text, menus, storage and more). OptimalGifts 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.

Optional soft dependency:

• PlaceholderAPI - resolves %...% placeholders from other plugins inside messages, titles, gift icons, menu items and menu actions. OptimalGifts does not register an expansion of its own.

Gift rewards are console commands, so whatever plugin hands out the reward (your economy, crates, keys) needs to be installed too. OptimalGifts does not hook it directly.

Steps

1. Confirm java -version matches your server version (see above).
2. Stop the server.
3. Drop OptimalLibrary.jar and OptimalGifts.jar into plugins/.
4. (Optional) Add PlaceholderAPI.jar.
5. Start the server. The plugin generates its files and prints a startup banner with the number of gifts loaded.
6. Run /plugins: both OptimalLibrary and OptimalGifts should be green.

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/OptimalGifts/
├─ config.yml             # settings and menu sounds
├─ gifts.yml              # every gift (12 ship by default)
├─ messages.yml           # every message
├─ guis/
│  └─ gifts-menu.yml      # the /gifts menu layout and temporary icons
└─ data/
   └─ data.db             # SQLite player data (do not edit by hand)

Twelve gifts ship in gifts.yml (three common, four rare, three epic, two legendary) so the menu is filled on first run. They hand out eco give money: point the reward commands at your own economy or crate plugin before going live.

config.yml, messages.yml and guis/gifts-menu.yml 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. gifts.yml is the exception: it is read exactly as written, so a gift never inherits values from the shipped gifts.

Upgrading from an older version

Temporary-Icons moved from config.yml to guis/gifts-menu.yml. A Temporary-Icons section left in an old config.yml is no longer read; copy your icons into the menu file.

Storage

Player data (the current day, banked playtime and today’s claims) is stored in SQLite at data/data.db, in a single player_gifts table. There is no MySQL option.

• A player’s data is loaded while they log in. If it cannot be loaded, the login is refused with the PROFILE-LOAD-FAILED message instead of letting them play with empty data.
• Changes are kept in memory and saved every Settings.Save-Interval seconds (default 60), when the player quits and when the server stops.
• Claims, /giftsadmin reset and /giftsadmin addtime are saved immediately.

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