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+, built against 1.21.11. The server must run Java 21.

Optional soft dependency:

• PlaceholderAPI - resolves %...% placeholders from other plugins inside messages, message titles and menu action arguments. OptimalGifts does not register an expansion of its own.

Gift rewards are console commands, so whatever plugin grants the reward (your economy, crates, tokens) needs to be installed as well - but OptimalGifts does not hook it directly.

Steps

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

XSeries downloads automatically on first startup via Paper’s library loader, so the first launch needs internet access and may take a few extra seconds. SQLite is not downloaded - the plugin uses the sqlite-jdbc driver Paper already bundles.

Generated files

plugins/OptimalGifts/
├─ config.yml             # settings, temporary icons, sounds
├─ gifts.yml              # every gift (12 ship by default)
├─ messages.yml           # every message
├─ guis/
│  └─ gifts-menu.yml      # the /gifts menu layout
└─ 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 populated on first run. They hand out eco give money - retarget the reward commands at your own economy before going live.

Storage

Player data (the cycle 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.

Writes are buffered in memory and flushed on Settings.Save-Interval (default 60 seconds), plus on quit and on server shutdown. Claims are the exception - they are written immediately, so a crash can never let a player re-claim a gift.

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