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

HBL - Hytale Ban List

Globally centralized moderation checks for Hytale servers with optional shared-ban enforcement, local warnings, and branded appeals pipeline & Staff Logins.

Stop known hackers, griefers and bad actors with ease.

✅ Activating the plugin

Run /hbl auth and use the magic link provided. That's it. Your dashboard is live and your server is protected from known bad actors.

/hbl auth registration flow

📜 (Optional) Configure your ban messages

modify config.json

🔨(Optional) Import your current bans.json

/hbl import

It is recommended to disable overlapping native moderation features in other installed mods.

✨ Core Features

Join-time ban checks against the Hytale Ban List API.
Built-in whitelist integration (Server/whitelist.json) that allows players immediately and skips API checks.
Immediate disconnect of banned players with reason, expiry, and appeal URLs.
Top-level moderation commands (/ban, /unban, /warning) registered by the plugin.
Warning system with auto-ban once a configurable threshold is reached.
Rate-limit fallback mode with hourly console reminders to increase limits at hytalebanlist.org.
Queued local bans while rate-limited (synced: false) with automatic retry sync at 00:01 UTC.
Smarter /hbl import pipeline that resolves usernames from UUIDs when possible and clears imported bans from in-memory cache after full success.
Compatibility detection for known moderation mods with red/green status output and config guidance.
Localisation support via editable locale files.

⚙️ Configuration Guide

`config.json` fields

Field	Type	Default	What it does
`api.key`	string	`"YOUR_API_KEY_HERE"`	API key from Hytale Ban List dashboard.
`messages.kickMessage`	string	Includes `{reason}`, `{expires}`, `{appealUrl}`	Message shown when a player is denied.
`moderation.warningThreshold`	number	`3`	Auto-ban after this many warnings.
`moderation.defaultBanDuration`	string	`"perm"`	Default duration when `/ban` is used without time.
`general.locale`	string	`"en"`	Locale filename to load from `HytaleBanList/locales`.
`general.replaceNativeBanCommands`	boolean	`true`	Replaces native `/ban` and `/unban` with plugin versions.

Supported duration tokens

Use these for /ban and defaultBanDuration:

s seconds
m minutes
h hours
d days
w weeks
mo months (~30d)
y years (~365d)
perm permanent

Examples: 30m, 2h, 7d, 2w, 1mo, 1y, perm

🧩 Commands

Main command

/hbl

Subcommands:

/hbl auth → returns magic link for server setup
/hbl reload → reload config and locale
/hbl ban <player> [duration] [reason]
/hbl unban <player>
/hbl warn <player> [reason]
/hbl checkbans
/hbl import

Top-level aliases registered by plugin

/ban <player> [duration] [reason]
/unban <player>
/warn <player> [reason]
/checkbans

`/hbl help` preview

HBL Help Usage

[HytaleBanList] Help
/ban {player} {time} {reason} | /hbl ban {player} {time} {reason}
/unban {player} | /hbl unban {player}
/warning {player} {reason} | /hbl warn {player} {reason}
/hbl checkbans | /checkbans
/hbl import (imports from Hytale bans.json)
/hbl auth | /hbl reload
time: 30m 2h 7d 2w 1mo 1y perm

Color key in game output: red = ban, green = unban, yellow = header/warn/time, cyan = utility commands.

Permissions

hytalebanlist.auth
hytalebanlist.reload
hytalebanlist.ban
hytalebanlist.unban
hytalebanlist.warning
hytalebanlist.checkbans
hytalebanlist.import

🌍 Localisation

Localisation is fully optional but supported.

Copy the default en.json locale.
Translate values into your target language.
Save as <your-locale>.json inside your plugin locale folder.
Set "locale": "<your-locale>" in config.json.
Run /hbl reload.

If a custom locale is missing/invalid, the plugin falls back to bundled English.

🛡️ Bans and Warnings

Ban flow

Staff issues /ban.
Plugin submits to Hytale Ban List API.
On success, player is disconnected with your configured kick template.
Appeal URL is included when provided by the API.

When API limit is reached:

/ban still applies locally and disconnects immediately.
Entry is written to bans.json with "synced": false.
Queued entries are retried automatically at 00:01 UTC.
Once synced successfully, the entry is marked "synced": true.

Warning flow

Staff issues /warn.
Warning count is tracked locally.
At warningThreshold, plugin auto-submits a permanent ban.
On successful auto-ban, warnings are cleared for that player.

🌐 Global Ban Behavior (Configurable)

Global/shared-ban behavior is controlled by your Hytale Ban List server-side settings (dashboard/API policy), while this plugin enforces the ban-check response it receives.

In practice:

This plugin always performs the configured API check on join.
Whether a returned ban is globally shared, pending, or server-scoped depends on your Hytale Ban List configuration.
Adjust global moderation policy in your Hytale Ban List dashboard for your server.

📉 API Rate-Limit Behavior

If API usage is exhausted (for example before reset at 00:00 UTC):

Plugin enters a temporary fallback mode until next UTC reset.
Join checks use whitelist/bans fallback and skip API calls during that window.
Console prints an hourly reminder that the API limit is reached and to visit hytalebanlist.org to increase limit.
/checkbans is skipped while limited and shows a rate-limit message.

After reset:

Queued local bans (synced: false) are retried automatically at 00:01 UTC.

🔗 Custom Domains via CNAME (Premium)

HytaleBanList.org supports custom moderation portals (ban list, lookup, appeals) on your own subdomain with a paid plan.

Example portal URLs:

DNS setup

Add both records at your DNS provider:

CNAME
- Host/Name: bans.yourserver.com (or your chosen subdomain)
- Target: appeals.hytalebanlist.org
TXT
- Host/Name: _hytale-verify.bans.yourserver.com
- Value: hbl_verify_<token>
- Token source: generated in your server settings dashboard when you save the custom domain.

Then verify DNS in dashboard once records propagate.

Notes

Custom domains are available on premium plans.
Subdomains are recommended (root/apex domains generally cannot use CNAME in standard DNS setups).
Typical propagation is fast, but global DNS can take longer.

✅ Recommended First Checks

After setup, verify these quickly:

API key is saved and no auth warnings appear in logs.
/hbl reload succeeds.
/ban and /warn permissions are assigned to staff roles.
Kick message placeholders render correctly ({reason}, {expires}, {appealUrl}).
Locale changes apply after reload.

📚 Useful Links

Main site: https://hytalebanlist.org
Register: https://hytalebanlist.org/register
Login/dashboard: https://hytalebanlist.org/login
Pricing: https://hytalebanlist.org/pricing
Custom domain details: https://appeals.hytalebanlist.org

HBL - Bans & Warnings