Package io.papermc.paper.command.brigadier

Interface Commands

All Superinterfaces:
Registrar
@Experimental @NullMarked @NonExtendable public interface Commands extends Registrar
The registrar for custom commands. Supports Brigadier commands and BasicCommand.

An example of a command being registered is below 


 class YourPluginClass extends JavaPlugin {

     @Override
     public void onEnable() {
         LifecycleEventManager<Plugin> manager = this.getLifecycleManager();
         manager.registerEventHandler(LifecycleEvents.COMMANDS, event -> {
             final Commands commands = event.registrar();
             commands.register(
                 Commands.literal("new-command")
                     .executes(ctx -> {
                         ctx.getSource().getSender().sendPlainMessage("some message");
                         return Command.SINGLE_SUCCESS;
                     })
                     .build(),
                 "some bukkit help description string",
                 List.of("an-alias")
             );
         });
     }
 }

You can also register commands in PluginBootstrap by getting the LifecycleEventManager from BootstrapContext. Commands registered in the PluginBootstrap will be available for datapack's command function parsing. Note that commands registered via PluginBootstrap with the same literals as a vanilla command will override that command within all loaded datapacks.

The register methods that do not have PluginMeta as a parameter will implicitly use the PluginMeta for the plugin that the LifecycleEventHandler was registered with.

See Also:

  • Method Details

    • literal

      static com.mojang.brigadier.builder.LiteralArgumentBuilder<CommandSourceStack> literal(String literal)
      Utility to create a literal command node builder with the correct generic.
      Parameters:
      literal - literal name
      Returns:
      a new builder instance

    • argument

      static <T> com.mojang.brigadier.builder.RequiredArgumentBuilder<CommandSourceStack,T> argument(String name, com.mojang.brigadier.arguments.ArgumentType<T> argumentType)
      Utility to create a required argument builder with the correct generic.
      Type Parameters:
      T - the generic type of the argument value
      Parameters:
      name - the name of the argument
      argumentType - the type of the argument
      Returns:
      a new required argument builder

    • getDispatcher

      @Experimental com.mojang.brigadier.CommandDispatcher<CommandSourceStack> getDispatcher()
      Gets the underlying CommandDispatcher.

      Note: This is a delicate API that must be used with care to ensure a consistent user experience.

      When registering commands, it should be preferred to use the register methods over directly registering to the dispatcher wherever possible. Register methods automatically handle command namespacing, command help, plugin association with commands, and more.

      Example use cases for this method may include:

      • Implementing integration between an external command framework and Paper (although register methods should still be preferred where possible)
      • Registering new child nodes to an existing plugin command (for example an "addon" plugin to another plugin may want to do this)
      • Retrieving existing command nodes to build redirects
      Returns:
      the dispatcher instance

    • register

      default @Unmodifiable Set<String> register(com.mojang.brigadier.tree.LiteralCommandNode<CommandSourceStack> node)
      Registers a command for the current plugin context.

      Commands have certain overriding behavior:

      • Aliases will not override already existing commands (excluding namespaced ones)
      • The main command/namespaced label will override already existing commands
      Parameters:
      node - the built literal command node
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • register

      default @Unmodifiable Set<String> register(com.mojang.brigadier.tree.LiteralCommandNode<CommandSourceStack> node, @Nullable String description)
      Registers a command for the current plugin context.

      Commands have certain overriding behavior:

      • Aliases will not override already existing commands (excluding namespaced ones)
      • The main command/namespaced label will override already existing commands
      Parameters:
      node - the built literal command node
      description - the help description for the root literal node
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • register

      default @Unmodifiable Set<String> register(com.mojang.brigadier.tree.LiteralCommandNode<CommandSourceStack> node, Collection<String> aliases)
      Registers a command for the current plugin context.

      Commands have certain overriding behavior:

      • Aliases will not override already existing commands (excluding namespaced ones)
      • The main command/namespaced label will override already existing commands
      Parameters:
      node - the built literal command node
      aliases - a collection of aliases to register the literal node's command to
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • register

      @Unmodifiable Set<String> register(com.mojang.brigadier.tree.LiteralCommandNode<CommandSourceStack> node, @Nullable String description, Collection<String> aliases)
      Registers a command for the current plugin context.

      Commands have certain overriding behavior:

      • Aliases will not override already existing commands (excluding namespaced ones)
      • The main command/namespaced label will override already existing commands
      Parameters:
      node - the built literal command node
      description - the help description for the root literal node
      aliases - a collection of aliases to register the literal node's command to
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • register

      @Unmodifiable Set<String> register(PluginMeta pluginMeta, com.mojang.brigadier.tree.LiteralCommandNode<CommandSourceStack> node, @Nullable String description, Collection<String> aliases)
      Registers a command for a plugin.

      Commands have certain overriding behavior:

      • Aliases will not override already existing commands (excluding namespaced ones)
      • The main command/namespaced label will override already existing commands
      Parameters:
      pluginMeta - the owning plugin's meta
      node - the built literal command node
      description - the help description for the root literal node
      aliases - a collection of aliases to register the literal node's command to
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • registerWithFlags

      @Internal @Unmodifiable Set<String> registerWithFlags(PluginMeta pluginMeta, com.mojang.brigadier.tree.LiteralCommandNode<CommandSourceStack> node, @Nullable String description, Collection<String> aliases, Set<CommandRegistrationFlag> flags)
      This allows configuring the registration of your command, which is not intended for public use. See register(PluginMeta, LiteralCommandNode, String, Collection) for more information.
      Parameters:
      pluginMeta - the owning plugin's meta
      node - the built literal command node
      description - the help description for the root literal node
      aliases - a collection of aliases to register the literal node's command to
      flags - a collection of registration flags that control registration behaviour.
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)
      API Note:
      This method is not guaranteed to be stable as it is not intended for public use. See CommandRegistrationFlag for a more indepth explanation of this method's use-case.

    • register

      default @Unmodifiable Set<String> register(String label, BasicCommand basicCommand)
      Registers a command under the same logic as register(LiteralCommandNode, String, Collection).
      Parameters:
      label - the label of the to-be-registered command
      basicCommand - the basic command instance to register
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • register

      default @Unmodifiable Set<String> register(String label, @Nullable String description, BasicCommand basicCommand)
      Registers a command under the same logic as register(LiteralCommandNode, String, Collection).
      Parameters:
      label - the label of the to-be-registered command
      description - the help description for the root literal node
      basicCommand - the basic command instance to register
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • register

      default @Unmodifiable Set<String> register(String label, Collection<String> aliases, BasicCommand basicCommand)
      Registers a command under the same logic as register(LiteralCommandNode, String, Collection).
      Parameters:
      label - the label of the to-be-registered command
      aliases - a collection of aliases to register the basic command under.
      basicCommand - the basic command instance to register
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • register

      @Unmodifiable Set<String> register(String label, @Nullable String description, Collection<String> aliases, BasicCommand basicCommand)
      Registers a command under the same logic as register(LiteralCommandNode, String, Collection).
      Parameters:
      label - the label of the to-be-registered command
      description - the help description for the root literal node
      aliases - a collection of aliases to register the basic command under.
      basicCommand - the basic command instance to register
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)

    • register

      @Unmodifiable Set<String> register(PluginMeta pluginMeta, String label, @Nullable String description, Collection<String> aliases, BasicCommand basicCommand)
      Registers a command under the same logic as register(PluginMeta, LiteralCommandNode, String, Collection).
      Parameters:
      pluginMeta - the owning plugin's meta
      label - the label of the to-be-registered command
      description - the help description for the root literal node
      aliases - a collection of aliases to register the basic command under.
      basicCommand - the basic command instance to register
      Returns:
      successfully registered root command labels (including aliases and namespaced variants)