User Tools

Site Tools


Sidebar

← Go back to the homepage

Fabric Tutorials

Setup

Basics

These pages are essential must-reads when modding with Fabric, and modding Minecraft in general, if you are new to modding, it is recommended you read the following.

Items

Blocks and Block Entities

Data Generation

World Generation

Commands

These pages will guide you through Mojang's Brigadier library which allows you to create commands with complex arguments and actions.

Events

These pages will guide you through using the many events included in Fabric API, and how to create your own events for you or other mods to use.

Entities

Fluids

Mixins & ASM

These pages will guide you through the usage of SpongePowered's Mixin library, which is a highly complex topic. We recommend you read these pages thoroughly.

Miscellaneous

Yarn

Contribute to Fabric

tutorial:command_suggestions

Licensing: The code in this article is licensed under the “Creative Commons Zero v1.0 Universal” license. The license grants you the rights to use the code examples shown in this article in your own mods.

Command Suggestions

Brigadier allows specification of custom suggestions for arguments. In Minecraft, these suggestions are sent to the client as a user is typing out the command.

Suggestion Providers

A SuggestionProvider is used to make a list of suggestions that will be sent to the client. A suggestion provider is a functional interface that takes a CommandContext and a SuggestionBuilder and returns some Suggestions. The SuggestionProvider returns a CompletableFuture as the suggestions may not be available immediately.

Suggestions can be contextual since a suggestion provider gives you access to the current command context.

An example suggestion provider

For example let's say you want to suggest all attributes an entity could have.

  1. class AttributeSuggestionProvider implements SuggestionProvider<ServerCommandSource> {
  2. @Override
  3. public CompletableFuture<Suggestions> getSuggestions(CommandContext<ServerCommandSource> context, SuggestionsBuilder builder) throws CommandSyntaxException {
  4. Identifier entityTypeId = context.getArgument("type", Identifier.class);
  5. ...

Since we have a command context, we can check the context for the value of any arguments before the argument this suggestion provider targets.

Next is a bunch of boilerplate code

  1. class AttributeSuggestionProvider implements SuggestionProvider<ServerCommandSource> {
  2. @Override
  3. public CompletableFuture<Suggestions> getSuggestions(CommandContext<ServerCommandSource> context, SuggestionsBuilder builder) {
  4. Identifier entityTypeId = context.getArgument("type", Identifier.class);
  5. EntityType<?> entityType = Registries.ENTITY_TYPE.getOrEmpty(entityTypeId).orElse(null);
  6. // For versions before 1.19.3, use ''Registry.ENTITY_TYPE'' instead.
  7.  
  8. if (!DefaultAttributeContainer.hasDefinitionFor(entityType)) {
  9. // TODO: Fail
  10. }
  11.  
  12. DefaultAttributeContainer attributeContainer = DefaultAttributeRegistry.get(entityType);
  13. // You will need mixin to get the 'instances map'. Lets assume we can just access it for the sake of the tutorial
  14. for (EntityAttribute attribute : attributeContainer.instances().keySet()) {
  15. Identifier attributeId = Registries.ATTRIBUTE.getId(attribute);
  16. if (attributeId != null) {
  17. ...

In order to have a suggestion appear on the client, you must add the suggestion to the builder. This can be done through one of the suggest methods. Some of these handle numbers, and a few support showing a tooltip.

  1. for (EntityAttribute attribute : attributeContainer.instances().keySet()) {
  2. Identifier attributeId = Registries.ATTRIBUTE.getId(attribute);
  3. if (attributeId != null) {
  4. builder.suggest(attributeId.toString());
  5. }
  6. }

You can also combine the result of another suggestion builder using the add(SuggestionBuilder) method.

Finally, you need to build the suggestions to be returned. This is done with the buildFuture method.

  1. return builder.buildFuture();

And the final product:

  1. class AttributeSuggestionProvider implements SuggestionProvider<ServerCommandSource> {
  2. @Override
  3. public CompletableFuture<Suggestions> getSuggestions(CommandContext<ServerCommandSource> context, SuggestionsBuilder builder) {
  4. Identifier entityTypeId = context.getArgument("type", Identifier.class);
  5. EntityType<?> entityType = Registries.ENTITY_TYPE.getOrEmpty(entityTypeId).orElse(null);
  6.  
  7. if (!DefaultAttributeContainer.hasDefinitionFor(entityType)) {
  8. // TODO: Fail
  9. }
  10.  
  11. DefaultAttributeContainer attributeContainer = DefaultAttributeRegistry.get(entityType);
  12. // You will need mixin to get the 'instances map'. Lets assume we can just access it for the sake of the tutorial
  13. for (EntityAttribute attribute : attributeContainer.instances().keySet()) {
  14. Identifier attributeId = Registries.ATTRIBUTE.getId(attribute);
  15. if (attributeId != null) {
  16. builder.suggest(attributeId.toString());
  17. }
  18. }
  19.  
  20. return builder.buildFuture();
  21. }
  22. }

Using a suggestion provider

Now that you have a suggestion provider, it is time to use the provider. Do note suggestion providers cannot be applied to literals.

When registering an argument, you can set the suggestion provider using the suggests(SuggestionProvider) method. This is applied to the RequiredArgumentBuilder as shown below:

  1. argument(argumentName, word())
  2. .suggests(CompletionProviders.suggestedStrings())
  3. .then(/*Rest of the command*/));

Builtin suggestion providers

Minecraft includes a few builtin suggestion providers, which includes:

Type Field/Method
Summonable entities SuggestionProviders.SUMMONABLE_ENTITIES
Available sounds SuggestionProviders.AVAILABLE_SOUNDS
Loot Tables LootCommand.SUGGESTION_PROVIDER
Biomes SuggestionProviders.ALL_BIOMES

Utilities in CommandSource

CommandSource contains a few utility methods to help remove boilerplate when making the suggestions. Many of the utility methods involve returning completed suggestions from a Stream or Set of Identifiers, positions or matching strings.

Other command tutorials

Click here to view the other command tutorials.

tutorial/command_suggestions.txt · Last modified: 2023/02/20 05:44 by solidblock