bans.json

Stores the server’s ban list. UUID-based — bans persist even if a player changes their name.

File: bans.json
Provider: HytaleBanProvider

Format

The file contains a flat JSON array of ban objects:

[
  {
    "type": "infinite",
    "target": "550e8400-e29b-41d4-a716-446655440000",
    "by": "660e8400-e29b-41d4-a716-446655440000",
    "timestamp": 1736942400000,
    "reason": "Griefing"
  },
  {
    "type": "timed",
    "target": "770e8400-e29b-41d4-a716-446655440000",
    "by": "660e8400-e29b-41d4-a716-446655440000",
    "timestamp": 1736942400000,
    "expiresOn": 1737028800000,
    "reason": "Spamming"
  }
]

Ban Types

Type	Description	Disconnect Message
infinite	Permanent ban, never expires	"You are permanently banned!"
timed	Expires at a set time, auto-pruned on load	"You are temporarily banned for <duration>!"

If a reason is set, " Reason: <reason>" is appended to the disconnect message.

Fields

Field	Type	Description
type	String	"infinite" or "timed"
target	UUID	Banned player’s UUID
by	UUID	UUID of who created the ban
timestamp	long	Epoch milliseconds when the ban was created
reason	String	Ban reason (optional)
expiresOn	long	Epoch milliseconds when the ban expires (timed bans only)

Expired timed bans are automatically removed when the file is loaded and during connection checks.

API

The built-in HytaleBanProvider is not directly accessible from the mod API. For custom ban logic, register an AccessProvider or use PlayerSetupConnectEvent. See Access Control for the full API, including custom ban parsers and access providers.

Commands

Command	Description
/ban <player> [reason]	Permanently ban a player
/unban <player>	Remove a ban

The /ban command always creates permanent bans. There is no built-in command for timed bans.

See Access Control Commands for details.