Berechtigungen

Eranio

Berechtigungen

Vollständige Anleitung zum Berechtigungssystem, 17 granulare Berechtigungen, benutzerdefinierte Berechtigungsgruppen und OP-Verwaltung.

Berechtigungsreferenz

Das Plugin definiert 17 benutzerdefinierte Berechtigungen zur Steuerung des Zugriffs auf jede Funktion:

Berechtigungshierarchie

Berechtigungen folgen einem lesen → verwalten-Muster:

• *-read = Nur-Lese-Zugriff
• *-manage = Volle Kontrolle (beinhaltet Lesen)

Berechtigungsgruppen

Gruppe erstellen

Gruppe löschen

Beispielgruppen

OP-Verwaltung

OP gewähren

OP widerrufen

Hinweis: OP-Verwaltung verwendet UUIDs, nicht Spielernamen. Das Plugin löst Namen zu UUIDs für dich auf.

Spiel-Übersetzungssystem

Für die Item-Suche und den Inventar-Editor werden Item-Namen über eine Prioritätskette übersetzt:

13 Sprachzuordnungen werden unterstützt.

Fehlerbehebung

Benutzer kann auf ein Feature nicht zugreifen

• Prüfe welche Berechtigung für das Feature erforderlich ist (siehe Tabelle oben)
• Verifiziere, dass der Benutzer/Unterbenutzer die Berechtigung zugewiesen hat
• Serverbesitzer haben standardmäßig alle Berechtigungen

Berechtigungsgruppen-Erstellung fehlgeschlagen

• Gruppenname existiert möglicherweise bereits
• API-Verbindung unterbrochen
• permissions.json-Datei gesperrt oder beschädigt

Aktivitätslog zeigt „unbekannt" als Akteur

• Der Admin-Benutzername wird aus der Panel-Sitzung übergeben
• Bei abgelaufener Sitzung während der Aktion kann der Akteur leer sein

API-Client & Interne Architektur

Vollständige API-Endpunkt-Dokumentation ist in der HytaleAdminAPI-Referenz verfügbar. Dieser Abschnitt behandelt den PHP-Client, den das Panel-Plugin intern zur Kommunikation mit dem Hytale-Server-Mod verwendet. Für Endpunkt-Parameter, Antwort-Schemata und Anfrage-Beispiele siehe die HytaleAdminAPI-Dokumentation.

HytaleApiService, PHP-Client

Das Panel-Plugin spricht mit dem Hytale-Mod über die Klasse HytaleApiService, die alle HTTP-Aufrufe kapselt. Jede Seite (Dashboard, Spieler, Chat usw.) nutzt diesen Dienst.

Woher die Verbindungsdaten kommen

Das Plugin liest die config.json des Mods über Pelicans Datei-Schnittstelle (ModConfigReader), es gibt keine Egg-Variablen und keine Einstellung im Panel dafür. Ändern lassen sich die Werte im Fenster Einstellungen bearbeiten auf der Einrichtungsseite, das Plugin schreibt sie dann in dieselbe Datei.

// Aufbau der Verbindung (vereinfacht aus HytaleApiService)
$modConfig = app(ModConfigReader::class)->readConfig($server);
$baseUrl   = 'http://' . $server->node->fqdn . ':' . ($modConfig['port'] ?? 5550);

Http::baseUrl($baseUrl)
    ->timeout($modConfig['requestTimeout'] ?? 10)
    ->withHeaders([
        'X-Admin-Token' => $modConfig['token'] ?? '',
        'Accept'        => 'application/json',
    ])
    ->get('/api/status');

Der Token geht im Header X-Admin-Token mit, nicht als Bearer-Token. Schlägt ein Aufruf fehl (Fehlercode oder keine Verbindung), gibt der Dienst null zurück statt eine Ausnahme zu werfen. Die Seiten zeigen dann ihren Hinweis, dass die API nicht erreichbar ist.

Anfrage-Ablauf, Panel zum Server-Mod

┌──────────────┐    HTTP/JSON     ┌─────────────────┐    Java API    ┌──────────────┐
│  Panel Plugin │ ──────────────> │ Hytale Mod HTTP  │ ──────────── > │ Hytale Server│
│  (PHP/Laravel)│ <────────────── │ Server (Netty)   │ < ──────────── │   (Spiel)    │
│               │  JSON-Antwort   │                  │   Spielzustand │              │
└──────────────┘                  └─────────────────┘                └──────────────┘

Wichtige Architektur-Hinweise:

• Der Mod bettet einen Netty HTTP-Server in den Hytale-Serverprozess ein
• Alle spielverändernden Operationen (Kick, Ban, Teleport) laufen auf dem Server-Hauptthread
• Nur-Lese-Operationen (Status, Spielerliste) können gecachte Daten verwenden
• Die API ist synchron aus Panel-Sicht, intern wird aber an den Spielthread weitergeleitet

Funktion → API-Endpunkt-Zuordnung

Siehe HytaleAdminAPI-Referenz für Anfrage-/Antwort-Details jedes Endpunkts.

Inventardaten

Bei Online-Spielern kommt das Inventar live von der API (GET /api/players/{name}/inventory), Änderungen gehen über POST /api/players/{name}/inventory/slot, /slot/remove, /slot/swap und /clear. Bei Offline-Spielern liest und schreibt das Plugin die Speicherdatei universe/players/{uuid}.json direkt über Pelicans Datei-Schnittstelle.

Die Speicherdateien werden als Objekte gelesen (json_decode($content, false)), nicht als Arrays. Hytale unterscheidet zwischen {} und [], ein Umwandeln in Arrays würde leere Objekte beim Zurückschreiben zu Listen machen und die Datei beschädigen.

Spielernamen (UUID-Auflösung)

Hytale speichert Spieler, Sperren und Rechte mit UUID. Das Panel zeigt Namen und sucht sie in known_players.json (vom Plugin gepflegt, neue Spieler kommen beim Öffnen von Dashboard oder Spielerseite dazu) und in whitelist.json. Ohne Treffer steht die UUID da.

Zwischenspeicher

Die Seiten fragen Daten bei jeder Aktualisierung frisch ab (Intervalle stehen bei den einzelnen Seiten). Zwischengespeichert wird nur wenig:

Demo-Modus-Architektur

Der Demo-Modus springt nie von selbst an, auch nicht bei einem Offline-Server. Er gilt, wenn

• auf der Einrichtungsseite Demo-Modus einschalten gedrückt wurde (Berechtigung hytale-admin.setup, toggleDemoMode()), dann legt DemoInventoryService für diesen Server Testdaten an und der Modus bleibt bis zum Ausschalten aktiv, oder
• eine Seite mit ?demo=1 aufgerufen wird, dann nur für diesen Aufruf.

Im Demo-Modus liefern DemoDataService und DemoInventoryService alle Daten, Aktionen zeigen nur eine Meldung („Diese Aktion wurde simuliert“) und senden nichts an den Server. Oben auf jeder Seite steht ein Hinweisbalken.

Ist der Server dagegen nur nicht erreichbar, zeigt das Dashboard API offline und die Seiten bleiben leer oder zeigen ihren Hinweis.

API-Client-Fehlertabelle

Vollständige Fehlerreferenz (Alle Funktionen)

Verbindung

Spieler

Chat

Welt

Backups

Serverkonfiguration

API-Antwortcode-Referenz

Der Java-Mod antwortet mit diesen Statuscodes:

Das Panel wertet jede Antwort außer 2xx als Fehler, die Seite zeigt dann ihre Fehlermeldung.

Meldungen

Die Erfolgs- und Fehlermeldungen jeder Aktion stehen mit ihrem genauen Wortlaut in den Abschnitten der einzelnen Seiten (Spieler, Moderation, Chat, Backups, Mods, Serverkonfiguration, Einrichtung).