From 69edd6d91fb5706a0b9d7f1068150ab717165cd1 Mon Sep 17 00:00:00 2001 From: Owen1212055 <23108066+Owen1212055@users.noreply.github.com> Date: Mon, 1 Aug 2022 22:50:29 -0400 Subject: [PATCH] Brigadier based command API Co-authored-by: Jake Potrebic --- paper-api/build.gradle.kts | 25 ++ .../brigadier/BukkitBrigadierCommand.java | 16 + .../BukkitBrigadierCommandSource.java | 25 ++ .../AsyncPlayerSendCommandsEvent.java | 73 ++++ .../AsyncPlayerSendSuggestionsEvent.java | 85 ++++ .../brigadier/CommandRegisteredEvent.java | 171 ++++++++ .../paper/brigadier/PaperBrigadier.java | 47 +++ .../paper/command/brigadier/BasicCommand.java | 62 +++ .../brigadier/CommandRegistrationFlag.java | 14 + .../command/brigadier/CommandSourceStack.java | 51 +++ .../paper/command/brigadier/Commands.java | 267 +++++++++++++ .../brigadier/MessageComponentSerializer.java | 25 ++ .../MessageComponentSerializerHolder.java | 12 + .../brigadier/argument/ArgumentTypes.java | 371 ++++++++++++++++++ .../argument/CustomArgumentType.java | 107 +++++ .../argument/RegistryArgumentExtractor.java | 36 ++ .../argument/SignedMessageResolver.java | 42 ++ .../argument/VanillaArgumentProvider.java | 106 +++++ .../predicate/ItemStackPredicate.java | 15 + .../argument/range/DoubleRangeProvider.java | 14 + .../argument/range/IntegerRangeProvider.java | 14 + .../argument/range/RangeProvider.java | 22 ++ .../argument/resolvers/ArgumentResolver.java | 27 ++ .../resolvers/BlockPositionResolver.java | 16 + .../resolvers/FinePositionResolver.java | 17 + .../resolvers/PlayerProfileListResolver.java | 17 + .../EntitySelectorArgumentResolver.java | 19 + .../PlayerSelectorArgumentResolver.java | 19 + .../selector/SelectorArgumentResolver.java | 17 + .../event/types/LifecycleEvents.java | 9 + .../main/java/org/bukkit/command/Command.java | 5 + .../bukkit/command/FormattedCommandAlias.java | 2 +- .../org/bukkit/command/SimpleCommandMap.java | 15 +- .../command/defaults/ReloadCommand.java | 14 +- .../bukkit/event/server/TabCompleteEvent.java | 2 + 35 files changed, 1774 insertions(+), 5 deletions(-) create mode 100644 paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommand.java create mode 100644 paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommandSource.java create mode 100644 paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java create mode 100644 paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java create mode 100644 paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java create mode 100644 paper-api/src/main/java/io/papermc/paper/brigadier/PaperBrigadier.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/BasicCommand.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandRegistrationFlag.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandSourceStack.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/Commands.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/MessageComponentSerializer.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/MessageComponentSerializerHolder.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/ArgumentTypes.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/CustomArgumentType.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/RegistryArgumentExtractor.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/SignedMessageResolver.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/VanillaArgumentProvider.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/predicate/ItemStackPredicate.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/range/DoubleRangeProvider.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/range/IntegerRangeProvider.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/range/RangeProvider.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/ArgumentResolver.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/BlockPositionResolver.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/FinePositionResolver.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/PlayerProfileListResolver.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/selector/EntitySelectorArgumentResolver.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/selector/PlayerSelectorArgumentResolver.java create mode 100644 paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/selector/SelectorArgumentResolver.java diff --git a/paper-api/build.gradle.kts b/paper-api/build.gradle.kts index 2b489adc50..571534b42c 100644 --- a/paper-api/build.gradle.kts +++ b/paper-api/build.gradle.kts @@ -39,6 +39,7 @@ abstract class MockitoAgentProvider : CommandLineArgumentProvider { // Paper end - configure mockito agent that is needed in newer java versions dependencies { + api("com.mojang:brigadier:1.2.9") // Paper - Brigadier command api // api dependencies are listed transitively to API consumers api("com.google.guava:guava:33.3.1-jre") api("com.google.code.gson:gson:2.11.0") @@ -108,9 +109,33 @@ sourceSets { } } // Paper end +// Paper start - brigadier API +val outgoingVariants = arrayOf("runtimeElements", "apiElements", "sourcesElements", "javadocElements") +val mainCapability = "${project.group}:${project.name}:${project.version}" +configurations { + val outgoing = outgoingVariants.map { named(it) } + for (config in outgoing) { + config { + attributes { + attribute(io.papermc.paperweight.util.mainCapabilityAttribute, mainCapability) + } + outgoing { + capability(mainCapability) + capability("io.papermc.paper:paper-mojangapi:${project.version}") + capability("com.destroystokyo.paper:paper-mojangapi:${project.version}") + } + } + } +} +// Paper end configure { publications.create("maven") { + // Paper start - brigadier API + outgoingVariants.forEach { + suppressPomMetadataWarningsFor(it) + } + // Paper end from(components["java"]) } } diff --git a/paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommand.java b/paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommand.java new file mode 100644 index 0000000000..03a1078446 --- /dev/null +++ b/paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommand.java @@ -0,0 +1,16 @@ +package com.destroystokyo.paper.brigadier; + +import com.mojang.brigadier.Command; +import com.mojang.brigadier.suggestion.SuggestionProvider; + +import java.util.function.Predicate; + +/** + * Brigadier {@link Command}, {@link SuggestionProvider}, and permission checker for Bukkit {@link Command}s. + * + * @param command source type + * @deprecated For removal, see {@link io.papermc.paper.command.brigadier.Commands} on how to use the new Brigadier API. + */ +@Deprecated(forRemoval = true, since = "1.20.6") +public interface BukkitBrigadierCommand extends Command, Predicate, SuggestionProvider { +} diff --git a/paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommandSource.java b/paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommandSource.java new file mode 100644 index 0000000000..28b44789e3 --- /dev/null +++ b/paper-api/src/main/java/com/destroystokyo/paper/brigadier/BukkitBrigadierCommandSource.java @@ -0,0 +1,25 @@ +package com.destroystokyo.paper.brigadier; + +import org.bukkit.Location; +import org.bukkit.World; +import org.bukkit.command.CommandSender; +import org.bukkit.entity.Entity; +import org.jetbrains.annotations.Nullable; + +/** + * @deprecated For removal, see {@link io.papermc.paper.command.brigadier.Commands} on how to use the new Brigadier API. + */ +@Deprecated(forRemoval = true) +public interface BukkitBrigadierCommandSource { + + @Nullable + Entity getBukkitEntity(); + + @Nullable + World getBukkitWorld(); + + @Nullable + Location getBukkitLocation(); + + CommandSender getBukkitSender(); +} diff --git a/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java b/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java new file mode 100644 index 0000000000..9e1b70d438 --- /dev/null +++ b/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendCommandsEvent.java @@ -0,0 +1,73 @@ +package com.destroystokyo.paper.event.brigadier; + +import com.mojang.brigadier.tree.RootCommandNode; +import io.papermc.paper.command.brigadier.CommandSourceStack; +import org.bukkit.Bukkit; +import org.bukkit.entity.Player; +import org.bukkit.event.HandlerList; +import org.bukkit.event.player.PlayerEvent; +import org.jetbrains.annotations.ApiStatus; +import org.jspecify.annotations.NullMarked; + +/** + * Fired any time a Brigadier RootCommandNode is generated for a player to inform the client of commands. + * You may manipulate this CommandNode to change what the client sees. + * + *

This event may fire on login, world change, and permission rebuilds, by plugin request, and potentially future means.

+ * + *

This event will fire before {@link org.bukkit.event.player.PlayerCommandSendEvent}, so no filtering has been done by + * other plugins yet.

+ * + *

WARNING: This event will potentially (and most likely) fire twice! Once for Async, and once again for Sync. + * It is important that you check event.isAsynchronous() and event.hasFiredAsync() to ensure you only act once. + * If for some reason we are unable to send this asynchronously in the future, only the sync method will fire.

+ * + *

Your logic should look like this: + * {@code if (event.isAsynchronous() || !event.hasFiredAsync()) { // do stuff }}

+ * + *

If your logic is not safe to run asynchronously, only react to the synchronous version.

+ * + *

This is a draft/experimental API and is subject to change.

+ */ +@ApiStatus.Experimental +@NullMarked +public class AsyncPlayerSendCommandsEvent extends PlayerEvent { + + private static final HandlerList HANDLER_LIST = new HandlerList(); + private final RootCommandNode node; + private final boolean hasFiredAsync; + + @ApiStatus.Internal + public AsyncPlayerSendCommandsEvent(final Player player, final RootCommandNode node, final boolean hasFiredAsync) { + super(player, !Bukkit.isPrimaryThread()); + this.node = node; + this.hasFiredAsync = hasFiredAsync; + } + + /** + * Gets the full Root Command Node being sent to the client, which is mutable. + * + * @return the root command node + */ + public RootCommandNode getCommandNode() { + return this.node; + } + + /** + * Gets if this event has already fired asynchronously. + * + * @return whether this event has already fired asynchronously + */ + public boolean hasFiredAsync() { + return this.hasFiredAsync; + } + + @Override + public HandlerList getHandlers() { + return HANDLER_LIST; + } + + public static HandlerList getHandlerList() { + return HANDLER_LIST; + } +} diff --git a/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java b/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java new file mode 100644 index 0000000000..faade9d355 --- /dev/null +++ b/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/AsyncPlayerSendSuggestionsEvent.java @@ -0,0 +1,85 @@ +package com.destroystokyo.paper.event.brigadier; + +import com.mojang.brigadier.suggestion.Suggestions; +import org.bukkit.Bukkit; +import org.bukkit.entity.Player; +import org.bukkit.event.Cancellable; +import org.bukkit.event.HandlerList; +import org.bukkit.event.player.PlayerEvent; +import org.jetbrains.annotations.ApiStatus; +import org.jspecify.annotations.NullMarked; + +/** + * Called when sending {@link Suggestions} to the client. Will be called asynchronously if a plugin + * marks the {@link com.destroystokyo.paper.event.server.AsyncTabCompleteEvent} event handled asynchronously, + * otherwise called synchronously. + */ +@NullMarked +public class AsyncPlayerSendSuggestionsEvent extends PlayerEvent implements Cancellable { + + private static final HandlerList HANDLER_LIST = new HandlerList(); + private boolean cancelled = false; + + private Suggestions suggestions; + private final String buffer; + + @ApiStatus.Internal + public AsyncPlayerSendSuggestionsEvent(final Player player, final Suggestions suggestions, final String buffer) { + super(player, !Bukkit.isPrimaryThread()); + this.suggestions = suggestions; + this.buffer = buffer; + } + + /** + * Gets the input buffer sent to request these suggestions. + * + * @return the input buffer + */ + public String getBuffer() { + return this.buffer; + } + + /** + * Gets the suggestions to be sent to client. + * + * @return the suggestions + */ + public Suggestions getSuggestions() { + return this.suggestions; + } + + /** + * Sets the suggestions to be sent to client. + * + * @param suggestions suggestions + */ + public void setSuggestions(final Suggestions suggestions) { + this.suggestions = suggestions; + } + + /** + * {@inheritDoc} + */ + @Override + public boolean isCancelled() { + return this.cancelled; + } + + /** + * Cancels sending suggestions to the client. + * {@inheritDoc} + */ + @Override + public void setCancelled(final boolean cancel) { + this.cancelled = cancel; + } + + @Override + public HandlerList getHandlers() { + return HANDLER_LIST; + } + + public static HandlerList getHandlerList() { + return HANDLER_LIST; + } +} diff --git a/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java b/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java new file mode 100644 index 0000000000..acc2bd2ec5 --- /dev/null +++ b/paper-api/src/main/java/com/destroystokyo/paper/event/brigadier/CommandRegisteredEvent.java @@ -0,0 +1,171 @@ +package com.destroystokyo.paper.event.brigadier; + +import com.destroystokyo.paper.brigadier.BukkitBrigadierCommand; +import com.mojang.brigadier.tree.ArgumentCommandNode; +import com.mojang.brigadier.tree.LiteralCommandNode; +import com.mojang.brigadier.tree.RootCommandNode; +import org.bukkit.Warning; +import org.bukkit.command.Command; +import org.bukkit.event.Cancellable; +import org.bukkit.event.HandlerList; +import org.bukkit.event.server.ServerEvent; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.NotNull; + +/** + * Fired anytime the server synchronizes Bukkit commands to Brigadier. + * + *

Allows a plugin to control the command node structure for its commands. + * This is done at Plugin Enable time after commands have been registered, but may also + * run at a later point in the server lifetime due to plugins, a server reload, etc.

+ * + *

This is a draft/experimental API and is subject to change.

+ * @deprecated For removal, use the new brigadier api. + */ +@ApiStatus.Experimental +@Deprecated(since = "1.20.6") +@Warning(reason = "This event has been superseded by the Commands API and will be removed in a future release. Listen to LifecycleEvents.COMMANDS instead.", value = true) +public class CommandRegisteredEvent extends ServerEvent implements Cancellable { + + private static final HandlerList handlers = new HandlerList(); + private final String commandLabel; + private final Command command; + private final com.destroystokyo.paper.brigadier.BukkitBrigadierCommand brigadierCommand; + private final RootCommandNode root; + private final ArgumentCommandNode defaultArgs; + private LiteralCommandNode literal; + private boolean rawCommand = false; + private boolean cancelled = false; + + public CommandRegisteredEvent(String commandLabel, com.destroystokyo.paper.brigadier.BukkitBrigadierCommand brigadierCommand, Command command, RootCommandNode root, LiteralCommandNode literal, ArgumentCommandNode defaultArgs) { + this.commandLabel = commandLabel; + this.brigadierCommand = brigadierCommand; + this.command = command; + this.root = root; + this.literal = literal; + this.defaultArgs = defaultArgs; + } + + /** + * Gets the command label of the {@link Command} being registered. + * + * @return the command label + */ + public String getCommandLabel() { + return this.commandLabel; + } + + /** + * Gets the {@link BukkitBrigadierCommand} for the {@link Command} being registered. This can be used + * as the {@link com.mojang.brigadier.Command command executor} or + * {@link com.mojang.brigadier.suggestion.SuggestionProvider} of a {@link com.mojang.brigadier.tree.CommandNode} + * to delegate to the {@link Command} being registered. + * + * @return the {@link BukkitBrigadierCommand} + */ + public BukkitBrigadierCommand getBrigadierCommand() { + return this.brigadierCommand; + } + + /** + * Gets the {@link Command} being registered. + * + * @return the {@link Command} + */ + public Command getCommand() { + return this.command; + } + + /** + * Gets the {@link RootCommandNode} which is being registered to. + * + * @return the {@link RootCommandNode} + */ + public RootCommandNode getRoot() { + return this.root; + } + + /** + * Gets the Bukkit APIs default arguments node (greedy string), for if + * you wish to reuse it. + * + * @return default arguments node + */ + public ArgumentCommandNode getDefaultArgs() { + return this.defaultArgs; + } + + /** + * Gets the {@link LiteralCommandNode} to be registered for the {@link Command}. + * + * @return the {@link LiteralCommandNode} + */ + public LiteralCommandNode getLiteral() { + return this.literal; + } + + /** + * Sets the {@link LiteralCommandNode} used to register this command. The default literal is mutable, so + * this is primarily if you want to completely replace the object. + * + * @param literal new node + */ + public void setLiteral(LiteralCommandNode literal) { + this.literal = literal; + } + + /** + * Gets whether this command should is treated as "raw". + * + * @see #setRawCommand(boolean) + * @return whether this command is treated as "raw" + */ + public boolean isRawCommand() { + return this.rawCommand; + } + + /** + * Sets whether this command should be treated as "raw". + * + *

A "raw" command will only use the node provided by this event for + * sending the command tree to the client. For execution purposes, the default + * greedy string execution of a standard Bukkit {@link Command} is used.

+ * + *

On older versions of Paper, this was the default and only behavior of this + * event.

+ * + * @param rawCommand whether this command should be treated as "raw" + */ + public void setRawCommand(final boolean rawCommand) { + this.rawCommand = rawCommand; + } + + /** + * {@inheritDoc} + */ + @Override + public boolean isCancelled() { + return this.cancelled; + } + + /** + * Cancels registering this command to Brigadier, but will remain in Bukkit Command Map. Can be used to hide a + * command from all players. + * + * {@inheritDoc} + */ + @Override + public void setCancelled(boolean cancel) { + this.cancelled = cancel; + } + + @NotNull + public HandlerList getHandlers() { + return handlers; + } + + @NotNull + public static HandlerList getHandlerList() { + return handlers; + } +} diff --git a/paper-api/src/main/java/io/papermc/paper/brigadier/PaperBrigadier.java b/paper-api/src/main/java/io/papermc/paper/brigadier/PaperBrigadier.java new file mode 100644 index 0000000000..9df8770820 --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/brigadier/PaperBrigadier.java @@ -0,0 +1,47 @@ +package io.papermc.paper.brigadier; + +import com.mojang.brigadier.Message; +import io.papermc.paper.command.brigadier.MessageComponentSerializer; +import net.kyori.adventure.text.Component; +import net.kyori.adventure.text.ComponentLike; +import net.kyori.adventure.text.TextComponent; +import org.checkerframework.checker.nullness.qual.NonNull; + +/** + * Helper methods to bridge the gaps between Brigadier and Paper-MojangAPI. + * @deprecated for removal. See {@link MessageComponentSerializer} for a direct replacement of functionality found in + * this class. + * As a general entrypoint to brigadier on paper, see {@link io.papermc.paper.command.brigadier.Commands}. + */ +@Deprecated(forRemoval = true, since = "1.20.6") +public final class PaperBrigadier { + private PaperBrigadier() { + throw new RuntimeException("PaperBrigadier is not to be instantiated!"); + } + + /** + * Create a new Brigadier {@link Message} from a {@link ComponentLike}. + * + *

Mostly useful for creating rich suggestion tooltips in combination with other Paper-MojangAPI APIs.

+ * + * @param componentLike The {@link ComponentLike} to use for the {@link Message} contents + * @return A new Brigadier {@link Message} + */ + public static @NonNull Message message(final @NonNull ComponentLike componentLike) { + return MessageComponentSerializer.message().serialize(componentLike.asComponent()); + } + + /** + * Create a new {@link Component} from a Brigadier {@link Message}. + * + *

If the {@link Message} was created from a {@link Component}, it will simply be + * converted back, otherwise a new {@link TextComponent} will be created with the + * content of {@link Message#getString()}

+ * + * @param message The {@link Message} to create a {@link Component} from + * @return The created {@link Component} + */ + public static @NonNull Component componentFromMessage(final @NonNull Message message) { + return MessageComponentSerializer.message().deserialize(message); + } +} diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/BasicCommand.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/BasicCommand.java new file mode 100644 index 0000000000..c89d6c4c38 --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/command/brigadier/BasicCommand.java @@ -0,0 +1,62 @@ +package io.papermc.paper.command.brigadier; + +import java.util.Collection; +import java.util.Collections; +import org.bukkit.command.CommandSender; +import org.jetbrains.annotations.ApiStatus; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; + +/** + * Implementing this interface allows for easily creating "Bukkit-style" {@code String[] args} commands. + * The implementation handles converting the command to a representation compatible with Brigadier on registration, usually in the form of {@literal /commandlabel }. + */ +@ApiStatus.Experimental +@NullMarked +@FunctionalInterface +public interface BasicCommand { + + /** + * Executes the command with the given {@link CommandSourceStack} and arguments. + * + * @param commandSourceStack the commandSourceStack of the command + * @param args the arguments of the command ignoring repeated spaces + */ + @ApiStatus.OverrideOnly + void execute(CommandSourceStack commandSourceStack, String[] args); + + /** + * Suggests possible completions for the given command {@link CommandSourceStack} and arguments. + * + * @param commandSourceStack the commandSourceStack of the command + * @param args the arguments of the command including repeated spaces + * @return a collection of suggestions + */ + @ApiStatus.OverrideOnly + default Collection suggest(final CommandSourceStack commandSourceStack, final String[] args) { + return Collections.emptyList(); + } + + /** + * Checks whether a command sender can receive and run the root command. + * + * @param sender the command sender trying to execute the command + * @return whether the command sender fulfills the root command requirement + * @see #permission() + */ + @ApiStatus.OverrideOnly + default boolean canUse(final CommandSender sender) { + final String permission = this.permission(); + return permission == null || sender.hasPermission(permission); + } + + /** + * Returns the permission for the root command used in {@link #canUse(CommandSender)} by default. + * + * @return the permission for the root command used in {@link #canUse(CommandSender)} + */ + @ApiStatus.OverrideOnly + default @Nullable String permission() { + return null; + } +} diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandRegistrationFlag.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandRegistrationFlag.java new file mode 100644 index 0000000000..7e24babf74 --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandRegistrationFlag.java @@ -0,0 +1,14 @@ +package io.papermc.paper.command.brigadier; + +import org.jetbrains.annotations.ApiStatus; + +/** + * A {@link CommandRegistrationFlag} is used in {@link Commands} registration for internal purposes. + *

+ * A command library may use this to achieve more specific customization on how their commands are registered. + * @apiNote Stability of these flags is not promised! This api is not intended for public use. + */ +@ApiStatus.Internal +public enum CommandRegistrationFlag { + FLATTEN_ALIASES +} diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandSourceStack.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandSourceStack.java new file mode 100644 index 0000000000..ac6f5b754a --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandSourceStack.java @@ -0,0 +1,51 @@ +package io.papermc.paper.command.brigadier; + +import org.bukkit.Location; +import org.bukkit.command.CommandSender; +import org.bukkit.entity.Entity; +import org.jetbrains.annotations.ApiStatus; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; + +/** + * The command source type for Brigadier commands registered using Paper API. + *

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

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

+ */ +@ApiStatus.Experimental +@NullMarked +@ApiStatus.NonExtendable +public interface CommandSourceStack { + + /** + * Gets the location that this command is being executed at. + * + * @return a cloned location instance. + */ + Location getLocation(); + + /** + * 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 {@link #getExecutor()} as the executor can be changed by a command, e.g. {@literal /execute}. + * + * @return the command sender instance + */ + CommandSender getSender(); + + /** + * Gets the entity that executes this command. + * May not always be {@link #getSender()} as the executor of a command can be changed to a different entity + * than the one that triggered the command. + * + * @return entity that executes this command + */ + @Nullable Entity getExecutor(); +} diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/Commands.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/Commands.java new file mode 100644 index 0000000000..e32559772a --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/command/brigadier/Commands.java @@ -0,0 +1,267 @@ +package io.papermc.paper.command.brigadier; + +import com.mojang.brigadier.CommandDispatcher; +import com.mojang.brigadier.arguments.ArgumentType; +import com.mojang.brigadier.builder.LiteralArgumentBuilder; +import com.mojang.brigadier.builder.RequiredArgumentBuilder; +import com.mojang.brigadier.tree.LiteralCommandNode; +import io.papermc.paper.plugin.bootstrap.BootstrapContext; +import io.papermc.paper.plugin.bootstrap.PluginBootstrap; +import io.papermc.paper.plugin.configuration.PluginMeta; +import io.papermc.paper.plugin.lifecycle.event.LifecycleEventManager; +import io.papermc.paper.plugin.lifecycle.event.registrar.Registrar; +import java.util.Collection; +import java.util.Collections; +import java.util.Set; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Unmodifiable; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; + +/** + * The registrar for custom commands. Supports Brigadier commands and {@link BasicCommand}. + *

+ * An example of a command being registered is below + * 

{@code
+ * class YourPluginClass extends JavaPlugin {
+ *
+ *     @Override
+ *     public void onEnable() {
+ *         LifecycleEventManager 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 {@link PluginBootstrap} by getting the {@link LifecycleEventManager} from + * {@link BootstrapContext}. + * Commands registered in the {@link PluginBootstrap} will be available for datapack's + * command function parsing. + * Note that commands registered via {@link PluginBootstrap} with the same literals as a vanilla command will override + * that command within all loaded datapacks. + *

+ *

The {@code register} methods that do not have {@link PluginMeta} as a parameter will + * implicitly use the {@link PluginMeta} for the plugin that the {@link io.papermc.paper.plugin.lifecycle.event.handler.LifecycleEventHandler} + * was registered with.

+ * + * @see io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents#COMMANDS + */ +@ApiStatus.Experimental +@NullMarked +@ApiStatus.NonExtendable +public interface Commands extends Registrar { + + /** + * Utility to create a literal command node builder with the correct generic. + * + * @param literal literal name + * @return a new builder instance + */ + static LiteralArgumentBuilder literal(final String literal) { + return LiteralArgumentBuilder.literal(literal); + } + + /** + * Utility to create a required argument builder with the correct generic. + * + * @param name the name of the argument + * @param argumentType the type of the argument + * @param the generic type of the argument value + * @return a new required argument builder + */ + static RequiredArgumentBuilder argument(final String name, final ArgumentType argumentType) { + return RequiredArgumentBuilder.argument(name, argumentType); + } + + /** + * Gets the underlying {@link 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 {@link #register(PluginMeta, LiteralCommandNode, String, Collection) register methods} + * over directly registering to the dispatcher wherever possible. + * {@link #register(PluginMeta, LiteralCommandNode, String, Collection) 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 {@link #register(PluginMeta, LiteralCommandNode, String, Collection) 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
    • + *
+ * + * @return the dispatcher instance + */ + @ApiStatus.Experimental + CommandDispatcher getDispatcher(); + + /** + * 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
    • + *
+ * + * @param node the built literal command node + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + default @Unmodifiable Set register(final LiteralCommandNode node) { + return this.register(node, null, Collections.emptyList()); + } + + /** + * 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
    • + *
+ * + * @param node the built literal command node + * @param description the help description for the root literal node + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + default @Unmodifiable Set register(final LiteralCommandNode node, final @Nullable String description) { + return this.register(node, description, Collections.emptyList()); + } + + /** + * 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
    • + *
+ * + * @param node the built literal command node + * @param aliases a collection of aliases to register the literal node's command to + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + default @Unmodifiable Set register(final LiteralCommandNode node, final Collection aliases) { + return this.register(node, null, 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
    • + *
+ * + * @param node the built literal command node + * @param description the help description for the root literal node + * @param aliases a collection of aliases to register the literal node's command to + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + @Unmodifiable Set register(LiteralCommandNode node, @Nullable String description, Collection 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
    • + *
+ * + * @param pluginMeta the owning plugin's meta + * @param node the built literal command node + * @param description the help description for the root literal node + * @param aliases a collection of aliases to register the literal node's command to + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + @Unmodifiable Set register(PluginMeta pluginMeta, LiteralCommandNode node, @Nullable String description, Collection aliases); + + /** + * This allows configuring the registration of your command, which is not intended for public use. + * See {@link Commands#register(PluginMeta, LiteralCommandNode, String, Collection)} for more information. + * + * @param pluginMeta the owning plugin's meta + * @param node the built literal command node + * @param description the help description for the root literal node + * @param aliases a collection of aliases to register the literal node's command to + * @param flags a collection of registration flags that control registration behaviour. + * @return successfully registered root command labels (including aliases and namespaced variants) + * + * @apiNote This method is not guaranteed to be stable as it is not intended for public use. + * See {@link CommandRegistrationFlag} for a more indepth explanation of this method's use-case. + */ + @ApiStatus.Internal + @Unmodifiable Set registerWithFlags(PluginMeta pluginMeta, LiteralCommandNode node, @Nullable String description, Collection aliases, Set flags); + + /** + * Registers a command under the same logic as {@link Commands#register(LiteralCommandNode, String, Collection)}. + * + * @param label the label of the to-be-registered command + * @param basicCommand the basic command instance to register + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + default @Unmodifiable Set register(final String label, final BasicCommand basicCommand) { + return this.register(label, null, Collections.emptyList(), basicCommand); + } + + /** + * Registers a command under the same logic as {@link Commands#register(LiteralCommandNode, String, Collection)}. + * + * @param label the label of the to-be-registered command + * @param description the help description for the root literal node + * @param basicCommand the basic command instance to register + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + default @Unmodifiable Set register(final String label, final @Nullable String description, final BasicCommand basicCommand) { + return this.register(label, description, Collections.emptyList(), basicCommand); + } + + /** + * Registers a command under the same logic as {@link Commands#register(LiteralCommandNode, String, Collection)}. + * + * @param label the label of the to-be-registered command + * @param aliases a collection of aliases to register the basic command under. + * @param basicCommand the basic command instance to register + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + default @Unmodifiable Set register(final String label, final Collection aliases, final BasicCommand basicCommand) { + return this.register(label, null, aliases, basicCommand); + } + + /** + * Registers a command under the same logic as {@link Commands#register(LiteralCommandNode, String, Collection)}. + * + * @param label the label of the to-be-registered command + * @param description the help description for the root literal node + * @param aliases a collection of aliases to register the basic command under. + * @param basicCommand the basic command instance to register + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + @Unmodifiable Set register(String label, @Nullable String description, Collection aliases, BasicCommand basicCommand); + + /** + * Registers a command under the same logic as {@link Commands#register(PluginMeta, LiteralCommandNode, String, Collection)}. + * + * @param pluginMeta the owning plugin's meta + * @param label the label of the to-be-registered command + * @param description the help description for the root literal node + * @param aliases a collection of aliases to register the basic command under. + * @param basicCommand the basic command instance to register + * @return successfully registered root command labels (including aliases and namespaced variants) + */ + @Unmodifiable Set register(PluginMeta pluginMeta, String label, @Nullable String description, Collection aliases, BasicCommand basicCommand); +} diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/MessageComponentSerializer.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/MessageComponentSerializer.java new file mode 100644 index 0000000000..19f3dc1242 --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/command/brigadier/MessageComponentSerializer.java @@ -0,0 +1,25 @@ +package io.papermc.paper.command.brigadier; + +import com.mojang.brigadier.Message; +import net.kyori.adventure.text.Component; +import net.kyori.adventure.text.serializer.ComponentSerializer; +import org.jetbrains.annotations.ApiStatus; +import org.jspecify.annotations.NullMarked; + +/** + * A component serializer for converting between {@link Message} and {@link Component}. + */ +@ApiStatus.Experimental +@NullMarked +@ApiStatus.NonExtendable +public interface MessageComponentSerializer extends ComponentSerializer { + + /** + * A component serializer for converting between {@link Message} and {@link Component}. + * + * @return serializer instance + */ + static MessageComponentSerializer message() { + return MessageComponentSerializerHolder.PROVIDER.orElseThrow(); + } +} diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/MessageComponentSerializerHolder.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/MessageComponentSerializerHolder.java new file mode 100644 index 0000000000..2db1295246 --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/command/brigadier/MessageComponentSerializerHolder.java @@ -0,0 +1,12 @@ +package io.papermc.paper.command.brigadier; + +import java.util.Optional; +import java.util.ServiceLoader; +import org.jetbrains.annotations.ApiStatus; + +@ApiStatus.Internal +final class MessageComponentSerializerHolder { + + static final Optional PROVIDER = ServiceLoader.load(MessageComponentSerializer.class) + .findFirst(); +} diff --git a/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/ArgumentTypes.java b/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/ArgumentTypes.java new file mode 100644 index 0000000000..9abb9ff336 --- /dev/null +++ b/paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/ArgumentTypes.java @@ -0,0 +1,371 @@ +package io.papermc.paper.command.brigadier.argument; + +import com.mojang.brigadier.arguments.ArgumentType; +import io.papermc.paper.command.brigadier.argument.predicate.ItemStackPredicate; +import io.papermc.paper.command.brigadier.argument.range.DoubleRangeProvider; +import io.papermc.paper.command.brigadier.argument.range.IntegerRangeProvider; +import io.papermc.paper.command.brigadier.argument.resolvers.BlockPositionResolver; +import io.papermc.paper.command.brigadier.argument.resolvers.FinePositionResolver; +import io.papermc.paper.command.brigadier.argument.resolvers.PlayerProfileListResolver; +import io.papermc.paper.command.brigadier.argument.resolvers.selector.EntitySelectorArgumentResolver; +import io.papermc.paper.command.brigadier.argument.resolvers.selector.PlayerSelectorArgumentResolver; +import io.papermc.paper.entity.LookAnchor; +import io.papermc.paper.registry.RegistryKey; +import io.papermc.paper.registry.TypedKey; +import java.util.UUID; +import net.kyori.adventure.key.Key; +import net.kyori.adventure.text.Component; +import net.kyori.adventure.text.format.NamedTextColor; +import net.kyori.adventure.text.format.Style; +import org.bukkit.GameMode; +import org.bukkit.HeightMap; +import org.bukkit.NamespacedKey; +import org.bukkit.World; +import org.bukkit.block.BlockState; +import org.bukkit.block.structure.Mirror; +import org.bukkit.block.structure.StructureRotation; +import org.bukkit.inventory.ItemStack; +import org.bukkit.scoreboard.Criteria; +import org.bukkit.scoreboard.DisplaySlot; +import org.jetbrains.annotations.ApiStatus; +import org.jspecify.annotations.NullMarked; + +import static io.papermc.paper.command.brigadier.argument.VanillaArgumentProvider.provider; + +/** + * Vanilla Minecraft includes several custom {@link ArgumentType}s that are recognized by the client. + * Many of these argument types include client-side completions and validation, and some include command signing context. + * + *

This class allows creating instances of these types for use in plugin commands, with friendly API result types.

+ * + *

{@link CustomArgumentType} is provided for customizing parsing or result types server-side, while sending the vanilla argument type to the client.

+ */ +@ApiStatus.Experimental +@NullMarked +public final class ArgumentTypes { + + /** + * Represents a selector that can capture any + * single entity. + * + * @return argument that takes one entity + */ + public static ArgumentType entity() { + return provider().entity(); + } + + /** + * Represents a selector that can capture multiple + * entities. + * + * @return argument that takes multiple entities + */ + public static ArgumentType entities() { + return provider().entities(); + } + + /** + * Represents a selector that can capture a + * singular player entity. + * + * @return argument that takes one player + */ + public static ArgumentType player() { + return provider().player(); + } + + /** + * Represents a selector that can capture multiple + * player entities. + * + * @return argument that takes multiple players + */ + public static ArgumentType players() { + return provider().players(); + } + + /** + * A selector argument that provides a list + * of player profiles. + * + * @return player profile argument + */ + public static ArgumentType playerProfiles() { + return provider().playerProfiles(); + } + + /** + * A block position argument. + * + * @return block position argument + */ + public static ArgumentType blockPosition() { + return provider().blockPosition(); + } + + /** + * A fine position argument. + * + * @return fine position argument + * @see #finePosition(boolean) to center whole numbers + */ + public static ArgumentType finePosition() { + return finePosition(false); + } + + /** + * A fine position argument. + * + * @param centerIntegers if whole numbers should be centered (+0.5) + * @return fine position argument + */ + public static ArgumentType finePosition(final boolean centerIntegers) { + return provider().finePosition(centerIntegers); + } + + /** + * A blockstate argument which will provide rich parsing for specifying + * the specific block variant and then the block entity NBT if applicable. + * + * @return argument + */ + public static ArgumentType blockState() { + return provider().blockState(); + } + + /** + * An ItemStack argument which provides rich parsing for + * specifying item material and item NBT information. + * + * @return argument + */ + public static ArgumentType itemStack() { + return provider().itemStack(); + } + + /** + * An item predicate argument. + * + * @return argument + */ + public static ArgumentType itemPredicate() { + return provider().itemStackPredicate(); + } + + /** + * An argument for parsing {@link NamedTextColor}s. + * + * @return argument + */ + public static ArgumentType namedColor() { + return provider().namedColor(); + } + + /** + * A component argument. + * + * @return argument + */ + public static ArgumentType component() { + return provider().component(); + } + + /** + * A style argument. + * + * @return argument + */ + public static ArgumentType