Minecraft has a powerful command suggestion system that's used in many places, such as the /give command. This system allows you to suggest values for command arguments to the user, which they can then select from - it's a great way to make your commands more user-friendly and ergonomic.

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.

Using Suggestion Providers

To use a suggestion provider, you can add the type string at the end of the method when adding a argument. (This will later be converted into a enum)

C#

CommandBuilder commandWithSuggestions = commandHandler.CreateCommand("command_with_suggestions")
        .AddArgument("entity", "string", false, "SUMMONABLE_ENTITIES")
        .Executes(ExecuteCommandWithSuggestions);

await commandHandler.RegisterCommandAsync(commandWithSuggestions);

C++

not yet implemented

C#

private static async Task ExecuteCommandWithSuggestions(CommandContext context)
{
    string entityType = context.Payload["entity"];
    await context.SendFeedback($"Called /command_with_suggestions with entity {entityType}.");
}

C++

not yet implemented

Built-in Suggestion Providers

There are a few built-in suggestion providers that you can use:

Suggestion Provider	Description
SuggestionProviders.SUMMONABLE_ENTITIES	Suggests all entities that can be summoned.
SuggestionProviders.AVAILABLE_SOUNDS	Suggests all sounds that can be played.
LootCommand.SUGGESTION_PROVIDER	Suggests all loot tables that are available.
SuggestionProviders.ALL_BIOMES	Suggests all biomes that are available.

Creating a Custom Suggestion Provider

If a built-in provider doesn't satisfy your needs, you can create your own suggestion provider. To do this, you can register a SuggestionProvider using the RegisterSuggestionProvider() method in the command handler.

C#

commandHandler.RegisterSuggestionProvider("player_names", async (completion, ctx) =>
{
    // completion would be the string that the user has already typed in the chat. (Can be used to filter/sort)
    List<string> playerNames = await ctx.GetPlayerNames();
    
    return playerNames;
});

C++

not yet implemented

To use this suggestion provider, you would simply pass the identifier with the prefix "CUSTOM:" into the registration of an argument.

C#

CommandBuilder commandWithCustomSuggestions = commandHandler.CreateCommand("command_with_custom_suggestions")
        .AddArgument("player_name", "string", false, "CUSTOM:player_names")
        .Executes(ExecuteCommandWithCustomSuggestions);

await commandHandler.RegisterCommandAsync(commandWithCustomSuggestions);

C++

not yet implemented

C#

private static async Task ExecuteCommandWithCustomSuggestions(CommandContext context)
{
    string name = context.Payload["player_name"];
    await context.SendFeedback($"Called /command_with_custom_suggestions with value = {name}.");
}

C++

not yet implemented

Obviously, suggestion providers can be more complex, since they can also read the command context to provide suggestions based on the command's state - such as the arguments that have already been provided.

This could be in the form of reading the player's inventory and suggesting items, or entities that are nearby the player.