commands-api-ADR-003 - Registration seam via a CommandRegistrar (Bukkit), neutral command roots¶
Status: Accepted Date: 2026-06-21
Context¶
The /rtp command tree is authored once and executed across platforms. On the Bukkit family the root command class (RTPCmdBukkit) was forced to extend BukkitTreeCommand extends org.bukkit.command.BukkitCommand purely so the object was a CommandExecutor / TabCompleter that could be dropped into the legacy command map. Registration was thus baked into the supertype a command had to extend, which meant:
- The Bukkit root could not be authored as the same neutral
BaseRTPCmdImplthat Fabric / NeoForge already use (their roots are wrapped by theBrigadierCommandAdapterrather than being a platform command). - The RTP-specific dispatch logic (teleport-path sender checks, the
RTPCmdcooldown / processing / reload guard, the help-row clickable rendering, success / fail event firing) was tangled with the platform command supertype.
This is the companion change to commands-api-ADR-002 (which moved reply-message delivery to a MessageSink). With message delivery already off the supertype, the only remaining reason to subclass a Bukkit command type was registration.
Decision¶
Registration is owned by commands-api, not by the command supertype:
commands-apiprovidesBukkitCommandRegistrar(aCommandExecutor/TabCompleter) that wraps a platform-neutralTreeCommandroot and binds it onto one or morePluginCommands viaregister(String... names). CallerUUIDresolution, the installedMessageSinkreply consumer, and tab-completion (root.onTabComplete) mirror the formerBukkitTreeCommandbehaviour exactly.- The legacy
String[]-args command path is delegated to an optionalStringCommandDispatcherfunctional seam, so a command tree can inject pre-dispatch behaviour (RTP's sender checks + theRTPCmdguard) without subclassing a platform command type. When no dispatcher is supplied the registrar falls back to the genericTreeCommandargs dispatch.
Consequently the Bukkit /rtp root (RTPCmdBukkit) now extends BaseRTPCmdImpl implements RTPCmd - the same neutral supertype Fabric / NeoForge use. It keeps its RTP-specific concerns as ordinary class members (they live in rtp-plugin and are platform-legitimate there):
successEvent/failEventcontinue to fire the BukkitTeleportCommandSuccessEvent/TeleportCommandFailEventfor third-party observability.- the help-row clickable
SendMessagereply consumer stays on the parametriconCommand. - the teleport-path sender-check list is lifted from
Predicate<CommandSender>to the platform-neutralPredicate<RTPCommandSender>(it already received a neutral guard via an at-call-site adapter; the adapter is removed). The legacy command entry is exposed asRTPCmdBukkit#dispatchString(UUID, String, String[])and handed to the registrar.
Consequences¶
-
Positive:
- The Bukkit
/rtproot is a neutral command class; adding a platform is "implement a registrar (or reuse the Brigadier bridge) + aMessageSink", not "subclass a platform command type". - The legacy Bukkit command-map path is preserved (no loss of Spigot support); it moves from "the supertype you extend" to "a thing the registrar wraps".
- Behaviour is preserved: the Bukkit dispatch (sender checks, the
RTPCmdguard, help-row rendering, events) runs exactly as before throughdispatchString; Fabric / NeoForge are untouched (their own root classes do not override the guard path, so no cross-platform guard behaviour changes).
- The Bukkit
-
Negative / Trade-offs:
BukkitTreeCommandremains incommands-apias a still-valid base for other consumers (notablyeffects-api's command classes), which are intentionally out of scope here and unaffected.- The
StringCommandDispatcheris a small additional seam; it is optional and only used where a command needs pre-dispatch behaviour beyond the generic args dispatch.
Scope¶
This ADR covers the Bukkit registration seam and the conversion of the /rtp Bukkit root to a neutral type. It does not convert effects-api's BukkitTreeCommand subclasses, and it does not unify the three platform root classes into a single shared class (their menu wiring and parameter sources still differ); that further de-duplication is a separate change.
References¶
api/commands-api/src/main/java/.../bukkit/BukkitCommandRegistrar.javaapi/commands-api/src/main/java/.../bukkit/StringCommandDispatcher.javartp-plugin/src/main/java/.../bukkit/commands/RTPCmdBukkit.java- neutral root +dispatchStringrtp-plugin/src/main/java/.../bukkit/BootstrapSupport.java- registrar wiring- commands-api-ADR-002 - the message-delivery seam (Phase 1)
- commands-api-ADR-001 - the Fabric / NeoForge registration path