Commands API¶
Platform-agnostic command framework used by RTP. Commands form a tree of
nodes; arguments split into subcommands (bare tokens) and parameters
(key:value); execution is deferred onto a tick-budgeted pipeline.
Read this before touching the module — three concerns (syntax, permissions,
dispatch) share one onCommand name, which is the #1 source of confusion.
1. Module layout¶
commands-api/src/main/java/io/github/dailystruggle/commandsapi/
├── common/ platform-agnostic core
│ ├── CommandsAPI global state, pipeline, execute() budget
│ ├── CommandsAPICommand command contract
│ ├── CommandParameter parameter contract
│ ├── CommandExecutor pipeline work item (Runnable + future)
│ ├── Factory name→supplier registry
│ └── localCommands/TreeCommand default traversal / tab-complete / help
└── bukkit/ Bukkit bindings (optional)
├── BukkitCommand
├── BukkitParameter bridges UUID callerId → CommandSender
├── localCommands/BukkitTreeCommand
└── LocalParameters/ ready-made parameter types
Consumers depend on common.*. A platform adapter only supplies: sender
identity, message sink, permission resolver.
2. Core concepts¶
2.1 Tree¶
Each node exposes name(), permission(), description(), parent(), a
parameter map (getParameterLookup()), and a subcommand map
(getCommandLookup()). The root is the server-registered command (e.g.
/rtp). TreeCommand.onCommand / onTabComplete recurse with
(args, i, tempParameters).
2.2 Argument syntax — the cardinal rule¶
| Form | Meaning | Example |
|---|---|---|
name |
subcommand (positional) | reload |
name=value |
parameter | player=steve |
name=v1,v2 |
parameter, multi-value | player=a,b |
Delimiter: CommandsAPI.parameterDelimiter (=) is the sole parameter
separator (input and tab-complete). Multi-value delimiter:
multiParameterDelimiter (,). The legacy : separator is no longer
accepted; tokens like player:steve are treated as a bare subcommand
name and produce msgInvalidCommand.
A bare token (no
=) is always a subcommand name. It is never treated as a "default" parameter value. Unknown bare token →msgInvalidCommand.Note: a
:inside a parameter value is preserved (e.g. namespaced Minecraft IDs likebiome=iris:volcanic_ash_plains); only the parameter name/value separator is restricted to=.
2.3 Parameters¶
CommandParameter (abstract) supplies:
- Set<String> values() — legal values (tab-complete source).
- isRelevant: BiFunction<UUID,String,Boolean> — per-caller filter →
relevantValues(UUID).
- subParamMap — additional parameters unlocked once a specific value is
chosen (subParams(value)).
- permission() (gates visibility and use), description(), priority
(tab-complete ordering).
Bundled Bukkit impls: see bukkit/LocalParameters/Readme.md.
2.4 Caller identity¶
The core uses UUID callerId — player UUID, or CommandsAPI.serverId
(UUID(0,0)) for console. Adapters translate back to platform senders.
2.5 Permissions¶
Threaded as a Predicate<String> permissionCheckMethod. A subcommand or
parameter the caller lacks permission for is invisible, not forbidden:
absent from tab-complete, and using its name produces msgInvalidCommand /
msgBadParameter rather than a permission error. This prevents
permission-probing.
3. Execution pipeline¶
3.1 Two onCommand overloads — don't confuse them¶
-
Parser / dispatcher (implemented by
TreeCommand):Walks the tree, firesCompletableFuture<Boolean> onCommand( UUID callerId, Predicate<String> permissionCheckMethod, Consumer<String> messageMethod, String[] args, int i, Map<String,CommandParameter> tempParameters);msgInvalidCommand/msgBadParameteron failure, enqueues aCommandExecutoronCommandsAPI.commandPipeline. -
Business logic (override this when you write a command):
Receives already-parsed, already-validated parameters. Returnboolean onCommand(UUID callerId, Map<String,List<String>> parameterValues, CommandsAPICommand nextCommand);trueto continue intonextCommand.
Takes String[] args → parser. Takes Map<String,List<String>> → your code.
3.2 Pipeline¶
Parsed commands are deferred, not run inline. The host drains the queue per tick:
CommandsAPI.execute(); // up to ~50 ms (one tick)
CommandsAPI.execute(nanosBudget); // custom budget
execute(budget) runs at least one executor (so a starving queue still
progresses), then stops when elapsed + next.avgTime() > budget. Returns
remaining queue length. avgTime() is advisory but inaccurate values cause
tick overshoot.
Because execution is deferred and results are CompletableFuture<Boolean>,
tests must await the future — synchronous assumptions flake.
3.3 CommandExecutor¶
Holds (command, callerId, parameterValues, nextCommand, messageMethod?,
result). Equality is (command, callerId) — lets "same caller spams same
command" be deduplicated if desired.
4. Error reporting¶
Failures go through callbacks, never a magic boolean return.
msgInvalidCommand(callerId, arg[, msg])— bare token matching no visible subcommand (/rtp frobnicate). Platform adapters requiring auditing (RTP REQ-RTP-S-004) log atWARNING.msgBadParameter(callerId, name, value[, msg])—key=valuewhere key is unknown, value is empty, orisRelevant(callerId, value)is false.
Consequences:
- Do not hand-parse positional args in business-logic onCommand — the
parser already classified the bare token as a subcommand; a second parser
causes double-dispatch.
- Do not ignore the parser's returned future — await or return it, so
feedback (success or error callback) actually fires.
5. Tab completion¶
onTabComplete mirrors onCommand: same recursion, same permission filter.
Subcommand names and parameter keys suggest as bare words; parameter values
suggest as key=value, filtered by relevantValues(callerId). priority
orders parameters that match the same prefix.
6. Writing a command¶
public final class ReloadCmd extends SomeTreeCommand {
public ReloadCmd(CommandsAPICommand parent) {
super(parent, "reload", "rtp.reload", "Reload RTP configuration");
}
@Override
public boolean onCommand(UUID callerId,
Map<String,List<String>> parameterValues,
CommandsAPICommand nextCommand) {
RTP.getInstance().reload();
return true; // continue into nextCommand
}
@Override public long avgTime() { return 5_000_000L; /* 5 ms */ }
}
Registering on a tree node:
tree.addParameter("player", new OnlinePlayerParameter(
"rtp.other", "target player",
(sender, name) -> sender.hasPermission("rtp.other")
&& Bukkit.getPlayerExact(name) != null));
tree.addSubCommand(new ReloadCmd(tree));
7. New parameter type¶
public final class WorldParameter extends BukkitParameter {
public WorldParameter(String perm, String desc,
BiFunction<CommandSender,String,Boolean> isRelevant) {
super(perm, desc, isRelevant);
}
@Override public Set<String> values() {
return Bukkit.getWorlds().stream().map(World::getName)
.collect(Collectors.toSet());
}
}
Unlock further params once a value is chosen:
w.subParamMap.put("world_nether", Map.of("portal", new BooleanParameter(...)));
8. Common pitfalls¶
- Bare token ≠ default parameter.
/rtp steveis subcommandsteve, notplayer=steve. Add shorthand at the adapter layer before handingargstoTreeCommand. - Blocking on the parser's future on the main thread — the pipeline
runs on
execute(); awaiting inline deadlocks the tick meant to run it. - Calling
msgInvalidCommand/msgBadParameterfrom business logic — the parser already fires them; doing so duplicates player messages and audit log entries. - Hand-building
parameterValuesin tests — misses permission filter,isRelevantvalidation, and sub-param unlocking. Drive via the parser. - Treating permission-less elements as forbidden — they're invisible and produce "invalid command". For a distinct denial, check permission explicitly in the leaf before delegating.
- Bad
avgTime()— pipeline pacing relies on it.0on a 30 ms command overshoots ticks.
9. RTP integration¶
RTPCmddelegates parsing toTreeCommand.onCommand; it must not run its own positional loop (double-dispatch — see.junie/AGENTS.md).- Platform
BukkitBaseRTPCmdoverrides ofmsgInvalidCommand/msgBadParametermustRTP.log(Level.WARNING, msg)to satisfy REQ-RTP-S-004 auditing and surface inrtp test full. - Brigadier integration belongs in
commands-api, not per-platform adapters — see commands-api-ADR-001 (commands-api/docs/adr/commands-api-ADR-001-brigadier-bridge.md).
10. Cheat sheet¶
| Question | Answer |
|---|---|
Where does bare foo go? |
Subcommand lookup only. |
Where does foo:bar go? |
Parameter lookup only. |
Unknown foo? |
msgInvalidCommand(callerId, "foo"). |
Unknown / empty / rejected foo:bar? |
msgBadParameter(callerId, "foo", "bar"). |
| Who enforces permissions? | Caller-supplied permissionCheckMethod. |
Who runs my onCommand? |
CommandExecutor via CommandsAPI.execute(budget). |
| When? | Next tick that drains the pipeline. |
| Testing? | Await the parser's CompletableFuture<Boolean>. |