Does the plugin support local warning thresholds with auto-ban?

Yes. warningThreshold controls automatic ban trigger when warning count reaches your configured value.

What happens when API limits are reached?

Plugin enters fallback mode, queues unsynced local bans, and retries sync at 00:01 UTC after reset.

Can I use a custom domain for appeals and search?

Yes on paid plans, via CNAME to appeals.hytalebanlist.org and TXT verification token in dashboard.

Official setup and command reference

Hytale Ban List Plugin Guide

This guide covers practical plugin setup for production moderation teams: install, auth, import, command flow, fallback behavior, and compatibility checks. If you are preparing your server before release, this is your complete implementation checklist.

Back to Download Page Register Server Owner Account

Quick Start (5-10 minutes)

Step 1

Register server and copy API key

Create your account, create server in dashboard, and keep the API key ready for /hbl auth.

Step 2

Install plugin in mods folder

Place extracted plugin JAR in Server/mods and restart once. Config file is generated automatically.

Step 3

Authenticate and reload

Run /hbl auth YOUR_API_KEY and then /hbl reload to apply API credentials and locale settings.

Step 4

Import legacy bans baseline

Run /hbl import to process Server/bans.json and keep moderation history aligned with plugin flow.

First commands to run

/hbl auth YOUR_API_KEY
/hbl reload
/hbl import

Command Reference

Primary command set plus top-level aliases registered by plugin.

/hbl auth <key>
/hbl reload
/hbl ban <player> [duration] [reason]
/hbl unban <player>
/hbl warn <player> [reason]
/hbl checkbans
/hbl import

Aliases: /ban /unban /warn /checkbans
Duration tokens: 30m 2h 7d 2w 1mo 1y perm

Hytale plugin help screenshot with /hbl command overview — In-game `/hbl help` output used as staff quick reference.

Configuration Fields

Field	Default	Purpose
api.key	YOUR_API_KEY_HERE	Dashboard API key used for join checks and moderation sync.
messages.kickMessage	Template string	Kick message placeholders: {reason}, {expires}, {appealUrl}.
moderation.warningThreshold	3	Warnings needed before automatic ban trigger.
moderation.defaultBanDuration	perm	Fallback duration for /ban when no explicit time token is supplied.
general.locale	en	Locale file key loaded from plugin locales folder.
general.replaceNativeBanCommands	true	Uses plugin moderation commands in place of default native command flow.

Compatibility Check

Disable overlapping moderation features in other mods. Plugin accepts both object and flat styles.

"ban": { "enabled": false },
"freeze": { "enabled": false }

OR

"ban": false,
"freeze": false

Rate-Limit Fallback Behavior

If API limit is exhausted, plugin runs fallback mode, queues unsynced bans, then retries sync after UTC reset.

- Local moderation still applies while limited.
- Queued entries are retried automatically at 00:01 UTC.
- Console emits reminder notices while fallback is active.

Custom Domain Setup (Premium)

Use your own moderation portal host (appeals/search/listing) with CNAME + TXT verification.

CNAME  bans.yourserver.com -> appeals.hytalebanlist.org
TXT    _hytale-verify.bans.yourserver.com = hbl_verify_<token>

Subdomains are recommended. Verify in dashboard after DNS propagation.