Information

BattleStudio plugin

OptimalAFKZone

Turn cuboid regions into rewarding AFK zones that pay players on a timer, with shards, boosters, a rotating shard shop and live displays.

Requires

Paper / FoliaMC 1.21.11+Java 21+OptimalLibraryPlaceholderAPI

Buy on BuiltByBitInstallation guideGet support

OptimalAFKZone turns cuboid regions into rewarding AFK zones. Standing inside a zone accrues time, and every Reward-Time seconds the player is paid out: a weighted roll from the zone’s own rewards, a number of shards, or both. Shards are spent in a rotating shard shop, and shard boosters (items or permissions) multiply what a zone pays.

Zones are created in-game with a selection wand, one file per zone. Every zone has its own payout timer, rewards, protections, enter and leave actions, action bar and boss bar.

How it works

• Presence is the only requirement. There is no idle detection and no player cap. A player whose feet are inside the region is in the zone.
• One zone at a time. When zones overlap, the one with the highest Settings.Priority wins.
• Progress is tracked in ticks, so the payout timer stays exact whatever Check-Interval you use. Leaving resets progress toward the next payout unless the zone sets Reset-Progress-On-Leave: false.
• Zone permissions. A zone with a Permission sends ZONE-NO-ACCESS once to a player without it. That player accrues nothing, gets no displays or protections and is not counted as an occupant.
• On each payout the zone first rolls its shards (when shards are enabled and the zone’s Reward-Mode includes them), then runs its Rewards (when the mode includes commands), then plays the ZONE-REWARD sound.
• Shards are multiplied by the player’s best multiplier: the highest of their optimalafkzone.booster.<n> permission and their active booster. They never stack.
• Total AFK time is kept per player and survives restarts. It is shown by /afkzone and the afk_time placeholders.

Features

• Cuboid AFK zones that pay players on a timer, one file per zone
• In-game zone creation with a selection wand and a live particle outline
• Shards currency with configurable names and number formatting (separated or abbreviated)
• Weighted reward groups per zone, a flat shard payout, or both, chosen per zone
• Rotating shard shop with weighted stock, per-player limits, item or command rewards and a confirm menu
• Booster items and permanent permission-based multipliers
• Per-zone action bar and boss bar with a live countdown
• Zone protections: damage, hunger and mob targeting
• Overlapping zones resolved by priority
• Renameable commands and aliases
• PlaceholderAPI expansion
• Folia-ready, built on OptimalLibrary

Commands

The command names below are the defaults. All three commands, and their aliases, can be renamed in the Commands section of config.yml (restart required).

Player - /afkzone (aliases /afk, /afkzones):

• /afkzone - show your progress in the zone you are standing in · optimalafkzone.use
• /afkzone shards (or balance) - view your shard balance · optimalafkzone.use
• /afkzone shards <player> - view another player’s balance, works offline · optimalafkzone.admin
• /afkzone shop - open the shard shop · optimalafkzone.use + optimalafkzone.shop
• /afkzone booster - view your active booster and its time left · optimalafkzone.use

Any other argument shows the AFKZONE-HELP panel.

Shop - /shardshop (alias /shardsshop):

• /shardshop - open the shard shop, the same as /afkzone shop · optimalafkzone.use + optimalafkzone.shop

Admin - /afkzoneadmin (aliases /afkadmin, /afkzonesadmin) · all optimalafkzone.admin:

• /afkzoneadmin wand - get the selection wand
• /afkzoneadmin create <zone> - create a zone from your selection
• /afkzoneadmin delete <zone> (or remove) - delete a zone and its file
• /afkzoneadmin list - list every zone with its world, timer and occupants
• /afkzoneadmin tp <zone> (or teleport) - teleport to the top centre of a zone
• /afkzoneadmin outline <zone> - toggle a zone’s particle outline for yourself
• /afkzoneadmin shards <give|take|set> <player> <amount> - manage a balance. Works on offline players. add and remove are accepted for give and take.
• /afkzoneadmin booster give <player> <booster> [amount] - give booster items (online players)
• /afkzoneadmin booster set <player> <multiplier> [duration] - set an active booster directly (online players). No duration, 0 or 0s means permanent.
• /afkzoneadmin booster remove <player> - remove a player’s active booster (online players)
• /afkzoneadmin reload - reload every config, zone, booster and shop file. Players keep their progress, protection and bars.

With no arguments the admin command shows the AFKZONE-ADMIN-HELP panel. Players without optimalafkzone.admin do not see the admin command or its aliases in tab completion.

Amounts and durations

• shards amounts accept $, , or _ separators and k/m/b/t/q suffixes (1.5k, 2m), up to 2147483647. give and take need at least 1; set accepts 0. Taking more than a player has leaves them at 0.
• booster give amounts must be at least 1.
• booster set multipliers are a plain number such as 2 or 1.5. Durations are a bare number of seconds or a token string like 30m, 1h30m, 1d, 2w.

Permissions

• optimalafkzone.use - /afkzone and /shardshop (default: everyone)
• optimalafkzone.shop - open the shard shop (default: everyone)
• optimalafkzone.admin - every admin command, the selection wand and /afkzone shards <player> (default: op)
• optimalafkzone.booster.<n> - permanent shard multiplier, for example optimalafkzone.booster.2 = ×2 and optimalafkzone.booster.1.5 = ×1.5. The prefix is configurable. Not declared by default, grant it explicitly (a * wildcard does not count).

Zones, shops, shop items and boosters can each require their own node through a Permission key in their file.

Placeholders

Requires PlaceholderAPI.

Placeholder	Value
%optimalafkzone_shards%	Shard balance, formatted with Settings.Number-Format.
%optimalafkzone_shards_raw%	Shard balance as a plain number.
%optimalafkzone_afk_time%	Total AFK time, formatted (1d, 2h, 5s).
%optimalafkzone_afk_time_raw%	Total AFK time in seconds.
%optimalafkzone_booster%	The player’s effective shard multiplier (the highest of permission and active booster), for example 2 or 1.5. 1 with none, and for offline players.
%optimalafkzone_booster_duration%	Time left on the active booster, Permanent for one without an expiry, None without a booster.
%optimalafkzone_zone%	Display name of the zone the player is in, None outside a zone or in a zone they cannot access.
%optimalafkzone_next_reward%	Countdown to the next payout, 0s outside a zone.
%optimalafkzone_zones%	Number of loaded zones.
%optimalafkzone_zone_players_<id>%	Players currently in zone <id>. 0 for an unknown zone.
%optimalafkzone_shop_rotation_<id>%	Countdown to shop <id>’s next rotation. None for an unknown or non-rotating shop.

zones, zone_players_<id> and shop_rotation_<id> work without a player (in a scoreboard, hologram or console). Balances and AFK time are read from loaded player data, so they are meant for online players.

Actions

One syntax is shared by Enter-Actions, Leave-Actions, reward Actions, booster Consume-Actions and shop item Actions. A line with no [tag] runs as a console command, so - "eco give %player% 25" works as written.

Action	Does
[message] <text>	Send a chat message. [center] centres the line.
[broadcast] <text>	Send a message to every player.
[actionbar] <text>	Show an action bar message.
[title] <title>;<subtitle>;<fadeIn>;<stay>;<fadeOut>	Show a title. Times are in ticks; omitted times default to 10, 40, 10.
[sound] <NAME>;<volume>;<pitch>	Play a sound to the player.
[command] / [console] <cmd>	Run a command from console.
[player] <cmd>	Run a command as the player.
[shards] <amount>	Give shards directly (no booster multiplier, no message).
[close]	Close the open menu.

A well-formed tag the plugin does not know does nothing.

Every action resolves {player}, %player%, {uuid} and, with PlaceholderAPI, any %...% placeholder. Some places add their own tokens:

Where	Extra tokens
Zone Enter-Actions, Leave-Actions, Rewards	{zone}, {zone-id}, {reward-time}, {players}
Booster Consume-Actions	{booster}, {multiplier}, {duration}
Shop item Actions	{item}, {price} (the raw price)

Folia ordering

Console commands (untagged, [command] and [console]) run on the global thread. On Folia, zone rewards fire from the player’s region thread, so there console commands land one tick after the tagged actions in the same list. Console-to-console order is preserved. If a [player] action depends on a console command earlier in the same list, split them across two lists or let the console command do the whole job.

Displays

Each zone has its own Action-Bar-Settings and Boss-Bar-Settings, both rendered on the zone tick. They accept these tokens:

Token	Value
{next}	Countdown to the next payout.
{percent}	Progress toward the next payout, 0 to 100.
{zone} / {zone-id}	Zone display name / zone id.
{reward-time}	The zone’s Reward-Time in seconds.
{players}	Players currently in the zone.
{session}	Time spent in the zone this visit.
{total}	The player’s total AFK time.
{shards} / {currency}	The player’s balance and the matching currency name.
{player}	The player’s name.

• Boss bar Color: PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
• Boss bar Style: PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, NOTCHED_20 (Bukkit’s SOLID and SEGMENTED_* names are accepted too)
• Progress: true drains the bar from full to empty as the payout approaches and refills it on each payout; false keeps it full

The action bar is the expensive one

An action bar has to be re-sent continuously or the client fades it out, so it costs a packet per player per send. A boss bar only sends when it changes. Action-Bar-Settings.Interval (default 40 ticks) throttles the sends; disabling the action bar and letting the boss bar show the countdown is the cheapest setup.

Formatting

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b,c>, <rainbow>, <bold>, <#RRGGBB>, <solid:HEX>, …) and, with PlaceholderAPI installed, %...% placeholders. Gradients work in action bar and boss bar formats too, {next} included.

Durations ({next}, {session}, {total}, booster durations, shop rotation timers) are printed as 1d, 2h, 5s, with zero units dropped and 0s for nothing left.

Reference

• Install: Installation
• Set up a zone: Creating AFK Zones
• Shards, boosters and the shop: Setting Up the Shard Shop
• Config files: config.yml · zones · messages.yml · boosters · shops · confirm.yml