Admin-Panel

hz_lib bringt ein zentrales Admin-Panel mit, in das sich jedes HZ-Script-Modul einklinkt. Statt dass jedes Script einen eigenen Befehl und eine eigene Oberfläche für die Konfiguration mitbringt, liegt alles hinter einem einzigen /hzpanel, das Admins öffnen können. Das Panel baut automatisch einen typisierten Editor für jedes Konfigurationsfeld, das im bridge_schema.lua eines Moduls deklariert ist.

Panel öffnen

Im Spiel (Chat, F8-Konsole oder Tastenkürzel):

/hzpanel

• Nur Konsole (Server-F8): /hzpanel aus der Serverkonsole öffnet die NUI nicht. Geben Sie es im Spiel ein.
• Erfordert die ACE-Berechtigung aus HZBridge.Panel.AcePermission (Standard admin). Siehe Berechtigungen einrichten weiter unten.
• Mit Escape oder dem Schließen-Button verlassen Sie das Panel. Sitzungen sind per Token geschützt und laufen nach HZBridge.Panel.SessionTokenTtlMs ohne Aktivität ab (Standard 5 Min.): Öffnen Sie das Panel erneut, um sie zu erneuern.

-- server export — opens the panel for `src` and preselects the named module
exports['hz_lib']:OpenPanel(src, 'hz_weather')

Berechtigungen einrichten

Das Panel ist durch den kanonischen FXServer-ACE-Knoten admin geschützt. Zwei Zeilen in der server.cfg sind nötig:

add_principal identifier.license:YOUR_LICENSE group.admin
add_ace group.admin admin allow

Ersetzen Sie YOUR_LICENSE durch die Spielerlizenz auf Ihrem Server (Sie sehen sie, wenn Sie einmal /hzpanel eingeben: Die Konsolenausgabe des Fehlschlags zeigt alle Ihre Kennungen und einen fertigen Block zum Kopieren, in dem Ihre Lizenz schon eingesetzt ist).

Sie können beide Zeilen direkt in die Serverkonsole einfügen, um das sofort zu beheben, ohne Neustart. Wenn Sie sie in die server.cfg schreiben, starten Sie FXServer neu (oder führen Sie exec server.cfg erneut aus), damit sie geladen werden.

Ein Spieler mit dem ACE command (darf jeden Befehl ausführen) kann das Panel ebenfalls öffnen. Beim ersten Start werden die Admin-Gruppen des Frameworks (admin, god, superadmin, owner auf ESX, QBCore, QBox oder Ox Core) als Staff-Rollen mit vollem Zugriff auf die Module angelegt: Admins, die Ihr Framework verwaltet, können das Panel also auch ohne ACE-Einrichtung öffnen. ACE bleibt trotzdem der empfohlene Weg, weil es vom Framework unabhängig ist und sich an einer Stelle prüfen lässt.

Schlägt die Prüfung fehl, zeigt die Serverkonsole:

• Den genauen geprüften ACE-Knoten
• Alle Ihre Spielerkennungen
• Eine ACE-Prüfmatrix (welche Knoten gewährt sind und welche nicht)
• Die zwei genauen Zeilen add_principal + add_ace zum Kopieren, mit bereits eingesetzter Lizenz

Eigener ACE-Knoten

Wenn Sie den kanonischen Knoten admin nicht nutzen möchten (zum Beispiel, weil nur ein Teil des Staffs das Panel öffnen soll, ohne alle anderen Admin-Befehle zu bekommen), legen Sie in config.lua einen eigenen Knoten fest:

HZBridge.Panel.AcePermission = 'hzbridge.panel.admin'

Dann in der server.cfg:

add_principal identifier.license:YOUR_LICENSE group.hzbridge.staff
add_ace group.hzbridge.staff hzbridge.panel.admin allow

Der Ersatzwert (wenn AcePermission nil oder '' ist) lautet 'admin', seit v1.1.1 passend zum Standard der Konfiguration. Ältere Versionen nutzten 'hz_lib.admin' als Ersatzwert und sperrten damit Kunden aus, die nur das kanonische ACE admin hatten. Aktualisieren Sie mindestens auf v1.1.1, wenn Sie betroffen sind.

Staff-Rollen

Der Zugriff ist nicht alles oder nichts: Jede Staff-Rolle erhält pro Modul eines oder mehrere dieser drei Rechte.

• Bearbeiten Sie die Rollen unter /hzpanel > Access control. Nur eine Rolle, die Zugriffe bearbeiten darf, sieht diesen Tab, und nur eine ACE-Gruppe kann dieses Recht erhalten.
• Beim ersten Start erhält die Gruppe hinter AcePermission (standardmäßig group.admin) vollen Zugriff und das Recht, Zugriffe zu bearbeiten: Die Installation von hz_lib sperrt also niemanden aus.
• Ein Spieler, dessen Gruppen zu keiner Rolle passen, behält vollen Zugriff, wenn er AcePermission oder command hat. Ein Spieler, der zu einer Rolle passt, behält die Grenzen dieser Rolle.
• Die Rechte werden bei jeder Aktion neu geprüft: Ein herabgestufter Admin verliert den Zugriff auch in einem bereits geöffneten Panel.
• Ausgesperrt? Führen Sie hzaccess_recover <gruppe> in der Serverkonsole aus (zum Beispiel hzaccess_recover admin).

Was Sie bearbeiten können

Das Panel erkennt automatisch jede Ressource, die eine Datei bridge_schema.lua in ihrem Stammverzeichnis mitbringt. Mit hz_lib v1.2.0 liefern diese HZ-Ressourcen ein Schema und haben einen eigenen Tab:

Ein im Panel gespeicherter Wert hat Vorrang vor der Config-Datei des Scripts. Ein Punkt markiert jede im Panel geänderte Einstellung, und ihre Zurücksetzen-Schaltfläche entfernt den Panel-Wert: Die Einstellung folgt wieder der Config-Datei des Scripts (hz_lib 1.2.1 und neuer). Bis hz_lib 1.2.0 speicherte die Zurücksetzen-Schaltfläche stattdessen den eigenen Standardwert des Panels.

Die Schema-DSL

Das bridge_schema.lua jedes Moduls ist eine kleine Lua-DSL, die die Konfiguration deklariert, die das Panel anzeigt. Die DSL läuft in einer abgeschotteten Umgebung (kein _G, kein direktes io, eingeschränkte Teilmengen von string / table / math), daher kann ein fehlerhaftes oder bösartiges Schema den Server nicht beschädigen.

Minimales Beispiel

-- resources/your-script/bridge_schema.lua
module('your-script', {
    schemaVersion = 1,
    label = { en = 'Your Script', fr = 'Ton script' },
}, function()
    section('general', {
        label = { en = 'General', fr = 'Général' },
    }, function()
        field('Enabled', 'boolean', {
            default = true,
            label = { en = 'Enabled', fr = 'Activé' },
            description = {
                en = 'Master on/off switch for the script.',
                fr = 'Interrupteur global du script.',
            },
        })

        field('PlayerLimit', 'number', {
            default = 32, min = 1, max = 256, step = 1,
            label = { en = 'Max concurrent players', fr = 'Joueurs simultanés max' },
        })
    end)
end)

Das ist alles: Öffnen Sie /hzpanel, der Tab "Your Script" erscheint mit zwei typisierten Feldern, und Änderungen werden auf die Festplatte geschrieben und an jeden abonnierten Client gesendet.

Feldtypen

Abschnitte, Gruppen, Tabs

• section(id, { label, tab, dependsOn }, body): visuelle Gruppierung im Tab eines Moduls. tab ist die ID des Untertabs (deklariert über module(name, { tabs = { ... } })). dependsOn = { field = 'X', equals = true } klappt den Abschnitt zu, wenn die Bedingung falsch ist.
• group(id, { label }, body): einklappbare Gruppe innerhalb eines Abschnitts.
• field(id, type, opts): ein einzelnes Feld. opts unterstützt default, description, requiresRestart, serverOnly, deprecated, hidden, dependsOn sowie die typspezifischen Extras. serverOnly = true behält den Wert auf dem Server (er wird nie an Spieler gesendet): für Geheimnisse wie Webhook-URLs.
• invariant(sectionId, fn): feldübergreifende Prüfung. Läuft bei jedem Speicherversuch. Gibt nil (ok) oder einen Text (Fehlermeldung) zurück.
• migrations({ [N] = function(values) ... end }): Erhöhen Sie schemaVersion und liefern Sie eine Migration, die alte gespeicherte Werte umschreibt.

Eigene Ansichten

Manche HZ-Scripts brauchen mehr als ein Formular: einen Karteneditor, ein Vorhersagediagramm, einen Ladebildschirm-Editor. Sie deklarieren ein Feld view mit einer Liste events der Server-Events, die die Ansicht auslösen darf. Die React-Komponente selbst ist im Panel von hz_lib integriert, dessen Quellcode nicht mitgeliefert wird: Ein Schema von Drittanbietern nutzt die Feldtypen oben.

HZ-Weather liefert sechs Ansichten mit: Map, ZoneEditor, Events, Forecast, SeasonsPanel, TimePanel.

Theme-Kaskade (Appearance)

Der Tab Appearance in hz_lib bündelt die visuellen Werte, die sich alle HZ-NUIs teilen. Eine einzige Änderung färbt HZ-Weather, HZ-AudioMixer und HZ-Television live um, ohne Neustart. Neue Scripts übernehmen die Kaskade automatisch, solange ihre NUI die kanonischen CSS-Variablen --hz-* liest.

Was Sie steuern

Position der Missionsziele

Derselbe Tab platziert die Missionsziele, die HZ-Jobs und -Missionen anzeigen (siehe Missionsziele):

So nutzen die Module das Theme

Der vollständige Inhalt wird bei jedem Speichern durch einen Admin gesendet:

-- server (any resource)
AddEventHandler('HZ-Bridge:theme:updated', function(theme)
    -- theme: { preset, accent, accentHi, gold, surface, subpanel, tint,
    --         gradientMode, radiusNone, radiusXs, radiusSm, ..., radiusXl,
    --         fontDisplay, fontBody, fontNumber,
    --         fonts = { display, body, number, href } }
end)

-- client
RegisterNetEvent('HZ-Bridge:theme:updated', function(theme)
    SendNUIMessage({ action = 'theme', data = theme })
end)

fonts enthält fertige CSS-Schriftstapel und die URL eines Google-Fonts-Stylesheets (href). Schreiben Sie in Ihrer NUI jeden Schlüssel als CSS-Variable auf :root (zum Beispiel --hz-accent-rgb, --hz-surface-rgb, --hz-radius-md). Die Komponenten verwenden die Variablen über rgb(var(--hz-accent-rgb) / 0.45) / var(--hz-radius-md), sodass die Kaskade automatisch greift.

Das aktuelle Theme beim Start synchron abrufen (Server):

local theme = exports['hz_lib']:GetTheme()

Oder per TriggerServerEvent('HZ-Bridge:theme:request') anfordern: Der Server antwortet mit TriggerClientEvent('HZ-Bridge:theme:updated', src, theme).

Sicherheit + Audit

• Abgeschottete Schemas: Die DSL läuft ohne direktes io, os oder debug und mit eingeschränkter Standardbibliothek. Ein fehlerhaftes bridge_schema.lua kann beim Laden scheitern (wird geloggt), aber den Server nicht abstürzen lassen.
• Begrenzte Schreibvorgänge: standardmäßig 10 Schreibvorgänge pro 5 s pro Quelle. Einstellbar über HZBridge.Panel.RateLimitWrites / RateLimitWindowMs.
• Sitzungstokens: Jedes Öffnen des Panels erzeugt ein Token, das nach 5 Minuten ohne Aktivität abläuft; abgelaufene Tokens erhalten bei der nächsten Anfrage einen neuen Start.
• Validierung: Jedes Speichern durchläuft die Prüfung des Feldtyps, die optionalen Prüfungen pattern / min / max und dann die invariant-Funktionen des Abschnitts, bevor der Wert auf der Festplatte landet.
• Audit-Log: Jedes akzeptierte Speichern schreibt eine Zeile in data/_audit.log. Ab 10 MB wird die Datei in data/_audit.<datum>.<zeit>.log umbenannt und eine neue begonnen. hz_lib löscht diese Dateien nie (HZBridge.Panel.AuditRetentionDays wird in v1.2.0 nicht angewendet): Löschen Sie alte Dateien selbst, wenn Sie eine Aufbewahrungsfrist brauchen.
• Atomare Schreibvorgänge: Die gespeicherte Konfiguration jedes Moduls wird über eine temporäre Datei nach data/<module>.json geschrieben. Felder mit requiresRestart werden zusätzlich in data/<module>.pending.json vorgemerkt und beim Neustart der Ressource angewendet.
• Rechte bei jeder Aktion geprüft, nicht nur beim Öffnen des Panels. Ein Admin, dem die Rechte entzogen werden, kann in einem offenen Panel nicht weiter bearbeiten.

Referenz

• Quellcode der Schema-DSL: modules/panel/schema_dsl.lua in Ihrem hz_lib-Ordner (offen, nicht verschlüsselt)
• Gespeicherte Konfiguration pro Modul: data/<module>.json, dazu data/<module>.pending.json für Änderungen, die auf einen Neustart warten
• Staff-Rollen: data/_access.json
• Audit: data/_audit.log