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

%APPDATA%\saba-chan\modules\<module_name>\
  • 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].name in module.toml, in englischen Kleinbuchstaben.
  • Der Daemon liest nur Ordner der ersten Ebene unterhalb des Modulstamms, die eine module.toml enthalten, und lädt kein Modul, dessen [module].entry-Datei fehlt.
  • Für den Einstieg empfehlen wir, __example/__example__module.toml nach module.toml und __example/__example__lifecycle.py nach lifecycle.py zu 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, version und entry sind erforderlich. log_pattern extrahiert die Protokollstufe einer Konsolenzeile über eine Gruppe (?P<level>…). Schlüssel in [module.dependencies] sind saba-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]: supported akzeptiert "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ßerdem rcon_port angeben, 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_mode bestimmt, 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, Standard stop), 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, group usw.). Vom Benutzer geänderte Werte werden als Instanzeinstellungen gespeichert und kommen bei jedem Funktionsaufruf in der config an.
  • [[commands.fields]]: Spielbefehle. Mit method = "console" (+ console_template) geht der Befehl an die Konsole (stdin), mit "rest" an die REST-API des Spiels und mit "module" (Standard) an command() in lifecycle.py. risk (safe/caution/danger) und description werden 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), und hook = 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 in docs/module-spec.md im Repository saba-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 mit config_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 geben extra_args_placed: true zurück. Andernfalls hängt der Daemon sie an das Ende von args an.
  • preview: true bedeutet 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.

FunktionWann der Daemon sie aufruftRückgabe
validatePrüfung vor dem Startsuccess, issues[] (der Server startet nicht, wenn ein Eintrag severity: "critical" hat)
stopStoppen von Servern ohne Konsole und von nicht verwalteten Servernsuccess
statusStatusabfrage bei nicht verwalteten Servernstatus, pid
commandBefehle mit method = "module"success, message
get_credentialsWenn REST-Verbindungsdaten benötigt werdenrest_username, rest_password
configure / read_properties / reset_properties / reset_serverEinstellungsbildschirm speichern / lesen / zurücksetzensuccess (+ gelesene Werte)
import_settingsImport eines vorhandenen Servers, Einstellungen lesensettings{}
list_versions / get_version_detailsVersionsliste / DetailsVersionsinformationen
install_serverInstallation und Updatesuccess, executable_path, install_path
get_installed_versionAbfrage der installierten Versionversion
accept_agreementsNachdem der Benutzer [[agreements]] zugestimmt hatsuccess
diagnose_logProtokollanalysesuccess
backup_pathsBackups (wenn [backup] hook = true)success, paths[]
instance_commandsBefehlsliste (wenn [commands] hook = true)success, commands[]

Allgemeine Regeln:

  • Jede Antwort enthält success: bool und message: str. Ist eine Aktion des Benutzers nötig, fügen Sie action_required: "<code>" hinzu.
  • Fehlt eine benötigte Erweiterung, antworten Sie mit error_code: "extension_required" und missing_extensions: [...].
  • Auf einen unbekannten Funktionsnamen antworten Sie mit {"success": false, "message": "Unknown function: X"} (das übernimmt run_lifecycle()).

Einen verwalteten Server mit Konsole stoppt der Daemon, indem er [config].stop_command an die Konsole (stdin) sendet und wartet. Das stop() 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 übergebene pid anfassen.


4. Unterprozess-Protokoll

Wie der Daemon Modulfunktionen aufruft, ist in src/plugin/mod.rs im Saba-chan-Repository implementiert. Zusammengefasst:

  1. Er startet python lifecycle.py <Funktionsname> mit der vom Daemon verwalteten Python-Umgebung.
  2. Injizierte Umgebungsvariablen:
    • PYTHONIOENCODING=utf-8, PYTHONUNBUFFERED=1
    • PYTHONPATH: der Modulordner mit den gemeinsamen Dateien (i18n.py, daemon_rcon.py) und das übergeordnete Verzeichnis des Erweiterungsordners
    • SABA_IPC_URL, SABA_IPC_PORT: Adresse der Daemon-API
    • SABA_TOKEN_PATH: Pfad der Datei mit dem Daemon-API-Token
    • SABA_LANG: GUI-Sprache
    • SABA_ENABLED_EXTENSIONS: kommagetrennte IDs der aktivierten Erweiterungen (z. B. steamcmd,ue4-ini)
  3. Er schreibt ein config-JSON-Objekt nach stdin und schließt es.
  4. Er parst die gesamte stdout-Ausgabe als JSON; schlägt das fehl, verwendet er die letzte nicht leere Zeile als Ergebnis.
  5. stderr ist das Protokoll. Zeilen, die mit PROGRESS: beginnen, werden als Fortschrittsereignisse geparst und für die Anzeige des Installationsfortschritts verwendet.
  6. Der Exit-Code muss 0 sein. Andernfalls behandelt der Daemon den Aufruf als allgemeinen Fehler, selbst wenn stdout success: false enthält.
  7. Der Prozess beendet sich nach jedem Aufruf. Das Standard-Zeitlimit beträgt 120 Sekunden; nur install_server beim 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_PATH und darf nur in den Instanz-, Arbeits- und Installationsordner sowie in die Ordner aus data_roots schreiben. Auch msiexec und Ordner, die tempfile.mkdtemp anlegt, 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:

FunktionZweck
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_killPrü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

ModulStandardportProtokollBenötigte ErweiterungenHinweise
minecraft25565stdin (Konsole)Keinedownload-Installation, Java-Erkennung/-Download, RCON zwangsweise aus
palworld8211REST-APIsteamcmd, ue4-iniSpiel ohne Konsole. credential_map ordnet rest_password ↔ AdminPassword zu
zomboid16261stdin (Konsole)steamcmdstop_command = "quit", [backup] hook = true
terraria7777stdin (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.

  1. Keine Abhängigkeit vom Daemon-Code. Verwenden Sie nur die config, die Umgebungsvariablen und die APIs, die der Daemon bereitstellt.
  2. Jeder Fehlschlag ist JSON + Exit-Code 0. Antworten Sie mit success: false und einem Grund.
  3. Protokolle gehen nach stderr. stdout ist für das Ergebnis-JSON. Geben Sie auch Exception-Tracebacks nach stderr aus; verschlucken Sie keine Fehler.
  4. 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 in supported ein.
  5. 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.
  6. Bauen Sie Pfade mit os.path.join; kodieren Sie sie nicht fest.
  7. Prüfen Sie die Zuordnung der Feldnamen. Kontrollieren Sie in configure und in import_settings, auf welchen Spieleinstellungsschlüssel jeder [[settings.fields]]-Name abgebildet wird.
  8. Tests. Halten Sie Unit-Tests in test_lifecycle.py vor 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 zu PYTHONPATH hinzu, damit daemon_rcon gefunden wird.
    echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command
    
  • Prüfen Sie module.toml mit 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 Repository saba-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 Sie module.toml geändert, lassen Sie ihn daher mit POST /api/modules/refresh neu laden.