Skip to content

Admin Tools#

BentoBox gives server admins a range of tools to manage the game, investigate problems, and keep things running smoothly — all without needing to edit files manually.

The Management Panel#

The main admin hub is the Management Panel, opened with: 

/bentobox manage
(or its alias /bbox manage)

From here you can see all running game modes, active islands, and basic server health at a glance.

The /bentobox Command#

All top-level BentoBox administration goes through /bentobox (alias /bbox):

Command What it does
/bentobox version Shows BentoBox version and all loaded addons. Always include this when reporting bugs.
/bentobox manage Opens the Management Panel GUI
/bentobox reload Reloads BentoBox config files and locales without a full server restart
/bentobox catalog Opens the addon catalogue
/bentobox perms Shows effective permissions for BentoBox and all addons
/bentobox rank Lists, adds, or removes custom ranks

Per-Game-Mode Admin Commands#

Each game mode has its own admin command. For BSkyBlock it's /bsb, for AcidIsland it's /acid admin, and so on. These give you controls specific to that game mode:

Command What it does
/[admin] info <player> Shows full details of a player's island. (3.22.4) If the player has several islands in the world (own and team), every island is listed, each with its name
/[admin] info <player> [island name] (3.22.4) Shows just the named island. Accepts island names and home names, matched forgivingly (case-insensitive, unique prefix), with tab completion; an unknown name lists the valid ones
/[admin] delete <player> Deletes a player's island
/[admin] delete (3.19.0) With no player argument, soft-deletes the island you are standing on after confirmation (refused if it still has a team)
/[admin] undelete (3.19.0) Clears the pending-deletion status of the island you are standing on, leaving it unowned, before its region files are purged
/[admin] register <player> Registers an unowned island to a player. On an island pending deletion this now shows a confirmation prompt and cancels the deletion instead of refusing
/[admin] setrange <player> <range> Changes a player's island protection range
/[admin] range removebonus <player> [id] Removes all bonus protection ranges from a single island, or just those for a given id
/[admin] range purgebonus <id> Removes a bonus range id from every island in the world — ideal after uninstalling an addon that granted bonus ranges. The scan runs asynchronously so it won't freeze large servers
/[admin] settings Opens the world settings panel for admins
/[admin] settings <player> Opens the island settings panel for a specific player
/[admin] why <player> Starts tracking why a player can or cannot do something (see below)
/[admin] reload Reloads the game mode's config
/[admin] blueprint Opens the Blueprint Manager GUI

The exact admin command prefix depends on the game mode's configuration. Check the game mode's documentation for its specific command.

The "Why" Diagnostic Tool#

One of the most useful admin tools is the why command. If a player reports that they can't do something on their island (or that they can do something they shouldn't), run:

/[admin_command] why <player>

After that, the server console will log the reason for every action that player takes — whether it was allowed or blocked, and which protection flag caused it. This makes it easy to diagnose misconfigured permissions without guessing.

To stop tracking, run the command again.

Admin Settings Panel#

The admin settings panel (opened with /[admin] settings) controls world-wide defaults — settings that apply everywhere in the game mode's world, not just on one island. This includes:

  • Default protection flags for new islands
  • World-wide restrictions (e.g. creeper explosion damage, piston behaviour)
  • Visibility settings for the player settings panel (hide flags you don't want players to change)

See Protection for a full explanation of the flag system.

Permissions-Based Control#

BentoBox is heavily permission-based. Almost everything — from how many homes a player can have, to whether they can fly, to the size of their island — can be controlled by giving or withholding permissions through your permissions plugin (e.g. LuckPerms).

Tip

Run /bentobox perms in the console to see a list of all permissions registered by BentoBox and its addons in YAML format. This is useful for configuring your permissions plugin.

Database Management#

BentoBox supports several database backends for storing island and player data:

  • JSON (flat file) — the default; easy to set up, no extra software needed
  • MySQL (5.7+)
  • MariaDB (10.2.3+)
  • MongoDB (3.6+)
  • SQLite (3.28+)
  • PostgreSQL

The database type is set in BentoBox's config.yml. To migrate from one database type to another without losing data, use: 

/bentobox migrate

Warning

Always take a full backup before migrating databases.

Reloading Without Restarting#

After changing a config file, you can apply it without fully restarting the server: 

/bentobox reload
This reloads BentoBox and all addons, including locales. Note that some changes (like world generation settings) always require a full restart to take effect.

Changelog#

What's new in v3.22.4

Released: 2026-09-06

A bug-fix and performance release. Compatibility: Paper Minecraft 1.21.x – 26.2, Java 25+.

  • 🔡 /[admin] info <player> shows every island. All of a player's islands in the world (owned and team) are listed, each block headed by the island name, and a new optional [island name] argument picks just one — see the command table above. Name matching is forgiving (exact, then case- and space-insensitive, then unique prefix), multi-word names need no quotes, and tab completion offers the player's island and home names.
  • ⚙️ Island history cap. A new island.history.max-entries option in config.yml caps how many history (log) entries each island keeps; the oldest are dropped first. The default 0 means unlimited, so existing servers keep their current behaviour. Capping can undercount the historical-members placeholder once old JOINED entries are dropped.
  • 🐛 Purge no longer crashes. /[admin] purge <days> confirm failed with IslandEvent may only be triggered synchronously on the first fully reaped island and left its database row behind. Island events are now fired on the main thread after the async region deletion.
  • 🐛 Sub-command labels no longer change. Typing an alias such as /ob h renamed the shared go command to h in everyone's tab completion and help — much more visible since Brigadier registration in 3.22.0. Fixed; the home / h aliases are unchanged.
  • 🐛 Player heads resolve through the server. Online players' heads come from their live profile and everyone else is looked up in Paper's own profile cache before falling back to mc-heads or Mojang, so panels such as TopBlock show real heads instead of Steve after rate limits.
  • ⚡ Performance: bounds checks no longer allocate, map sweeps use iterators, and a shared GSON instance replaces per-call construction.

🔡 Locale note. commands.admin.info.parameters now reads <player> [island name] and a new key commands.admin.info.island-name was added. All 24 bundled locales are updated; if you maintain a custom locale file, add the new key or the admin info block will show the raw key for the island name line.

Release v3.22.4

What's new in v3.22.3 — bStats opt-out & Paper 26.2

Released: 2026-08-22

Mostly a bug-fix and API release. Compatibility: Paper Minecraft 1.21.5 – 26.2, Java 25+.

  • ⚙️ bStats metrics opt-out. A new general.metrics option in config.yml (default true) lets you disable BentoBox's anonymous, aggregate usage statistics without touching the global switch in plugins/bStats/config.yml, which turns bStats off for every plugin on the server. Set it to false and restart — the collector is registered at startup, so /bbox reload is not enough. No personal data is ever sent; see Privacy & Data Collection.
  • 🔺 Built against Paper 26.2 and Adventure 5. Addon authors: Adventure 5 seals Component (Mockito can no longer mock it) and replaces ClickEvent.value() with payload(). Addons already deployed on a 26.2 server may be affected at runtime; recompiling against BentoBox 3.22.3 surfaces any issues at compile time — see PR #3067 for the full removal list. Server admins need do nothing.
  • 🔲 Dialog grid layout for addon developers. DialogBuilder#columns(int) lays a multi-action dialog's buttons out in a grid instead of the default two-wide list, and DialogButton gains a width (1–1024) plus withWidth(int). Existing callers are unaffected.
  • 🐛 Player-head 429 spam fixed. Opening a panel with player heads (a top-ten list, say) could flood the console with HTTP 429 errors from sessionserver.mojang.com, because heads delivered without texture data were re-resolved on every open. Texture-less heads now degrade to a plain head, and a failed fetch no longer evicts a cached head that already works.
  • 🐛 YAML numbers load into the declared field type. A config value such as 20, written without a decimal point, now loads correctly into double, float and long fields instead of throwing ClassCastException.
  • 🐛 Literal colour names in panels. The Management panel showed addon names like whiteChallenges after a colour refactor; fixed.
  • 📄 Published JSON Schemas (draft 2020-12) for the .blueprint and blueprint-bundle file formats.

Release v3.22.3

What's new in v3.22.2

Released: 2026-08-10

A bug-fix patch on top of 3.22.0 — no new features, config keys or locale changes; a drop-in replacement. There is no 3.22.1 release. Compatibility: Paper Minecraft 1.21.5 – 26.2, Java 25+.

  • 🔺 🐛 Player name lookups resolve to the right account. /[player_command] team trust <name> and /[player_command] info <name> could silently answer for a UUID that had not held that name in months: superseded name records were never deleted from the database, and the lookup took the first match. Names are now matched ignoring case, stale records are deleted, and online players are checked first. Take a backup before updating — existing databases heal themselves as players log in (the purge runs once per rename, not per join) and no manual migration is needed.
  • 🐛 Bedrock players can use panels again. Geyser expands one tap into several Java click packets in the same tick, and the panel.click-cooldown-ms check introduced in 3.22.0 was swallowing the one that mattered — every tap got slow-down and nothing happened. Same-tick clicks are now treated as one gesture; spam protection is unchanged at one action-bearing click per tick.
  • 🐛 A disabled addon no longer leaves broken commands behind. A game mode dropped for a missing dependency (ChunkBlock without Level, for instance) kept its commands registered, and every subcommand threw an NPE. Commands, flags and listeners are now all withdrawn when an addon fails to enable.
  • 🐛 Returning from a standard nether lands you on your own island. With a shared nether and create-and-link-portals: false (AOneBlock's default), players coming back through a portal were dumped on whichever island sits nearest 0,0. The destination now falls back to the island's home location.

Release v3.22.2

What's new in v3.22.0 — Brigadier commands

Released: 2026-08-01

A commands-and-visibility release. Compatibility: Paper Minecraft 1.21.5 – 26.2, Java 25+.

  • ⚙️ 🔺 Commands are registered with Paper's Brigadier API. Players now see BentoBox subcommands and completions as they type — /island t… offers team in the chat bar — instead of the client knowing nothing until enter or TAB. The subcommand tree is advertised to a depth of 4; deeper subcommands still work, they just are not pre-advertised. Aliases and the plugin:label form are sent as redirects rather than duplicated trees. A new general.brigadier-commands option in config.yml defaults on; set it to false and /bbox reload to fall back to the legacy command map if another plugin conflicts. BentoBox also falls back automatically if it cannot hook the registrar.
  • 🔺 Structure searches are suppressed automatically in worlds that generate no structures. A cartographer rolling an explorer-map trade — or an Eye of Ender, dolphin or treasure map — used to run a synchronous structure search that could never succeed in a void world, scanning to the radius cap and blowing past the 60-second watchdog. BentoBox now asks the world's generator whether it places structures at all and skips the search if it does not, with no configuration needed. AOneBlock and BSkyBlock get this automatically; SkyGrid, Boxed, CaveBlock and AcidIsland are unaffected because they do generate structures. A per-world structures entry of true still force-enables a structure, as an escape hatch for converted worlds that contain pre-existing ones. This complements the opt-in world.disabled-structures list added in 3.20.0.
  • /island settings now opens out in the world. Players away from any island, or in a game mode where they never own one, used to get "You do not have an island!". The panel now opens with a read-only World Protections tab showing which protection flags are active for the world — which is exactly what governs them where they are standing. See Protection.
  • 🐛 Addon data queued during shutdown is no longer discarded. Anything an addon saved from onDisable() was queued into a database pipeline that had already stopped draining, so it was silently, intermittently lost on every restart. Nine bundled addons save on disable — Boxed, AOneBlock, Raft, Challenges, Limits, DragonFights, CheckMeOut, ControlPanel and InvSwitcher — and with InvSwitcher the stale stored inventory was then re-applied on join, making it a rollback rather than just a lost write. Shutdown writes are now drained before the database closes.
  • 🐛 BentoBox commands work from NPCs, signs and GUI plugins again. Brigadier registration had taken BentoBox commands out of the Bukkit command map that other plugins dispatch through, so an NPC running /oneblock go answered with the server's no-permission message and ran nothing. Commands are now registered with the command map as well. This only ever affected 3.22.0 development builds.
  • 🐛 Island.setFlag no longer discards writes. Setting a protection rank on an island that had no entry yet for that flag — which is every freshly created island — silently did nothing. SETTING and WORLD_SETTING flags were unaffected.
  • 🐛 Repeated warnings stay throttled. A player alternating between two different limit messages bypassed the 4-second notification cooldown entirely. Each distinct message is now throttled independently.
  • 🐛 BlueMap marker sets stay in their own worlds. An addon's marker set no longer appears in the sidebar of every other map on the server, and createMarkerSet() / removeMarkerSet() no longer throw during a /bluemap reload.
  • 🐛 Multiverse tidy-up. BentoBox worlds now get auto-load: false even when Multiverse already knew about them, and the dead seed-world (<world>/bentobox) registration is gone. Existing stale entries still need /mv remove.
  • 🐛 Flags from addons dropped for missing dependencies are cleaned up. An addon whose hard dependency was absent had already registered its flags and listeners before being dropped, leaving listeners firing for a world that never existed.
  • Six new bStats charts report addon and game mode versions, addon API levels, settings changed away from their defaults, and how and where commands fail. Only the failure kind and a stable permission-derived command key are submitted — never arguments or player names.
  • 🔡 Traditional Chinese (zh-TW) locale added, contributed by @qwe664. No existing locale keys changed, so custom locale files need no work.

Release v3.22.0

What's new in v3.21.0 — modal dialogs

Released: 2026-07-22

A player-experience release. Compatibility: Paper Minecraft 1.21.5 – 26.2, Java 25+.

  • ⚙️ 🔡 Modal dialogs for high-friction flows. Sensitive-command confirmations, the /island go destination picker, team invites, and a first-join game-mode chooser can now appear as real modal dialogs the player cannot misread or scroll past. A new island.dialogs section in config.yml holds one toggle per flow — confirmations, go-picker and team-invites default on, game-mode-selection defaults off because it is intrusive by design. Dialogs need a Minecraft 26+ server; on anything older every toggle is ignored and the classic chat/command behaviour is used, so no action is needed there.
  • Forgiving /island go matching. /island go myisland, hom, or a name typed with the wrong case or a stray double space now teleports the player where they meant instead of failing an exact match and dumping the full list. See Home Locations.
  • 🔡 Locale note: new dialog keys (general.dialogs.*, plus dialog and picker keys under the confirmation, island go and team-invite commands) were added to all 22 bundled locales. Regenerate or update any custom locale files.
  • 🔧 Addon developers get the same world.bentobox.bentobox.api.dialogs API used by core — see Modal dialogs.

Release v3.21.0

What's new in v3.20.0 — command suggestions & core structure suppression

Released: 2026-07-11

A quality-of-life release. Compatibility: Paper Minecraft 1.21.5 – 26.2, Java 25+. Nothing changes on upgrade unless you opt in.

  • 🔡 ⚙️ Did-you-mean command suggestions. A mistyped command like /teams or /island invit Floris now offers the closest matching BentoBox command — clickable, or accept by typing yes/y within 30 seconds — instead of dumping the help text. Suggestions match labels and aliases across every command tree, are permission-filtered, and use the game-mode world the player is standing in to disambiguate. Two new toggles under general.did-you-mean in config.yml — unknown-commands and subcommands — both default on; set either to false and /bbox reload to disable.
  • ⚙️ 🔺 Core vanilla-structure suppression for every game mode. Disabling a vanilla structure is now a single core setting instead of a per-addon job. A new world.disabled-structures list in config.yml (applied to every BentoBox overworld/nether/end) stops the listed structures generating and skips them in structure searches — /locate, Eyes of Ender, explorer/treasure maps, dolphins and villager cartographer trades — fixing the long-standing /locate main-thread freeze and near-spawn structure leaks. Keys are case- and separator-insensitive (trial_chambers, ancient-city). A game mode can override the list per-structure. The list is empty by default, so behaviour is unchanged until you opt in.
  • 🔌 Nexo hook. BentoBox can now place and detect Nexo custom blocks and items, alongside the other custom-item integrations.
  • 🔌 Oraxen block placement. OraxenHook.placeBlock exposes Oraxen custom-block placement to addons, matching the other custom-block hooks.
  • 🔡 Locale note: three new general.did-you-mean keys were added to all 22 bundled locales, and the pre-existing missing key commands.admin.team.setowner.specify-island was filled in every non-English file. Regenerate or update any custom locale files.

Release v3.20.0

What's new in v3.19.0 — bed/anchor respawns now honored

Released: 2026-07-08

Compatibility: Paper Minecraft 1.21.5 – 26.2, Java 25+.

  • 🔡 New FISHING protection flag. Stops players fishing into protected areas from outside the island (the flag checks the hook's location). Defaults to visitor rank, so nothing changes until you raise it.
  • 🔺 Bed & respawn-anchor spawns are now honored. Dying on an island now respawns you at your bed or charged respawn anchor when it's on an island you're a member of. Controlled by the new BED_ANCHOR_RESPAWN world setting (enabled by default); economy-sensitive servers that want the old "always respawn at island home" behaviour should disable it.
  • 🐛 End exit portal no longer dumps you at world spawn. Jumping through the end exit portal now routes you to your safe island home on multi-gamemode servers.
  • 🐛 Item frames and paintings survive blueprints. Frames keep their facing and contents, and paintings restore their artwork, instead of popping off or facing the wrong way.
  • 🔡 Recover islands pending deletion. New /[admin] undelete, a stand-on /[admin] delete (no player argument), and a confirmation prompt on /[admin] register can now rescue soft-deleted islands before their region files are purged (see the Per-Game-Mode Admin Commands table above).
  • ⚙️ BlueMap island layer survives reloads. Owner pins and area boxes no longer vanish after /bluemap reload. A new bluemap section in config.yml adds island-markers and island-areas toggles (both default true), mirroring the Dynmap toggles, plus marker customization.
  • ⚙️ Configurable team panel button icons + member/prospect text. The STATUS, RANK-filter and INVITE buttons in the team panel now honour the icon: set in team_panel.yml, and the member/prospect button name and description are now driven by locale keys. Defaults reproduce the previous appearance exactly.
  • ⚡ Settings-GUI click spam no longer spikes MSPT. Spam-clicking /is settings dropped from ~30–40 MSPT to negligible via in-place panel refresh and a translation cache.

Release v3.19.0

What's new in v3.18.0 — Minecraft 26.2 support requires Java 25 (server)

Released: 2026-06-27

  • 🔺 Minecraft 26.2 support + Java 25. BentoBox now runs on the Minecraft 26.x line (26.2 supported at runtime) and the build has migrated to the Java 25 toolchain. Your server must run on a Java 25-capable Paper build for the 26.x line. Already-built addon jars keep working unchanged — only addon developers recompiling against this release need to move their own build to Java 25. Compatibility: Paper Minecraft 1.21.5 – 26.2, Java 25+.
  • ⚙️ Dynmap island marker / area toggles. A new dynmap section in config.yml adds island-markers (the house icon at the centre of every island) and island-areas (the protected-area border box) switches. Both default to true, preserving existing behaviour; set either to false and run /bbox reload to hide those overlays on servers where dense islands flood the map.
  • Admin range bonus management. New /[admin] range removebonus and /[admin] range purgebonus commands clear bonus protection ranges from one island or every island — ideal after uninstalling an addon that granted them (see the Per-Game-Mode Admin Commands table above).
  • 🐛 /is team setowner is no longer blocked by the island limit when transferring to an existing team member.
  • 🐛 The Vault hook now retries after addons enable, fixing economy integration that depended on load order.

Release v3.18.0

What's new in v3.18.1

Released: 2026-07-01

Maintenance release.

  • 🐛 Multi-line lore & names keep their colour. Text after the first line of a GUI tooltip no longer falls back to the default purple — the serializer now re-emits the active colour (and decorations) after each newline, fixing tooltips across all addons.

Release v3.18.1