Tworzenie Placeholderów

Ostrzeżenie

Ta dokumentacja została napisana dla SpongeAPI 7 i możliwe, że jest już przestarzała. Jeśli masz ochotę wspomóc w jej aktualizacji, prosimy, utwórz PR!

Główną umiejętnością Placeholder API Sponge-a jest tworzenie własnych tokenów i udostępnianie ich innym pluginom. Aby stworzyć swój własnych placeholder, musisz utworzyć obiekt, który implementuje PlaceholderParser oraz zarejestrować go w odpowiednim rejestrze.

Tworzenie PlaceholderParserów

Istnieją dwa sposoby na utworzenie PlaceholderParser'a:

• Używając PlaceholderParser#builder(), dostarczając swój PluginContainer, ID bez namespace i funkcję, która przyjmuje PlaceholderContext i zwraca Component.

• Bezpośrednio zaimplementuj interfejs.

Obiekty PlaceholderParser przyjmują obiekt PlaceholderContext, który zawiera kontekst żądania oraz zwracają Component bazując na tym kontekście. Informacje jakie PlaceholderContext może zawierać to:

• Powiązany obiekt, taki jak Player

• Argument string, który na zazwyczaj będzie dostarczony przez silnik szablonów.

Jest to minimum określone przez Sponge.

Jeśli Twój placeholder nie potrafi dostarczyć tekstu z powodu niepełnego kontekstu lub braku jakichś argumentów, powinien zwrócić pusty Component i nie rzucać wyjątkiem.

Wskazówka

Jeśli chcesz dodać możliwość przekazywania wielu argumentów do swojego placeholder’a, zastanów się nad dzieleniem argumentu string.

Pamiętaj aby poinformować użytkowników Twojego pluginu jak argument string powinien wyglądać.

Przykład: PlaceholderParser dla nazwy domyślnego świata

Ten PlaceholderParser próbuje uzyskać domyślną nazwę świata, zwracając pusty Component jeśli nie uda mu się jej wydobyć. Używa builder-a, aby utworzyć parser o ID spongedocs:defaultworld, przyjmując, że ID pluginu to spongedocs.

import net.kyori.adventure.text.Component;

PluginContainer thisPlugin = ...;

PlaceholderParser parser = PlaceholderParser.builder()
    .plugin(this.thisPlugin)
    .id("defaultworld")
    .name("Default World Placeholder")
    .parser(placeholderContext -> {
        return Sponge.getServer()
            .getDefaultWorld()
            .map(x -> x.getWorldName())
            .orElse(Component.empty());
    })
    .build();

Example: Player Location PlaceholderParser

Ten PlaceholderParser próbuje wydobyć pozycję gracza na świecie. Jeśli zostanie użyty bez obiektu Player, zwróci pusty Component. To implementuje interfejs PlaceholderParser bezpośrednio.

import net.kyori.adventure.text.TextComponent;

public class PlayerLocationPlaceholder implements PlaceholderParser {

    @Override
    public String getId() {
        return "spongedocs:location"
    }

    @Override
    public String getName() {
        return "Location Placeholder"
    }

    @Override
    public Component parse(PlaceholderContext placeholderContext) {
        placeholderContext.associatedObject()
            .filter(x -> x instanceof Player)
            .map(player -> ((Player) player).getLocation())
            .map(location -> TextComponent.ofChildren(
                Component.text("World: "),
                Component.text(location.getExtent().getName()),
                Component.text(" - "),
                Component.text(location.getPosition())))
            .orElse(Component.empty());
    }
}

Example: Current Time PlaceholderParser

This PlaceholderParser returns the current time in the server’s local timezone. If the string „UTC” is provided as the argument string, it returns the current time in the UTC time zone. This implements the PlaceholderParser interface directly.

public class CurrentTimePlaceholder implements PlaceholderParser {

    @Override
    public String getId() {
        return "spongedocs:currenttime";
    }

    @Override
    public String getName() {
        return "Current Time parser";
    }

    @Override
    public Component parse(PlaceholderContext placeholderContext) {
        if (placeholderContext.argumentString().filter(x -> x.equalsIgnoreCase("UTC")).isPresent()) {
            return Component.text(OffsetDateTime.now(ZoneOffset.UTC).format(FORMATTER));
        }
        return Component.text(OffsetDateTime.now().format(FORMATTER));
    }

}

Registering Your PlaceholderParser

For your parser to be easily accessible to other plugins, it must be registered in the registry. This should be done by listening to the GameRegistryEvent.Register<PlaceholderParser> event and registering your parsers using the register method.

Example: Registering a PlaceholderParser

PlaceholderParser parser = ...;

@Listener
public void registerTokensEvent(GameRegistryEvent.Register<PlaceholderParser> event) {
    event.register(this.parser);
}