Suggerimenti dei Comandi 1.21.8

Impara come suggerire i valori per gli argomenti dei comandi agli utenti.

WARNING

Questa pagina si applica alla versione 1.21.8. La documentazione delle versioni meno recenti potrebbe essere incompleta.

Minecraft ha un potente sistema di suggerimento comandi che viene usato in molti posti, come nel comando /give. Questo sistema ti permette di suggerire valori per argomenti dei comandi all'utente, da cui possono poi selezionare - è un ottimo modo per rendere i tuoi comandi più user-friendly ed ergonomici.

Provider di Suggerimenti

Un SuggestionProvider viene usato per creare una lista di suggerimenti che verrà mandata al client. Un provider di suggerimenti è un'interfaccia funzionale che accetta un CommandContext e un SuggestionBuilder e restituisce alcune Suggestions. Il SuggestionProvider restituisce un CompletableFuture siccome i suggerimenti potrebbero non essere disponibili immediatamente.

Usare i Provider di Suggerimenti

Per usare un provider di suggerimenti, devi chiamare il metodo suggests nel costruttore di argomenti. Questo metodo accetta un SuggestionProvider e restituisce il costruttore di argomenti modificato con l'aggiunta del suggestion provider.

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(FabricDocsReferenceCommands::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;
}

Provider di Suggerimenti Predefiniti

Ci sono alcuni provider di suggerimenti predefiniti che puoi usare:

Provider di Suggerimenti	Descrizione
SuggestionProviders.SUMMONABLE_ENTITIES	Suggerisce tutte le entità che possono essere evocate.
SuggestionProviders.AVAILABLE_SOUNDS	Suggerisce tutti i suoni che possono essere riprodotti.
LootCommand.SUGGESTION_PROVIDER	Suggerisce tutte le loot table disponibili.
SuggestionProviders.ALL_BIOMES	Suggerisce tutti i biomi disponibili.

Creare un Provider di Suggerimenti Personalizzato

Se un provider predefinito non soddisfa i tuoi requisiti, puoi creare il tuo provider di suggerimenti personalizzato. Per fare questo, devi creare una classe che implementa l'interfaccia SuggestionProvider e fare override del metodo getSuggestions.

Per questo esempio, creeremo un provider di suggerimenti che suggerisce tutti i nomi utente dei giocatori sul server.

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();
	}
}

Per usare questo provider di suggerimenti, passeresti semplicemente una sua istanza al metodo .suggests nel costruttore di comandi.

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(FabricDocsReferenceCommands::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;
}

Ovviamente, i provider di suggerimenti possono essere più complessi, siccome possono anche leggere il contesto dei comandi per fornire suggerimenti basati sullo stato del comando - per esempio quali argomenti sono già stati forniti.

Ciò potrebbe essere ad esempio leggere l'inventario del giocatore e suggerire oggetti, o entità che sono vicine al giocatore.