Créer des Tokens de Placeholders

Avertissement

These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

At the heart of the Sponge Placeholder API is the ability to create your own tokens and have them accessible to all plugins. To create your own placeholder, you must create an object that implements PlaceholderParser and then registered in the appropriate registry.

Créer des PlaceholderParsers

Il y a deux façons de créer un PlaceholderParser :

• Using PlaceholderParser#builder(), supplying your PluginContainer, un-namespaced ID and a function that takes a PlaceholderContext and returns a Component.

• Implémenter directement l’interface.

PlaceholderParser objects take a PlaceholderContext object which contains the context of the request and returns a Component based on that context. Information that the PlaceholderContext may contain includes:

• Un objet associé, comme un Player

• Un string d’argument, qui sera généralement fourni par un moteur de template.

C’est le minimum spécifié par Sponge.

If your placeholder is unable to provide text because the context does not provide the context or arguments it requires, the placeholder should return an empty Component and not throw an exception.

Astuce

Si vous souhaitez fournir la possibilité d’ajouter plusieurs arguments à votre placeholder, envisagez de spécifier un moyen de séparer le string d’argument.

N’oubliez pas de dire aux utilisateurs de votre plugin ce à quoi votre string d’argument doit ressembler.

Exemple : PlaceholderParser pour le Nom du Monde par Défaut

This PlaceholderParser attempts to get the default world’s name, returning an empty Component if it cannot be found. It uses the builder to create the parser with ID spongedocs:defaultworld, assuming the plugin has an ID of 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();

Exemple : PlaceholderParser pour la Position du Joueur

This PlaceholderParser attempts to get the player’s location in the world. If used without a Player as the associated object, it returns an empty Component. This implements the PlaceholderParser interface directly.

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

Exemple : PlaceholderParser pour l’Heure Actuelle

Ce PlaceholderParser retourne l’heure actuelle dans le fuseau horaire local du serveur. Si le string « UTC » est fourni comme string d’argument, il retournera l’heure dans le fuseau horaire UTC. Il implémente l’interface PlaceholderParser directement.

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

}

Enregistrer Votre PlaceholderParser

Pour que votre parser soit facilement accessible aux autres plugins, il doit être enregistré dans le registre. Cela doit se faire en écoutant l’événement GameRegistryEvent.Register<PlaceholderParser> et en enregistrant vos parsers avec la méthode register.

Exemple : Enregistrer un PlaceholderParser

PlaceholderParser parser = ...;

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