Skip to content
BattleStudio Wiki

Information

OptimalAFKZone turns cuboid regions into rewarding AFK zones. Standing in a zone accrues time, and every Reward-Time seconds the player is paid - a weighted roll from the zone’s rewards, a number of shards, or both. Shards buy items from a rotating shop, and boosters multiply payouts.

  • Software: Paper / Folia (and Paper forks)
  • Minecraft: 1.20.4 → 1.21.11+
  • Java: 21+ (required)
  • Soft dependency: PlaceholderAPI

Features

Section titled “Features”
  • Cuboid AFK zones that pay players on a timer
  • In-game zone creation with a selection wand and live particle outline
  • Shards currency (name/format configurable, optional abbreviation)
  • Weighted reward groups per zone, or a flat shard payout, or both
  • Per-zone reward mode (Shards / Commands / Both)
  • Rotating shard shop with weighted stock, per-player limits 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
  • Full PlaceholderAPI support
  • Folia-ready (region schedulers throughout) and heavily optimized

Commands

Section titled “Commands”

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

  • /afkzone - show your AFK zone progress · optimalafkzone.use
  • /afkzone shards - view your shard balance · optimalafkzone.use
  • /afkzone shards <player> - view another balance · optimalafkzone.admin
  • /afkzone shop - open the shard shop · optimalafkzone.shop
  • /afkzone booster - view your active booster · optimalafkzone.use

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> - delete a zone
  • /afkzoneadmin list - list every zone
  • /afkzoneadmin tp <zone> - teleport to a zone’s center
  • /afkzoneadmin outline <zone> - toggle a zone’s particle outline
  • /afkzoneadmin shards <give|take|set> <player> <amount> - manage balances (works offline)
  • /afkzoneadmin booster give <player> <booster> [amount] - give a booster item
  • /afkzoneadmin booster <set|remove> <player> [multiplier] [duration] - set/remove a booster
  • /afkzoneadmin reload - reload all configs (keeps active sessions)

Permissions

Section titled “Permissions”
  • optimalafkzone.use - /afkzone command (default: everyone)
  • optimalafkzone.shop - the shard shop (default: everyone)
  • optimalafkzone.admin - every admin command + /afkzone shards <player> (default: op)
  • optimalafkzone.booster.<n> - permanent shard multiplier, e.g. optimalafkzone.booster.2 = ×2, optimalafkzone.booster.1.5 = ×1.5. Highest of (permission, active booster) wins - they never stack.

Individual zones can also require their own node via Settings.Permission in the zone file.

Placeholders

Section titled “Placeholders”

Requires PlaceholderAPI.

  • %optimalafkzone_shards% / %optimalafkzone_shards_raw% - shard balance
  • %optimalafkzone_afk_time% / %optimalafkzone_afk_time_raw% - total AFK time
  • %optimalafkzone_booster% / %optimalafkzone_booster_duration% - active booster + remaining time
  • %optimalafkzone_zone% - the zone the player is in
  • %optimalafkzone_next_reward% - countdown to next payout
  • %optimalafkzone_zones% - number of configured zones
  • %optimalafkzone_zone_players_<id>% - players in zone <id>
  • %optimalafkzone_shop_rotation_<id>% - countdown to shop <id> rotation

Actions

Section titled “Actions”

One syntax is shared by Enter-Actions, Leave-Actions, reward Actions, booster Consume-Actions and shop Actions. A line with no [tag] runs as a console command.

  • [message] <text> - chat message
  • [broadcast] <text> - server broadcast
  • [actionbar] <text> - action bar message
  • [title] <title>;<subtitle>;<fadeIn>;<stay>;<fadeOut> - title (timings in ticks)
  • [sound] <NAME>;<volume>;<pitch> - play a sound
  • [command] / [console] <cmd> - run as console
  • [player] <cmd> - run as the player
  • [shards] <amount> - give shards
  • [close] - close the open menu

Tokens: {player} / %player% / {uuid} everywhere; PlaceholderAPI resolved; zone actions also get {zone}, {zone-id}, {reward-time}, {players}.

Displays

Section titled “Displays”

Per-zone Action-Bar-Settings and Boss-Bar-Settings. Both accept these tokens: {next}, {percent}, {zone}, {zone-id}, {reward-time}, {players}, {session}, {total}, {shards}, {currency}.

  • Boss bar Color: PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
  • Boss bar Style: PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, NOTCHED_20
  • Progress: true drains the bar toward the next payout; false keeps it full

The action bar is the plugin’s most expensive feature (it must be re-sent continuously). Raise Action-Bar-Settings.Interval (default 40 ticks) or disable it and let the boss bar show the countdown to cut cost.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient>, <rainbow>, <bold>, …), and PlaceholderAPI %...%.

Reference

Section titled “Reference”