Help
Help topics can be added to your command using the withHelp()
, withShortDescription()
, withFullDescription()
or withUsage()
methods when registering a command. Help allows users to understand what your command does and provides them with a list of usage forms to aid in writing a command.
Parts of a help
A help topic consists of two mains parts:
- A short description which is displayed in a help list and displayed at the top of a help topic for that command
- A full description which is displayed in the "Description" section of a help topic
This can be seen with the following example, for a command /mycmd
. This example has the short description "Says hi", and a full description "Broadcasts hi to everyone on the server". The short help is shown in the help list, which (in this example) is viewed using /help 5
. The full description is shown for the help for the command on its own, which is viewed using /help mycmd
:
Help methods and semantics
The CommandAPI has three methods to register parts of a help. The withShortDescription()
sets the short description for the command, the withFullDescription()
sets the full description for the command and withHelp()
is a simple way to set both the short and full description at the same time. The withHelp()
method is the recommended method to use to set the help for a command.
If no short description is provided, the CommandAPI will attempt to use the full description if one is present. Note that this may be truncated automatically, so it is recommended to provide your own short description.
These are the following methods that the CommandAPI provides to set the help topic for a command:
CommandAPICommand withShortDescription(String description);
The withShortDescription
method simply sets the short description for the command. In the above screenshot, the short description is "Says hi".
CommandAPICommand withFullDescription(String description);
The withFullDescription
method sets the full description for the command. In the above screenshot, the full description is "Broadcasts hi to everyone on the server".
CommandAPICommand withHelp(String shortDescription, String fullDescription);
The withHelp
method sets both the short description and the full description at the same time.
Example - Adding help to a command
In this simple example, we implement the above screenshot's help topic. We register a command /mycmd
and use the withShortDescription
and withFullDescription
methods to create a help topic:
new CommandAPICommand("mycmd")
.withShortDescription("Says hi")
.withFullDescription("Broadcasts hi to everyone on the server")
.executes((sender, args) -> {
Bukkit.broadcastMessage("Hi!");
})
.register();
CommandAPICommand("mycmd")
.withShortDescription("Says hi")
.withFullDescription("Broadcasts hi to everyone on the server")
.executes(CommandExecutor { _, _ ->
Bukkit.broadcastMessage("Hi!")
})
.register()
commandAPICommand("mycmd") {
withShortDescription("Says hi")
withFullDescription("Broadcasts hi to everyone on the server")
anyExecutor { _, _ ->
Bukkit.broadcastMessage("Hi!")
}
}
We could also register this command using the withHelp
method instead:
new CommandAPICommand("mycmd")
.withHelp("Says hi", "Broadcasts hi to everyone on the server")
.executes((sender, args) -> {
Bukkit.broadcastMessage("Hi!");
})
.register();
CommandAPICommand("mycmd")
.withHelp("Says hi", "Broadcasts hi to everyone on the server")
.executes(CommandExecutor { _, _ ->
Bukkit.broadcastMessage("Hi!")
})
.register()
commandAPICommand("mycmd") {
withHelp("Says hi", "Broadcasts hi to everyone on the server")
anyExecutor { _, _ ->
Bukkit.broadcastMessage("Hi!")
}
}
Advanced help topics
For more control over help topics, the CommandAPI offers the following method, which allows you to provide your own HelpTopic
object:
CommandAPICommand withHelp(HelpTopic helpTopic);
Example - Adding locale-specific help
In this example, we implement locale-specific help so players can see help in their desired language. To do this, we must make use of the Bukkit HelpTopic
object which gives us more control over the content of help that is displayed to a player:
public HelpTopic makeHelp(String command) {
return new HelpTopic() {
@Override
public String getShortText() {
return "Says hi";
}
@Override
public String getFullText(CommandSender forWho) {
String helpText = "";
if (forWho instanceof Player player) {
// Make use of the player's locale to make language-specific help!
Locale playerLocale = player.locale();
if (playerLocale.getLanguage().equals("en")) {
helpText = "Broadcasts \"Hi!\" to everyone on the server";
} else if (playerLocale.getLanguage().equals("de")) {
helpText = "Sendet \"Hi!\" an alle auf dem Server";
}
} else {
helpText = "Broadcasts \"Hi!\" to everyone on the server";
}
return helpText;
}
// Allow anyone to see this help topic
@Override
public boolean canSee(CommandSender player) {
return true;
}
};
}
fun makeHelp(command: String): HelpTopic = object: HelpTopic() {
override fun getShortText(): String = "Says hi"
override fun getFullText(forWho: CommandSender): String {
var helpText = ""
if (forWho is Player) {
// Make use of the player's locale to make language-specific help!
val playerLocale = forWho.locale()
if (playerLocale.getLanguage() == "en") {
helpText = "Broadcasts \"Hi!\" to everyone on the server"
} else if (playerLocale.getLanguage() == "de") {
helpText = "Sendet \"Hi!\" an alle auf dem Server"
}
} else {
helpText = "Broadcasts \"Hi!\" to everyone on the server"
}
return helpText
}
// Allow anyone to see this help topic
override fun canSee(player: CommandSender): Boolean = true
}
We then add our new HelpTopic
to the command using the withHelp
method:
new CommandAPICommand("mycmd")
.withHelp(makeHelp("mycmd"))
.executes((sender, args) -> {
Bukkit.broadcastMessage("Hi!");
})
.register();
return CommandAPICommand("mycmd")
.withHelp(makeHelp("mycmd"))
.executes(CommandExecutor { _, _ ->
Bukkit.broadcastMessage("Hi!")
})
.register()
Command usage
When registering a command, there also is a command usage generated. The CommandAPI provides a way to customise this usage by providing the withUsage()
method:
CommandAPICommand withUsage(String... usage)
Example - Providing a command usage
In this example, we want to showcase how usage generation displays the usage vs. how a custom usage displays the usage:
/command <help> <admin|user|moderator|vip>
/command <reload> <commandsystem|config|server>
This is how it would get displayed:
Usage:
- /command <help> <admin>
- /command <help> <user>
- /command <help> <moderator>
- /command <help> <vip>
- /command <reload> <commandsystem>
- /command <reload> <config>
- /command <reload> <server>
Now, we are implementing the withUsage()
method:
new CommandAPICommand("...")
.withUsage(
"/command <help> <section>",
"/command <reload> <system>"
)
By using withUsage()
like that, the CommandAPI will produce this usage:
Usage:
- /command <help> <section>
- /command <reload> <system>