Erweiterungs-Entwicklungsleitfaden

Die 10 tatsächlichen Hooks von Saba-chan, die manifest.json-Spezifikation, die GUI-Slot-Injektion und Implementierungshinweise aus den mitgelieferten Erweiterungen.

Erweiterungs-Entwicklungsleitfaden

Eine Erweiterung (Plugin) ist ein Zusatz, der nicht an ein bestimmtes Spiel gebunden ist, sondern sich global in den Lebenszyklus des Daemons einklinkt, oder Komponenten in die GUI einfügt. Der Saba-chan-Daemon übergibt die Kontrolle an den folgenden 10 Punkten (Hooks) an aktivierte Erweiterungen. Die derzeit mitgelieferten Erweiterungen sind SteamCMD-Installation/-Update (steamcmd) und der UE4-INI-Parser (ue4-ini).

Der Inhalt dieses Dokuments basiert auf den tatsächlichen manifest.json-Dateien im Repository saba-chan-extensions und dem Erweiterungssystem auf Daemon-Seite (src/extension/mod.rs).


1. Dateistruktur

%APPDATA%\saba-chan\extensions\<extension_id>\
  • manifest.jsonerforderlich. Deklariert Hooks, Abhängigkeiten, Feldererforderlich. Deklariert Hooks, Abhängigkeiten, Felder
  • __init__.pyermöglicht Modulen den Import als extensions.<name>ermöglicht Modulen den Import als extensions.<name>
  • <python_modules>.pyDateien, auf die python_modules in manifest.json verweistDateien, auf die python_modules in manifest.json verweist
  • icon.pngoptionaloptional
  • gui/optional. Quellcode und Build-Ausgabe des GUI-Bundles (UMD)optional. Quellcode und Build-Ausgabe des GUI-Bundles (UMD)
  • i18n/optional. Festgelegt mit i18n_dir im Manifest (<locale>.json)optional. Festgelegt mit i18n_dir im Manifest (<locale>.json)
  • test_<name>.pyempfohlen. pytest-Testsempfohlen. pytest-Tests
  • Der Ordnername muss der id im Manifest entsprechen. Die ID mit Unterstrichen statt Bindestrichen wird ebenfalls akzeptiert (z. B. ID ue4-ini → Ordner ue4_ini). Andernfalls lädt der Daemon sie nicht und führt sie in GET /api/extensions unter failed auf.
  • Eine ID darf nur Buchstaben, Ziffern, - und _ enthalten.

2. Spezifikation von manifest.json

Das tatsächliche Manifest der SteamCMD-Erweiterung:

{
  "schema_version": 1,                    // bei 1 sind unbekannte Schlüssel und nie ausgelöste Hooks Fehler
  "id": "steamcmd",                       // entspricht dem Ordnernamen
  "name": "SteamCMD",
  "version": "0.1.0",
  "description": "Installs and updates game servers with SteamCMD",
  "descriptions": { "ko": "SteamCMD를 사용한 게임 서버 설치 및 업데이트 자동화" },
  "author": "WareAoba",
  "min_app_version": "0.1.0",
  "dependencies": [],                     // Abhängigkeiten von anderen Erweiterungen (Array oder { "id": ">=x.y.z" })

  "python_modules": {
    "steamcmd": "steamcmd.py"             // logischer Name → Dateipfad
  },

  "hooks": {
    "server.check_update": {
      "module": "steamcmd",
      "function": "check_update",
      "condition": "instance.ext_data.install_method_steamcmd"
    }
  },

  "instance_fields": {
    "install_method_steamcmd": { "type": "boolean", "default": false },
    "steamcmd_app_id": { "type": "number", "optional": true },
    "steamcmd_anonymous": { "type": "boolean", "default": true },
    "steamcmd_beta": { "type": "string", "optional": true },
    "steamcmd_platform": { "type": "string", "optional": true }
  },
  "permissions": { "network": true, "spawn_process": true }
}

Übersicht der Felder:

  • schema_version: Bei 1 sind unbekannte Schlüssel, Hook-Namen, die nicht in FIRED_HOOKS stehen, und Verweise auf fehlende python_modules Fehler. Ohne das Feld (0) sind es nur Warnungen.
  • id, name, version: Erforderlich. version wird für Update- und Abhängigkeitsvergleiche verwendet.
  • description / descriptions: Englische Beschreibung und Beschreibungen pro Sprache. Die Listen-API wählt die passende zur GUI-Sprache.
  • min_app_version: Auf einem älteren Saba-chan lässt sich die Erweiterung weder aktivieren noch installieren.
  • dependencies: Abhängigkeiten von anderen Erweiterungen (oder von saba-core). Nur Versionsanforderungen mit >= werden unterstützt. Beim Aktivieren wird geprüft, ob die Abhängigkeiten aktiviert sind; sie werden nicht automatisch aktiviert.
  • python_modules: Registriert die Python-Dateien, auf die Hooks und Befehle verweisen, unter logischen Namen. Dateien, die hier nicht registriert sind, können von Hooks nicht aufgerufen werden.
  • hooks.<Hook-Name>
    • module: ein in python_modules deklarierter logischer Name
    • function: der Funktionsname in dieser Datei
    • condition (optional): nur die Form instance.ext_data.<key> wird unterstützt. Der Hook läuft nur für Instanzen, bei denen dieser Wert true, eine von null verschiedene Zahl oder eine nicht leere Zeichenkette ist.
  • instance_fields: Werte pro Instanz, die diese Erweiterung verwendet (extension_data). Hat irgendeine Instanz einen Wert gesetzt, wird das Deaktivieren oder Entfernen der Erweiterung abgelehnt (in_use).
  • config_fields: Globale Einstellungsfelder der Erweiterung. Die Werte werden in extensions.settings.<id> in config.json gespeichert.
  • gui: bundle (Pfad zum UMD-Bundle), styles (CSS-Pfad). Siehe Abschnitt 5 unten.
  • cli: CLI-Slot-Deklarationen (cli.slots).
  • commands: Befehle, die der Befehlsliste der Instanz hinzugefügt werden (name, label, risk, inputs, module, function, condition).
  • priority: Reihenfolge, wenn mehrere Erweiterungen denselben Hook haben (niedriger läuft zuerst, Standard 100).
  • i18n_dir: Ordner für Übersetzungsdateien.
  • permissions: Deklariert die riskanten Fähigkeiten, die der Code nutzt (dieselbe Tabelle wie [permissions] eines Moduls).

Hooks haben kein async-Feld, und das Manifest hat keine manifest_url. Die Erweiterungsliste und Updates kommen ausschließlich aus dem signierten Release-Manifest von Saba-chan.


3. Die 10 tatsächlichen Hooks

Hook-Funktionen laufen genauso wie Module. Der Daemon startet python <file>.py <Funktionsname>, schreibt das Kontext-JSON nach stdin und liest das JSON auf stdout (vollständig oder letzte Zeile) als Ergebnis. Der Exit-Code muss 0 sein. Die folgende Liste entspricht FIRED_HOOKS im Daemon-Code.

Hook-NameWann er aufgerufen wirdWie das Ergebnis verwendet wirdAusführung
daemon.startupDirekt nach dem Daemon-Start / direkt nach dem Aktivieren einer Erweiterung (nur diese Erweiterung)success/message gehen in den Init-Status (/api/extensions/init-status)Hintergrund
daemon.shutdownDirekt vor dem Herunterfahren des DaemonsNur protokolliertSynchron
server.pre_startDirekt vor dem Start eines Servershandled: true ersetzt den Standardstart (ist success dann nicht true, schlägt der Start fehl)Synchron
server.stopDirekt vor dem Stoppen eines Servershandled: true übernimmt das StoppenSynchron
server.statusBei der Statusabfrage eines einzelnen Servershandled: true gibt dieses Ergebnis unverändert zurückSynchron
server.list_enrichBeim Auflisten von Instanzenhandled: true füllt status und extension_status. 10 s Timeout, 30 s TTL-CacheSynchron
server.post_createDirekt nach dem Erstellen einer InstanzErgebnis wird nicht verwendetHintergrund
server.pre_deleteDirekt vor dem Löschen einer InstanzBei handled wird kurz gewartet, damit Dateisperren freigegeben werdenSynchron
server.settings_changedNach dem Speichern von InstanzeinstellungenErgebnis wird nicht verwendetSynchron
server.check_updateWenn eine Update-Prüfung angefordert wirdDas erste erfolgreiche Ergebnis wird zur AntwortSynchron

Namen wie server.pre_create, server.pre_install, server.post_install, server.post_start, module.parse_settings und module.write_settings gibt es nicht; ihre Verwendung in einem Manifest mit schema_version = 1 lässt das Laden fehlschlagen.

3.1 Kontext und Einstiegspunkt

Eine Hook-Funktion nimmt ein Kontext-Dictionary entgegen und gibt ein Dictionary zurück. Je nach Hook enthält der Kontext instance_id, instance_name, module, instance_dir, extension_data usw., und jeder Hook erhält außerdem die globalen Einstellungen der Erweiterungen als extension_config. Die Python-Datei muss Funktionsname und stdin in __main__ selbst verarbeiten. Ein gekürztes Beispiel für den Aufbau von steamcmd.py:

import json, sys, traceback

def check_update(ctx: dict) -> dict:
    """
    ctx-Beispiel (server.check_update):
      {
        "instance_id": "…",
        "instance_name": "My Palworld",
        "module": "palworld",
        "instance_dir": "…",
        "install_dir": "…",
        "app_id": 2394010,
        "extension_data": {"install_method_steamcmd": true, ...},
        "extension_config": {...}
      }
    """
    ...
    return {"success": True, "update_available": False}

FUNCTIONS = {"check_update": check_update}

if __name__ == "__main__":
    name = sys.argv[1] if len(sys.argv) > 1 else ""
    try:
        raw = sys.stdin.read()
        ctx = json.loads(raw) if raw.strip() else {}
        result = FUNCTIONS[name](ctx) if name in FUNCTIONS else \
            {"success": False, "message": f"Unknown function: {name}"}
    except Exception as e:
        traceback.print_exc(file=sys.stderr)      # Protokolle gehen nach stderr
        result = {"success": False, "message": str(e)}
    print(json.dumps(result, ensure_ascii=False))  # auch Fehler sind JSON + Exit-Code 0

3.2 handled und Ausführungsreihenfolge

  • Erweiterungen mit demselben Hook laufen nacheinander, sortiert nach priority, dann nach ID.
  • Enthält ein Ergebnis handled: true, werden die übrigen Erweiterungen übersprungen. Lassen Sie handled weg, sofern Sie nicht das Standardverhalten dieses Hooks ersetzen.
  • Schlägt eine Erweiterung fehl, wird der Fehler protokolliert und die nächste Erweiterung ausgeführt.
  • Das Standard-Zeitlimit beträgt 120 Sekunden. Auf dem Hook-Pfad gibt es keine Fortschrittsanzeige (PROGRESS:).

3.3 TTL-Cache für server.list_enrich

Dieser Hook kann bei jeder Anforderung der Instanzliste nacheinander für jede Instanz mit extension_data aufgerufen werden; der Daemon speichert erfolgreiche Ergebnisse daher 30 Sekunden zwischen. Solange der Cache gültig ist, verwendet er das vorherige Ergebnis erneut, ohne einen Python-Prozess zu starten. Jeder Aufruf hat ein Timeout von 10 Sekunden; gestalten Sie ihn also so, dass er schnell fertig wird. Die status_line des Ergebnisses ist ein kurzer einzeiliger Status für die Discord-Statusanzeige; schreiben Sie daher keine Pfade oder Geheimnisse hinein.


4. Die 3 mitgelieferten Erweiterungen

steamcmd

  • id: steamcmd
  • Python: steamcmd.py (Klasse SteamCMD: portable SteamCMD-Installation, Installation/Update von Spieleservern, Update-Prüfung)
  • Hook: nur server.check_update (condition: instance.ext_data.install_method_steamcmd).
  • Die eigentliche Installation erledigt das install_server des Moduls direkt über from extensions.steamcmd import SteamCMD.
  • instance_fields: install_method_steamcmd, steamcmd_app_id, steamcmd_anonymous, steamcmd_beta, steamcmd_platform. Der Daemon füllt sie nach einer allgemeinen Regel (install_method_<method>, <method>_<field>) aus dem Abschnitt [install] des Moduls.
  • Keine GUI.

ue4-ini

  • id: ue4-ini (Ordnername ue4_ini)
  • Python: ue4_ini.py (parse_option_settings, write_option_settings)
  • Zweck: stellt Modulen Hilfsmittel zum Lesen und Schreiben von OptionSettings=(...) in den INI-Dateien von UE4-Spielen wie Palworld bereit.
  • Es ist eine reine Bibliothek, die keine Hooks deklariert; Module importieren sie als extensions.ue4_ini.

xna

  • id: xna
  • Python: xna.py (install, present, XnaError)
  • Zweck: legt die feste Version Microsoft XNA Framework 4.0 Refresh neben den Spieleserver-Ordner, ohne sie auf dem PC zu installieren. Der Windows-Server von Terraria nutzt sie. Das offizielle MSI wird einmal heruntergeladen, mit einer festen SHA-256 geprüft, und es werden nur die nötigen Dateien extrahiert.
  • Es ist eine reine Bibliothek, die keine Hooks deklariert; Module nutzen sie mit from extensions.xna import install, present.

Module können deaktivierte Erweiterungen nicht importieren. Der Import-Wächter des Daemons blockiert den Import jeder extensions.<name>, die nicht in SABA_ENABLED_EXTENSIONS steht.


5. GUI-Bundle (Slot-Injektion)

Deklariert manifest.json ein gui.bundle, ruft die GUI diese Datei über GET /api/extensions/:id/gui ab und führt sie aus (und injiziert außerdem das CSS, falls gui.styles gesetzt ist).

"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" }   // Beispielpfade
  • Das Bundle liegt im UMD-Format vor und muss die globale Variable window.SabaExt<PascalCase-ID> anlegen. Entfernen Sie - und _ aus der ID und schreiben Sie den folgenden Buchstaben groß (z. B. steamcmd → window.SabaExtSteamcmd, ue4-ini → window.SabaExtUe4Ini).
  • Gibt registerSlots() dieser globalen Variable { slotId: Component | Component[] } zurück, hängt die GUI sie in die entsprechenden Slots ein.
  • React wird als External aus window.React des Hosts referenziert. Komponenten müssen allein mit den Props funktionieren, die der Slot übergibt.
  • Übersetzungen werden über GET /api/extensions/:id/i18n/:locale in den Namespace ext_<id> geladen.
Slot-IDOrtprops
ServerCard.badgeBadge der Serverkarteserver
ServerCard.headerGaugeAnzeige im Kopf der Serverkarteserver
ServerCard.provisionServerkarte während des Provisioningsserver, provisionProgress, onDismiss, t
ServerCard.expandedStatsStatistiken der aufgeklappten Serverkarteserver, t
ServerSettings.tabTab der Servereinstellungenserver, activeTab, setActiveTab, settings, onSettingsChange, t
AddServer.optionsOptionen beim Hinzufügen eines Serverst

server sind die Serverinformationen aus /api/servers; Komponenten können extension_data und extension_status[<extension_id>] (das Ergebnis von server.list_enrich) lesen.


6. Erweiterungen über die REST-API verwalten

GET    /api/extensions                   Installierte Liste (+ Ladefehler)
GET    /api/extensions/init-status       daemon.startup-Ergebnisse
POST   /api/extensions/rescan            Ordner neu einlesen
GET    /api/extensions/manifest          Entfernter Katalog (signiertes Release-Manifest)
GET    /api/extensions/updates           Update-Liste
POST   /api/extensions/:id/install       Installieren (aus dem Katalog, sha256-geprüft)
POST   /api/extensions/:id/enable        Aktivieren → führt daemon.startup dieser Erweiterung aus
POST   /api/extensions/:id/disable       Deaktivieren
POST   /api/extensions/:id/mount         Im Speicher registrieren
POST   /api/extensions/:id/unmount       Aus dem Speicher abmelden
DELETE /api/extensions/:id               Entfernen
GET    /api/extensions/:id/config        Werte der config_fields
PUT    /api/extensions/:id/config        Werte aktualisieren
GET    /api/extensions/:id/gui           GUI-Bundle (JS)
GET    /api/extensions/:id/gui/styles    GUI-Stile (CSS)
GET    /api/extensions/:id/icon          Symbol
GET    /api/extensions/:id/audit         Vom Code genutzte Fähigkeiten mit permissions vergleichen
GET    /api/extensions/:id/i18n/:locale  Sprach-JSON

Die Liste der aktivierten Erweiterungen wird in extensions.enabled in config.json gespeichert, globale Einstellungswerte in extensions.settings.


7. Entwicklungsregeln

  • Auch Erweiterungen dürfen nicht vom Daemon-Code abhängen. Verwenden Sie nur den Kontext und die Umgebungsvariablen, die der Daemon übergibt.
  • Bauen Sie Pfade mit os.path.join; kodieren Sie sie nicht fest.
  • Auch Hook-Funktionen beantworten Fehlschläge mit JSON (success: false und einem Grund) und Exit-Code 0 und senden Protokolle und Tracebacks nach stderr.
  • Verwenden Sie für condition nur die Form instance.ext_data.<key>. Jede andere Form ergibt immer false.
  • Python-Abhängigkeiten nutzen die gemeinsame Umgebung des Daemons. Es gibt keine Requirements-Deklaration pro Erweiterung.
  • Nicht verifizierte Erweiterungen: Erweiterungen, die nicht aus dem signierten Katalog heruntergeladen oder nach dem Download verändert wurden, laufen wie Module in einer isolierten Umgebung (Windows AppContainer, Linux bubblewrap). Ein Virenscan findet nicht statt. Die folgenden Angaben gelten für Windows. Sie können Loopback (etwa die Daemon-API) nicht erreichen, erhalten kein SABA_TOKEN_PATH und können Instanzordner nur lesen. Legen Sie Daten, die Sie schreiben müssen, in dem eigenen Ordner ab, auf den die Umgebungsvariable SABA_EXTENSION_DATA_DIR zeigt.
  • Führen Sie Tests mit pytest im Stammverzeichnis des Repositorys aus.