Sugestões de Comando 1.21.11

Aprenda como sugerir valores de argumentos de comando aos usuários.

WARNING

Esta página foi escrita para a versão 1.21.11. A documentação de versões antigas pode estar incompleta.

O Minecraft possui um poderoso sistema de sugestões de comando usado em muitos lugares, como no comando /give. Esse sistema permite que você sugira valores para os argumentos de comando ao usuário, quele pode então selecionar — é uma ótima maneira de tornar seus comandos mais amigáveis e ergonômicos.

Provedores de Sugestões

Um SuggestionProvideré usado para criar uma lista de sugestões que será enviada ao cliente. Um provedor de sugestões é uma interface funcional que recebe um CommandContexte um SuggestionBuilder, e retorna algumas Suggestions. O SuggestionProvider retorna um CompletableFuture já que as sugestões podem não estar disponíveis imediatamente.

Usando Provedores de Sugestões

Para usar um provedor de sugestões, você precisa chamar o método suggestsno builder do argumento. Este método recebe um SuggestionProvider e retorna o builder do argumento modificado com o provedor de sugestões anexado.

CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> {
	dispatcher.register(Commands.literal("command_with_suggestions").then(
			Commands.argument("entity", ResourceArgument.resource(registryAccess, Registries.ENTITY_TYPE))
					.suggests(SuggestionProviders.cast(SuggestionProviders.SUMMONABLE_ENTITIES))
					.executes(ExampleModCommands::executeCommandWithSuggestions)
	));
});

private static int executeCommandWithSuggestions(CommandContext<CommandSourceStack> context) throws CommandSyntaxException {
	var entityType = ResourceArgument.getSummonableEntityType(context, "entity");
	context.getSource().sendSuccess(() -> Component.literal("Called /command_with_suggestions with entity = %s".formatted(entityType.value().toShortString())), false);
	return 1;
}

Provedores de Sugestões Integrados

Existem alguns provedores de sugestões integrados que você pode usar:

Provedor de Sugestão	Descrição
SuggestionProviders.SUMMONABLE_ENTITIES	Sugere todas as entidades que podem ser invocadas.
SuggestionProviders.AVAILABLE_SOUNDS	Sugere todos os sons que podem ser tocados.
LootCommand.SUGGESTION_PROVIDER	Sugere todas as tabelas de itens que estão disponíveis.
SuggestionProviders.ALL_BIOMES	Sugere todos os biomas que estão disponíveis.

Criando um Provedor de Sugestões Personalizado

Se um provedor integrado não atender às suas necessidades, você pode criar seu próprio provedor de sugestões. Para fazer isso, é necessário criar uma classe que implemente a interface SuggestionProvider e sobrescreva o método getSuggestions.

Neste exemplo, criaremos um provedor de sugestões que sugere todos os nomes de usuário dos jogadores no servidor.

public class PlayerSuggestionProvider implements SuggestionProvider<CommandSourceStack> {
	@Override
	public CompletableFuture<Suggestions> getSuggestions(CommandContext<CommandSourceStack> context, SuggestionsBuilder builder) throws CommandSyntaxException {
		CommandSourceStack source = context.getSource();

		// Thankfully, the ServerCommandSource has a method to get a list of player names.
		Collection<String> playerNames = source.getOnlinePlayerNames();

		// Add all player names to the builder.
		for (String playerName : playerNames) {
			builder.suggest(playerName);
		}

		// Lock the suggestions after we've modified them.
		return builder.buildFuture();
	}
}

Para usar esse provedor de sugestões, você simplesmente passaria uma instância dele para o método .suggestsno builder do argumento.

CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> {
	dispatcher.register(Commands.literal("command_with_custom_suggestions").then(
			Commands.argument("player_name", StringArgumentType.string())
					.suggests(new PlayerSuggestionProvider())
					.executes(ExampleModCommands::executeCommandWithCustomSuggestions)
	));
});

private static int executeCommandWithCustomSuggestions(CommandContext<CommandSourceStack> context) {
	String name = StringArgumentType.getString(context, "player_name");
	context.getSource().sendSuccess(() -> Component.literal("Called /command_with_custom_suggestions with value = %s".formatted(name)), false);
	return 1;
}

Obviamente, os provedores de sugestões podem ser mais complexos, pois também podem ler o contexto do comando para fornecer sugestões baseadas no estado do comando — como os argumentos que já foram fornecidos.

Isso poderia acontecer na forma de ler o inventário do jogador e sugerir itens, ou entidades que estão perto desse jogador.