Spielerverwaltung

Vollständige Anleitung zur Spieler-Seite — Online-/Offline-Spieler anzeigen, Spieleraktionen (Kicken, Heilen, Teleportieren, Spielmodus, OP), Inventarbearbeitung, Items geben und das Spieler-Entdeckungssystem.

Spielerliste

Die Spieler-Seite zeigt alle bekannten Spieler mit zwei zusammengefügten Datenquellen:

Datenquellen-Zusammenführung

Quelle	Priorität	Bereitgestellte Daten
Java-Mod-API (`GET /players`)	Primär für Online-Spieler	Name, UUID, Position, Spielmodus, Gesundheit
Speicherdateien (`universe/players/*.json`)	Primär für Offline-Spieler	Vollständige Stats, Inventar, letzte Position

Zusammenführungslogik:

Online-Spieler: API ist die Wahrheitsquelle für Echtzeitdaten. Speicherdatei-Daten werden ignoriert solange online.
Offline-Spieler: Speicherdatei überschreibt Stats, behält aber API-Name/UUID bei falls verfügbar.
Veralteter-API-Schutz: Wenn der Serverstatus 0 Online-Spieler meldet, die API aber noch Spieler zurückgibt, werden alle auf online=false gesetzt.

Die Spielertabelle aktualisiert sich alle 15 Sekunden.

Spieler-Entdeckung

Klicke Spieler entdecken um das universe/players/-Verzeichnis nach neuen Speicherdateien zu scannen:

Findet Spieler, die beigetreten sind, aber nicht in der Spielerliste stehen
Erfolg: „X neue Spieler entdeckt"
Neue Spieler werden zu known_players.json hinzugefügt

Angezeigte Spalten

Spalte	Beschreibung
Avatar	Spieler-Skin-Kopf (Identicon im Demo-Modus)
Name	In-Game-Spielername
Status	Online (grün) / Offline (grau)
Gesundheit	Aktuell / Maximum
Spielmodus	Aktueller Spielmodus
Position	X, Y, Z Koordinaten

Spieleraktionen

Jede Aktion erfordert die Berechtigung hytale-admin.players-manage.

Spieler kicken

Detail	Wert
API	`POST /players/{name}/kick`
Erfolg	„Spieler gekickt: {player}"
Fehler	„Kick fehlgeschlagen"
Hinweis	Spieler muss online sein

Spieler heilen

Detail	Wert
API	`POST /players/{name}/heal`
Erfolg	„Spieler geheilt: {player}"
Fehler	„Heilung fehlgeschlagen"
Hinweis	Stellt Gesundheit auf Maximum wieder her

Spieler teleportieren

Detail	Wert
API	`POST /players/{name}/teleport`
Body	`{ "x": float, "y": float, "z": float }`
Erfolg	„Spieler teleportiert: {player}"
Fehler	„Teleportation fehlgeschlagen" ODER API-Fehlermeldung aus `$result['error']`

Spielmodus setzen

Detail	Wert
API	`POST /players/{name}/gamemode`
Body	`{ "mode": string }`
Erfolg	„Spielmodus gesetzt: {player} → {gamemode}"
Fehler	„Spielmodus-Änderung fehlgeschlagen"

OP / De-OP

Detail	Wert
API (OP)	`POST /players/{name}/op`
API (De-OP)	`POST /players/{name}/deop`
Erfolg	„Spieler OP gegeben: {player}" / „Spieler De-OP: {player}"
Fehler	„OP fehlgeschlagen" / „De-OP fehlgeschlagen"

Item geben

Detail	Wert
API	`POST /players/{name}/give`
Body	`{ "itemId": string, "amount": int }`
Berechtigung	`hytale-admin.players-inventory`
Erfolg	„Item gegeben: {item} ×{amount} an {player}"
Fehler	„Item-Gabe fehlgeschlagen" ODER API-Fehlermeldung

Inventar leeren

Detail	Wert
API	`POST /players/{name}/clear-inventory`
Berechtigung	`hytale-admin.players-inventory`
Erfolg	„Inventar geleert: {player}"
Fehler	„Inventar-Leeren fehlgeschlagen" ODER API-Fehlermeldung

Inventar-Editor

Der visuelle Inventar-Editor erfordert die Berechtigung hytale-admin.players-inventory.

Online vs. Offline Bearbeitung

Spielerstatus	Methode	Latenz	Risiko
Online	Java-Mod-API	Echtzeit	Gering — API validiert Änderungen
Offline	Direkte Speicherdatei-Bearbeitung	Sofort	Mittel — keine Validierung, Vorsicht geboten

Inventar-Bereiche

Bereich	Slots	Beschreibung
Hauptinventar	Variabel	Reguläre Inventar-Slots
Rüstung	4	Kopf, Brust, Hände, Beine
Schnellleiste	Variabel	Schnellzugriff-Slots

Rüstungs-Slot-Filterung

Items werden nach passendem Rüstungsslot per Suffix gefiltert:

_Head → Nur Kopf-Slot
_Chest → Nur Brust-Slot
_Hands → Nur Hände-Slot
_Legs → Nur Bein-Slot

Slot-Operationen

Slot setzen: Erfolg: „Slot aktualisiert" / Fehler: „Slot-Aktualisierung fehlgeschlagen"

Slot leeren: Erfolg: „Slot geleert: {section} #{slot}" / Fehler: „Slot-Leeren fehlgeschlagen"

Slots tauschen: Erfolg: „Slot verschoben" / Fehler: „Slot-Verschieben fehlgeschlagen"

Item-Suche

Die Item-Suchfunktion (GET /items/search) hat besonderes Verhalten:

Max. 50 Ergebnisse um Livewire-Snapshot-Aufblähung zu verhindern
Rückwärtssuche für nicht-englische Panels: Übersetzte Item-Namen werden auf englische Schlüssel zurückgemappt, dann via API mit englischen Begriffen gesucht
Auto-Vervollständigung mit Debounce
Base64-Item-Icons aus Item-Daten extrahiert für visuelle Darstellung

BSON-Kompatibilität: Spieler-Speicherdateien verwenden json_decode($content, false) (NICHT assoziative Arrays), da Hytale eine BSON-ähnliche Kodierung nutzt, bei der die Unterscheidung zwischen {} (Objekt) und [] (Array) wichtig ist.

Fehlerbehebung

Spielerliste ist leer

Keine Spieler haben je den Server betreten
Java-Mod läuft nicht (API nicht erreichbar)
known_players.json fehlt — Spieler entdecken versuchen

Online-Spieler wird als offline angezeigt

Veralteter-API-Schutz ausgelöst: Status meldet 0 online, API gibt aber noch Spieler zurück
Nächsten Abfragezyklus abwarten (15s)

Inventar-Editor lädt nicht

Spieler-Speicherdatei fehlt oder ist beschädigt
Bei Online-Spielern: API-Endpunkt hat Fehler zurückgegeben
storage/logs/laravel.log auf „Hytale API error" prüfen

„Item-Gabe fehlgeschlagen" mit spezifischem Fehler

Ungültige Item-ID — Schreibweise des Item-Namens prüfen
Menge außerhalb des Bereichs
Die API gibt spezifische Fehlermeldungen in $result['error'] zurück

Speicherdatei-Bearbeitung — Probleme

Niemals Speicherdateien bearbeiten, während ein Spieler online ist — der Server überschreibt die Änderungen
Der Offline-Editor modifiziert das JSON direkt — Fehler können die Datei beschädigen
Speicherdatei vor größeren Änderungen sichern