Moderation
Moderation
Complete guide to the moderation system — banning, unbanning, muting, unmuting players with reasons, durations, and admin attribution.
Ban System
Data Sources
The ban system uses dual data sources with fallback:
- Primary:
bans.jsonfile on the server — read directly via Daemon file API - Fallback: Java Mod API (
GET /mods→ ban endpoints) — used if file is unavailable
Banning a Player
| Detail | Value |
|---|---|
| Permission | hytale-admin.moderation-manage |
| API | POST /players/{name}/ban |
| Body | { "reason": string, "admin": string } |
| Success | "Player banned: {player}" |
| Failure | "Ban failed" |
| Logged as | server:hytale-admin.ban |
Unbanning a Player
Uses dual strategy:
- First attempts to remove the entry from
bans.jsondirectly - Falls back to API call
POST /players/{name}/unbanif file modification fails
| Detail | Value |
|---|---|
| Permission | hytale-admin.moderation-manage |
| Success | "Player unbanned: {player}" |
| Failure | "Unban failed" |
| Logged as | server:hytale-admin.unban |
Ban List Display
| Column | Description |
|---|---|
| Player | Name and UUID (resolved via known_players + whitelist lookup) |
| Reason | Ban reason text |
| Banned By | Admin who issued the ban |
| Date | Ban timestamp |
The ban table polls every 30 seconds.
Mute System
Muting a Player
| Detail | Value |
|---|---|
| Permission | hytale-admin.moderation-manage |
| API | POST /players/{name}/mute |
| Body | { "duration": int, "reason": string, "admin": string } |
| Duration | In minutes |
| Success | "Player muted: {player}" |
| Failure | "Mute failed" |
| Logged as | server:hytale-admin.mute |
Duration is in minutes, not seconds or hours. A 1-hour mute =
duration: 60.
Unmuting a Player
| Detail | Value |
|---|---|
| Permission | hytale-admin.moderation-manage |
| API | POST /players/{name}/unmute |
| Success | "Player unmuted: {player}" |
| Failure | "Unmute failed" |
| Logged as | server:hytale-admin.unmute |
Mute List Display
The mute table also polls every 30 seconds.
UUID → Name Resolution
The moderation display resolves UUIDs to player names using a lookup map built from:
known_players.json— primary sourcewhitelist.json— fallback for whitelisted players not in known_players
If no name is found, the raw UUID is displayed.
Timestamp Handling
The moderation system handles three timestamp formats:
| Format | Example | Source |
|---|---|---|
| Millisecond timestamps | 1703001234567 |
Java mod epoch millis |
| ISO date strings | 2024-01-01T12:00:00Z |
Standard JSON format |
| Raw strings | "January 1, 2024" |
Fallback parsing |
All timestamps are normalized to the panel's timezone for display.
Activity Logging
All moderation actions are recorded to Pelican's activity_logs table:
| Action | Event Key |
|---|---|
| Ban | server:hytale-admin.ban |
| Unban | server:hytale-admin.unban |
| Mute | server:hytale-admin.mute |
| Unmute | server:hytale-admin.unmute |
These appear in the Activity Log tab on the dashboard.
Troubleshooting
Ban list doesn't load
bans.jsonmay not exist yet (no bans issued)- Daemon file API unable to read file — check permissions
- Fallback to API also failed — check API connection
"Ban failed" error
- Player name may not match exactly (case-sensitive)
- API connection lost — check Java mod is running
- Check
storage/logs/laravel.logfor "Hytale API error"
"Unban failed" error
- Player may not be in the ban list
- Dual strategy: both file edit and API call failed
- File may be locked by the server process
Mute duration seems wrong
- Duration is in minutes —
60= 1 hour, not 1 minute - Server timezone may differ from panel timezone
Ban shows UUID instead of name
- Player not found in
known_players.jsonorwhitelist.json - Player may have never joined the server
- Run Discover Players on the Players page to update the known list