Guía de desarrollo de módulos
Cómo crear un módulo Python que añade un juego nuevo a Saba-chan. Cubre el esquema de module.toml y el contrato de funciones y el protocolo reales de lifecycle.py.
Guía de desarrollo de módulos (Python)
El demonio de Saba-chan no conoce los detalles propios de cada juego. En su lugar, cada juego se describe con un módulo Python. Añadir un módulo permite a Saba-chan gestionar un juego nuevo.
Este documento se basa en los módulos reales del repositorio saba-chan-modules (minecraft, palworld, zomboid), en la plantilla comentada __example y en el código del demonio.
1. Estructura de archivos de un módulo
- module.tomlobligatorio. Declaraciones (esquema v1)obligatorio. Declaraciones (esquema v1)
- lifecycle.pyobligatorio. Archivo de entrada indicado por [module].entryobligatorio. Archivo de entrada indicado por [module].entry
- icon.pngopcional. Se define con [module].iconopcional. Se define con [module].icon
- locales/
- en.jsonidioma de referenciaidioma de referencia
- ko.json
- ...cadenas de la interfazcadenas de la interfaz
- test_lifecycle.pyopcional. Pruebas unitarias con pytest (recomendado)opcional. Pruebas unitarias con pytest (recomendado)
- Ponga a la carpeta el mismo nombre que
[module].nameenmodule.toml, en inglés y en minúsculas. - El demonio solo lee las carpetas de primer nivel bajo la raíz de módulos que contienen un
module.toml, y no carga un módulo si falta su archivo[module].entry. - Para empezar, recomendamos copiar
__example/__example__module.tomlamodule.tomly__example/__example__lifecycle.pyalifecycle.py, y luego borrar lo que no necesite.
2. Especificación de module.toml
Un ejemplo resumido de la parte superior del minecraft/module.toml real:
[module]
schema_version = 1 # obligatorio. Las claves desconocidas o los valores no válidos hacen fallar la carga
name = "minecraft" # igual que el nombre de la carpeta
version = "0.1.0"
display_name = "Minecraft"
game_name = "Minecraft"
entry = "lifecycle.py" # archivo Python que ejecuta el demonio
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" # componente → versión mínima (solo ">=")
[permissions]
network = true # capacidades que usa el código
spawn_process = true
[protocols]
supported = ["stdin"] # entre "stdin" / "rest"
default = "stdin"
interaction_mode = "console" # "console" o "commands"
[config]
server_executable = "server.jar"
process_name = "java.exe"
default_port = 25565
announce_command = "say" # nombre de [[commands.fields]] usado para los anuncios
# stop_command vale "stop" por defecto si se omite
[backup]
paths = ["{level_name}", "{level_name}_nether", "{level_name}_the_end"]
save_command = "save-all"
[install]
method = "download" # "manual" (predeterminado) / "download" / un id de extensión (p. ej. "steamcmd")
[detection]
dir_signatures = ["server.jar"]
graceful_exit_patterns = ["Stopping the server"]
crash_artifacts = ["crash-reports/*.txt", "hs_err_pid*.log"]
Qué significa cada sección:
[module]: Metadatos.name,versionyentryson obligatorios.log_patternextrae el nivel de log de una línea de consola mediante un grupo(?P<level>…). Las claves de[module.dependencies]sonsaba-core,ext-<id de extensión>, etc.[permissions]: Declara las capacidades de riesgo que usa el código (network,spawn_process,native_code,dynamic_code,env_secrets,fs_outside_instance).[protocols]:supportedadmite"stdin","rest"y"rcon". El orden de las rutas de comandos es stdin, luego REST y luego RCON. Use RCON solo en un juego que no tenga consola ni API REST. Ese juego también debe declararrcon_port, y el daemon asigna un puerto y una contraseña aleatoria a cada instancia. Si el juego tiene consola o REST, el módulo desactiva su ajuste de RCON.interaction_modedecide si se muestra una vista de consola (console) o solo botones de comandos (commands).[config]:server_executable,executable_path,process_name,default_port,stop_command(comando de parada enviado a la consola,stoppor defecto),stop_timeout(segundos, 30 por defecto),announce_command. Los ajustes del juego van en[[settings.fields]], no aquí.[[settings.fields]]: Elementos de la pantalla de ajustes de la instancia (name,type,label,default,options,group, etc.). Los valores que cambia el usuario se guardan como ajustes de la instancia y llegan en la config de cada llamada a función. Los elementos coninstall = trueson valores que se eligen al crear un servidor nuevo (tipo de servidor, ajustes del mundo nuevo, etc.), y los pregunta la pantalla de creación, la web yserver addde la CLI. Elinstall_optionsde un elemento select solo contiene los valores que Saba-chan puede instalar de nuevo (el resto deoptionssolo se usa para reconocer un servidor importado).[[commands.fields]]: Comandos del juego. Conmethod = "console"(+console_template) el comando va a la consola (stdin); con"rest", a la API REST del juego; y con"module"(predeterminado), acommand()enlifecycle.py.risk(safe/caution/danger) ydescriptionlos lee la interpretación de comandos por IA.[install]: Método de instalación,app_id,requires_extensions(lista de id de extensiones necesarias), etc. Palworld requiere["steamcmd", "ue4-ini"].[detection]: Reconocimiento de carpetas de servidor existentes (dir_signatures), búsqueda de procesos (process_patterns,cmd_patterns) y detección de fallos (graceful_exit_patterns,crash_artifacts). Solo se reinician automáticamente las salidas consideradas fallos.[backup]: Rutas que se incluyen en las copias (paths), el comando que se ejecuta justo antes de una copia (save_command) yhook = truecuando las rutas se calculan en código.[credential_map]: Asigna las claves estándar del demonio a las claves de ajustes del juego. Ejemplo de Palworld:rest_password = "AdminPassword".- También existen
[launch],[[agreements]],[[presets]],[[queries]],[aliases],[errors],[[syntax_highlight.rules]]y[extensions.<id>]. Para la lista completa de claves, consultedocs/module-spec.mden el repositoriosaba-chan-modules.
3. Contrato de funciones de lifecycle.py
Cada vez que lo necesita, el demonio lanza un nuevo proceso de Python para llamar a una función de este archivo. Cada función recibe un único config: dict y devuelve un dict, y debe registrarse en la tabla FUNCTIONS al final del archivo. Los módulos no tienen función start: el demonio lanza el servidor por sí mismo a partir del resultado de get_launch_command.
3.1 Funciones obligatorias
La única función obligatoria es 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)
- El demonio extiende los ajustes de la instancia (
module_settings) en el nivel superior de config. Leerlos conconfig_value(config, key, default)es la forma segura. - Si config contiene
extra_args(argumentos de inicio añadidos por el usuario), colóquelos donde corresponda y devuelvaextra_args_placed: true. Si no, el demonio los añade al final deargs. preview: trueindica una vista previa de los argumentos de inicio. No escriba archivos de ajustes; devuelva solo la información de inicio.
3.2 Funciones opcionales
Implemente solo las funciones que admita y, si implementa una, añádala siempre a la tabla FUNCTIONS.
| Función | Cuándo la llama el demonio | Devuelve |
|---|---|---|
validate | Comprobación previa al arranque | success, issues[] (el servidor no arranca si alguno tiene severity: "critical") |
stop | Parada de servidores sin consola y de servidores no gestionados | success |
status | Consulta de estado de un servidor no gestionado | status, pid |
command | Comandos con method = "module" | success, message |
get_credentials | Cuando se necesitan los datos de conexión REST | rest_username, rest_password |
configure / read_properties / reset_properties / reset_server | Guardar / leer / restablecer la pantalla de ajustes | success (+ valores leídos) |
import_settings | Importar un servidor existente, leer sus ajustes | settings{} |
list_versions / get_version_details | Lista de versiones / detalles | Información de versión |
install_server | Instalación y actualización | success, executable_path, install_path |
get_installed_version | Consulta de la versión instalada | version |
accept_agreements | Después de que el usuario acepte los [[agreements]] | success |
diagnose_log | Diagnóstico de logs | success |
backup_paths | Copias de seguridad (cuando [backup] hook = true) | success, paths[] |
instance_commands | Lista de comandos (cuando [commands] hook = true) | success, commands[] |
Reglas comunes:
- Toda respuesta incluye
success: boolymessage: str. Si hace falta una acción del usuario, incluyaaction_required: "<code>". - Si falta una extensión necesaria, responda con
error_code: "extension_required"ymissing_extensions: [...]. - Para un nombre de función desconocido, responda
{"success": false, "message": "Unknown function: X"}(run_lifecycle()se encarga de ello).
En un servidor gestionado con consola, el demonio lo detiene enviando
[config].stop_commanda la consola (stdin) y esperando. Elstop()del módulo solo se llama cuando no hay consola; debe seguir el orden petición de parada ordenada → espera → cierre forzado, y tocar únicamente elpidque le pasa el demonio.
4. Protocolo de subprocesos
La forma en que el demonio llama a las funciones de los módulos está implementada en src/plugin/mod.rs del repositorio de Saba-chan. En resumen:
- Lanza
python lifecycle.py <nombre de función>, usando el entorno de Python que gestiona el demonio. - Variables de entorno inyectadas:
PYTHONIOENCODING=utf-8,PYTHONUNBUFFERED=1PYTHONPATH: la carpeta de módulos que contiene los archivos compartidos (i18n.py,daemon_rcon.py) y la carpeta padre de la de extensionesSABA_IPC_URL,SABA_IPC_PORT: dirección de la API del demonioSABA_TOKEN_PATH: ruta del archivo que contiene el token de la API del demonioSABA_LANG: idioma de la GUISABA_ENABLED_EXTENSIONS: id de las extensiones activadas separados por comas (p. ej.steamcmd,ue4-ini)
- Escribe un objeto JSON de config en stdin y lo cierra.
- Analiza todo stdout como JSON; si falla, usa la última línea no vacía como resultado.
- stderr es el log. Las líneas que empiezan por
PROGRESS:se analizan como eventos de progreso y se usan para mostrar el progreso de instalación. - El código de salida debe ser 0. Si no lo es, el demonio trata la llamada como un error genérico aunque stdout contenga
success: false. - El proceso termina tras cada llamada. El límite de tiempo predeterminado es de 120 segundos; solo
install_serverdurante el aprovisionamiento y las actualizaciones dispone de más tiempo (1800 segundos).
Módulos no verificados: un módulo que no viene del catálogo firmado de Saba-chan, o que cambió después de descargarlo, se ejecuta en AppContainer en Windows y en bubblewrap en Linux. Saba-chan no lo analiza con un antivirus. Donde no se puede aislar (Linux sin bubblewrap o donde no se puede usar, y macOS), Saba-chan solo lo ejecuta después de que usted acepte sus archivos actuales. En el aislamiento, el módulo no puede conectarse al loopback (use las utilidades compartidas, y el daemon reenvía la solicitud), no recibe
SABA_TOKEN_PATHy solo puede escribir en las carpetas de instancia, de trabajo y de instalación, y en las carpetas dedata_roots. Tampoco puede usarmsiexecni las carpetas que creatempfile.mkdtemp. Vea la lista completa en Crear un módulo: de la investigación a la publicación.
4.1 Ejemplo de informe de progreso
# Dentro de 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")
# … descarga real …
report(2, 3, 70, "Extracting")
# …
report(3, 3, 100, "Install complete")
Los campos reconocidos son percent, message, step, total y label.
5. Utilidades compartidas
El demonio coloca los archivos compartidos i18n.py y daemon_rcon.py en la carpeta de módulos y la añade a PYTHONPATH. No los copie en la carpeta de su módulo.
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="…") # sustituye {{error}} en la cadena
daemon_stdin_command(config["instance_id"], "save-all") # envía una línea a la consola del servidor
daemon_rcon.py conserva su nombre solo por motivos históricos; nunca abre un socket RCON. Utilidades principales:
| Función | Uso |
|---|---|
daemon_stdin_command(instance_id, line) | Envía un comando a la consola de un servidor gestionado por el demonio |
daemon_post(path, payload) | Llama a otras API del demonio (el token se añade automáticamente) |
is_process_alive, wait_for_exit, force_kill | Comprobación / espera / cierre forzado por PID |
config_value(config, key, default) | Busca un valor de ajuste en config |
run_lifecycle(FUNCTIONS) | Punto de entrada de python lifecycle.py <function> |
Las extensiones activadas se pueden importar, p. ej. from extensions.steamcmd import SteamCMD o import extensions.ue4_ini. Las extensiones desactivadas quedan bloqueadas por una protección de importación (ModuleNotFoundError), así que impórtelas dentro de la función y responda extension_required si falla.
6. Referencia: módulos integrados
| Módulo | Puerto predeterminado | Protocolo | Extensiones necesarias | Notas |
|---|---|---|---|---|
minecraft | 25565 | stdin (consola) | Ninguna | Instalación download, detección/descarga automática de Java, RCON forzado a desactivado |
palworld | 8211 | API REST | steamcmd, ue4-ini | Juego sin consola. credential_map asigna rest_password ↔ AdminPassword |
zomboid | 16261 | stdin (consola) | steamcmd | stop_command = "quit", [backup] hook = true |
terraria | 7777 | stdin (seudoconsola pty) | xna (Windows) | Instalación download, servidor para Windows y Linux, [backup] hook = true |
Todos se construyen en torno a module.toml y lifecycle.py. Al crear un módulo nuevo, recomendamos partir de __example o del que más se parezca de estos cuatro.
7. Reglas de desarrollo (obligatorias)
Los PR de módulos deben cumplir estas reglas.
- Sin dependencia del código del demonio. Use solo la config, las variables de entorno y las API que proporciona el demonio.
- Todo fallo es JSON + código de salida 0. Responda con
success: falsey un motivo. - Los logs van a stderr. stdout es para el JSON de resultado. Escriba también en stderr las trazas de las excepciones; no se trague los errores.
- Use primero stdin y luego REST. Use RCON solo en un juego que no tenga ninguno de los dos. Si el juego tiene consola o REST, desactive su ajuste de RCON y no ponga
"rcon"ensupported. - Maneje los procesos solo por el
pidque le da el demonio. Matar por nombre de ejecutable también termina otras instancias del mismo juego. - Construya las rutas con
os.path.join; no las escriba a fuego. - Verifique la correspondencia de nombres de campos. Compruebe a qué clave de ajuste del juego corresponde cada nombre de
[[settings.fields]], tanto enconfigurecomo enimport_settings. - Pruebas. Mantenga pruebas unitarias en
test_lifecycle.pyy supere el kit de conformidad (sección 8 más abajo).
8. Consejos de depuración
- El resultado se lee de la última línea de stdout, así que envíe la salida de depuración a stderr. Imprimir cualquier cosa después del JSON de resultado rompe el análisis.
- Puede ejecutar una función directamente, sin el demonio. Añada la carpeta
modules/del repositorio de Saba-chan aPYTHONPATHpara que se encuentredaemon_rcon.echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command - Compruebe
module.tomlcon el mismo analizador que usa el demonio:saba-core module validate <carpeta del módulo> - Kit de conformidad:
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules(en el repositoriosaba-chan-modules) - Si el progreso no aparece en la GUI, compruebe que la línea de stderr empieza exactamente por
PROGRESS:y que el JSON que sigue es válido. - Después de editar un módulo, aplique también el cambio en
modules\<name>\dentro de la carpeta de datos para que el demonio use el código más reciente. El demonio guarda en caché la lista de módulos, así que si cambiómodule.toml, haga que la recargue conPOST /api/modules/refresh.