diff --git a/_redirects b/_redirects index 1f18face..9c12be44 100644 --- a/_redirects +++ b/_redirects @@ -7,3 +7,4 @@ /paper/per-world-configuration /paper/configuration /paper/configuration /paper/reference/configuration /paper/reference/vanilla-command-permissions /paper/reference/permissions +/paper/dev/commands /paper/dev/commands-api/commands diff --git a/config/sidebar.paper.ts b/config/sidebar.paper.ts index 8a4dff63..756be038 100644 --- a/config/sidebar.paper.ts +++ b/config/sidebar.paper.ts @@ -127,6 +127,12 @@ const paper: SidebarsConfig = { "dev/api/event-api/chat-event", ], }, + { + type: "category", + label: "Brigadier Command API", + collapsed: true, + items: ["dev/api/command-api/commands", "dev/api/command-api/arguments"], + }, { type: "category", label: "Entity API", @@ -145,7 +151,6 @@ const paper: SidebarsConfig = { }, "dev/api/pdc", "dev/api/custom-inventory-holder", - "dev/api/commands", "dev/api/scheduler", "dev/api/plugin-messaging", "dev/api/plugin-configs", diff --git a/docs/paper/dev/api/command-api/arguments.mdx b/docs/paper/dev/api/command-api/arguments.mdx new file mode 100644 index 00000000..15860c2c --- /dev/null +++ b/docs/paper/dev/api/command-api/arguments.mdx @@ -0,0 +1,179 @@ +--- +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() { + 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().asString() + ); + 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 + +## Enchantment 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 | Events in the game (eating, flying with an elytra etc.) | +| STRUCTURE_TYPE | StructureType | [Structures](https://minecraft.wiki/w/Structure#Overworld) +| INSTRUMENT | CraftMusicInstrument | [Note block instrument](https://minecraft.wiki/w/Note_Block) | +| ENCHANTMENT | Enchantment | [Enchantment type](https://minecraft.wiki/w/Enchanting#Summary_of_enchantments) | +| MOB_EFFECT | PotionEffectType | [Potion effect](https://minecraft.wiki/w/Effect#List) | +| BLOCK | BlockType | [Block type - not modifiable](https://minecraft.wiki/w/Block#List_of_blocks) | +| ITEM | ItemType | [Item type - not modifiable](https://minecraft.wiki/w/Item#List_of_items) | +| BIOME | Biome | [Biome type](https://minecraft.wiki/w/Biome#Biome_types) | +| 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 since 1.20.5](https://minecraft.wiki/w/Wolf#Variants) | +| PAINTING_VARIANT | Art | [All paintings](https://minecraft.wiki/w/Painting#Canvases) | +| ATTRIBUTE | Attribute | [Entity attribute](https://minecraft.wiki/w/Attribute) | +| BANNER_PATTERN | PatternType | [Armor Pattern type](https://minecraft.wiki/w/Banner_Pattern#Variants) | +| CAT_VARIANT | Cat.Type | [Cat variants](https://minecraft.wiki/w/Cat#Appearance) | +| 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) | +| SOUND_EVENT | Sound | [Events that trigger sound effects](https://minecraft.wiki/w/Sounds.json#Sound_events) | +| 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) | +| MEMORY_MODULE_TYPE | MemoryKey | Keys for saving per-entity data | +| FROG_VARIANT | Frog.Variant | [Frog variants](https://minecraft.wiki/w/Frog) | +| MAP_DECORATION_TYPE | MapCursor.Type | [Types of sprites displayed on a map](https://minecraft.wiki/w/Map#Map_icons) | +| FLUID | Fluid | [Fluid types](https://minecraft.wiki/w/Fluid) + +Minecraft itself also specifies many 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 +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 +public class IceCreamTypeArgument implements CustomArgumentType.Converted { + + @Override + public @NotNull IceCreamType convert(String nativeType) throws CommandSyntaxException { + try { + return IceCreamType.valueOf(nativeType.toUpperCase()); + } catch (Exception e) { + Message message = MessageComponentSerializer.message().serialize(Component.text("Invalid flavor %s!".formatted(nativeType), NamedTextColor.RED)); + + throw new CommandSyntaxException(new SimpleCommandExceptionType(message), message); + } + } + + @Override + public @NotNull 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 CompletableFuture.completedFuture( + builder.build() + ); + } +} +``` + +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 +public void onEnable() { + 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((commandContext -> { + IceCreamType argumentResponse = commandContext.getArgument("flavor", IceCreamType.class); + commandContext.getSource().getSender().sendMessage(Component.text("You ordered: " + argumentResponse)); + return 1; + })) + ).build() + ); + }); +} +``` + +Now that we have registered the command, we can execute it ingame: + +![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/assets/command-executed.gif b/docs/paper/dev/api/command-api/assets/command-executed.gif new file mode 100644 index 00000000..bddfd95d Binary files /dev/null and b/docs/paper/dev/api/command-api/assets/command-executed.gif differ diff --git a/docs/paper/dev/api/command-api/assets/icecreamargument.gif b/docs/paper/dev/api/command-api/assets/icecreamargument.gif new file mode 100644 index 00000000..533e6bee Binary files /dev/null and b/docs/paper/dev/api/command-api/assets/icecreamargument.gif differ diff --git a/docs/paper/dev/api/commands.mdx b/docs/paper/dev/api/command-api/commands.mdx similarity index 64% rename from docs/paper/dev/api/commands.mdx rename to docs/paper/dev/api/command-api/commands.mdx index 85f784ba..6a21b2b6 100644 --- a/docs/paper/dev/api/commands.mdx +++ b/docs/paper/dev/api/command-api/commands.mdx @@ -1,9 +1,9 @@ --- -slug: /dev/commands +slug: /dev/command-api/commands description: A guide to Paper's Brigadier command API. --- -# Command API +# Commands Paper's command system is built on top of Minecraft's Brigadier command system. This system is a powerful and flexible way to define commands and arguments. @@ -19,7 +19,7 @@ Paper's command system is still experimental and may change in the future. :::note This uses the LifecycleEventManager -to register the command. See the [Lifecycle Events](./lifecycle.mdx) page for more information. +to register the command. See the [Lifecycle Events](../lifecycle.mdx) page for more information. ::: @@ -109,57 +109,6 @@ class FunCommand implements BasicCommand { } ``` -## Arguments - -### Built-in arguments - -Vanilla has lots of built-in arguments that the client also supports. These can provide better -syntax and error-checking before even executing the commands. ArgumentTypes -has all the argument types available to the API. - -For now, you can find specific examples of arguments, among other things, on the [Fabric Wiki](https://fabricmc.net/wiki/tutorial:commands). - -### Custom arguments - -Custom arguments can be created by implementing the CustomArgumentType -interface. See the Javadocs for more information on how they work. - -### Command suggestions - -Custom command suggestions can be supplied by either overriding the -listSuggestions -method in `CustomArgumentType`, or using the `suggests(SuggestionProvider)` method to define a `SuggestionProvider` for the argument. - -An example suggestion provider might look like this: -```java -Commands.argument("count", IntegerArgumentType.integer()) - .suggests((ctx, builder) -> { - builder.suggest(1); - builder.suggest(10); - return builder.buildFuture(); - }) -``` - -Suggestions can also be contextual since they have access to the `CommandContext`. - -:::note - -To access other arguments when building suggestions, make sure the correct `CommandContext` -is obtained with `CommandContext.getLastChild()`. - -::: - -An example contextual suggestion provider: -```java -Commands.argument("min", IntegerArgumentType.integer()) - .then(Commands.argument("max", IntegerArgumentType.integer()) - .suggests((ctx, builder) -> { - int min = ctx.getLastChild().getArgument("min", Integer.class); - builder.suggest(min + 1); - return builder.buildFuture(); - })) -``` - ## Lifecycle Commands are not just registered once at the start, but anytime a reload happens. This can be diff --git a/docs/paper/dev/getting-started/paper-plugins.mdx b/docs/paper/dev/getting-started/paper-plugins.mdx index 08a561b6..88623672 100644 --- a/docs/paper/dev/getting-started/paper-plugins.mdx +++ b/docs/paper/dev/getting-started/paper-plugins.mdx @@ -187,7 +187,7 @@ See [declaring dependencies](#dependency-declaration) for more information on ho ### Commands Paper plugins do not use the `commands` field to register commands. This means that you do not need to include all of your commands in the `paper-plugin.yml` file. Instead, you can register commands using the -[Brigadier Command API](../api/commands.mdx). +[Brigadier Command API](../api/command-api/commands.mdx). ### Cyclic plugin loading