Modul-Entwicklungsleitfaden
So erstellen Sie ein Python-Modul, das Saba-chan um ein neues Spiel erweitert. Behandelt das module.toml-Schema sowie den tatsächlichen Funktionsvertrag und das Protokoll von lifecycle.py.
Modul-Entwicklungsleitfaden (Python)
Der Saba-chan-Daemon kennt keine spielspezifischen Details. Stattdessen wird jedes Spiel durch ein Python-Modul beschrieben. Mit einem zusätzlichen Modul kann Saba-chan ein neues Spiel verwalten.
Dieses Dokument basiert auf den echten Modulen im Repository saba-chan-modules (minecraft, palworld, zomboid), der kommentierten Vorlage __example und dem Daemon-Code.
1. Dateistruktur eines Moduls
- module.tomlerforderlich. Deklarationen (Schema v1)erforderlich. Deklarationen (Schema v1)
- lifecycle.pyerforderlich. Einstiegsdatei, benannt durch [module].entryerforderlich. Einstiegsdatei, benannt durch [module].entry
- icon.pngoptional. Festgelegt mit [module].iconoptional. Festgelegt mit [module].icon
- locales/
- en.jsonReferenzspracheReferenzsprache
- ko.json
- ...UI-TexteUI-Texte
- test_lifecycle.pyoptional. pytest-Unit-Tests (empfohlen)optional. pytest-Unit-Tests (empfohlen)
- Benennen Sie den Ordner genauso wie
[module].nameinmodule.toml, in englischen Kleinbuchstaben. - Der Daemon liest nur Ordner der ersten Ebene unterhalb des Modulstamms, die eine
module.tomlenthalten, und lädt kein Modul, dessen[module].entry-Datei fehlt. - Für den Einstieg empfehlen wir,
__example/__example__module.tomlnachmodule.tomlund__example/__example__lifecycle.pynachlifecycle.pyzu kopieren und dann zu löschen, was Sie nicht brauchen.
2. Spezifikation von module.toml
Ein gekürztes Beispiel vom Anfang der echten minecraft/module.toml:
[module]
schema_version = 1 # erforderlich. Unbekannte Schlüssel oder ungültige Werte lassen das Laden fehlschlagen
name = "minecraft" # identisch mit dem Ordnernamen
version = "0.1.0"
display_name = "Minecraft"
game_name = "Minecraft"
entry = "lifecycle.py" # Python-Datei, die der Daemon ausführt
icon = "icon.png"
log_pattern = '^\[\d{2}:\d{2}:\d{2}(?:\] \[[^\]]*/| )(?P<level>INFO|WARN|ERROR|DEBUG|FATAL)\]'
[module.dependencies]
saba-core = ">=0.1.5" # Komponente → Mindestversion (nur ">=")
[permissions]
network = true # Fähigkeiten, die der Code nutzt
spawn_process = true
[protocols]
supported = ["stdin"] # aus "stdin" / "rest"
default = "stdin"
interaction_mode = "console" # "console" oder "commands"
[config]
server_executable = "server.jar"
process_name = "java.exe"
default_port = 25565
announce_command = "say" # [[commands.fields]]-Name für Ankündigungen
# stop_command ist "stop", wenn er weggelassen wird
[backup]
paths = ["{level_name}", "{level_name}_nether", "{level_name}_the_end"]
save_command = "save-all"
[install]
method = "download" # "manual" (Standard) / "download" / eine Erweiterungs-ID (z. B. "steamcmd")
[detection]
dir_signatures = ["server.jar"]
graceful_exit_patterns = ["Stopping the server"]
crash_artifacts = ["crash-reports/*.txt", "hs_err_pid*.log"]
Was die einzelnen Abschnitte bedeuten:
[module]: Metadaten.name,versionundentrysind erforderlich.log_patternextrahiert die Protokollstufe einer Konsolenzeile über eine Gruppe(?P<level>…). Schlüssel in[module.dependencies]sindsaba-core,ext-<Erweiterungs-ID>usw.[permissions]: Deklariert die riskanten Fähigkeiten, die der Code nutzt (network,spawn_process,native_code,dynamic_code,env_secrets,fs_outside_instance).[protocols]:supportedakzeptiert"stdin","rest"und"rcon". Die Reihenfolge der Befehlswege ist stdin, dann REST, dann RCON. RCON ist nur für ein Spiel ohne Konsole und ohne REST-API bestimmt. Ein solches Spiel muss außerdemrcon_portangeben, und der Daemon legt dann für jede Instanz einen Port und ein zufälliges Passwort fest. Hat das Spiel eine Konsole oder REST, schaltet das Modul die RCON-Einstellung aus.interaction_modebestimmt, ob eine Konsolenansicht (console) oder nur Befehlsschaltflächen (commands) angezeigt werden.[config]:server_executable,executable_path,process_name,default_port,stop_command(an die Konsole gesendeter Stoppbefehl, Standardstop),stop_timeout(Sekunden, Standard 30),announce_command. Spieleinstellungen gehören in[[settings.fields]], nicht hierher.[[settings.fields]]: Einträge im Einstellungsbildschirm der Instanz (name,type,label,default,options,groupusw.). Vom Benutzer geänderte Werte werden als Instanzeinstellungen gespeichert und kommen bei jedem Funktionsaufruf in der config an.[[commands.fields]]: Spielbefehle. Mitmethod = "console"(+console_template) geht der Befehl an die Konsole (stdin), mit"rest"an die REST-API des Spiels und mit"module"(Standard) ancommand()inlifecycle.py.risk(safe/caution/danger) unddescriptionwerden von der KI-Befehlsinterpretation gelesen.[install]: Installationsmethode,app_id,requires_extensions(Liste der benötigten Erweiterungs-IDs) usw. Palworld benötigt["steamcmd", "ue4-ini"].[detection]: Erkennen vorhandener Serverordner (dir_signatures), Finden von Prozessen (process_patterns,cmd_patterns) und Absturzerkennung (graceful_exit_patterns,crash_artifacts). Nur als Absturz eingestufte Beendigungen werden automatisch neu gestartet.[backup]: Pfade, die in Backups aufgenommen werden (paths), der Befehl, der unmittelbar vor einem Backup ausgeführt wird (save_command), undhook = true, wenn die Pfade im Code berechnet werden.[credential_map]: Ordnet Standardschlüssel des Daemons Schlüsseln der Spieleinstellungen zu. Palworld-Beispiel:rest_password = "AdminPassword".- Außerdem gibt es
[launch],[[agreements]],[[presets]],[[queries]],[aliases],[errors],[[syntax_highlight.rules]]und[extensions.<id>]. Die vollständige Schlüsselliste finden Sie indocs/module-spec.mdim Repositorysaba-chan-modules.
3. Funktionsvertrag von lifecycle.py
Wann immer er sie braucht, startet der Daemon einen neuen Python-Prozess, um eine Funktion in dieser Datei aufzurufen. Jede Funktion nimmt ein einzelnes config: dict entgegen, gibt ein dict zurück und muss in der Tabelle FUNCTIONS am Ende der Datei registriert sein. Module haben keine start-Funktion: Der Daemon startet den Server selbst anhand des Ergebnisses von get_launch_command.
3.1 Erforderliche Funktionen
Die einzige erforderliche Funktion ist get_launch_command.
import os
from daemon_rcon import config_value, run_lifecycle
def get_launch_command(config: dict) -> dict:
"""Gibt zurück, wie der Server gestartet wird. Den Prozess startet der Daemon."""
exe = config.get("server_executable", "")
if not exe or not os.path.exists(exe):
return {"success": False, "message": f"Server executable not found: {exe}"}
port = config_value(config, "port", 7777)
return {
"success": True,
"program": exe,
"args": [f"-port={port}"],
"working_dir": config.get("working_dir") or os.path.dirname(exe),
"env_vars": {},
}
FUNCTIONS = {"get_launch_command": get_launch_command}
if __name__ == "__main__":
run_lifecycle(FUNCTIONS)
- Der Daemon breitet die Instanzeinstellungen (
module_settings) auf der obersten Ebene der config aus. Sie mitconfig_value(config, key, default)zu lesen ist der sichere Weg. - Enthält die config
extra_args(vom Benutzer hinzugefügte Startargumente), platzieren Sie sie an der passenden Stelle und gebenextra_args_placed: truezurück. Andernfalls hängt der Daemon sie an das Ende vonargsan. preview: truebedeutet eine Vorschau der Startargumente. Schreiben Sie dann keine Einstellungsdateien; geben Sie nur die Startinformationen zurück.
3.2 Optionale Funktionen
Implementieren Sie nur die Funktionen, die Sie unterstützen, und tragen Sie jede implementierte Funktion unbedingt in die Tabelle FUNCTIONS ein.
| Funktion | Wann der Daemon sie aufruft | Rückgabe |
|---|---|---|
validate | Prüfung vor dem Start | success, issues[] (der Server startet nicht, wenn ein Eintrag severity: "critical" hat) |
stop | Stoppen von Servern ohne Konsole und von nicht verwalteten Servern | success |
status | Statusabfrage bei nicht verwalteten Servern | status, pid |
command | Befehle mit method = "module" | success, message |
get_credentials | Wenn REST-Verbindungsdaten benötigt werden | rest_username, rest_password |
configure / read_properties / reset_properties / reset_server | Einstellungsbildschirm speichern / lesen / zurücksetzen | success (+ gelesene Werte) |
import_settings | Import eines vorhandenen Servers, Einstellungen lesen | settings{} |
list_versions / get_version_details | Versionsliste / Details | Versionsinformationen |
install_server | Installation und Update | success, executable_path, install_path |
get_installed_version | Abfrage der installierten Version | version |
accept_agreements | Nachdem der Benutzer [[agreements]] zugestimmt hat | success |
diagnose_log | Protokollanalyse | success |
backup_paths | Backups (wenn [backup] hook = true) | success, paths[] |
instance_commands | Befehlsliste (wenn [commands] hook = true) | success, commands[] |
Allgemeine Regeln:
- Jede Antwort enthält
success: boolundmessage: str. Ist eine Aktion des Benutzers nötig, fügen Sieaction_required: "<code>"hinzu. - Fehlt eine benötigte Erweiterung, antworten Sie mit
error_code: "extension_required"undmissing_extensions: [...]. - Auf einen unbekannten Funktionsnamen antworten Sie mit
{"success": false, "message": "Unknown function: X"}(das übernimmtrun_lifecycle()).
Einen verwalteten Server mit Konsole stoppt der Daemon, indem er
[config].stop_commandan die Konsole (stdin) sendet und wartet. Dasstop()des Moduls wird nur aufgerufen, wenn es keine Konsole gibt; es muss der Reihenfolge ordnungsgemäße Stoppanforderung → Warten → Zwangsbeendigung folgen und darf nur die vom Daemon übergebenepidanfassen.
4. Unterprozess-Protokoll
Wie der Daemon Modulfunktionen aufruft, ist in src/plugin/mod.rs im Saba-chan-Repository implementiert. Zusammengefasst:
- Er startet
python lifecycle.py <Funktionsname>mit der vom Daemon verwalteten Python-Umgebung. - Injizierte Umgebungsvariablen:
PYTHONIOENCODING=utf-8,PYTHONUNBUFFERED=1PYTHONPATH: der Modulordner mit den gemeinsamen Dateien (i18n.py,daemon_rcon.py) und das übergeordnete Verzeichnis des ErweiterungsordnersSABA_IPC_URL,SABA_IPC_PORT: Adresse der Daemon-APISABA_TOKEN_PATH: Pfad der Datei mit dem Daemon-API-TokenSABA_LANG: GUI-SpracheSABA_ENABLED_EXTENSIONS: kommagetrennte IDs der aktivierten Erweiterungen (z. B.steamcmd,ue4-ini)
- Er schreibt ein config-JSON-Objekt nach stdin und schließt es.
- Er parst die gesamte stdout-Ausgabe als JSON; schlägt das fehl, verwendet er die letzte nicht leere Zeile als Ergebnis.
- stderr ist das Protokoll. Zeilen, die mit
PROGRESS:beginnen, werden als Fortschrittsereignisse geparst und für die Anzeige des Installationsfortschritts verwendet. - Der Exit-Code muss 0 sein. Andernfalls behandelt der Daemon den Aufruf als allgemeinen Fehler, selbst wenn stdout
success: falseenthält. - Der Prozess beendet sich nach jedem Aufruf. Das Standard-Zeitlimit beträgt 120 Sekunden; nur
install_serverbeim Provisioning und bei Updates erhält mehr Zeit (1800 Sekunden).
Nicht verifizierte Module: Ein Modul, das nicht aus dem signierten Saba-chan-Katalog stammt oder nach dem Download geändert wurde, läuft unter Windows in einem AppContainer, unter Linux in bubblewrap. Saba-chan prüft es nicht mit einem Virenscanner. In Umgebungen, die sich nicht isolieren lassen (Linux ohne oder mit nicht nutzbarem bubblewrap, macOS), führt Saba-chan es nur aus, nachdem Sie den aktuellen Dateien zugestimmt haben. In der Isolation kann das Modul keine Loopback-Verbindung öffnen (nutzen Sie die gemeinsamen Hilfsfunktionen, der Daemon leitet die Anfrage weiter), erhält kein
SABA_TOKEN_PATHund darf nur in den Instanz-, Arbeits- und Installationsordner sowie in die Ordner ausdata_rootsschreiben. Auchmsiexecund Ordner, dietempfile.mkdtempanlegt, sind nicht nutzbar. Die vollständige Liste steht unter Ein Modul bauen: von der Recherche bis zur Veröffentlichung.
4.1 Beispiel für Fortschrittsmeldungen
# Innerhalb von install_server
import json, sys
def report(step, total, percent, msg):
sys.stderr.write("PROGRESS:" + json.dumps({
"step": step, "total": total, "percent": percent, "message": msg
}) + "\n")
sys.stderr.flush()
report(1, 3, 10, "Starting download")
# … eigentlicher Download …
report(2, 3, 70, "Extracting")
# …
report(3, 3, 100, "Install complete")
Erkannte Felder sind percent, message, step, total und label.
5. Gemeinsame Hilfsmittel
Der Daemon legt die gemeinsamen Dateien i18n.py und daemon_rcon.py im Modulordner ab und fügt diesen zu PYTHONPATH hinzu. Kopieren Sie sie nicht in Ihren Modulordner.
import os
from i18n import I18n
from daemon_rcon import daemon_stdin_command, wait_for_exit, force_kill
MODULE_DIR = os.path.dirname(os.path.abspath(__file__))
i18n = I18n(MODULE_DIR) # MODULE_DIR/locales/<SABA_LANG>.json
msg = i18n.t("errors.failed_to_stop", error="…") # ersetzt {{error}} im Text
daemon_stdin_command(config["instance_id"], "save-all") # eine Zeile an die Serverkonsole senden
daemon_rcon.py trägt seinen Namen nur aus historischen Gründen; es öffnet nie einen RCON-Socket. Wichtigste Hilfsfunktionen:
| Funktion | Zweck |
|---|---|
daemon_stdin_command(instance_id, line) | Einen Befehl an die Konsole eines vom Daemon verwalteten Servers senden |
daemon_post(path, payload) | Andere Daemon-APIs aufrufen (Token wird automatisch hinzugefügt) |
is_process_alive, wait_for_exit, force_kill | Prüfen / Warten / Zwangsbeenden pro PID |
config_value(config, key, default) | Einen Einstellungswert in der config finden |
run_lifecycle(FUNCTIONS) | Einstiegspunkt für python lifecycle.py <function> |
Aktivierte Erweiterungen können importiert werden, z. B. from extensions.steamcmd import SteamCMD oder import extensions.ue4_ini. Deaktivierte Erweiterungen werden von einem Import-Wächter blockiert (ModuleNotFoundError); importieren Sie daher innerhalb der Funktion und antworten Sie bei einem Fehlschlag mit extension_required.
6. Referenz: Mitgelieferte Module
| Modul | Standardport | Protokoll | Benötigte Erweiterungen | Hinweise |
|---|---|---|---|---|
minecraft | 25565 | stdin (Konsole) | Keine | download-Installation, Java-Erkennung/-Download, RCON zwangsweise aus |
palworld | 8211 | REST-API | steamcmd, ue4-ini | Spiel ohne Konsole. credential_map ordnet rest_password ↔ AdminPassword zu |
zomboid | 16261 | stdin (Konsole) | steamcmd | stop_command = "quit", [backup] hook = true |
terraria | 7777 | stdin (Pseudokonsole pty) | xna (Windows) | download-Installation, Windows- und Linux-Server, [backup] hook = true |
Alle sind um module.toml und lifecycle.py herum aufgebaut. Für ein neues Modul empfehlen wir, mit __example oder dem ähnlichsten dieser vier zu beginnen.
7. Entwicklungsregeln (verbindlich)
Modul-PRs müssen diese Regeln einhalten.
- Keine Abhängigkeit vom Daemon-Code. Verwenden Sie nur die config, die Umgebungsvariablen und die APIs, die der Daemon bereitstellt.
- Jeder Fehlschlag ist JSON + Exit-Code 0. Antworten Sie mit
success: falseund einem Grund. - Protokolle gehen nach stderr. stdout ist für das Ergebnis-JSON. Geben Sie auch Exception-Tracebacks nach stderr aus; verschlucken Sie keine Fehler.
- Nutzen Sie zuerst stdin, dann REST. RCON nur für ein Spiel, das keines von beiden hat. Hat das Spiel eine Konsole oder REST, schalten Sie die RCON-Einstellung aus und tragen Sie
"rcon"nicht insupportedein. - Behandeln Sie Prozesse nur über die
pid, die Ihnen der Daemon übergibt. Ein Beenden über den Namen der ausführbaren Datei beendet auch andere Instanzen desselben Spiels. - Bauen Sie Pfade mit
os.path.join; kodieren Sie sie nicht fest. - Prüfen Sie die Zuordnung der Feldnamen. Kontrollieren Sie in
configureund inimport_settings, auf welchen Spieleinstellungsschlüssel jeder[[settings.fields]]-Name abgebildet wird. - Tests. Halten Sie Unit-Tests in
test_lifecycle.pyvor und bestehen Sie das Konformitäts-Kit (Abschnitt 8 unten).
8. Tipps zur Fehlersuche
- Das Ergebnis wird aus der letzten Zeile von stdout gelesen; senden Sie Debug-Ausgaben daher nach stderr. Jede Ausgabe nach dem Ergebnis-JSON macht das Parsen kaputt.
- Sie können eine Funktion ohne den Daemon direkt ausführen. Fügen Sie das Verzeichnis
modules/des Saba-chan-Repositorys zuPYTHONPATHhinzu, damitdaemon_rcongefunden wird.echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command - Prüfen Sie
module.tomlmit demselben Parser, den der Daemon verwendet:saba-core module validate <Modulordner> - Konformitäts-Kit:
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules(im Repositorysaba-chan-modules) - Erscheint der Fortschritt nicht in der GUI, prüfen Sie, dass die stderr-Zeile exakt mit
PROGRESS:beginnt und das JSON danach gültig ist. - Übernehmen Sie Änderungen an einem Modul auch unter
modules\<name>\im Datenordner, damit der Daemon den neuesten Code verwendet. Der Daemon speichert die Modulliste zwischen; haben Siemodule.tomlgeändert, lassen Sie ihn daher mitPOST /api/modules/refreshneu laden.