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, magic link activation, 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 a server owner account

Create your account at hytalebanlist.org. No API key needed — the plugin handles registration for you.

Step 2

Install plugin in mods folder

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

Step 3

Activate via magic link

Run /hbl auth in-game. The plugin will display a link in chat — click it to activate your server on the HBL Network. No key needed.

Step 4

Import legacy bans baseline

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

Commands to run after install

/hbl auth
/hbl reload
/hbl import

Command Reference

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

/hbl auth
/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.

Permission Nodes

Assign these permission nodes to staff roles in your permission manager.

hytalebanlist.auth

hytalebanlist.reload

hytalebanlist.ban

hytalebanlist.unban

hytalebanlist.warning

hytalebanlist.checkbans

hytalebanlist.import

Configuration Fields

Field	Default	Purpose
api.key	auto	Set automatically when you run /hbl auth. Do not edit manually.
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.