HBLCore - Ban Detection

---

For issues or suggestions, please raise them in the HBL Nexus discord HERE

---

HBLCore - Hytale Ban List Core

Simple passive ban-status awareness for Hytale servers. Know exactly who is joining & their history on networked servers - no bans applied, no local data touched.

If you want in-game notifications when a known bad actor joins - without wiring up a full ban system - this is the plugin for you.

If you are a developer building a moderation plugin, HBLCore gives you a clean event hook to receive ban status on every join without having to implement the API yourself.

---

Getting Started

1. Activate

Run /hblcore auth and click the magic link. Your server is registered.

2. Grant notify permission (Optional)

Give the HBLCore.notify permission to any staff rank. They will receive an in-game notification every time a player joins, showing their HBL status.

3. That's it

HBLCore runs silently in the background. No bans are applied. No local files are written to. Staff with the notify permission stay informed.

---

What HBLCore Does NOT Do

It is important to be clear about this:

• It does not kick or disconnect any player
• It does not write to bans.json, whitelist.json, or any server file
• It does not manage warnings, bans, or moderation history locally
• It does not override or replace any native server commands

HBLCore is purely an information layer. What you do with that information is up to you or the plugins consuming its events.

---

In-Game Notifications

When notify: true is set in config, staff with the HBLCore.notify permission receive a notification popup on every player join:

Status	Notification
Clear	Green - "[HBLCore] PlayerName - Clear"
Banned	Red - "[HBLCore] PlayerName - BANNED - {reason}"
Pending Ban	Orange - "[HBLCore] PlayerName - PENDING BAN - {reason}"
Whitelisted	Green - "[HBLCore] PlayerName - Whitelisted"

Notifications are silent to players without the HBLCore.notify permission.

---

Configuration

Config is created automatically at HBLCore/config.json on first run.

{
  "APIKey": "YOUR_API_KEY_HERE",
  "notify": true,
  "BanReports": true
}

Field	Type	Default	Description
APIKey	string	"YOUR_API_KEY_HERE"	Your hytalebanlist.org API key. Set via /hblcore auth.
notify	boolean	true	Send in-game status notifications to staff with HBLCore.notify.
BanReports	boolean	true	Enable the /hblcore report command.

---

Commands

/hblcore auth

Registers this server with hytalebanlist.org. Opens a magic link - click it in your browser to complete activation. The API key is saved automatically.

Requires: HBLCore.auth

/hblcore report {time} {username}

Submits a report for a player without a reason. The API returns a magic link - open it to add reasoning, evidence, and complete the submission via the web UI. Nothing is applied locally.

Requires: HBLCore.report and BanReports: true in config.

Duration examples: 30m 2h 7d 2w 1mo 1y perm

/hblcore report 7d SomePlayer
> Report submitted for SomePlayer. Complete it at:
> https://hytalebanlist.org/report/...

---

Permissions

Permission	Who to give it to	What it does
HBLCore.auth	Server admins	Run /hblcore auth
HBLCore.report	Staff who submit reports	Run /hblcore report
HBLCore.notify	Staff / moderators	Receive in-game join status notifications

---

For Plugin Developers - Event Hooks

HBLCore exposes a static event API that any plugin can hook into with a single line. You receive the ban status of every joining player without having to implement the hytalebanlist.org API yourself.

Registering a listener

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

// In your plugin's setup():
HBLCorePlugin.registerStatusListener(event -> {
    if (event.getStatus() == PlayerStatus.BANNED) {
        // kick, log, alert - your call
    }
});

Available event data

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)

Status values

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.

Handling all statuses

HBLCorePlugin.registerStatusListener(event -> {
    switch (event.getStatus()) {
        case BANNED -> {
            // Active ban confirmed - kick, log, restrict, etc.
            String reason = event.getReason();
            String appeal = event.getAppealUrl();
        }
        case LOCAL_BAN -> {
            // Ban exists but is pending review - not yet confirmed
        }
        case WHITELISTED -> {
            // Explicitly whitelisted - clear any local restrictions
        }
        case CLEAR -> {
            // Clean player - no action needed
        }
    }
});

Declaring HBLCore as a dependency

In your plugin's manifest.json:

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

Important notes for developers

• HBLCore never kicks players. Your listener decides what action to take.
• Listeners are called asynchronously. Avoid blocking operations inside the callback.
• Exceptions are caught per listener. A crash in your code will not affect other listeners or the join flow.
• Registration is load-order safe. Call registerStatusListener any time in your plugin's setup().

Full developer documentation: plugin-event-usage.md

---

Useful Links

• Main site: https://hytalebanlist.org
• Register: https://hytalebanlist.org/register
• Dashboard: https://hytalebanlist.org/login