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
- 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].namedansmodule.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].entryest absent. - Pour commencer, nous recommandons de copier
__example/__example__module.tomlversmodule.tomlet__example/__example__lifecycle.pyverslifecycle.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,versionetentrysont obligatoires.log_patternextrait le niveau de log d'une ligne de console via un groupe(?P<level>…). Les clés de[module.dependencies]sontsaba-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]:supportedaccepte"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éclarerrcon_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_modedé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,stoppar 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. Avecmethod = "console"(+console_template), la commande va à la console (stdin) ; avec"rest", à l'API REST du jeu ; et avec"module"(défaut), àcommand()danslifecycle.py.risk(safe/caution/danger) etdescriptionsont 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), ethook = truelorsque 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, consultezdocs/module-spec.mddans le dépôtsaba-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 avecconfig_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 renvoyezextra_args_placed: true. Sinon, le démon les ajoute à la fin deargs. preview: truesignifie 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.
| Fonction | Quand le démon l'appelle | Valeur renvoyée |
|---|---|---|
validate | Vérification avant démarrage | success, issues[] (le serveur ne démarre pas si l'une d'elles a severity: "critical") |
stop | Arrêt des serveurs sans console et des serveurs non gérés | success |
status | Consultation de l'état d'un serveur non géré | status, pid |
command | Commandes avec method = "module" | success, message |
get_credentials | Quand des informations de connexion REST sont nécessaires | rest_username, rest_password |
configure / read_properties / reset_properties / reset_server | Enregistrement / lecture / réinitialisation de l'écran des paramètres | success (+ valeurs lues) |
import_settings | Import d'un serveur existant, lecture des paramètres | settings{} |
list_versions / get_version_details | Liste des versions / détails | Informations de version |
install_server | Installation et mise à jour | success, executable_path, install_path |
get_installed_version | Consultation de la version installée | version |
accept_agreements | Après l'acceptation des [[agreements]] par l'utilisateur | success |
diagnose_log | Diagnostic des logs | success |
backup_paths | Sauvegardes (lorsque [backup] hook = true) | success, paths[] |
instance_commands | Liste des commandes (lorsque [commands] hook = true) | success, commands[] |
Règles communes :
- Chaque réponse inclut
success: booletmessage: str. Si une action de l'utilisateur est nécessaire, incluezaction_required: "<code>". - S'il manque une extension requise, répondez avec
error_code: "extension_required"etmissing_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. Lestop()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'aupidtransmis 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é :
- Il lance
python lifecycle.py <nom de fonction>, avec l'environnement Python géré par le démon. - Variables d'environnement injectées :
PYTHONIOENCODING=utf-8,PYTHONUNBUFFERED=1PYTHONPATH: le dossier des modules contenant les fichiers partagés (i18n.py,daemon_rcon.py) et le parent du dossier des extensionsSABA_IPC_URL,SABA_IPC_PORT: adresse de l'API du démonSABA_TOKEN_PATH: chemin du fichier contenant le jeton de l'API du démonSABA_LANG: langue de la GUISABA_ENABLED_EXTENSIONS: id des extensions activées, séparés par des virgules (p. ex.steamcmd,ue4-ini)
- Il écrit un objet JSON de config sur stdin et le ferme.
- 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.
- 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. - 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. - Le processus se termine après chaque appel. La limite de temps par défaut est de 120 secondes ; seul
install_serverpendant 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_PATHet ne peut écrire que dans les dossiers d'instance, de travail et d'installation, et dans les dossiers dedata_roots. Il ne peut pas non plus utilisermsiexecni les dossiers que créetempfile.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 :
| Fonction | Rô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_kill | Vé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
| Module | Port par défaut | Protocole | Extensions requises | Remarques |
|---|---|---|---|---|
minecraft | 25565 | stdin (console) | Aucune | Installation download, détection/téléchargement automatique de Java, RCON forcé à désactivé |
palworld | 8211 | API REST | steamcmd, ue4-ini | Jeu sans console. credential_map associe rest_password ↔ AdminPassword |
zomboid | 16261 | stdin (console) | steamcmd | stop_command = "quit", [backup] hook = true |
terraria | 7777 | stdin (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.
- 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.
- Tout échec se traduit par du JSON + code de sortie 0. Répondez avec
success: falseet une raison. - 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.
- 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"danssupported. - Ne manipulez les processus que par le
pidfourni par le démon. Tuer par nom d'exécutable arrête aussi les autres instances du même jeu. - Construisez les chemins avec
os.path.join; ne les codez pas en dur. - 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 dansconfigureet dansimport_settings. - 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 auPYTHONPATHpour quedaemon_rconsoit trouvé.echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command - Vérifiez
module.tomlavec 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ôtsaba-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 avecPOST /api/modules/refresh.