Interface CommandRegistrar<T>

Type Parameters:
T - The type of command interface this handles.

@DoNotStore public interface CommandRegistrar<T>
CommandRegistrars are the entry point for plugins wishing to provide their own command framework. The CommandManager will proxy calls to the correct registrar and will handle the final CommandResult.

This interface defines a way to register commands. This registration method must call CommandManager.Mutable.registerAlias(CommandRegistrar, PluginContainer, CommandTreeNode.Root, String, String...) to indicate that they wish to take control of certain aliases. Beyond this call, the CommandRegistrar will only need to retain the link between the CommandMapping and its command (of type) T to execute, as the CommandManager will always supply the mapping of the command being invoked at runtime. The alias that was matched will also be supplied.

For a command that wishes to investigate the command string that was executed, they may investigate the context in CommandCause.cause(), looking for the EventContextKeys.COMMAND context key.

Command frameworks are free to choose how they parse commands. However, a framework's CommandRegistrar must do the following in order to be successfully registered and receive their commands:

  • Method Details

    • type

      Get the type defining this command registrar.
      Returns:
      the type
    • register

      CommandMapping register(org.spongepowered.plugin.PluginContainer container, T command, String primaryAlias, String... secondaryAliases) throws CommandFailedRegistrationException
      Registers a command.
      Parameters:
      container - The PluginContainer performing the registration
      command - The command to register
      primaryAlias - The primary alias
      secondaryAliases - Any secondary aliases. May be empty.
      Returns:
      The CommandMapping
      Throws:
      CommandFailedRegistrationException - if the registration failed
    • process

      CommandResult process(CommandCause cause, CommandMapping mapping, String command, String arguments) throws CommandException
      Process the provided command.

      Note for implementors: the provided command will be the one registered as the primary alias when registering with the CommandManager.

      Parameters:
      cause - The CommandCause that caused the command to be executed
      mapping - The CommandMapping for the command being invoked
      command - The alias that was used to invoke the command
      arguments - The arguments of the command (that is, the raw string with the command alias removed, so if /sponge test test2 is invoked, arguments will contain test test2.)
      Returns:
      The CommandResult
      Throws:
      CommandException - if there is an error executing the command
    • complete

      List<CommandCompletion> complete(CommandCause cause, CommandMapping mapping, String command, String arguments) throws CommandException
      Provides a list of completions associated with the provided argument string.

      See process(CommandCause, CommandMapping, String, String) for any implementation notes.

      Parameters:
      cause - The CommandCause that caused the command to be executed
      mapping - The CommandMapping for the command being invoked
      command - The alias that was used to invoke the command
      arguments - The arguments of the command (that is, the raw string with the command alias removed, so if /sponge test test2 is invoked, arguments will contain test test2.)
      Returns:
      The completions
      Throws:
      CommandException - if there is an error providing the suggestions
    • shortDescription

      default Optional<Component> shortDescription(CommandCause cause, CommandMapping mapping)
      Returns a short description for the invoked command, if one is available.

      A good short description is not necessarily help, rather, it should be a short description of the command's function. This short description may also be part of the standard help for the function.

      It is recommended that any description here is kept very short as such a description may be used in a command listing.

      Parameters:
      cause - The CommandCause that caused the command to be executed
      mapping - The CommandMapping that is associated with the command
      Returns:
      The help, if any
    • help

      Returns help text for the invoked command, if one is available.
      Parameters:
      cause - The CommandCause that caused the command to be executed
      mapping - The CommandMapping that is associated with the command
      Returns:
      The help, if any
    • canExecute

      boolean canExecute(CommandCause cause, CommandMapping mapping)
      Gets whether the given CommandCause can execute the command associated with the given CommandMapping.
      Parameters:
      cause - The CommandCause
      mapping - The CommandMapping
      Returns:
      true of the command can execute the command