Player Management
Player Management
Complete guide to the Players page — viewing online/offline players, player actions (kick, heal, teleport, gamemode, OP), inventory editing, item giving, and the player discovery system.
Player List
The Players page displays all known players with two data sources merged:
Data Source Merging
| Source |
Priority |
Data Provided |
Java Mod API (GET /players) |
Primary for online players |
Name, UUID, position, gamemode, health |
Save Files (universe/players/*.json) |
Primary for offline players |
Full stats, inventory, last position |
Merge logic:
- Online players: API is source of truth for real-time stats. Save file data ignored while online.
- Offline players: Save file overrides stats but keeps API name/UUID if available.
- Stale API protection: If server status reports 0 online players but API still returns players, all are forced to
online=false.
The player table polls every 15 seconds.
Player Discovery
Click Discover Players to scan universe/players/ directory for new save files:
- Finds players who joined but aren't in the known players list
- Success: "X new players discovered" with
:count parameter
- New players added to
known_players.json
Displayed Columns
| Column |
Description |
| Avatar |
Player skin head (identicon for demo mode) |
| Name |
In-game player name |
| Status |
Online (green) / Offline (gray) |
| Health |
Current / max health |
| Gamemode |
Current gamemode |
| Position |
X, Y, Z coordinates |
Player Actions
Each action requires the hytale-admin.players-manage permission.
Kick Player
| Detail |
Value |
| API |
POST /players/{name}/kick |
| Success |
"Player kicked: {player}" |
| Failure |
"Kick failed" |
| Notes |
Player must be online |
Heal Player
| Detail |
Value |
| API |
POST /players/{name}/heal |
| Success |
"Player healed: {player}" |
| Failure |
"Heal failed" |
| Notes |
Restores health to maximum |
Teleport Player
| Detail |
Value |
| API |
POST /players/{name}/teleport |
| Body |
{ "x": float, "y": float, "z": float } |
| Success |
"Player teleported: {player}" |
| Failure |
"Teleport failed" OR API error message from $result['error'] |
| Notes |
The API may return a specific error message instead of a generic failure |
Set Gamemode
| Detail |
Value |
| API |
POST /players/{name}/gamemode |
| Body |
{ "mode": string } |
| Success |
"Gamemode set: {player} → {gamemode}" |
| Failure |
"Gamemode change failed" |
OP / De-OP Player
| Detail |
Value |
| API (OP) |
POST /players/{name}/op |
| API (De-OP) |
POST /players/{name}/deop |
| Success |
"Player OPed: {player}" / "Player de-OPed: {player}" |
| Failure |
"OP failed" / "De-OP failed" |
Give Item
| Detail |
Value |
| API |
POST /players/{name}/give |
| Body |
{ "itemId": string, "amount": int } |
| Permission |
hytale-admin.players-inventory |
| Success |
"Item given: {item} ×{amount} to {player}" |
| Failure |
"Give failed" OR API error message |
Clear Inventory
| Detail |
Value |
| API |
POST /players/{name}/clear-inventory |
| Permission |
hytale-admin.players-inventory |
| Success |
"Inventory cleared: {player}" |
| Failure |
"Clear failed" OR API error message |
Inventory Editor
The visual inventory editor requires the hytale-admin.players-inventory permission.
Online vs. Offline Editing
| Player State |
Method |
Latency |
Risk |
| Online |
Java Mod API |
Real-time |
Low — API validates changes |
| Offline |
Direct save file editing |
Immediate |
Medium — no validation, be careful |
Inventory Sections
| Section |
Slots |
Description |
| Main Inventory |
Variable |
Regular inventory slots |
| Armor |
4 |
Head, Chest, Hands, Legs |
| Quick Bar |
Variable |
Fast-access slots |
Armor Slot Filtering
Items are filtered for appropriate armor slots by suffix:
_Head → Head slot only_Chest → Chest slot only_Hands → Hands slot only_Legs → Legs slot only
Slot Operations
Set Slot:
| Detail |
Value |
| API |
POST /players/{name}/inventory/set-slot |
| Success |
"Slot updated" |
| Failure |
"Slot update failed" |
Remove Slot:
| Detail |
Value |
| API |
POST /players/{name}/inventory/remove-slot |
| Success |
"Slot cleared: {section} #{slot}" |
| Failure |
"Slot clear failed" |
Swap Slots:
| Detail |
Value |
| API |
POST /players/{name}/inventory/swap-slots |
| Success |
"Slot moved" |
| Failure |
"Slot move failed" |
Item Search
The item search function (GET /items/search) has special behavior:
- Max 50 results to prevent Livewire snapshot bloat
- Reverse lookup for non-English panels: Translated item names are reverse-mapped to English keys, then searched via the API with English terms
- Auto-complete with debounce
- Base64 item icons extracted from item data for visual display
Player Stats from Save Files
When reading save files (universe/players/*.json), the following stats are extracted:
| Stat |
Field |
| Health |
health |
| Max Health |
maxHealth |
| Stamina |
stamina |
| Max Stamina |
maxStamina |
| Mana |
mana |
| Max Mana |
maxMana |
| Defence |
defence |
| Position |
X, Y, Z |
| Gamemode |
gamemode |
BSON Compatibility: Player save files use json_decode($content, false) (NOT associative arrays) because Hytale uses a BSON-like encoding where the distinction between {} (object) and [] (array) matters. Using json_decode($content, true) would break the save format.
Troubleshooting
Player list is empty
- No players have ever joined the server
- Java mod not running (API unavailable)
known_players.json missing — try Discover Players
Online player shows as offline
- Stale API protection triggered: Status says 0 online but API still returns the player
- Wait for next poll cycle (15s)
- Player may have disconnected between status and player API calls
Inventory editor doesn't load
- Player save file missing or corrupted
- For online players: API endpoint
/players/{name}/inventory returned error
- Check
storage/logs/laravel.log for "Hytale API error"
"Give failed" with specific error
- Invalid item ID — check item name spelling
- Amount out of range
- The API returns specific error messages in
$result['error']
Item search returns wrong results
- Non-English panel: reverse lookup maps translated name → English key → API search
- Try searching in English for more accurate results
- Item database may not include modded items
Save file editing issues
- Never edit save files while a player is online — the server will overwrite your changes
- The offline editor modifies the JSON directly — mistakes can corrupt the save
- Back up the save file before major edits