Interface Command

All Known Subinterfaces:
Command.Parameterized, Command.Raw

public interface Command
The Command interface is the low-level interface that all commands in the Sponge ecosystem inherit.

Most plugins are highly recommended (but not obligated) to use builder() to create commands. The Command.Builder allows plugins to take advantage of a higher level of abstraction, such as argument parsers and simple child command handling, removing the need for boilerplate code. Such Command.Parameterized commands should register themselves during the RegisterCommandEvent<Command.Parameterized> event.

Plugins that do not want to use the Command.Builder or any third-party command system should implement the Command.Raw sub-interface instead. Such Command.Raw commands should register themselves during the RegisterCommandEvent<Command.Raw> event.

Plugins must not implement the Command.Parameterized sub-interface themselves.

Upon execution, commands are provided with a CommandCause, providing the Cause and EventContext that invoked the command. See the CommandCause documentation for more information of the structure of this cause.

  • Method Details

    • builder

      static Command.Builder builder()
      Gets a builder for building a Command.
      Returns:
      The Command.Builder
    • process

      Execute the command based on input arguments.

      The implementing class must perform the necessary permission checks.

      Parameters:
      cause - The CommandCause of the invocation of command
      arguments - The raw arguments for this command
      Returns:
      The result of a command being processed
      Throws:
      CommandException - Thrown on a command error
    • complete

      Gets a list of completions based on input.

      If a completion is chosen by the user, it will replace the last word.

      Parameters:
      cause - The CommandCause of the command
      arguments - The arguments entered up to this point
      Returns:
      A list of suggestions
      Throws:
      CommandException - Thrown if there was a parsing error
    • canExecute

      boolean canExecute(CommandCause cause)
      Test whether this command can probably be executed given this Cause.

      If implementations are unsure if the command can be executed by the source, true should be returned. Return values of this method may be used to determine whether this command is listed in command listings.

      Parameters:
      cause - The Cause to check
      Returns:
      Whether this command will execute
    • shortDescription

      Optional<Component> shortDescription(CommandCause cause)
      Gets a short one-line description of this command.

      The help system may display the description in the command list, or in any other function that displays a command list. It is therefore recommended that any description here is kept very short.

      Parameters:
      cause - The CommandCause of the help request
      Returns:
      A description
      See Also:
    • extendedDescription

      Optional<Component> extendedDescription(CommandCause cause)
      Gets a longer formatted help message about this command.

      The help system may display this description when displaying details about this specific command. It should not contain the description provided by shortDescription(CommandCause).

      Parameters:
      cause - The Cause of the help request
      Returns:
      A description
    • help

      default Optional<Component> help(@NonNull CommandCause cause)
      Gets a longer formatted help message about this command. This will typically comprise of shortDescription(CommandCause) and extendedDescription(CommandCause) together.

      The help system may display this message when a source requests detailed information about a command.

      Parameters:
      cause - The Cause of the help request
      Returns:
      A help text
      See Also:
    • usage

      Component usage(CommandCause cause)
      Gets the usage string of this command.

      A usage string may look like [<world>] <var1> <var2>.

      The string must not contain the command alias.

      Parameters:
      cause - The Cause of the help request
      Returns:
      A usage string