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
- 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
idim Manifest entsprechen. Die ID mit Unterstrichen statt Bindestrichen wird ebenfalls akzeptiert (z. B. IDue4-ini→ Ordnerue4_ini). Andernfalls lädt der Daemon sie nicht und führt sie inGET /api/extensionsunterfailedauf. - 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: Bei1sind unbekannte Schlüssel, Hook-Namen, die nicht inFIRED_HOOKSstehen, und Verweise auf fehlendepython_modulesFehler. Ohne das Feld (0) sind es nur Warnungen.id,name,version: Erforderlich.versionwird 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 vonsaba-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 inpython_modulesdeklarierter logischer Namefunction: der Funktionsname in dieser Dateicondition(optional): nur die Forminstance.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 inextensions.settings.<id>inconfig.jsongespeichert.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 keinemanifest_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-Name | Wann er aufgerufen wird | Wie das Ergebnis verwendet wird | Ausführung |
|---|---|---|---|
daemon.startup | Direkt 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.shutdown | Direkt vor dem Herunterfahren des Daemons | Nur protokolliert | Synchron |
server.pre_start | Direkt vor dem Start eines Servers | handled: true ersetzt den Standardstart (ist success dann nicht true, schlägt der Start fehl) | Synchron |
server.stop | Direkt vor dem Stoppen eines Servers | handled: true übernimmt das Stoppen | Synchron |
server.status | Bei der Statusabfrage eines einzelnen Servers | handled: true gibt dieses Ergebnis unverändert zurück | Synchron |
server.list_enrich | Beim Auflisten von Instanzen | handled: true füllt status und extension_status. 10 s Timeout, 30 s TTL-Cache | Synchron |
server.post_create | Direkt nach dem Erstellen einer Instanz | Ergebnis wird nicht verwendet | Hintergrund |
server.pre_delete | Direkt vor dem Löschen einer Instanz | Bei handled wird kurz gewartet, damit Dateisperren freigegeben werden | Synchron |
server.settings_changed | Nach dem Speichern von Instanzeinstellungen | Ergebnis wird nicht verwendet | Synchron |
server.check_update | Wenn eine Update-Prüfung angefordert wird | Das erste erfolgreiche Ergebnis wird zur Antwort | Synchron |
Namen wie
server.pre_create,server.pre_install,server.post_install,server.post_start,module.parse_settingsundmodule.write_settingsgibt es nicht; ihre Verwendung in einem Manifest mitschema_version = 1lä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 Siehandledweg, 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(KlasseSteamCMD: 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_serverdes Moduls direkt überfrom 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(Ordnernameue4_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 inSABA_ENABLED_EXTENSIONSsteht.
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.Reactdes Hosts referenziert. Komponenten müssen allein mit den Props funktionieren, die der Slot übergibt. - Übersetzungen werden über
GET /api/extensions/:id/i18n/:localein den Namespaceext_<id>geladen.
| Slot-ID | Ort | props |
|---|---|---|
ServerCard.badge | Badge der Serverkarte | server |
ServerCard.headerGauge | Anzeige im Kopf der Serverkarte | server |
ServerCard.provision | Serverkarte während des Provisionings | server, provisionProgress, onDismiss, t |
ServerCard.expandedStats | Statistiken der aufgeklappten Serverkarte | server, t |
ServerSettings.tab | Tab der Servereinstellungen | server, activeTab, setActiveTab, settings, onSettingsChange, t |
AddServer.options | Optionen beim Hinzufügen eines Servers | t |
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: falseund einem Grund) und Exit-Code 0 und senden Protokolle und Tracebacks nach stderr. - Verwenden Sie für
conditionnur die Forminstance.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_PATHund können Instanzordner nur lesen. Legen Sie Daten, die Sie schreiben müssen, in dem eigenen Ordner ab, auf den die UmgebungsvariableSABA_EXTENSION_DATA_DIRzeigt. - Führen Sie Tests mit
pytestim Stammverzeichnis des Repositorys aus.