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

%APPDATA%\saba-chan\modules\<module_name>\
  • 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].name en module.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.toml a module.toml y __example/__example__lifecycle.py a lifecycle.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, version y entry son obligatorios. log_pattern extrae el nivel de log de una línea de consola mediante un grupo (?P<level>…). Las claves de [module.dependencies] son saba-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]: supported admite "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 declarar rcon_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_mode decide 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, stop por 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 con install = true son 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 y server add de la CLI. El install_options de un elemento select solo contiene los valores que Saba-chan puede instalar de nuevo (el resto de options solo se usa para reconocer un servidor importado).
  • [[commands.fields]]: Comandos del juego. Con method = "console" (+ console_template) el comando va a la consola (stdin); con "rest", a la API REST del juego; y con "module" (predeterminado), a command() en lifecycle.py. risk (safe/caution/danger) y description los 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) y hook = true cuando 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, consulte docs/module-spec.md en el repositorio saba-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 con config_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 devuelva extra_args_placed: true. Si no, el demonio los añade al final de args.
  • preview: true indica 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ónCuándo la llama el demonioDevuelve
validateComprobación previa al arranquesuccess, issues[] (el servidor no arranca si alguno tiene severity: "critical")
stopParada de servidores sin consola y de servidores no gestionadossuccess
statusConsulta de estado de un servidor no gestionadostatus, pid
commandComandos con method = "module"success, message
get_credentialsCuando se necesitan los datos de conexión RESTrest_username, rest_password
configure / read_properties / reset_properties / reset_serverGuardar / leer / restablecer la pantalla de ajustessuccess (+ valores leídos)
import_settingsImportar un servidor existente, leer sus ajustessettings{}
list_versions / get_version_detailsLista de versiones / detallesInformación de versión
install_serverInstalación y actualizaciónsuccess, executable_path, install_path
get_installed_versionConsulta de la versión instaladaversion
accept_agreementsDespués de que el usuario acepte los [[agreements]]success
diagnose_logDiagnóstico de logssuccess
backup_pathsCopias de seguridad (cuando [backup] hook = true)success, paths[]
instance_commandsLista de comandos (cuando [commands] hook = true)success, commands[]

Reglas comunes:

  • Toda respuesta incluye success: bool y message: str. Si hace falta una acción del usuario, incluya action_required: "<code>".
  • Si falta una extensión necesaria, responda con error_code: "extension_required" y missing_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_command a la consola (stdin) y esperando. El stop() 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 el pid que 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:

  1. Lanza python lifecycle.py <nombre de función>, usando el entorno de Python que gestiona el demonio.
  2. Variables de entorno inyectadas:
    • PYTHONIOENCODING=utf-8, PYTHONUNBUFFERED=1
    • PYTHONPATH: la carpeta de módulos que contiene los archivos compartidos (i18n.py, daemon_rcon.py) y la carpeta padre de la de extensiones
    • SABA_IPC_URL, SABA_IPC_PORT: dirección de la API del demonio
    • SABA_TOKEN_PATH: ruta del archivo que contiene el token de la API del demonio
    • SABA_LANG: idioma de la GUI
    • SABA_ENABLED_EXTENSIONS: id de las extensiones activadas separados por comas (p. ej. steamcmd,ue4-ini)
  3. Escribe un objeto JSON de config en stdin y lo cierra.
  4. Analiza todo stdout como JSON; si falla, usa la última línea no vacía como resultado.
  5. 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.
  6. 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.
  7. El proceso termina tras cada llamada. El límite de tiempo predeterminado es de 120 segundos; solo install_server durante 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_PATH y solo puede escribir en las carpetas de instancia, de trabajo y de instalación, y en las carpetas de data_roots. Tampoco puede usar msiexec ni las carpetas que crea tempfile.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ónUso
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_killComprobació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óduloPuerto predeterminadoProtocoloExtensiones necesariasNotas
minecraft25565stdin (consola)NingunaInstalación download, detección/descarga automática de Java, RCON forzado a desactivado
palworld8211API RESTsteamcmd, ue4-iniJuego sin consola. credential_map asigna rest_password ↔ AdminPassword
zomboid16261stdin (consola)steamcmdstop_command = "quit", [backup] hook = true
terraria7777stdin (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.

  1. Sin dependencia del código del demonio. Use solo la config, las variables de entorno y las API que proporciona el demonio.
  2. Todo fallo es JSON + código de salida 0. Responda con success: false y un motivo.
  3. 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.
  4. 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" en supported.
  5. Maneje los procesos solo por el pid que le da el demonio. Matar por nombre de ejecutable también termina otras instancias del mismo juego.
  6. Construya las rutas con os.path.join; no las escriba a fuego.
  7. Verifique la correspondencia de nombres de campos. Compruebe a qué clave de ajuste del juego corresponde cada nombre de [[settings.fields]], tanto en configure como en import_settings.
  8. Pruebas. Mantenga pruebas unitarias en test_lifecycle.py y 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 a PYTHONPATH para que se encuentre daemon_rcon.
    echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command
    
  • Compruebe module.toml con 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 repositorio saba-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 con POST /api/modules/refresh.