diff --git a/_redirects b/_redirects index 71d9f81b8..e59cc167c 100644 --- a/_redirects +++ b/_redirects @@ -7,4 +7,6 @@ /paper/per-world-configuration /paper/configuration /paper/configuration /paper/reference/configuration /paper/reference/vanilla-command-permissions /paper/reference/permissions -/paper/dev/commands /paper/dev/command-api/commands +/paper/dev/commands /paper/dev/command-api/basics/introduction +/paper/dev/command-api/commands /paper/dev/command-api/basics/introduction +/paper/dev/command-api/arguments /paper/dev/command-api/basics/arguments-and-literals \ No newline at end of file diff --git a/config/sidebar.paper.ts b/config/sidebar.paper.ts old mode 100644 new mode 100755 index 756be0385..b735c57f0 --- a/config/sidebar.paper.ts +++ b/config/sidebar.paper.ts @@ -131,7 +131,45 @@ const paper: SidebarsConfig = { type: "category", label: "Brigadier Command API", collapsed: true, - items: ["dev/api/command-api/commands", "dev/api/command-api/arguments"], + items: [ + { + type: "category", + label: "Basics", + collapsed: true, + items: [ + "dev/api/command-api/basics/introduction", + "dev/api/command-api/basics/command-tree", + "dev/api/command-api/basics/arguments-and-literals", + "dev/api/command-api/basics/executors", + "dev/api/command-api/basics/registration", + "dev/api/command-api/basics/requirements", + ], + }, + { + type: "category", + label: "Arguments", + collapsed: true, + items: [ + "dev/api/command-api/arguments/minecraft", + "dev/api/command-api/arguments/location", + "dev/api/command-api/arguments/entity-player", + "dev/api/command-api/arguments/registry", + "dev/api/command-api/arguments/paper", + "dev/api/command-api/arguments/enums", + "dev/api/command-api/arguments/predicate", + "dev/api/command-api/arguments/adventure", + ], + }, + { + type: "category", + label: "Misc", + collapsed: true, + items: [ + "dev/api/command-api/misc/comparison-bukkit-brigadier", + "dev/api/command-api/misc/basic-command", + ], + }, + ], }, { type: "category", diff --git a/docs/paper/dev/api/command-api/arguments.mdx b/docs/paper/dev/api/command-api/arguments.mdx deleted file mode 100644 index 06aae8d24..000000000 --- a/docs/paper/dev/api/command-api/arguments.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -slug: /dev/command-api/arguments -description: A guide to arguments in Paper's Brigadier command API. ---- - -# Arguments - -Argument types are datatypes that we can use instead of strings. - -:::danger[Experimental] - -Paper's command system is still experimental and may change in the future. - -::: - -## Basic usage of arguments - -You can add arguments to a command by doing the following: -```java title="YourPluginClass.java" -public class YourPluginClass extends JavaPlugin { - @Override - public void onEnable() { - final LifecycleEventManager manager = this.getLifecycleManager(); - manager.registerEventHandler(LifecycleEvents.COMMANDS, event -> { - final Commands commands = event.registrar(); - commands.register( - Commands.literal("enchantmentargumentcommand") - .then( - Commands.argument("enchantmentargument", ArgumentTypes.resource(RegistryKey.ENCHANTMENT)) - .executes(ctx -> { - ctx.getSource().getSender().sendPlainMessage( - ctx.getArgument("enchantmentargument", Enchantment.class).getKey().toString() - ); - return Command.SINGLE_SUCCESS; - }) - ).build() - ); - }); - } -} -``` - -This command has one argument of the `Enchantment` datatype. When the command is executed, the command -sender will get a message containing the key of the enchantment they selected. - -## Advantages over string-based arguments - -- Direct conversion to usable type -- Client-side error handling -- Custom types -- Non-alphanumerical sorting - -## Argument types - -By default, you can use [the registry API](../registries) to get simple argument types like -blocks, items, potions and many more. In the example above, we used the Enchantment -Argument type, but there are many others: - -### Predefined types (Registry) - -| Registry key name | Return datatype class | Description | -|---------------------|-----------------------|---------------------------------------------------------------------------------------------| -| GAME_EVENT | GameEvent | [Game events](https://minecraft.wiki/w/Sculk_Sensor#Vibration_frequencies) | -| STRUCTURE_TYPE | StructureType | [Structure types](https://minecraft.wiki/w/Structure#Overworld) | -| MOB_EFFECT | PotionEffectType | [Potion effect](https://minecraft.wiki/w/Effect#List) | -| BLOCK | BlockType | [Block type](https://minecraft.wiki/w/Block#List_of_blocks) | -| ITEM | ItemType | [Item type](https://minecraft.wiki/w/Item#List_of_items) | -| CAT_VARIANT | Cat.Type | [Cat variants](https://minecraft.wiki/w/Cat#Appearance) | -| FROG_VARIANT | Frog.Variant | [Frog variants](https://minecraft.wiki/w/Frog) | -| VILLAGER_PROFESSION | Villager.Profession | [Villager professions](https://minecraft.wiki/w/Villager#Professions) | -| VILLAGER_TYPE | Villager.Type | [Villager biome specific type](https://minecraft.wiki/w/Villager#Professions) | -| MAP_DECORATION_TYPE | MapCursor.Type | [Types of sprites displayed on a map](https://minecraft.wiki/w/Map#Map_icons) | -| MENU | MenuType | [Menu type](https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Inventory) | -| ATTRIBUTE | Attribute | [Entity attribute](https://minecraft.wiki/w/Attribute) | -| FLUID | Fluid | [Fluid types](https://minecraft.wiki/w/Fluid) | -| SOUND_EVENT | Sound | [Events that trigger sound effects](https://minecraft.wiki/w/Sounds.json#Sound_events) | -| BIOME | Biome | [Biome type](https://minecraft.wiki/w/Biome#Biome_types) | -| STRUCTURE | Structure | [Structures](https://minecraft.wiki/w/Structure#Overworld) | -| TRIM_MATERIAL | TrimMaterial | [Materials used to trim armor](https://minecraft.wiki/w/Smithing#Material) | -| TRIM_PATTERN | TrimPattern | [Trim patterns](https://minecraft.wiki/w/Smithing#Trimming) | -| DAMAGE_TYPE | DamageType | [All types of damage dealt to an entity](https://minecraft.wiki/w/Damage_type) | -| WOLF_VARIANT | Wolf.Variant | [Wolf variants](https://minecraft.wiki/w/Wolf#Variants) | -| ENCHANTMENT | Enchantment | [Enchantment type](https://minecraft.wiki/w/Enchanting#Summary_of_enchantments) | -| JUKEBOX_SONG | JukeboxSong | Music disc songs | -| BANNER_PATTERN | PatternType | [Banner patterns](https://minecraft.wiki/w/Banner_Pattern#Variants) | -| PAINTING_VARIANT | Art | [Painting variants](https://minecraft.wiki/w/Painting#Canvases) | -| INSTRUMENT | MusicInstrument | [Goat horns](https://minecraft.wiki/w/Goat_Horn#Playing) | -| ENTITY_TYPE | EntityType | [Every entity type](https://minecraft.wiki/w/Entity#Types_of_entities) | -| PARTICLE_TYPE | Particle | [Every particle type](https://minecraft.wiki/w/Particles_(Java_Edition)#Types_of_particles) | -| POTION | PotionType | [Every potion type](https://minecraft.wiki/w/Potion#Effect_potions) | -| MEMORY_MODULE_TYPE | MemoryKey | Keys for saving per-entity data | - -Paper specifies many more argument types. For more information on them, see ArgumentTypes. - -### Custom types - -Custom arguments can be created by implementing the CustomArgumentType -interface. - -Now, let's say that we want to implement a command which lets you order ice cream. For that, -we add an enum that specifies all available values for our custom type. - -```java title="IceCreamType.java" -public enum IceCreamType { - VANILLA, - CHOCOLATE, - STRAWBERRY, - MINT, - COOKIES -} -``` -Now, we have to define the argument itself. We do this by implementing the CustomArgumentType.Converted interface: - -```java title="IceCreamTypeArgument.java" -public class IceCreamTypeArgument implements CustomArgumentType.Converted { - - @Override - public IceCreamType convert(String nativeType) throws CommandSyntaxException { - try { - return IceCreamType.valueOf(nativeType.toUpperCase(Locale.ENGLISH)); - } catch (IllegalArgumentException ignored) { - Message message = MessageComponentSerializer.message().serialize(Component.text("Invalid flavor %s!".formatted(nativeType), NamedTextColor.RED)); - - throw new CommandSyntaxException(new SimpleCommandExceptionType(message), message); - } - } - - @Override - public ArgumentType getNativeType() { - return StringArgumentType.word(); - } - - @Override - public CompletableFuture listSuggestions(CommandContext context, SuggestionsBuilder builder) { - for (IceCreamType flavor : IceCreamType.values()) { - builder.suggest(flavor.name(), MessageComponentSerializer.message().serialize(Component.text("look at this cool green tooltip!", NamedTextColor.GREEN))); - } - - return builder.buildFuture(); - } -} -``` - -We implemented the CustomArgumentType.Converted -interface. This interface takes two type arguments: our custom enum, T, and a native Java type called N. - -- `convert()` converts the native type (in this case `String`) into our custom type. - -- `getNativeType()` returns the type of string that our command argument uses. This uses a single word, so we return `StringArgumentType.word()`. - -- `listSuggestions()` returns `CompletableFuture` so that the client -can suggest all available options. We can even add tooltips to the suggestions to explain them in greater -detail. - -We then need to register the command: - -```java title="TestPlugin.java" -@Override -public void onEnable() { - final LifecycleEventManager manager = this.getLifecycleManager(); - manager.registerEventHandler(LifecycleEvents.COMMANDS, event -> { - final Commands commands = event.registrar(); - commands.register(Commands.literal("ordericecream") - .then( - Commands.argument("flavor", new IceCreamTypeArgument()) - .executes(ctx -> { - IceCreamType argumentResponse = ctx.getArgument("flavor", IceCreamType.class); - ctx.getSource().getSender().sendMessage(Component.text("You ordered: " + argumentResponse)); - return Command.SINGLE_SUCCESS; - }) - ).build() - ); - }); -} -``` - -Now that we have registered the command, we can execute it in-game: - -![command with suggestions](./assets/icecreamargument.gif) -Look, we can even see our tooltip and if we execute the command, we get the message we specified: - -![executed command](./assets/command-executed.gif) diff --git a/docs/paper/dev/api/command-api/arguments/adventure.mdx b/docs/paper/dev/api/command-api/arguments/adventure.mdx new file mode 100755 index 000000000..781072b65 --- /dev/null +++ b/docs/paper/dev/api/command-api/arguments/adventure.mdx @@ -0,0 +1,189 @@ +--- +slug: /dev/command-api/arguments/adventure +description: Documentation for all arguments returning Adventure API objects. +--- + +import ComponentMp4 from "./assets/vanilla-arguments/component.mp4"; +import KeyMp4 from "./assets/vanilla-arguments/key.mp4"; +import NamedColorMp4 from "./assets/vanilla-arguments/namedcolor.mp4"; +import StyleMp4 from "./assets/vanilla-arguments/style.mp4"; +import SignedMessageMp4 from "./assets/vanilla-arguments/signedmessage.mp4"; + +# Adventure Library Arguments +These arguments return a class from the `net.kyori` package. They are technically not native to Minecraft or Bukkit, but as Paper includes the Adventure library, they are +widely used in the Paper ecosystem. + +## Component argument +:::note + +This argument is very technical. Following the same format as the `/tellraw ` command for its second argument, it expects the JSON +representation of a text component, making it inappropriate for general user input. + +::: + +The result is returned as an Adventure component to work with. + +### Example usage +```java +public static LiteralCommandNode componentArgument() { + return Commands.literal("componentargument") + .then(Commands.argument("arg", ArgumentTypes.component()) + .executes(ctx -> { + final Component component = ctx.getArgument("arg", Component.class); + + ctx.getSource().getSender().sendRichMessage( + "Your message: ", + Placeholder.component("input", component) + ); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## Key argument +The key argument allows a user to put in any artificial (namespaced) key, ensuring its validity. This returns a [`Key`](https://jd.advntr.dev/key/latest/net/kyori/adventure/key/Key.html), +which can be used at various other places in the Paper API. + +### Example usage +```java +public static LiteralCommandNode keyArgument() { + return Commands.literal("key") + .then(Commands.argument("key_input", ArgumentTypes.key()) + .executes(ctx -> { + final Key key = ctx.getArgument("key_input", Key.class); + + ctx.getSource().getSender().sendRichMessage("You put in !", + Placeholder.unparsed("key", key.asString()) + ); + + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## Named color argument +This argument provides the user with the ability to select between the 16 built-in "named" text colors. This argument returns a +[`NamedTextColor`](https://javadoc.io/doc/net.kyori/adventure-api/latest/net/kyori/adventure/text/format/NamedTextColor.html), +which you can use for applying a color to components. + +### Example usage +```java +public static LiteralCommandNode namedColorArgument() { + return Commands.literal("namedcolor") + .then(Commands.argument("color", ArgumentTypes.namedColor()) + .then(Commands.argument("message", StringArgumentType.greedyString()) + .executes(ctx -> { + final NamedTextColor color = ctx.getArgument("color", NamedTextColor.class); + final String msg = StringArgumentType.getString(ctx, "message"); + + ctx.getSource().getSender().sendMessage( + Component.text(msg).color(color) + ); + return Command.SINGLE_SUCCESS; + }))) + .build(); +} +``` + +### In-game preview + + + +## Adventure style argument +:::note + +Similar to the component argument, this argument is not really appropriate for general user input, as it also follows the JSON format for displaying components. Most users +do not know how to use that format and thus its general usage is not advised. + +::: + +The style argument returns its value in the form of a [`Style`](https://javadoc.io/doc/net.kyori/adventure-api/latest/net/kyori/adventure/text/format/Style.html) object. +This can be applied to any component using `Component#style(Style)`. Whilst the JSON input allows for the `text` field, its content is completely ignored. + +### Example usage +```java +public static LiteralCommandNode styleArgument() { + return Commands.literal("style") + .then(Commands.argument("style", ArgumentTypes.style()) + .then(Commands.argument("message", StringArgumentType.greedyString()) + .executes(ctx -> { + final Style style = ctx.getArgument("style", Style.class); + final String msg = StringArgumentType.getString(ctx, "message"); + + ctx.getSource().getSender().sendRichMessage("Your input: ", + Placeholder.component("input", Component.text(message).style(style)) + ); + return Command.SINGLE_SUCCESS; + }))) + .build(); +} +``` + +### In-game preview + + + +## Signed message argument +The signed message argument allows a player to send an argument in the form of a **signed message** to the server. This signed message is a special type - it +allows the server to send that message, without the ability to directly modify it, to any player. The visible difference is that unsigned messages have a white bar at the left, +whilst signed messages don't. + +A signed message argument returns a `SignedMessageResolver`. In order to call its `#resolve` method, you have to pass in two parameters: +* The argument name +* The `CommandContext` object + +The resolved value is a `CompletableFuture`, whose [`SignedMessage`](https://javadoc.io/doc/net.kyori/adventure-api/latest/net/kyori/adventure/chat/SignedMessage.html) +value you can handle using `thenAccept(Consumer)`. Inside of the consumer, you can send the signed message to players or work with it in other ways. + +:::warning + +By default, the consumer passed into `thenAccept` is not executed on the main thread, making it unsafe to use most of Paper API within it. +If you need to use the API, you can schedule a task to be run on the next available tick. For this you can use the +main thread executor. +You can read up on that [here](../../scheduler.mdx). + +::: + +:::note + +A non-player sender is not capable of sending a signed message, which means that the resolved `CompletableFuture` will never be completed. +You should make sure that only players can use your argument with `.requires(ctx -> ctx.getSender() instanceof Player)` on your `SignedArgument`. You may +add a fallback greedy string argument for non-player senders if you want the argument to execute regardless of signing. + +::: + +### Example usage +```java title="MinecraftArguments.java" +public static LiteralCommandNode signedMessageArgument() { + return Commands.literal("signedmessage") + .then(Commands.argument("target", ArgumentTypes.player()) + .then(Commands.argument("message", ArgumentTypes.signedMessage()) + .executes(MinecraftArguments::executeSignedMessageCommand))) + .build(); +} + +private static int executeSignedMessageCommand(final CommandContext ctx) throws CommandSyntaxException { + final Player target = ctx.getArgument("target", PlayerSelectorArgumentResolver.class).resolve(ctx.getSource()).getFirst(); + final SignedMessageResolver messageResolver = ctx.getArgument("message", SignedMessageResolver.class); + + messageResolver.resolveSignedMessage("message", ctx).thenAccept(msg -> { + target.sendMessage(msg, ChatType.CHAT.bind(ctx.getSource().getSender().name())); + }); + + + return Command.SINGLE_SUCCESS; +} +``` + +### In-game preview + \ No newline at end of file diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/enchants-registry.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/enchants-registry.mp4 new file mode 100644 index 000000000..6329c1d0f Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/enchants-registry.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-attributes.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-attributes.mp4 new file mode 100644 index 000000000..8dc0c9e56 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-attributes.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-banner-pattern.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-banner-pattern.mp4 new file mode 100644 index 000000000..c8ea8de4a Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-banner-pattern.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-biome.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-biome.mp4 new file mode 100644 index 000000000..da5a19d9b Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-biome.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-block.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-block.mp4 new file mode 100644 index 000000000..e0c3916a5 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-block.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-cat-variant.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-cat-variant.mp4 new file mode 100644 index 000000000..7ca007baf Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-cat-variant.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-damage-type.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-damage-type.mp4 new file mode 100644 index 000000000..7a7343c1d Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-damage-type.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-data-component-type.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-data-component-type.mp4 new file mode 100644 index 000000000..0c7fcc05c Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-data-component-type.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-enchantment.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-enchantment.mp4 new file mode 100644 index 000000000..a97b45595 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-enchantment.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-entity-type.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-entity-type.mp4 new file mode 100644 index 000000000..d3f18394c Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-entity-type.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-fluid.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-fluid.mp4 new file mode 100644 index 000000000..9429144da Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-fluid.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-frog-variant.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-frog-variant.mp4 new file mode 100644 index 000000000..a19430b9a Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-frog-variant.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-game-event.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-game-event.mp4 new file mode 100644 index 000000000..d5184925e Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-game-event.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-instrument.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-instrument.mp4 new file mode 100644 index 000000000..d32e36be6 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-instrument.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-item.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-item.mp4 new file mode 100644 index 000000000..4320185b3 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-item.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-jukebox-song.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-jukebox-song.mp4 new file mode 100644 index 000000000..ef30eaf07 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-jukebox-song.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-map-decoration-type.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-map-decoration-type.mp4 new file mode 100644 index 000000000..4428ee2fd Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-map-decoration-type.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-memory-module-type.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-memory-module-type.mp4 new file mode 100644 index 000000000..0aa7f89f2 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-memory-module-type.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-menu.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-menu.mp4 new file mode 100644 index 000000000..2b1c89132 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-menu.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-mob-effect.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-mob-effect.mp4 new file mode 100644 index 000000000..846948784 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-mob-effect.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-painting-variant.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-painting-variant.mp4 new file mode 100644 index 000000000..5ffdbe764 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-painting-variant.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-particle-type.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-particle-type.mp4 new file mode 100644 index 000000000..43f3eb1bc Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-particle-type.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-potion.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-potion.mp4 new file mode 100644 index 000000000..95f39b4f1 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-potion.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-sound-event.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-sound-event.mp4 new file mode 100644 index 000000000..254ed7318 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-sound-event.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-structure-type.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-structure-type.mp4 new file mode 100644 index 000000000..483adb589 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-structure-type.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-material.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-material.mp4 new file mode 100644 index 000000000..054f149ce Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-material.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-pattern.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-pattern.mp4 new file mode 100644 index 000000000..03c7e312f Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-trim-pattern.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-profession.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-profession.mp4 new file mode 100644 index 000000000..28319039d Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-profession.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-type.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-type.mp4 new file mode 100644 index 000000000..c8f21913d Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-villager-type.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-wolf-variant.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-wolf-variant.mp4 new file mode 100644 index 000000000..786e54752 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resource-wolf-variant.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resourcekey-item.mp4 b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resourcekey-item.mp4 new file mode 100644 index 000000000..6930a7d76 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/registry-arguments/resourcekey-item.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockposition.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockposition.mp4 new file mode 100644 index 000000000..58f06fcb8 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockposition.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockstate.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockstate.mp4 new file mode 100644 index 000000000..1728fa219 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/blockstate.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/component.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/component.mp4 new file mode 100644 index 000000000..d6152bb59 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/component.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/doublerange.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/doublerange.mp4 new file mode 100644 index 000000000..a453ce573 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/doublerange.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entities.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entities.mp4 new file mode 100644 index 000000000..8f32158cf Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entities.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-opped.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-opped.mp4 new file mode 100644 index 000000000..9bb8511ec Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-opped.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-unopped.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-unopped.mp4 new file mode 100644 index 000000000..310691041 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entity-unopped.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entityanchor.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entityanchor.mp4 new file mode 100644 index 000000000..31e2d621c Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/entityanchor.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/fineposition.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/fineposition.mp4 new file mode 100644 index 000000000..6298266e4 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/fineposition.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/gamemode.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/gamemode.mp4 new file mode 100644 index 000000000..51d29e2f6 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/gamemode.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/heightmap.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/heightmap.mp4 new file mode 100644 index 000000000..4f46acc80 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/heightmap.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/integerrange.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/integerrange.mp4 new file mode 100644 index 000000000..0fdf92161 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/integerrange.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itempredicate.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itempredicate.mp4 new file mode 100644 index 000000000..08b8ec933 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itempredicate.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itemstack.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itemstack.mp4 new file mode 100644 index 000000000..d7dacc774 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/itemstack.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/key.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/key.mp4 new file mode 100644 index 000000000..4c736bd42 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/key.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namedcolor.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namedcolor.mp4 new file mode 100644 index 000000000..6ada543ac Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namedcolor.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namespacedkey.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namespacedkey.mp4 new file mode 100644 index 000000000..0fe21c773 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/namespacedkey.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/objectivecriteria.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/objectivecriteria.mp4 new file mode 100644 index 000000000..a31bea20a Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/objectivecriteria.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/player.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/player.mp4 new file mode 100644 index 000000000..7da51e805 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/player.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/playerprofiles.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/playerprofiles.mp4 new file mode 100644 index 000000000..360328072 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/playerprofiles.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/players.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/players.mp4 new file mode 100644 index 000000000..db067b925 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/players.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/scoreboarddisplayslot.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/scoreboarddisplayslot.mp4 new file mode 100644 index 000000000..c9836e4c6 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/scoreboarddisplayslot.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/signedmessage.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/signedmessage.mp4 new file mode 100644 index 000000000..42264d7d2 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/signedmessage.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/style.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/style.mp4 new file mode 100644 index 000000000..73009ef66 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/style.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templatemirror.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templatemirror.mp4 new file mode 100644 index 000000000..73d39c687 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templatemirror.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templaterotation.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templaterotation.mp4 new file mode 100644 index 000000000..ab2db8e79 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/templaterotation.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/time.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/time.mp4 new file mode 100644 index 000000000..78e5a102e Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/time.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/uuid.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/uuid.mp4 new file mode 100644 index 000000000..46cc53ec7 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/uuid.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/world.mp4 b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/world.mp4 new file mode 100644 index 000000000..26e97d3b8 Binary files /dev/null and b/docs/paper/dev/api/command-api/arguments/assets/vanilla-arguments/world.mp4 differ diff --git a/docs/paper/dev/api/command-api/arguments/entity-player.mdx b/docs/paper/dev/api/command-api/arguments/entity-player.mdx new file mode 100755 index 000000000..23101943a --- /dev/null +++ b/docs/paper/dev/api/command-api/arguments/entity-player.mdx @@ -0,0 +1,184 @@ +--- +slug: /dev/command-api/arguments/entity-player +description: Player and Entity arguments documentation. +--- + +import EntityOppedMp4 from "./assets/vanilla-arguments/entity-opped.mp4"; +import EntityUnoppedMp4 from "./assets/vanilla-arguments/entity-unopped.mp4"; +import EntitiesMp4 from "./assets/vanilla-arguments/entities.mp4"; +import PlayerMp4 from "./assets/vanilla-arguments/player.mp4"; +import PlayersMp4 from "./assets/vanilla-arguments/players.mp4"; +import PlayerProfilesMp4 from "./assets/vanilla-arguments/playerprofiles.mp4"; + +# Entity and Player Arguments +The arguments described in this section relate to arguments which you can use to retrieve entities. Their main usage is the selection of command targets. +All of these have entity selectors (`@a`, `@e`, `@n`, etc.) as valid inputs, though they require the `minecraft.command.selector` permission in order to +be able to be used. The specific arguments may allow or disallow certain selectors. + +Due to the permission requirement for selectors it is advised to add a `requires` statement to your command: +```java +.requires(ctx -> ctx.getSender().hasPermission("minecraft.command.selector")) +``` + +You can find more information about requirements [here](../basics/requirements.mdx). + +## Entity argument +This argument, after resolving its returning `EntitySelectorArgumentResolver`, returns a list of exactly one, no more and no less, entity. It is safe +to call `List#getFirst()` to retrieve that entity. You can resolve it using `ArgumentResolver#resolve(CommandSourceStack)` + +### Example usage +```java +public static LiteralCommandNode entityArgument() { + return Commands.literal("entityarg") + .then(Commands.argument("arg", ArgumentTypes.entity()) + .executes(ctx -> { + final EntitySelectorArgumentResolver entitySelectorArgumentResolver = ctx.getArgument("arg", EntitySelectorArgumentResolver.class); + final List entities = entitySelectorArgumentResolver.resolve(ctx.getSource()); + + ctx.getSource().getSender().sendRichMessage("Found ", + Placeholder.component("entityname", entities.getFirst().name()) + ); + + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview +If the executing player doesn't have the `minecraft.command.selector` permission: + + +If the executing player has the `minecraft.command.selector` permission: + + + +## Entities argument +In contrast to the single entity argument, this multiple-entities argument accepts any amount of entities, with the minimum amount of entities being 1. They can, once again, be resolved using +`ArgumentResolver#resolve(CommandSourceStack)`, +which returns a `List`. + +### Example usage +```java +public static LiteralCommandNode entitiesArgument() { + return Commands.literal("entitiesarg") + .then(Commands.argument("arg", ArgumentTypes.entities()) + .executes(ctx -> { + final EntitySelectorArgumentResolver entitySelectorArgumentResolver = ctx.getArgument("arg", EntitySelectorArgumentResolver.class); + final List entities = entitySelectorArgumentResolver.resolve(ctx.getSource()); + + final Component foundEntities = Component.join(JoinConfiguration.commas(true), entities.stream().map(Entity::name).toList()); + + ctx.getSource().getSender().sendRichMessage("Found ", + Placeholder.component("entitynames", foundEntities) + ); + + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## Player argument +The player argument allows to retrieve a `PlayerSelectorArgumentResolver` for player arguments. +For this "single player" argument, you can safely get the target player by running `PlayerSelectorArgumentResolver.resolve(ctx.getSource()).getFirst()`, +which returns a Player object. + +### Example usage +This command yeets the targeted player into the air! + +```java +public static LiteralCommandNode playerArgument() { + return Commands.literal("player") + .then(Commands.argument("target", ArgumentTypes.player()) + .executes(ctx -> { + final PlayerSelectorArgumentResolver targetResolver = ctx.getArgument("target", PlayerSelectorArgumentResolver.class); + final Player target = targetResolver.resolve(ctx.getSource()).getFirst(); + + target.setVelocity(new Vector(0, 100, 0)); + target.sendRichMessage("Yeeeeeeeeeet"); + + ctx.getSource().getSender().sendRichMessage("Yeeted !", + Placeholder.component("target", target.name()) + ); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## Players argument +The "multiple players" argument works similarly to the "single player" argument, also returning a `PlayerSelectorArgumentResolver`. Instead of just resolving to exactly one `Player`, this +one can resolve to more than just one player - which you should account for in case of using this argument. `PlayerSelectorArgumentResolver.resolve(ctx.getSource())` returns a +`List`, which you can just iterate through. + +### Example usage +Extending the "single player" yeet command to support multiple targets can look like this: + +```java +public static LiteralCommandNode playersArgument() { + return Commands.literal("players") + .then(Commands.argument("targets", ArgumentTypes.players()) + .executes(ctx -> { + final PlayerSelectorArgumentResolver targetResolver = ctx.getArgument("targets", PlayerSelectorArgumentResolver.class); + final List targets = targetResolver.resolve(ctx.getSource()); + final CommandSender sender = ctx.getSource().getSender(); + + for (final Player target : targets) { + target.setVelocity(new Vector(0, 100, 0)); + target.sendRichMessage("Yeeeeeeeeeet"); + + sender.sendRichMessage("Yeeted !", + Placeholder.component("target", target.name()) + ); + } + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## Player profiles argument +The player profiles argument is a very powerful argument which can retrieve both offline and online players. It returns the result of the argument as a `PlayerProfileListResolver`, +which resolves to a `Collection`. This collection can be iterated to get the resulting profile(s). Usually, it only returns a single `PlayerProfile` if retrieving +a player by name, but it can return multiple if using the entity selectors (like `@a` on online players). Thus it always makes sense to run whatever operation you want to run on +all entries in the collection instead of just the first one. + +This argument will run API calls to Mojang servers in order to retrieve player information for players which have never joined the server before. Due to this operation sometimes +taking a bit longer, it is suggested to resolve this argument in an asynchronous context in order to not cause any server lag. + +Sometimes, these API calls may fail. This is also visible in the in-game preview down below. This behavior is also the reason for `/whitelist add` sometimes. + +### Example usage - player lookup command +```java +public static LiteralCommandNode playerProfilesArgument() { + return Commands.literal("lookup") + .then(Commands.argument("profile", ArgumentTypes.playerProfiles()) + .executes(ctx -> { + final PlayerProfileListResolver profilesResolver = ctx.getArgument("profile", PlayerProfileListResolver.class); + final Collection foundProfiles = profilesResolver.resolve(ctx.getSource()); + + for (final PlayerProfile profile : foundProfiles) { + ctx.getSource().getSender().sendPlainMessage("Found " + profile.getName()); + } + + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + \ No newline at end of file diff --git a/docs/paper/dev/api/command-api/arguments/enums.mdx b/docs/paper/dev/api/command-api/arguments/enums.mdx new file mode 100755 index 000000000..ec44d64a3 --- /dev/null +++ b/docs/paper/dev/api/command-api/arguments/enums.mdx @@ -0,0 +1,167 @@ +--- +slug: /dev/command-api/arguments/enums +description: Documentation for EntityAnchor, GameMode and similar enum value arguments. +--- + +import EntityAnchorMp4 from "./assets/vanilla-arguments/entityanchor.mp4"; +import GameModeMp4 from "./assets/vanilla-arguments/gamemode.mp4"; +import HeightMapMp4 from "./assets/vanilla-arguments/heightmap.mp4"; +import ScoreboardDisplaySlotMp4 from "./assets/vanilla-arguments/scoreboarddisplayslot.mp4"; +import TemplateMirrorMp4 from "./assets/vanilla-arguments/templatemirror.mp4"; +import TemplateRotationMp4 from "./assets/vanilla-arguments/templaterotation.mp4"; + +# Enum Value Arguments + +## Entity anchor argument +The entity anchor argument has two valid inputs: `feet` and `eyes`. The resulting `LookAnchor` is mainly used for methods like +`Entity#lookAt(Position, LookAnchor)` or +`Player#lookAt(Entity, LookAnchor, LookAnchor)`. + +### Example usage +```java +public static LiteralCommandNode entityAnchorArgument() { + return Commands.literal("entityanchor") + .then(Commands.argument("arg", ArgumentTypes.entityAnchor()) + .executes(ctx -> { + final LookAnchor lookAnchor = ctx.getArgument("arg", LookAnchor.class); + + ctx.getSource().getSender().sendRichMessage("You chose !", + Placeholder.unparsed("anchor", lookAnchor.name()) + ); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## GameMode argument +The game mode argument works the same way as the first argument of the Vanilla `/gamemode ` command. It accepts any of the 4 valid game modes, returning +a `GameMode` enum to use in code. + +### Example usage +```java +public static LiteralCommandNode gameModeArgument() { + return Commands.literal("gamemodearg") + .then(Commands.argument("arg", ArgumentTypes.gameMode()) + .executes(ctx -> { + final GameMode gamemode = ctx.getArgument("arg", GameMode.class); + + if (ctx.getSource().getExecutor() instanceof Player player) { + player.setGameMode(gamemode); + player.sendRichMessage("Your gamemode has been set to !", + Placeholder.component("gamemode", Component.translatable(gamemode)) + ); + return Command.SINGLE_SUCCESS; + } + + ctx.getSource().getSender().sendPlainMessage("This command requires a player!"); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## HeightMap argument +The `HeightMap` argument consists of the following, valid inputs: `motion_blocking`, `motion_blocking_no_leaves`, `ocean_floor`, and `world_surface`. It is often +used for declaring relative positioning for data packs or the `/execute positioned over ` command. E.g. `world_surface` +would mean that the Y coordinate of the surface of the world on the set X/Z values should be used. + +### Example usage +```java +public static LiteralCommandNode heightMapArgument() { + return Commands.literal("heightmap") + .then(Commands.argument("arg", ArgumentTypes.heightMap()) + .executes(ctx -> { + final HeightMap heightMap = ctx.getArgument("arg", HeightMap.class); + + ctx.getSource().getSender().sendRichMessage("You selected ", + Placeholder.unparsed("selection", heightMap.name()) + ); + + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## Scoreboard display slot argument +This argument allows you to retrieve a `DisplaySlot` enum value from the user. + +### Example usage +```java +public static LiteralCommandNode scoreboardDisplaySlotArgument() { + return Commands.literal("scoreboarddisplayslot") + .then(Commands.argument("slot", ArgumentTypes.scoreboardDisplaySlot()) + .executes(ctx -> { + final DisplaySlot slot = ctx.getArgument("slot", DisplaySlot.class); + + ctx.getSource().getSender().sendPlainMessage("You selected: " + slot.getId()); + + return Command.SINGLE_SUCCESS; + }) + ).build(); +} +``` + +### In-game preview + + + +## Template mirror argument +Here, the user has 3 valid input possibilities: `front_back`, `left_right`, and `none`. You can retrieve the result of +the argument as a `Mirror` enum value. + +### Example usage +```java +public static LiteralCommandNode templateMirrorArgument() { + return Commands.literal("templatemirror") + .then(Commands.argument("mirror", ArgumentTypes.templateMirror()) + .executes(ctx -> { + final Mirror mirror = ctx.getArgument("mirror", Mirror.class); + + ctx.getSource().getSender().sendPlainMessage("You selected: " + mirror.name()); + + return Command.SINGLE_SUCCESS; + }) + ).build(); +} +``` + +### In-game preview + + + +## Template rotation argument +For the template rotation argument, the user has 4 valid input possibilities: `180`, `clockwise_90`, `counterclockwise_90`, and `none`. You can retrieve the result +of the argument as a `StructureRotation` enum value. + +### Example usage +```java +public static LiteralCommandNode templateRotationArgument() { + return Commands.literal("templaterotation") + .then(Commands.argument("rotation", ArgumentTypes.templateRotation()) + .executes(ctx -> { + final StructureRotation rotation = ctx.getArgument("rotation", StructureRotation.class); + + ctx.getSource().getSender().sendPlainMessage("You selected: " + rotation.name()); + + return Command.SINGLE_SUCCESS; + }) + ).build(); +} +``` + +### In-game preview + \ No newline at end of file diff --git a/docs/paper/dev/api/command-api/arguments/location.mdx b/docs/paper/dev/api/command-api/arguments/location.mdx new file mode 100755 index 000000000..9714e2573 --- /dev/null +++ b/docs/paper/dev/api/command-api/arguments/location.mdx @@ -0,0 +1,99 @@ +--- +slug: /dev/command-api/arguments/location +description: BlockPosition, FinePosition and World argument documentation. +--- + +import BlockPositionMp4 from "./assets/vanilla-arguments/blockposition.mp4"; +import FinePositionMp4 from "./assets/vanilla-arguments/fineposition.mp4"; +import WorldMp4 from "./assets/vanilla-arguments/world.mp4"; + +# Location Arguments + +## Block position argument +The block position argument is used for retrieving the position of a block. It works the same way as the first argument of the `/setblock ` Vanilla command. +In order to retrieve the `BlockPosition` variable from the +`BlockPositionResolver`, we have to resolve it using the command source. + +### Example usage +```java +public static LiteralCommandNode blockPositionArgument() { + return Commands.literal("blockpositionargument") + .then(Commands.argument("arg", ArgumentTypes.blockPosition()) + .executes(ctx -> { + final BlockPositionResolver blockPositionResolver = ctx.getArgument("arg", BlockPositionResolver.class); + final BlockPosition blockPosition = blockPositionResolver.resolve(ctx.getSource()); + + ctx.getSource().getSender().sendPlainMessage("Put in " + blockPosition.x() + " " + blockPosition.y() + " " + blockPosition.z()); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## Fine position argument +The fine position argument works similarly to the block position argument, with the only difference being that it can accept decimal (precise) location input. The optional +overload (`ArgumentTypes.finePosition(boolean centerIntegers)`), which defaults to false if not set, will center whole input, meaning 5 becomes 5.5 (5.0 would stay as 5.0 though), +as that is the "middle" of a block. This only applies to X/Z. The y coordinate is untouched by this operation. + +This argument returns a `FinePositionResolver`. You can resolve that by running `FinePositionResolver#resolve(CommandSourceStack)` to get the resulting +`FinePosition`. + +### Example usage +```java +public static LiteralCommandNode finePositionArgument() { + return Commands.literal("fineposition") + .then(Commands.argument("arg", ArgumentTypes.finePosition(true)) + .executes(ctx -> { + final FinePositionResolver resolver = ctx.getArgument("arg", FinePositionResolver.class); + final FinePosition finePosition = resolver.resolve(ctx.getSource()); + + ctx.getSource().getSender().sendRichMessage("Position: ", + Placeholder.unparsed("x", Double.toString(finePosition.x())), + Placeholder.unparsed("y", Double.toString(finePosition.y())), + Placeholder.unparsed("z", Double.toString(finePosition.z())) + ); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + + +## World argument +This argument allows the user to select one of the currently loaded world. You can retrieve the result of that as a generic Bukkit +`World` object. + +### Example usage +```java +public static LiteralCommandNode worldArgument() { + return Commands.literal("teleport-to-world") + .then(Commands.argument("world", ArgumentTypes.world()) + .executes(ctx -> { + final World world = ctx.getArgument("world", World.class); + + if (ctx.getSource().getExecutor() instanceof Player player) { + player.teleport(world.getSpawnLocation(), PlayerTeleportEvent.TeleportCause.COMMAND); + ctx.getSource().getSender().sendRichMessage("Successfully teleported to ", + Placeholder.component("player", player.name()), + Placeholder.unparsed("world", world.getName()) + ); + return Command.SINGLE_SUCCESS; + } + + ctx.getSource().getSender().sendRichMessage("This command requires a player!"); + return Command.SINGLE_SUCCESS; + }) + ).build(); +} +``` + +### In-game preview + \ No newline at end of file diff --git a/docs/paper/dev/api/command-api/arguments/minecraft.mdx b/docs/paper/dev/api/command-api/arguments/minecraft.mdx new file mode 100755 index 000000000..adf02ef30 --- /dev/null +++ b/docs/paper/dev/api/command-api/arguments/minecraft.mdx @@ -0,0 +1,44 @@ +--- +slug: /dev/command-api/arguments/minecraft +description: Everything regarding the essential Brigadier arguments. +--- + +# Minecraft Arguments +The [Arguments and Literals](../basics/arguments-and-literals) page covers the most used, native Brigadier arguments. But Minecraft (and Paper) define a few more. These can be accessed +in a static context using the `ArgumentTypes` class. We will go over all of those in this section. + +## Quick overview +A quick overview of all possible arguments is defined here: + +| Method Name | Return Value | Quick Link | +|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| +| `blockPosition()` | BlockPositionResolver | [Block Position Argument](./location#block-position-argument) | +| `blockState()` | BlockState | [Block State Argument](./paper#block-state-argument) | +| `component()` | [Component (Kyori)](https://javadoc.io/doc/net.kyori/adventure-api/latest/net/kyori/adventure/text/Component.html) | [Component Argument](./adventure#component-argument) | +| `doubleRange()` | DoubleRangeProvider | [Double Range argument](./predicate#double-range-argument) | +| `entity()` | EntitySelectorArgumentResolver | [Entity Argument](./entity-player#entity-argument) | +| `entities()` | EntitySelectorArgumentResolver | [Entities Argument](./entity-player#entities-argument) | +| `entityAnchor()` | LookAnchor | [Entity Anchor Argument](./enums#entity-anchor-argument) | +| `finePosition(boolean centerIntegers)` | FinePositionResolver | [Fine Position Argument](./location#fine-position-argument) | +| `gameMode()` | GameMode | [GameMode Argument](./enums#gamemode-argument) | +| `heightMap()` | HeightMap | [HeightMap Argument](./enums#heightmap-argument) | +| `integerRange()` | IntegerRangeProvider | [Integer Range Argument](./predicate#integer-range-argument) | +| `itemPredicate()` | ItemStackPredicate | [Item Predicate Argument](./predicate#item-predicate-argument) | +| `itemStack()` | ItemStack | [ItemStack Argument](./paper#itemstack-argument) | +| `key()` | [Key (Kyori)](https://jd.advntr.dev/key/4.18.0/net/kyori/adventure/key/Key.html) | [Key Argument](./adventure#key-argument) | +| `namedColor()` | [NamedTextColor (Kyori)](https://javadoc.io/doc/net.kyori/adventure-api/latest/net/kyori/adventure/text/format/NamedTextColor.html) | [Named Color Argument](./adventure#named-color-argument) | +| `namespacedKey()` | NamespacedKey | [Bukkit NamespacedKey Argument](./paper#namespacedkey-argument) | +| `objectiveCriteria()` | Criteria | [Objective Criteria Argument](./paper#objective-criteria-argument) | +| `player()` | PlayerSelectorArgumentResolver | [Player Argument](./entity-player#player-argument) | +| `players()` | PlayerSelectorArgumentResolver | [Players Argument](./entity-player#players-argument) | +| `playerProfiles()` | PlayerProfileListResolver | [Player Profiles Argument](./entity-player#player-profiles-argument) | +| `resource(RegistryKey)` | (Depends on RegistryKey) | [Resource Argument](./registry#resource-argument) | +| `resourceKey(RegistryKey)` | (Depends on RegistryKey) | [Resource Key Argument](./registry#resource-key-argument) | +| `style()` | [Style (Kyori)](https://javadoc.io/doc/net.kyori/adventure-api/latest/net/kyori/adventure/text/format/Style.html) | [Style Argument](./adventure#adventure-style-argument) | +| `signedMessage()` | SignedMessageResolver | [Signed Message Argument](./adventure#signed-message-argument) | +| `scoreboardDisplaySlot()` | DisplaySlot | [Scoreboard Display Slot Argument](./enums#scoreboard-display-slot-argument) | +| `time(int mintime)` | Integer | [Time Argument](./paper#time-argument) | +| `templateMirror()` | Mirror | [Template Mirror Argument](./enums#template-mirror-argument) | +| `templateRotation()` | StructureRotation | [Template Rotation Argument](./enums#template-rotation-argument) | +| `uuid()` | UUID | [UUID Argument](./paper#uuid-argument) | +| `world()` | World | [World Argument](./location#world-argument) | \ No newline at end of file diff --git a/docs/paper/dev/api/command-api/arguments/paper.mdx b/docs/paper/dev/api/command-api/arguments/paper.mdx new file mode 100755 index 000000000..c5a80500b --- /dev/null +++ b/docs/paper/dev/api/command-api/arguments/paper.mdx @@ -0,0 +1,184 @@ +--- +slug: /dev/command-api/arguments/paper +description: Documentation for arguments handling miscellaneous Paper API values. +--- + +import BlockStateMp4 from "./assets/vanilla-arguments/blockstate.mp4"; +import ItemStackMp4 from "./assets/vanilla-arguments/itemstack.mp4"; +import NamespacedKeyMp4 from "./assets/vanilla-arguments/namespacedkey.mp4"; +import TimeMp4 from "./assets/vanilla-arguments/time.mp4"; +import UuidMp4 from "./assets/vanilla-arguments/uuid.mp4"; +import ObjectiveCriteriaMp4 from "./assets/vanilla-arguments/objectivecriteria.mp4"; + +# Paper Arguments +The arguments in this section return objects frequently used in Paper API. + +## Block state argument +The block state argument can be used for getting a block type and explicit, associated data. + +### Example usage +```java +public static LiteralCommandNode blockStateArgument() { + return Commands.literal("blockstateargument") + .then(Commands.argument("arg", ArgumentTypes.blockState()) + .executes(ctx -> { + final BlockState blockState = ctx.getArgument("arg", BlockState.class); + + ctx.getSource().getSender().sendPlainMessage("You specified a " + blockState.getType() + "!"); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## ItemStack argument +The item stack argument is the way to retrieve an `ItemStack` following the same argument format as the Vanilla `/give []` +command as its second argument. The user may also define components to further customize the `ItemStack`. If you only require a `Material`, you should instead +check out the [registry arguments](./registry.mdx). + +### Example usage +```java +public static LiteralCommandNode itemStackArgument() { + return Commands.literal("itemstack") + .then(Commands.argument("stack", ArgumentTypes.itemStack()) + .executes(ctx -> { + final ItemStack itemStack = ctx.getArgument("stack", ItemStack.class); + + if (ctx.getSource().getExecutor() instanceof Player player) { + player.getInventory().addItem(itemStack); + ctx.getSource().getSender().sendRichMessage("Successfully gave a ", + Placeholder.component("player", player.name()), + Placeholder.component("item", Component.translatable(itemStack)) + ); + return Command.SINGLE_SUCCESS; + } + + ctx.getSource().getSender().sendRichMessage("This argument requires a player!"); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## NamespacedKey argument +This argument allows the user to provide any artificial (namespaced) key. The return value of this argument is a +`NamespacedKey`, which makes it useful when dealing with Bukkit API. + +### Example usage +```java +public static LiteralCommandNode namespacedKeyArgument() { + return Commands.literal("namespacedkey") + .then(Commands.argument("key", ArgumentTypes.namespacedKey()) + .executes(ctx -> { + final NamespacedKey key = ctx.getArgument("key", NamespacedKey.class); + + ctx.getSource().getSender().sendRichMessage("You put in !", + Placeholder.unparsed("key", key.toString()) + ); + return Command.SINGLE_SUCCESS; + })) + .build(); +} +``` + +### In-game preview + + + +## Time argument +The time argument allows the user to define a time frame, similar to the Vanilla `/time