Interface CommandSourceStack

@NonExtendable public interface CommandSourceStack
The command source type for Brigadier commands registered using Paper API.

While the general use case for CommandSourceStack is similar to that of CommandSender, it provides access to important additional context for the command execution. Specifically, commands such as /execute may alter the location or executor of the source stack before passing it to another command.

The CommandSender returned by getSender() may be a "no-op" instance of CommandSender in cases where the server either doesn't exist yet, or no specific sender is available. Methods on such a CommandSender will either have no effect or throw an UnsupportedOperationException.

  • Method Details

    • getLocation

      Location getLocation()
      Gets the location that this command is being executed at.
      Returns:
      a cloned location instance.

    • getSender

      CommandSender getSender()
      Gets the command sender that executed this command. The sender of a command source stack is the one that initiated/triggered the execution of a command. It differs to getExecutor() as the executor can be changed by a command, e.g. /execute.
      Returns:
      the command sender instance

    • getExecutor

      @Nullable Entity getExecutor()
      Gets the entity that executes this command. May not always be getSender() as the executor of a command can be changed to a different entity than the one that triggered the command.
      Returns:
      entity that executes this command

    • getPlayerOrThrow

      Player getPlayerOrThrow() throws com.mojang.brigadier.exceptions.CommandSyntaxException
      Returns the Player that is executing this command.
      Returns:
      the Player that is executing this command
      Throws:
      com.mojang.brigadier.exceptions.CommandSyntaxException - if the executor of this command is not a Player

    • getEntityOrThrow

      Entity getEntityOrThrow() throws com.mojang.brigadier.exceptions.CommandSyntaxException
      Returns the Entity that is executing this command.
      Returns:
      the Entity that is executing this command
      Throws:
      com.mojang.brigadier.exceptions.CommandSyntaxException - if the executor of this command is not an Entity

    • withLocation

      CommandSourceStack withLocation(Location location)
      Creates a new CommandSourceStack object with a different location for redirecting commands to other nodes.
      Parameters:
      location - The location to create a new CommandSourceStack object with
      Returns:
      The newly created CommandSourceStack
      See Also:
      • getLocation()
      • ArgumentBuilder.fork(CommandNode, RedirectModifier)

    • withExecutor

      CommandSourceStack withExecutor(Entity executor)
      Creates a new CommandSourceStack object with a different executor for redirecting commands to other nodes.
      Parameters:
      executor - The executing entity to create a new CommandSourceStack object with
      Returns:
      The newly created CommandSourceStack
      See Also:
      • getExecutor()
      • ArgumentBuilder.fork(CommandNode, RedirectModifier)

    • sendReply

      void sendReply(ComponentLike message)
      Sends a system message to the getExecutor() if it is a Player, otherwise sends a system message to the getSender().
      Parameters:
      message - the message to send
      Throws:
      IllegalArgumentException - if the message is null

    • sendRichReply

      default void sendRichReply(String message, TagResolver... resolvers)
      Sends a system message with the MiniMessage format to the getExecutor() if it is a Player, otherwise sends it to the getSender().

      See MiniMessage docs and MiniMessage Placeholders docs for more information on the format.

      This method provides the target of the system message as a Pointered to the MiniMessage MiniMessage.deserialize(String, Pointered, TagResolver...) method.

      Parameters:
      message - the MiniMessage message to send
      resolvers - resolvers to use
      Throws:
      IllegalArgumentException - if the message is null

    • sendSuccess

      void sendSuccess(ComponentLike message, boolean allowInformingAdmins)
      Sends a system message to the getSender(), admins, and console indicating successful command execution according to vanilla semantics.

      This currently includes checking for environments with suppressed output, GameRules.SEND_COMMAND_FEEDBACK, and GameRules.LOG_ADMIN_COMMANDS.

      Parameters:
      message - the message to send
      allowInformingAdmins - whether admins and console may be informed of this success
      Throws:
      IllegalArgumentException - if the message is null

    • sendSuccess

      default void sendSuccess(ComponentLike message)
      Sends a system message to the getSender(), admins, and console indicating successful command execution according to vanilla semantics. This method informs admins and the console of this success.

      This currently includes checking for environments with suppressed output, GameRules.SEND_COMMAND_FEEDBACK, and GameRules.LOG_ADMIN_COMMANDS.

      Parameters:
      message - the message to send
      Throws:
      IllegalArgumentException - if the message is null
      See Also:

    • sendRichSuccess

      default void sendRichSuccess(String message, TagResolver... resolvers)
      Sends a system message with the MiniMessage format to the getSender(), admins, and console indicating successful command execution according to vanilla semantics. This method informs admins and the console of this success.

      This currently includes checking for environments with suppressed output, GameRules.SEND_COMMAND_FEEDBACK, and GameRules.LOG_ADMIN_COMMANDS.

      See MiniMessage docs and MiniMessage Placeholders docs for more information on the format.

      This method provides the CommandSender of this command as a Pointered to the MiniMessage MiniMessage.deserialize(String, Pointered, TagResolver...) method.

      Parameters:
      message - the MiniMessage message to send
      resolvers - resolvers to use
      Throws:
      IllegalArgumentException - if the message is null
      See Also:

    • sendFailure

      void sendFailure(ComponentLike message)
      Sends a system message indicating a failed command execution to the getSender(). Does not apply red styling to the message as vanilla does to allow for custom failure message styling.

      Respects vanilla semantics for accepting failure output and suppressed output environments.

      Parameters:
      message - the message to send
      Throws:
      IllegalArgumentException - if the message is null

    • sendRichFailure

      default void sendRichFailure(String message, TagResolver... resolvers)
      Sends a system message with the MiniMessage format indicating a failed command execution to thegetSender(). Does not apply red styling to the message as vanilla does to allow for custom failure message styling.

      Respects vanilla semantics for accepting failure output and suppressed output environments.

      See MiniMessage docs and MiniMessage Placeholders docs for more information on the format.

      This method provides the CommandSender of this command as a Pointered to the MiniMessage MiniMessage.deserialize(String, Pointered, TagResolver...) method.

      Parameters:
      message - the MiniMessage message to send
      resolvers - resolvers to use
      Throws:
      IllegalArgumentException - if the message is null