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

• 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

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

[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.

1. Copy the default en.json locale.
2. Translate values into your target language.
3. Save as <your-locale>.json inside your plugin locale folder.
4. Set "locale": "<your-locale>" in config.json.
5. 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:

• https://bans.yourserver.com/
• https://bans.yourserver.com/search
• https://bans.yourserver.com/appeal/:banId

DNS setup

Add both records at your DNS provider:

1. CNAME

• Host/Name: bans.yourserver.com (or your chosen subdomain)
• Target: appeals.hytalebanlist.org

1. 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