Installation

Requirements

• OptimalLibrary - required. OptimalAFKZone depends on it and will not enable without it. It is a separate, free plugin that provides the shared runtime (text and MiniMessage, menus, storage, scheduling). Install the latest version alongside the plugin.
• 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. These are the versions OptimalLibrary supports; other versions are not.
• Java 21 for 1.21.11, Java 25 for the 26.x servers. Check with java -version.

Optional soft dependency:

• PlaceholderAPI - registers the %optimalafkzone_...% placeholders and resolves %...% placeholders from other plugins inside messages, actions, displays and menus.

Zone rewards and the default shop items use console commands (eco give, lp user ...), so whatever plugin those commands belong to needs to be installed too. OptimalAFKZone does not hook them directly - retarget the commands at your own plugins.

Steps

1. Confirm java -version reports the right Java for your server version.
2. Stop the server.
3. Drop OptimalLibrary.jar and OptimalAFKZone.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 - OptimalLibrary and OptimalAFKZone should both be green.

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

Generated files

plugins/OptimalAFKZone/
├─ config.yml            # settings, wand, shards, commands, shop switches, sounds
├─ messages.yml          # every message
├─ zones/                # one file per zone (empty until you create one)
├─ boosters/
│  ├─ shard2x.yml        # 2x shards for 1 hour
│  └─ shard3x.yml        # 3x shards for 30 minutes
├─ shops/
│  └─ shards.yml         # the default rotating shard shop
├─ guis/
│  └─ confirm.yml        # purchase confirmation menu
└─ data/
   └─ data.db            # SQLite player data (do not edit by hand)

No zones ship by default. Create them in-game with the wand, see Creating AFK Zones.

boosters/ and shops/ are only extracted when the folder does not exist yet, so a default file you delete stays deleted. Delete the whole folder to get the defaults back.

Storage

Player data is stored in SQLite at data/data.db. There is no MySQL option. The database holds:

• each player’s shard balance and total AFK time
• each player’s active booster (multiplier and expiry)
• every shop’s current rotation (which items are stocked and when it rotates next)
• each player’s purchase counts for the current rotation

Balances and AFK time are kept in memory and saved on Settings.Save-Interval (default 300 seconds), when a player quits, and on server shutdown. Boosters and shop rotations are written the moment they change. /afkzoneadmin shards on an offline player edits the stored balance directly, so it cannot be overwritten by a later save.

Shop rotations survive restarts: a rotation that is still running when the server starts keeps its stock and countdown.

Continue to Creating AFK Zones, or read the Information overview first.