Register commands with Paper's Brigadier API (#3023 phases 1 and 2)

[tastybento]

Closes #3023 (phases 1 and 2).

Replaces the SimpleCommandMap reflection in CommandsManager with Brigadier registration, and exposes the CompositeCommand subcommand tree to clients so completions appear while the player types rather than only after enter or TAB.

Phases 1 and 2 are done together deliberately: the registration shim alone carries the entire risk of the change with none of the player-facing benefit.

The timing problem, and why the dispatcher is captured

Paper only permits Brigadier registration inside the LifecycleEvents.COMMANDS callback. Probing the real ordering on a 26.2 server gives:

onEnable returns  ->  COMMANDS fires (cause=INITIAL)  ->  first server tick: completeSetup()

completeSetup() is where enableAddons() runs, so game mode commands such as /island and /acid do not exist yet while the lifecycle window is open. Using the registrar after the window closes throws No lifecycle owner context is set, and calling getDispatcher() on it then throws cannot access the dispatcher in this context.

Three escape routes were tested and rejected:

• Re-fire the event — CraftServer#syncCommands() does not re-run the COMMANDS lifecycle. Verified directly.
• Move the addon enable earlier — that was tried and reverted in This changes the loading to not be on STARTUP #2214, so the deferred tick has to stay.
• Use the registrar late — throws, as above.

What does work: the CommandDispatcher instance is the live one the server dispatches against. BrigadierCommandRegistrar captures it inside the window and registers nodes into it afterwards as addons come up. Those nodes survive syncCommands() and dispatch correctly for players and console.

Design consequences

• No stale references. Brigadier has no API for removing a node, so nodes never capture a CompositeCommand — they resolve it by label on every use. A reload that swaps the command objects leaves nothing stale behind, and a label that goes away is hidden because its requires predicate stops matching.
• Aliases and plugin:label are redirects, not duplicated trees. A game mode admin tree runs to dozens of nodes and every one of them is sent to every client.
• Console keeps seeing player-only commands, so /ai from console still reports "This command is only available in-game" rather than Brigadier's generic "unknown command".
• Literal tree is depth-capped at 4. Deeper subcommands still work — they fall through to the greedy argument — they are just not pre-advertised.

Config

Guarded by general.brigadier-commands (default true). Turning it off restores the legacy command map path, which is kept intact as the fallback and is also used automatically if the registrar cannot hook.

Testing

Verified on a Paper 26.2 test server with AcidIsland, AOneBlock, CaveBlock, Biomes, Challenges and Level:

• top-level commands and aliases (/bbox version)
• deep subcommands (/acid range set)
• namespaced form (/acidisland:acid version)
• unknown subcommand falling through to BentoBox's own error rather than Brigadier's
• player-only commands from console giving the correct message
• everything still working after /bentobox reload
• in-game client behaviour confirmed by @tastybento

Full test suite passes. New unit tests cover the raw command line tokenizing and the suggestion offset arithmetic — the parts that have to agree exactly with what CompositeCommand expects.

Left for phase 3

Deliberately not half-done here:

• No tooltips on subcommand names. A literal node's suggestion cannot carry one, and emitting a parallel tooltipped suggestion would show every subcommand twice, since Brigadier does not deduplicate across nodes.
• No typed arguments, so no red-underline validation or quoting-free multi-word island names yet.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ATRqygFLZ5CA3zrWmutx7H

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
10.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud