Plugin Developer Guide

Building a plugin integration?

API Integration Dependency (HBLCore Events)

HBLCore is the official plugin that checks every joining player against hytalebanlist.org and fires an HBLStatusEvent your plugin can hook into. HBLCore does not kick players — your plugin decides what to do with the result.

Check Statuses

Status	Meaning
`CLEAR`	No ban on record. Player is clean.
`BANNED`	Active ban confirmed by hytalebanlist.org.
`LOCAL_BAN`	Ban exists on hytalebanlist.org but is pending review - not yet confirmed.
`WHITELISTED`	Player is whitelisted on hytalebanlist.org.

Quick Start

Register a listener in your plugin

Call HBLCorePlugin.registerStatusListener() in your plugin's setup() method. No event registry, no interfaces to extend beyond the functional interface.

Quick start

import org.hblcore.HBLCorePlugin;
import org.hblcore.event.HBLStatusEvent;
import org.hblcore.event.HBLStatusEvent.PlayerStatus;

public class YourPlugin extends JavaPlugin {

    @Override
    protected void setup() {
        HBLCorePlugin.registerStatusListener(event -> {
            if (event.getStatus() == PlayerStatus.BANNED) {
                // Handle banned player
            }
        });
    }
}

HBLStatusEvent Fields

event.getUsername()   // String        - the joining player's username
event.getUuid()       // String        - the joining player's UUID
event.getStatus()     // PlayerStatus  - CLEAR | BANNED | LOCAL_BAN | WHITELISTED
event.getReason()     // String        - ban reason (null if CLEAR or WHITELISTED)
event.getAppealUrl()  // String        - appeal URL (null if not applicable)
event.getExpiresAt()  // Instant       - ban expiry (null if permanent or not applicable)

Handling All Statuses

HBLCorePlugin.registerStatusListener(event -> {
    switch (event.getStatus()) {

        case BANNED -> {
            String reason   = event.getReason() != null ? event.getReason() : "No reason provided";
            String appeal   = event.getAppealUrl();
            Instant expires = event.getExpiresAt(); // null = permanent

            // Example: kick the player
            event.getPacketHandler().disconnect(
                "You are banned.\nReason: " + reason +
                (appeal != null ? "\nAppeal: " + appeal : "")
            );
        }

        case LOCAL_BAN -> {
            // Ban exists but is pending review - not yet confirmed.
            // You may want to flag or monitor this player without taking action.
            String reason = event.getReason();
        }

        case WHITELISTED -> {
            // Player is explicitly whitelisted on HBL.
            // You may want to clear any local restrictions.
        }

        case CLEAR -> {
            // Player is clean. No action required in most cases.
        }
    }
});

Unregistering a Listener

Store the reference when you register, then unregister it in shutdown():

// Store the reference when you register
private final HBLStatusListener myListener = event -> { ... };

@Override
protected void setup() {
    HBLCorePlugin.registerStatusListener(myListener);
}

@Override
protected void shutdown() {
    HBLCorePlugin.unregisterStatusListener(myListener);
}

Load Order

Listeners can be registered at any time — before or after HBLCore loads. If you want to be safe, declare HBLCore as a dependency in your manifest.json:

manifest.json

{
  "Dependencies": {
    "HBLCore": "*"
  }
}

Notes

-HBLCore does not kick players. It only fires the event. Your plugin decides what to do with the result.
-LOCAL_BAN is a signal, not a confirmed ban. It means the ban is pending review on hytalebanlist.org and has not yet been confirmed. Use it as a trigger to monitor the player without taking immediate action.
-Listeners run asynchronously — the check is performed off the main thread. Avoid blocking operations inside your listener callback.
-Exceptions inside a listener are caught by HBLCore and logged, so a crash in your listener will not affect other listeners or the join flow.

← Back to API Docs