Suggestions API v1.0.5

Эта библиотека интегрируется в исходный код Minecraft и отвечает за логику работы подсказок в чате, предоставляя удобные инструменты для их добавления и модификации. На данный момент библиотека включает следующие возможности:

Основные функции

• Добавление синхронных и асинхронных подсказок на основе вводимого пользователем текста
• Изменение внешнего вида отображаемых подсказок
• Обработка событий, связанных с подсказками:
  • Инициализация сессии
  • Выбор подсказки
• Замена подсказок, созданных без использования Suggestions API

Готовые реализации

Библиотека предлагает готовые типы подсказок:

• Постоянно отображаемые подсказки (с условием всегда показывать)
• Простые текстовые подсказки (с стандартным или пользовательским условием отображения)
• Подсказки с иконками (текст с изображением слева или справа)
• Синхронные и асинхронные инжекторы (динамическое добавление подсказок при вводе текста по регулярным выражениям)

Моды, использующие Suggestions API

Среди проектов, применяющих эту библиотеку:

• emogg
• JIME

Начало работы

Для подключения библиотеки добавьте следующие настройки в зависимости от используемой платформы.

Для Fabric или Quilt

repositories {
    maven {
        url = "https://api.modrinth.com/maven"
    }
}

dependencies {
    modImplementation "maven.modrinth:suggestions-api:1.0.6+fabric"
}

Для Forge или Neoforge

repositories {
    maven("https://api.modrinth.com/maven")
}

dependencies {
    modImplementation("maven.modrinth", "suggestions-api", "1.0.6+forge")
}

Краткая документация

Типы встроенных подсказок

Интерфейс Suggestion находится в пакете io.github.aratakileo.suggestionsapi.suggestion.

Библиотека поддерживает два основных типа подсказок:

• Suggestion.simple(...) - простые текстовые
• Suggestion.withIcon(...) - с иконкой (отображается слева)

Пример создания простой подсказки:

final var simpleSuggestion = Suggestion.simple("bonjour!");

Для подсказки с иконкой нужно указать текст и ресурс изображения (вызывать после загрузки текстур игры):

final var suggestionWithIcon = Suggestion.withIcon("barrier", new ResourceLocation("minecraft", "textures/item/barrier.png"));

По умолчанию подсказки появляются при начале ввода их текста. Можно задать собственное условие отображения:

final var anotherSimpleSuggetion = Suggestion.simple(
        "bonjour!",
        (suggestionText, currentExpression) -> suggestionText.toLowerCase().equals(currentExpression.toLowerCase())
);

Для постоянного отображения используйте условие (suggestionText, currentExpression) -> true или специальные функции:

final var alwaysShownSuggestion = Suggestion.alwaysShown("bonjour!");

Добавление новых подсказок

Для добавления подсказок используйте интерфейс Injector из пакета io.github.aratakileo.suggestionsapi.injector.

Пример простого инжектора с двумя подсказками:

SuggestionsAPI.registerInjector(Injector.simple(
        Injector.ANYTHING_WITHOUT_SPACES_PATTERN,
        (stringContainer, startOffset) -> List.of(
                Suggestion.alwaysShownWithIcon("barrier", new ResourceLocation("minecraft", "textures/item/barrier.png")),
                alwaysShownSuggestion
        )
));

Для исключения отображения в командах:

SuggestionsAPI.registerInjector(Injector.simple(
        Injector.ANYTHING_WITHOUT_SPACES_PATTERN,
        (stringContainer, startOffset) -> stringContainer.getContext().isNotCommand() ? List.of(
                Suggestion.alwaysShownWithIcon("barrier", new ResourceLocation("minecraft", "textures/item/barrier.png")),
                alwaysShownSuggestion
        ) : null
));

Пример с числами:

SuggestionsAPI.registerInjector(Injector.simple(
        Pattern.compile(":[A-Za-z0-9](:)?$"),
        (stringContainer, startOffset) -> Stream.of(
            "67487",
            "nothing",
            "bedrock",
            "bedrock_2"
        ).map(value -> Suggestion.simple(':' + value + ':')).toList()
));

SuggestionsAPI.registerInjector(Injector.simple(
        Pattern.compile(":[0-9](:)?$"),
        (stringContainer, startOffset) -> IntStream.rangeClosed(1000, 1010)
            .boxed()
            .map(Objects::toString)
            .map(Suggestion::alwaysShown)
            .toList(),
        InputRelatedInjector.NestingStatus.ALL_NESTABLE
));

Асинхронные инжекторы

Для асинхронной обработки используйте Injector.async(...):

SuggestionsAPI.registerInjector(Injector.async(
        / ваш шаблон здесь /,
        (stringContainer, startOffset) -> {
            / ваш асинхронный код здесь /

            return / список подсказок здесь /;
        }
));

Замена существующих подсказок

Библиотека позволяет заменять подсказки, созданные без её использования:

SuggestionsAPI.registerInjector(Injector.replacement(
        nonApiSuggestion -> nonApiSuggestion.equals("minecraft:barrier") ? Suggestion.withIcon(
                nonApiSuggestion,
                new ResourceLocation("minecraft", "textures/item/barrier.png")
        ) : null
));