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.
📜 (Optional) Configure your ban messages
🔨(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 secondsm minutesh hoursd daysw weeksmo 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
[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.authhytalebanlist.reloadhytalebanlist.banhytalebanlist.unbanhytalebanlist.warninghytalebanlist.checkbanshytalebanlist.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
