Berechtigungen

Berechtigungen

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

Berechtigungsreferenz

Das Plugin definiert 16 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 kommuniziert mit dem Hytale-Server-Mod über eine HytaleApiService-Klasse, die alle HTTP-Aufrufe kapselt. Jede Funktion (Dashboard, Spieler, Chat, etc.) nutzt diesen Service.

Client-Konfigurationsparameter

// Wie der API-Service aufgebaut wird — aus Server-Zuweisung + Egg-Variablen
$allocation = $server->allocation;
$host = $allocation->ip;  // Server-IP aus Zuweisung
$port = $server->egg_variable('HYTALE_API_PORT') ?? 8080;
$token = $server->egg_variable('HYTALE_API_TOKEN');

$service = new HytaleApiService($host, $port, $token);

// Basis-Anfragemethode — alle API-Aufrufe gehen hierüber
protected function request(string $method, string $endpoint, array $data = []): array
{
    $response = Http::timeout($this->timeout)
        ->withToken($this->token)  // Bearer-Token
        ->withHeaders([
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
        ])
        ->{$method}("{$this->baseUrl}/{$endpoint}", $data);

    if ($response->failed()) {
        throw new HytaleApiException(
            "API {$method} /{$endpoint} fehlgeschlagen: HTTP {$response->status()}",
            $response->status()
        );
    }

    return $response->json();
}

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.

BSON Item-Datenverarbeitung

Hytale verwendet BSON (Binary JSON) für die Item-Serialisierung. Das Panel muss die Kodierung/Dekodierung für Inventar-Operationen handhaben.

// Item-Datenstruktur — wie von der API zurückgegeben
$item = [
    'id'       => 'hytale:wooden_sword',     // Namespaced Item-ID
    'count'    => 1,                          // Stapelanzahl
    'slot'     => 3,                          // Inventar-Slot-Index
    'nbt'      => [                           // BSON-kodierte Eigenschaften
        'damage'     => 15,
        'enchants'   => [
            ['id' => 'sharpness', 'level' => 3],
        ],
        'customName' => '§6Legendäre Klinge',  // Farbkodierter Anzeigename
    ],
];

// Item an Spieler geben — erstellt BSON-Payload
$this->request('POST', "items/give", [
    'uuid'     => $playerUuid,
    'item_id'  => $itemId,       // z.B. 'hytale:iron_ore'
    'count'    => $count,
    'nbt_data' => $nbtData,      // Optionale BSON-Eigenschaften
]);
// Läuft auf Server-Hauptthread, Item erscheint sofort im Spielerinventar

Spielerdaten-Zusammenführung (UUID-Auflösung)

Das Plugin behandelt UUID-zu-Name-Auflösung mit Zusammenführungslogik für Spieler, die ihre Namen ändern.

// UUID-Auflösung — der Mod verfolgt Spieler per UUID, Panel zeigt Namen
$players = $this->request('GET', 'players');

// Jeder Spieler hat sowohl UUID als auch aktuellen Namen
// Das Panel cached UUID→Name-Zuordnungen
// Wenn ein Spieler sich umbenennt, wird der alte Name beim nächsten Login ersetzt
foreach ($players as $player) {
    // $player['uuid']     => "550e8400-e29b-41d4-a716-446655440000"
    // $player['name']     => "Steve"
    // $player['position'] => { "x": 100.5, "y": 64.0, "z": -200.3 }
    // $player['gameMode'] => "SURVIVAL"
    // $player['health']   => 20.0
    // $player['food']     => 18
}

Caching-Strategie

// Cache-Beispiel — Status mit 5-Sekunden-TTL
$status = Cache::remember("hytale_status_{$serverId}", 5, function () {
    return $this->apiService->getStatus();
});

Demo-Modus-Architektur

Wenn der Server offline ist, wechselt das Plugin in den Demo-Modus — es zeigt Platzhalter-Daten, damit Admins die UI ohne laufenden Server erkunden können.

// Demo-Modus-Erkennung — aktiviert sich automatisch bei unerreichbarer API
try {
    $status = $this->apiService->getStatus();
    $demoMode = false;
} catch (HytaleApiException $e) {
    $demoMode = true;
    $status = $this->getDemoStatus();  // Gibt fest kodierte Mockdaten zurück
}

// Demo-Daten umfassen:
// - 0 TPS, 0 Spieler, alle Funktionen zeigen Platzhalter-Daten
// - UI ist voll interaktiv, aber Änderungen werden nicht an den Server gesendet
// - Gelbes Banner zeigt „Demo-Modus — Server ist offline"

API-Client-Fehlertabelle

Vollständige Fehlerreferenz (Alle Funktionen)

Verbindungsfehler

Authentifizierungs- / Token-Fehler

Spielerverwaltungs-Fehler

Chat-System-Fehler

Welt-Verwaltungs-Fehler

Backup-System-Fehler

Serverkonfigurationsfehler

API-Antwortcode-Referenz

Vollständige Benachrichtigungs-Referenz