premium banner

HBL - Bans & Warnings

/hbl auth | ban appeals, staff logins.

Description

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

Buy Me a Coffee at ko-fi.com

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.

  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:

DNS setup

Add both records at your DNS provider:

  1. CNAME

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

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