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 image

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 ho 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!")
    }
}

Help 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>