Suggestions API v1.0.5

This library integrates into Minecraft's source code and handles the logic of chat suggestions, providing convenient tools for adding and modifying them. Currently, the library includes the following capabilities:

Core Features

• Adding synchronous and asynchronous suggestions based on user input
• Modifying the appearance of displayed suggestions
• Processing suggestion-related events:
  • Session initialization
  • Suggestion selection
• Replacing suggestions created without using Suggestions API

Ready-made Implementations

The library offers pre-built suggestion types:

• Always shown suggestions (with condition to always display)
• Simple text suggestions (with default or custom display condition)
• Icon suggestions (text with image on left or right)
• Synchronous and asynchronous injectors (dynamic suggestion addition when typing text using regular expressions)

Mods Using Suggestions API

Among projects utilizing this library:

• emogg
• JIME

Getting Started

To connect the library, add the following settings depending on your platform.

For Fabric or Quilt

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

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

For Forge or Neoforge

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

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

Quick Documentation

Built-in Suggestion Types

The Suggestion interface is located in package io.github.aratakileo.suggestionsapi.suggestion.

The library supports two main suggestion types:

• Suggestion.simple(...) - simple text
• Suggestion.withIcon(...) - with icon (displayed on left)

Example of creating a simple suggestion:

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

For icon suggestions, specify text and image resource (call after loading game textures):

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

By default, suggestions appear when starting to type their text. You can set custom display conditions:

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

For always displayed suggestions, use condition (suggestionText, currentExpression) -> true or special functions:

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

Adding New Suggestions

To add suggestions, use the Injector interface from package io.github.aratakileo.suggestionsapi.injector.

Example of a simple injector with two suggestions:

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

To exclude display in commands:

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

Example with numbers:

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

Asynchronous Injectors

For asynchronous processing, use Injector.async(...):

SuggestionsAPI.registerInjector(Injector.async(
        / your pattern here /,
        (stringContainer, startOffset) -> {
            / your async code here /

            return / list of suggestions here /;
        }
));

Replacing Existing Suggestions

The library allows replacing suggestions created without its use:

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