Design rule: missing/unmatched command argument opens a picker, never just usage text

[tastybento]

Motivation

The current pattern when a command is missing or given a wrong argument is: print an error, print usage, sometimes dump help. New players do not read any of it — they retype variations until they give up. The observed worst cases are /[gamemode] go <name> with multiple islands (multi-word, colored names typed wrong) and the team invite flow.

Proposal: a design rule

If a command needs an argument and can enumerate the valid values, running it bare (or with an unmatched value) opens a picker — it never just prints usage.

The error message is the menu. Concretely:

• /[gamemode] go with multiple islands/homes → island picker (one entry per destination, click to teleport). Today IslandGoCommand does an exact containsKey match on the joined args and on failure prints the valid names as plain, non-clickable chat (src/main/java/world/bentobox/bentobox/api/commands/island/IslandGoCommand.java).
• /[gamemode] team invite → nearby/online players picker. Precedent already exists: IslandTeamInviteGUI — this rule generalizes what the team command already started.
• Same shape applies to coop, trust, ban, expel, warps, etc., in core and addons.

Supporting API

Rather than every command hand-rolling this, give CompositeCommand an overridable hook, e.g.:

/**
 * Called instead of showing usage when required args are missing/unmatched
 * and the command can enumerate valid choices.
 * @return true if a picker was opened (suppresses the usage message)
 */
protected boolean openPicker(User user, List<String> args) { return false; }

Commands that can enumerate their argument space implement it; everything else keeps today's behavior. The picker itself is a Panel today, and becomes a Dialog when the Dialogs API lands (see related issue) — the hook is presentation-agnostic.

Complementary low-cost fix

Even with a picker, typed input should be forgiving. IslandGoCommand's name match should be case-insensitive, strip color codes, collapse spaces/underscores, and accept a unique prefix (/is go hap → "Happy Place"). This is a small, self-contained change to getNameIslandMap matching and worth doing first.

Where to start

• Reference implementation on IslandGoCommand: forgiving matching + a Panel-based picker on bare/unmatched input. It is the single highest-friction command and exercises the openPicker hook design.
• Then sweep core commands that can enumerate (team invite/coop/trust, ban, expel, deletehome/renamehome), and document the rule for addon authors.

Open questions

• Bare /[gamemode] go with one island must keep teleporting immediately (current behavior) — the picker only appears for genuinely ambiguous input.
• Console senders and command blocks must keep the text path; the hook should only fire for players.

Related design issues

• Design: Dialogs API — modal dialogs alongside Panels for high-friction player flows #3021 — Dialogs API
• 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: did-you-mean layer — intercept unknown commands and suggest the intended BentoBox command #3027 — did-you-mean unknown-command interception

[mrfloris]

i also think that a way to communicate to the player what's expected of them .. /is resolving to "try /oneblock instead, or /skyblock.." or to have a list of 'capture failed commands true/false, with failed-commands-list: is island ob 1block' etc that then opens the /oneblock menu or /oneblock help, or whatever we configure. so we can choose the preference per server without having to have 50 alias commands for all the gametypes just to tell them that our server has multiple gametypes like /skyblock and /oneblock