Пропозиції команд 1.21.8

Дізнайтеся як пропонувати користувачам можливі значення аргументу команди.

WARNING

Ця сторінка написана для версії 1.21.8. Документація для старіших версій може бути неповною.

Minecraft має потужну систему пропозицій команд, що використовується у багатьох місцях, таких як команда /give. Ця система дозволяє пропонувати гравцю значення аргументу, які вони можуть вибрати, що є гарним засобом створення більш зручних та ергономічних команд.

Постачальники пропозицій

Клас SuggestionProvider використовується для створення списку пропозицій, які будуть надіслані гравцю. Постачальник пропозицій - це функція, що приймає об'єкти CommandContext та SuggestionBuilder, та повертає об'єкт Suggestions. SuggestionProvider повертає об'єкт CompletableFuture тому, що пропозиції можуть бути не доступні відразу.

Використання постачальників пропозицій

Для використання постачальника пропозицій треба викликати метод suggests в об'єкта ArgumentBuilder. Цей метод приймає об'єкт SuggestionProvider та повертає свій ArgumentBuilder з доданим постачальником пропозицій.

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

Вбудовані постачальники пропозицій

Minecraft надає декілька вбудованих постачальників пропозицій:

Постачальник	Опис
SuggestionProviders.SUMMONABLE_ENTITIES	Пропонує всі істоти, що можуть бути викликані.
SuggestionProviders.AVAILABLE_SOUNDS	Пропонує всі звуки, що можуть бути зіграні.
LootCommand.SUGGESTION_PROVIDER	Пропонує всі доступні таблиці здобичі.
SuggestionProviders.ALL_BIOMES	Пропонує всі доступні біоми.

Створити власний постачальник пропозицій

Якщо вбудовані постачальники пропозицій не підходять, ви можете створити свій постачальник. Для цього треба створити клас, який реалізує інтерфейс SuggestionProvider і перевизначає метод getSuggestions.

Для цього прикладу ми зробимо постачальник, який пропонує імена гравців на сервері.

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

Щоб скористатися цим постачальником, треба просто передати його об'єкт у метод .suggests у ArgumentBuilder.

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

Звісно, що постачальники пропозицій можуть бути складнішими, оскільки вони також можуть зчитувати контекст команди та надавати пропозиції на основі її стану - наприклад, аргументи, що вже були надані.

Це може також зчитувати інвентар гравця та пропонувати предмети, або сутностей, які неподалік від гравця.