Writing an addon

An addon is a separate plugin on the same proxy that builds on Identica, such as a plugin that blocks chat or commands until a player has logged in. This page covers what such an addon usually needs. Set up the dependency first, as described in Getting started.

The repository's examples/addon is a complete Velocity addon built this way: it holds back chat and commands until a player has authenticated, reads the allowed commands again after a reload, and holds players who join through a hold. or ask. hostname at checkpoints, which the same jar also registers on BungeeCord. Its live tests run it on a real proxy, so it follows the current API.

Start once Identica is runningCopy Anchor Link

Get the IdenticaAPI through IdenticaAPI.whenReady(...) and pass it to your addon's classes. The examples below assume it is called identica.

IdenticaAPI.whenReady(identica -> new ChatBlocker(identica).enable());

Tell whether a player still has to authenticateCopy Anchor Link

While a player has not yet logged in, registered or finished a migration, a scenario is pending for their connection. Ask PendingScenarioService instead of following the scenario events yourself:

PendingScenarioService pending = identica.getPendingScenarioService();

if (pending.isPending(player.getUniqueId())) {
    // hold back chat or commands
}

pending.find(player.getUniqueId()); // Optional<PipelineType>: AUTHENTICATION, REGISTRATION or MIGRATION

The connection's unique id is the player's unique id on the proxy. A scenario is pending from its ScenarioRequiredEvent until its ScenarioResolvedEvent, or until the player leaves. Listeners of those events already see the new state, so an addon that reacts to the events can ask the service from inside its listener.

To react to the moment a scenario starts or ends, listen to ScenarioRequiredEvent and ScenarioResolvedEvent. A listener of these interfaces receives authentication, registration and migration alike.

Allow the commands a player needs to log inCopy Anchor Link

Commands such as /login, /pass, /identica enroll or /2fa confirm are marked as available while a scenario is pending. Their names are aliases an administrator can change, so read them from Identica instead of listing them yourself:

Set<String> allowed = identica.getCommandService().getCommandsAvailableWhilePending();

The set holds each command as a player types it, without the slash and in lower case, with subcommands under every alias of Identica's root command: login, l, identica enroll, id enroll, 2fa confirm. A typed command is allowed when it is one of them or starts with one of them followed by a space. A provider or feature that adds its own login command marks its method with @AvailableWhilePending next to @Definition, and the command appears here once registered.

Read Identica's messagesCopy Anchor Link

Core, every feature and every loaded provider keep their own messages document. Each one implements MessageDocument, so the catalog returns all of them, including those of providers loaded later:

Collection<MessageDocument> messages = identica.getConfigCatalog().documents(MessageDocument.class);

documents() without a type returns every loaded document. The models are the current ones; read them again after a reload instead of keeping them.

To show a message to players another way, such as a dialog instead of chat or an action bar next to it, present it by its ID through MessageService. See Messages to players.

Follow reloadsCopy Anchor Link

/identica admin reload replaces the configuration documents. Rebuild what you derived from them in one of two ways:

• listen to IdenticaReloadedEvent, which is called after everything has reloaded
• or register a Reloadable with identica.getReloadables().register(...); it is reloaded after every configuration document, and you unregister it when your addon is disabled

public final class MessageIndex implements EventListener {
    @IdenticEvent
    public void onReloaded(IdenticaReloadedEvent event) {
        rebuild();
    }
}

identica.getEventManager().register(new MessageIndex());

Keep your own settings in Identica's formatCopy Anchor Link

identica.getConfigura() returns the Configura instance Identica uses. Derive your addon's configuration from it, and your settings file uses the same format as Identica's without bundling a library of your own.