Design: Dialogs API — modal dialogs alongside Panels for high-friction player flows

[tastybento]

Motivation

Feedback from server owners is consistent: new players do not read chat, signs, or help text. They spend 10–15 minutes failing at basic flows — choosing between two islands with /[gamemode] go <name>, accepting a team invite, picking a game mode — and then quit. Inventory-GUI panels help, but they are dismissable, they compete with gameplay, and multi-word / colored island names still confuse players when a command has to be typed.

Minecraft now has a server-driven dialog system, exposed through Paper's Dialog API (io.papermc.paper.dialog.Dialog, DialogResponseView, and the io.papermc.paper.registry.data.dialog types — all present in our current paper-api 26.1.2 compile target). Dialogs are real modal UI: buttons, text inputs, multi-action screens, and they can be configured so Esc does not dismiss them. This is the "menu they can't click away" that server owners are asking for.

Proposal

Add a Dialogs API to BentoBox alongside the existing Panels API, so core and all addons can present modal choices without typing:

• New api/dialogs/ package mirroring the structure of api/panels/: a fluent builder (DialogBuilder in the spirit of PanelBuilder), localized titles/bodies via the existing User translation system, and a callback registry for button actions (the dialog equivalent of PanelListenerManager).
• Server owners should be able to choose per-feature between chat, panel (GUI), and dialog presentation where it matters, with dialogs becoming the default for the high-friction flows below.

First consumers (in rough order)

1. Confirmation prompts — ConfirmableCommand.askConfirmation(...) currently requires re-typing the command within a time window. A two-button dialog ([Confirm] / [Cancel]) is a drop-in replacement and the smallest end-to-end slice.
2. Team invites — auto-open an [Accept] / [Decline] dialog when an invite is received, instead of hoping the player finds and types /[gamemode] team accept.
3. /[gamemode] go island picker — when the player has multiple islands/homes, show one button per destination. Eliminates the multi-word-name problem entirely.
4. First-join game mode selection — when multiple game modes are installed, a non-dismissable "pick your game" dialog.

Where to start

• Model the package on src/main/java/world/bentobox/bentobox/api/panels/ and its builders/.
• First migration target: api/commands/ConfirmableCommand.java behind a config/per-command flag — small surface, immediately exercised by island reset etc.
• Dialog body text must be built as Adventure Components end-to-end. The legacy §-string round-trip used by some chat paths cannot carry click/interaction data, so the Dialogs API should consume the Component-based translation path from the start.

Open questions

• Addon-facing API surface: this becomes public API with binary-compatibility commitments, so the builder/type surface needs review before release (see the API stability notes in the repo).
• Bedrock players (Geyser): do dialogs translate to Bedrock forms, or do we need a fallback to Panels? Needs testing.
• How far to take "cannot close": non-dismissable dialogs are right for first-join onboarding but hostile elsewhere; the API should make dismissability an explicit builder choice.

Related design issues

• Design: command-friction telemetry via bStats custom charts #3022 — command-friction telemetry (bStats)
• Design: migrate command registration to Paper's Brigadier API (phased) #3023 — Brigadier migration
• Design rule: missing/unmatched command argument opens a picker, never just usage text #3024 — missing-argument-opens-picker rule
• Design: did-you-mean layer — intercept unknown commands and suggest the intended BentoBox command #3027 — did-you-mean unknown-command interception

[mrfloris]

We do not need dialogs for everything, but if someone gets an invite it's just text in the chat. It's clear to me on a daily basis that players do not read it or can't read more than two words. They are just too f dumb.. They need a [CLICK THIS WITH MOUSE] and a small [cancel] button. And just text "you are invited to play oneblock with %playername%"

And also, if someone's invite request has not been accepted, or expired, etc. It should properly communicate that to the island owner "That went wrong, try inviting again, or accept that they dont want to join your team".

Having /oneblock go actually be an island picker, and option to rename existing islands that you own .. would be fantastic.
if that's an old fashioned gui or a dialog window that pops up so they can't do anything but pick an island to avoid confusion.. excellent

Clear confirmation prompts using dialogs will be very nice.