Event Bus - Refinery WIKI

RefineryBus (xyz.refineryteam.refinerycore.api.event) is a process-wide, string-keyed publish/subscribe bus for lightweight cross-plugin signaling. Unlike Bukkit events, channels are just strings, so one plugin can publish on a channel and another can subscribe to it without either plugin depending on the other’s classes at compile time.

This is meant for lightweight signaling — notify, refresh, sync. For anything that needs to be cancellable or intercepted mid-flow, use a real Bukkit Event instead.

Publishing

EconomyManager.java

// In an economy plugin, with no dependency on whatever subscribes:
RefineryBus.get().publish("economy:balance-changed", new BalanceChangedPayload(uuid, newBalance));

Delivery is synchronous, on the calling thread, in subscriber priority order (highest first). A throwing subscriber doesn’t prevent others on the same channel from receiving the payload — the exception is logged and swallowed.

Subscribing

EconomyManager.java

// In a cosmetics plugin reacting to balance changes, with no dependency
// on the economy plugin's jar:
RefineryBus.get().subscribe("economy:balance-changed", BalanceChangedPayload.class, payload -> {
    // react to payload.newBalance(), etc.
});

Only payloads assignable to the given type are delivered to that subscriber, so multiple unrelated payload shapes can technically share a channel name (though using separate channel names per payload shape is usually clearer).

RefineryBus.java

public <T> UUID subscribe(String channel, Class<T> type, Consumer<T> handler);
public <T> UUID subscribe(String channel, Class<T> type, Consumer<T> handler, int priority);

subscribe returns a UUID handle you can pass to unsubscribe(channel, id) later. Payloads are plain objects — records work well — shared by convention: both the publisher and subscriber need to agree on the payload’s shape, typically documented per channel name or via a small shared “API” module.

Cleaning up — `BusSubscriptions`

Manually tracking every subscription UUID to unsubscribe them on plugin disable is tedious, so BusSubscriptions groups them for you:

MyPlugin.java

public final class MyPlugin extends JavaPlugin implements RefineryPluginImplementation {
    private final BusSubscriptions bus = new BusSubscriptions();

    @Override
    public void onEnable() {
        bus.on("economy:balance-changed", BalanceChangedPayload.class, payload -> {
            // handle it
        });
    }

    @Override
    public void onDisable() {
        bus.unsubscribeAll();
    }
}

Always call unsubscribeAll() (or manually unsubscribe) in onDisable(). Since RefineryBus is a JVM-wide singleton, stale subscriptions from a disabled or reloaded plugin will otherwise keep firing against a plugin instance that’s no longer active.

Other operations

Method	Description
`hasSubscribers(channel)`	Whether any subscriber is currently registered on a channel
`clearChannel(channel)`	Removes every subscription on a channel, across all plugins. Prefer `unsubscribe`/`BusSubscriptions` in plugin code so you don’t tear down another plugin’s subscriptions — mainly useful for tests or a full reset

​Publishing

​Subscribing

​Cleaning up — BusSubscriptions

​Other operations

Publishing

Subscribing

Cleaning up — `BusSubscriptions`

Other operations