OlaChat

Developer API

OlaChat was built to be the foundational backbone for your proxy network's chat and moderation systems. We expose a massive suite of Async events, custom MiniMessage tag injectors, and even cross-server Redis networking wrappers.

Installation

To depend on the OlaChat API, add the following to your project's build configuration. Since OlaChat is published to Maven Central, you won't need to add any custom repositories other than mavenCentral().

Gradle (Kotlin DSL)

repositories {
    mavenCentral()
}

dependencies {
    compileOnly("com.olaneria.repo:olachat-api:1.0.0")
}

Gradle (Groovy DSL)

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.olaneria.repo:olachat-api:1.0.0'
}

Maven (pom.xml)

<dependencies>
    <dependency>
        <groupId>com.olaneria.repo</groupId>
        <artifactId>olachat-api</artifactId>
        <version>1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Getting the API

To access the core managers, channels, and methods, use the singleton:

OlaChatAPI api = OlaChatAPI.get();

1. Custom Chat Filters

You can register custom chat filters to intercept, modify, or block chat messages before they are sent to the dynamic channel systems.

api.registerFilter(new ChatFilter() {
    @Override
    public FilterResult process(Player sender, String message) {
        if (message.contains("lag")) {
            return FilterResult.cancelled("<red>Please do not complain about lag.</red>");
        }
        return FilterResult.allowed(message.replace("fuck", "****"));
    }
}, FilterPriority.NORMAL);

2. Dynamic MiniMessage Tags

Want to let players type <item> to show off their sword in chat? Register a DynamicTagProvider! These are injected into the MiniMessage parser dynamically for the specific sender.

api.registerDynamicTagProvider(player -> {
    return TagResolver.resolver("item", (argumentQueue, context) -> {
        String itemName = player.getInventory().getItemInMainHand().getType().name();
        return net.kyori.adventure.text.minimessage.tag.Tag.inserting(
            Component.text("[" + itemName + "]").color(NamedTextColor.AQUA)
        );
    });
});

3. Cross-Server Redis Hooks

Don't want to setup your own Redis instances for your custom proxy plugins? Use OlaChat's!

Publish a payload globally:

OlaChatAPI.get().publishRedisMessage("my_custom_channel", "Hello Network!");

Listen to payloads globally:

OlaChatAPI.get().registerRedisListener("my_custom_channel", payload -> {
    System.out.println("Received: " + payload);
});

Send a Cross-Server RPC Request & Await Response: Need to get data from a specific server? Send an RPC request!

JsonObject request = new JsonObject();
request.addProperty("action", "GET_ECO_BALANCE");
request.addProperty("uuid", player.getUniqueId().toString());

OlaChatAPI.get().sendRedisRequest("my_economy", request, response -> {
    double balance = response.get("balance").getAsDouble();
    player.sendMessage("Your global balance is: " + balance);
});

(Make sure another plugin on the target server is listening to AsyncOlaRedisRpcRequestEvent to reply using sendRedisResponse()!)

4. Listening to Events

OlaChat provides 25 custom events covering everything from chat pipelines to Redis networking. Because OlaChat runs on Paper, you listen to these events exactly like standard Bukkit/Paper events using @EventHandler.

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import com.olaneria.olachat.paper.api.events.AsyncOlaChatEvent;

public class MyChatListener implements Listener {
    
    @EventHandler
    public void onOlaChat(AsyncOlaChatEvent event) {
        // Example: Modify the recipients list
        event.getRecipients().removeIf(player -> !player.isOp());
    }
}

Complete Event List

Chat Pipeline Events (Async)

• AsyncOlaChatPreFilterEvent: Fired before any chat filters are applied.
• AsyncOlaChatEvent: Fired after channels, formats, and placeholders are applied, but before viewer-specific hover/click text is injected. Modify the getRecipients() list here.
• AsyncOlaChatViewerEvent: Allows you to dynamically change the hover-text, click-command, and ping-sound for each individual viewer receiving the message.
• AsyncOlaChatFormatEvent: The absolute final event containing the compiled Adventure Component right before it is dispatched to the viewer.
• AsyncOlaChatLogEvent: Fired when a chat message is logged to the console/file.
• AsyncOlaFilterTriggerEvent: Fired when a message triggers a registered ChatFilter.

Messaging & Network Events (Async)

• AsyncOlaChannelChatEvent: Fired when a message is sent specifically into a channel.
• AsyncOlaPrivateMessageEvent: Fired when a cross-server private message is sent.
• AsyncOlaReplyEvent: Fired when a player replies to a previous private message.
• AsyncOlaMentionEvent: Fired when a player is mentioned in chat.
• AsyncOlaBroadcastEvent: Fired when a network-wide broadcast is dispatched.
• AsyncOlaNetworkPresenceEvent: Fired when a player joins or quits the proxy network (Redis presence).

Spy & Moderation Events (Async)

• AsyncOlaSpyEvent: Fired when a private message or similar is sent to a player with Social Spy enabled.
• AsyncOlaCommandSpyEvent: Intercept and monitor player commands before they are broadcasted to the Redis command spy network.
• AsyncOlaIgnoreCheckEvent: Check if a viewer is currently ignoring a sender.

Redis Networking Events (Async)

• AsyncOlaRedisMessageEvent: Fired when a raw payload is received on a subscribed OlaChat Redis channel.
• AsyncOlaRedisRpcRequestEvent: Fired when a cross-server RPC request is received.
• AsyncOlaRedisRpcResponseEvent: Fired when a response to a previously sent RPC request arrives.

Player & Data Events (Sync)

• OlaPlayerDataLoadEvent: Fired when a joining player's database cache is successfully loaded.
• OlaPlayerDataUnloadEvent: Fired when a player quits and their data cache is unloaded.
• OlaSettingsUpdateEvent: Fired when a player updates personal settings (e.g., receive PMs, sounds, social spy).
• OlaIgnoreUpdateEvent: Fired when a player ignores or unignores another player.

Channel Lifecycle Events (Sync)

• OlaChannelRegisterEvent: Fired when a new dynamic ChatChannel is registered to the server.
• OlaChannelUnregisterEvent: Fired when a ChatChannel is unregistered.
• OlaChannelToggleEvent: Fired when a player toggles their active focus into or out of a channel.