Guide de développement de modules

Comment créer un module Python qui ajoute un nouveau jeu à Saba-chan. Couvre le schéma de module.toml ainsi que le contrat de fonctions et le protocole réels de lifecycle.py.

Guide de développement de modules (Python)

Le démon Saba-chan ne connaît pas les détails propres à chaque jeu. Chaque jeu est plutôt décrit par un module Python. Ajouter un module permet à Saba-chan de gérer un nouveau jeu.

Ce document s'appuie sur les vrais modules du dépôt saba-chan-modules (minecraft, palworld, zomboid), sur le modèle annoté __example et sur le code du démon.


1. Structure des fichiers d'un module

%APPDATA%\saba-chan\modules\<module_name>\
  • module.tomlobligatoire. Déclarations (schéma v1)obligatoire. Déclarations (schéma v1)
  • lifecycle.pyobligatoire. Fichier d'entrée désigné par [module].entryobligatoire. Fichier d'entrée désigné par [module].entry
  • icon.pngfacultatif. Défini avec [module].iconfacultatif. Défini avec [module].icon
  • locales/
  • en.jsonlangue de référencelangue de référence
  • ko.json
  • ...chaînes de l'interfacechaînes de l'interface
  • test_lifecycle.pyfacultatif. Tests unitaires pytest (recommandé)facultatif. Tests unitaires pytest (recommandé)
  • Donnez au dossier le même nom que [module].name dans module.toml, en anglais et en minuscules.
  • Le démon ne lit que les dossiers de premier niveau sous la racine des modules qui contiennent un module.toml, et il ne charge pas un module dont le fichier [module].entry est absent.
  • Pour commencer, nous recommandons de copier __example/__example__module.toml vers module.toml et __example/__example__lifecycle.py vers lifecycle.py, puis de supprimer ce dont vous n'avez pas besoin.

2. Spécification de module.toml

Un exemple résumé tiré du début du vrai minecraft/module.toml :

[module]
schema_version = 1                # obligatoire. Une clé inconnue ou une valeur invalide fait échouer le chargement
name = "minecraft"                # identique au nom du dossier
version = "0.1.0"
display_name = "Minecraft"
game_name = "Minecraft"
entry = "lifecycle.py"            # fichier Python exécuté par le démon
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"             # composant → version minimale (">=" uniquement)

[permissions]
network = true                    # capacités utilisées par le code
spawn_process = true

[protocols]
supported = ["stdin"]             # parmi "stdin" / "rest"
default = "stdin"
interaction_mode = "console"      # "console" ou "commands"

[config]
server_executable = "server.jar"
process_name = "java.exe"
default_port = 25565
announce_command = "say"          # nom [[commands.fields]] utilisé pour les annonces
# stop_command vaut "stop" par défaut s'il est omis

[backup]
paths = ["{level_name}", "{level_name}_nether", "{level_name}_the_end"]
save_command = "save-all"

[install]
method = "download"               # "manual" (défaut) / "download" / un id d'extension (p. ex. "steamcmd")

[detection]
dir_signatures = ["server.jar"]
graceful_exit_patterns = ["Stopping the server"]
crash_artifacts = ["crash-reports/*.txt", "hs_err_pid*.log"]

Signification de chaque section :

  • [module] : Métadonnées. name, version et entry sont obligatoires. log_pattern extrait le niveau de log d'une ligne de console via un groupe (?P<level>…). Les clés de [module.dependencies] sont saba-core, ext-<id d'extension>, etc.
  • [permissions] : Déclare les capacités à risque utilisées par le code (network, spawn_process, native_code, dynamic_code, env_secrets, fs_outside_instance).
  • [protocols] : supported accepte "stdin", "rest" et "rcon". L'ordre des chemins de commande est stdin, puis REST, puis RCON. Utilisez RCON uniquement pour un jeu sans console et sans API REST. Ce jeu doit aussi déclarer rcon_port, et le daemon attribue alors un port et un mot de passe aléatoire à chaque instance. Si le jeu a une console ou REST, le module désactive son réglage RCON. interaction_mode décide s'il faut afficher une vue console (console) ou seulement des boutons de commande (commands).
  • [config] : server_executable, executable_path, process_name, default_port, stop_command (commande d'arrêt envoyée à la console, stop par défaut), stop_timeout (secondes, 30 par défaut), announce_command. Les paramètres de jeu vont dans [[settings.fields]], pas ici.
  • [[settings.fields]] : Éléments de l'écran des paramètres de l'instance (name, type, label, default, options, group, etc.). Les valeurs modifiées par l'utilisateur sont stockées comme paramètres de l'instance et arrivent dans la config de chaque appel de fonction.
  • [[commands.fields]] : Commandes de jeu. Avec method = "console" (+ console_template), la commande va à la console (stdin) ; avec "rest", à l'API REST du jeu ; et avec "module" (défaut), à command() dans lifecycle.py. risk (safe/caution/danger) et description sont lus par l'interprétation des commandes par IA.
  • [install] : Méthode d'installation, app_id, requires_extensions (liste des id d'extensions requises), etc. Palworld requiert ["steamcmd", "ue4-ini"].
  • [detection] : Reconnaissance des dossiers de serveur existants (dir_signatures), recherche des processus (process_patterns, cmd_patterns) et détection des crashs (graceful_exit_patterns, crash_artifacts). Seuls les arrêts jugés comme des crashs sont redémarrés automatiquement.
  • [backup] : Chemins à inclure dans les sauvegardes (paths), commande à exécuter juste avant une sauvegarde (save_command), et hook = true lorsque les chemins sont calculés dans le code.
  • [credential_map] : Associe les clés standard du démon aux clés de paramètres du jeu. Exemple Palworld : rest_password = "AdminPassword".
  • Il existe aussi [launch], [[agreements]], [[presets]], [[queries]], [aliases], [errors], [[syntax_highlight.rules]] et [extensions.<id>]. Pour la liste complète des clés, consultez docs/module-spec.md dans le dépôt saba-chan-modules.

3. Contrat de fonctions de lifecycle.py

Chaque fois qu'il en a besoin, le démon lance un nouveau processus Python pour appeler une fonction de ce fichier. Chaque fonction prend un unique config: dict et renvoie un dict, et doit être enregistrée dans la table FUNCTIONS à la fin du fichier. Les modules n'ont pas de fonction start : le démon lance lui-même le serveur à partir du résultat de get_launch_command.

3.1 Fonctions obligatoires

La seule fonction obligatoire est get_launch_command.

import os
from daemon_rcon import config_value, run_lifecycle

def get_launch_command(config: dict) -> dict:
    """Return how to launch the server. The daemon spawns the process."""
    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)
  • Le démon étale les paramètres de l'instance (module_settings) au premier niveau de config. Les lire avec config_value(config, key, default) est la méthode sûre.
  • Si config contient extra_args (arguments de lancement ajoutés par l'utilisateur), placez-les là où ils doivent aller et renvoyez extra_args_placed: true. Sinon, le démon les ajoute à la fin de args.
  • preview: true signifie un aperçu des arguments de lancement. N'écrivez pas de fichiers de paramètres ; renvoyez seulement les informations de lancement.

3.2 Fonctions facultatives

N'implémentez que les fonctionnalités que vous prenez en charge, et si vous en implémentez une, ajoutez-la toujours à la table FUNCTIONS.

FonctionQuand le démon l'appelleValeur renvoyée
validateVérification avant démarragesuccess, issues[] (le serveur ne démarre pas si l'une d'elles a severity: "critical")
stopArrêt des serveurs sans console et des serveurs non géréssuccess
statusConsultation de l'état d'un serveur non géréstatus, pid
commandCommandes avec method = "module"success, message
get_credentialsQuand des informations de connexion REST sont nécessairesrest_username, rest_password
configure / read_properties / reset_properties / reset_serverEnregistrement / lecture / réinitialisation de l'écran des paramètressuccess (+ valeurs lues)
import_settingsImport d'un serveur existant, lecture des paramètressettings{}
list_versions / get_version_detailsListe des versions / détailsInformations de version
install_serverInstallation et mise à joursuccess, executable_path, install_path
get_installed_versionConsultation de la version installéeversion
accept_agreementsAprès l'acceptation des [[agreements]] par l'utilisateursuccess
diagnose_logDiagnostic des logssuccess
backup_pathsSauvegardes (lorsque [backup] hook = true)success, paths[]
instance_commandsListe des commandes (lorsque [commands] hook = true)success, commands[]

Règles communes :

  • Chaque réponse inclut success: bool et message: str. Si une action de l'utilisateur est nécessaire, incluez action_required: "<code>".
  • S'il manque une extension requise, répondez avec error_code: "extension_required" et missing_extensions: [...].
  • Pour un nom de fonction inconnu, répondez {"success": false, "message": "Unknown function: X"} (run_lifecycle() s'en charge).

Pour un serveur géré doté d'une console, le démon l'arrête en envoyant [config].stop_command à la console (stdin) et en attendant. Le stop() du module n'est appelé qu'en l'absence de console ; il doit suivre l'ordre demande d'arrêt propre → attente → arrêt forcé, et ne toucher qu'au pid transmis par le démon.


4. Protocole des sous-processus

La façon dont le démon appelle les fonctions des modules est implémentée dans src/plugin/mod.rs du dépôt Saba-chan. En résumé :

  1. Il lance python lifecycle.py <nom de fonction>, avec l'environnement Python géré par le démon.
  2. Variables d'environnement injectées :
    • PYTHONIOENCODING=utf-8, PYTHONUNBUFFERED=1
    • PYTHONPATH : le dossier des modules contenant les fichiers partagés (i18n.py, daemon_rcon.py) et le parent du dossier des extensions
    • SABA_IPC_URL, SABA_IPC_PORT : adresse de l'API du démon
    • SABA_TOKEN_PATH : chemin du fichier contenant le jeton de l'API du démon
    • SABA_LANG : langue de la GUI
    • SABA_ENABLED_EXTENSIONS : id des extensions activées, séparés par des virgules (p. ex. steamcmd,ue4-ini)
  3. Il écrit un objet JSON de config sur stdin et le ferme.
  4. Il analyse l'intégralité de stdout comme du JSON ; en cas d'échec, il utilise la dernière ligne non vide comme résultat.
  5. stderr sert de log. Les lignes commençant par PROGRESS: sont analysées comme des événements de progression et servent à afficher la progression de l'installation.
  6. Le code de sortie doit être 0. Sinon, le démon traite l'appel comme une erreur générique, même si stdout contient success: false.
  7. Le processus se termine après chaque appel. La limite de temps par défaut est de 120 secondes ; seul install_server pendant le provisionnement et les mises à jour dispose de plus de temps (1800 secondes).

Modules non vérifiés : un module qui ne vient pas du catalogue signé de Saba-chan, ou qui a changé après le téléchargement, s'exécute dans un AppContainer sous Windows, dans bubblewrap sous Linux. Saba-chan ne l'analyse pas avec un antivirus. Là où l'isolation est impossible (Linux sans bubblewrap ou avec un bubblewrap inutilisable, macOS), Saba-chan l'exécute seulement après votre accord pour ses fichiers actuels. Dans l'isolation, le module ne peut pas se connecter au loopback (utilisez les utilitaires partagés, le daemon relaie la requête), ne reçoit pas SABA_TOKEN_PATH et ne peut écrire que dans les dossiers d'instance, de travail et d'installation, et dans les dossiers de data_roots. Il ne peut pas non plus utiliser msiexec ni les dossiers que crée tempfile.mkdtemp. Voir la liste complète dans Créer un module : de la recherche à la publication.

4.1 Exemple de rapport de progression

# Dans 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")
# … téléchargement réel …
report(2, 3, 70, "Extracting")
# …
report(3, 3, 100, "Install complete")

Les champs reconnus sont percent, message, step, total et label.


5. Utilitaires partagés

Le démon place les fichiers partagés i18n.py et daemon_rcon.py dans le dossier des modules et l'ajoute au PYTHONPATH. Ne les copiez pas dans le dossier de votre module.

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="…")  # remplace {{error}} dans la chaîne

daemon_stdin_command(config["instance_id"], "save-all")  # envoie une ligne à la console du serveur

daemon_rcon.py ne garde ce nom que pour des raisons historiques ; il n'ouvre jamais de socket RCON. Principaux utilitaires :

FonctionRôle
daemon_stdin_command(instance_id, line)Envoie une commande à la console d'un serveur géré par le démon
daemon_post(path, payload)Appelle d'autres API du démon (jeton ajouté automatiquement)
is_process_alive, wait_for_exit, force_killVérification / attente / arrêt forcé par PID
config_value(config, key, default)Recherche une valeur de paramètre dans config
run_lifecycle(FUNCTIONS)Point d'entrée de python lifecycle.py <function>

Les extensions activées peuvent être importées, p. ex. from extensions.steamcmd import SteamCMD ou import extensions.ue4_ini. Les extensions désactivées sont bloquées par une garde d'import (ModuleNotFoundError) ; importez-les donc à l'intérieur de la fonction et répondez extension_required en cas d'échec.


6. Référence : modules intégrés

ModulePort par défautProtocoleExtensions requisesRemarques
minecraft25565stdin (console)AucuneInstallation download, détection/téléchargement automatique de Java, RCON forcé à désactivé
palworld8211API RESTsteamcmd, ue4-iniJeu sans console. credential_map associe rest_password ↔ AdminPassword
zomboid16261stdin (console)steamcmdstop_command = "quit", [backup] hook = true
terraria7777stdin (pseudo-console pty)xna (Windows)installation par download, serveur Windows et Linux, [backup] hook = true

Tous sont construits autour de module.toml et de lifecycle.py. Pour créer un nouveau module, nous recommandons de partir de __example ou de celui de ces quatre modules qui s'en rapproche le plus.


7. Règles de développement (obligatoires)

Les PR de modules doivent respecter ces règles.

  1. Aucune dépendance au code du démon. N'utilisez que la config, les variables d'environnement et les API fournies par le démon.
  2. Tout échec se traduit par du JSON + code de sortie 0. Répondez avec success: false et une raison.
  3. Les logs vont sur stderr. stdout est réservé au JSON de résultat. Écrivez aussi les tracebacks d'exception sur stderr ; n'avalez pas les erreurs.
  4. Utilisez d'abord stdin, puis REST. Utilisez RCON uniquement pour un jeu qui n'a ni l'un ni l'autre. Si le jeu a une console ou REST, désactivez son réglage RCON et ne mettez pas "rcon" dans supported.
  5. Ne manipulez les processus que par le pid fourni par le démon. Tuer par nom d'exécutable arrête aussi les autres instances du même jeu.
  6. Construisez les chemins avec os.path.join ; ne les codez pas en dur.
  7. Vérifiez les correspondances de noms de champs. Contrôlez à quelle clé de paramètre du jeu correspond chaque nom de [[settings.fields]], à la fois dans configure et dans import_settings.
  8. Tests. Gardez des tests unitaires dans test_lifecycle.py, et passez le kit de conformité (section 8 ci-dessous).

8. Conseils de débogage

  • Le résultat est lu sur la dernière ligne de stdout ; envoyez donc la sortie de débogage sur stderr. Afficher quoi que ce soit après le JSON de résultat casse l'analyse.
  • Vous pouvez exécuter une fonction directement, sans le démon. Ajoutez le dossier modules/ du dépôt Saba-chan au PYTHONPATH pour que daemon_rcon soit trouvé.
    echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command
    
  • Vérifiez module.toml avec le même analyseur que celui du démon : saba-core module validate <dossier du module>
  • Kit de conformité : pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules (dans le dépôt saba-chan-modules)
  • Si la progression ne s'affiche pas dans la GUI, vérifiez que la ligne stderr commence exactement par PROGRESS: et que le JSON qui suit est valide.
  • Après avoir modifié un module, appliquez aussi la modification sous modules\<name>\ dans le dossier de données pour que le démon utilise le code le plus récent. Le démon met en cache la liste des modules ; si vous avez modifié module.toml, faites-la recharger avec POST /api/modules/refresh.