Guía de desarrollo de extensiones

Los 10 hooks reales de Saba-chan y la especificación de manifest.json, la inyección de slots en la GUI y notas de implementación de las extensiones incluidas.

Guía de desarrollo de extensiones

Una extensión (plugin) es un complemento que no está ligado a un juego concreto, sino que se engancha de forma global al ciclo de vida del demonio, o que inyecta componentes en la GUI. El demonio de Saba-chan cede el control a las extensiones activadas en los 10 puntos (hooks) siguientes. Las extensiones incluidas hoy son la instalación/actualización con SteamCMD (steamcmd) y el analizador INI de UE4 (ue4-ini).

El contenido de este documento se basa en los archivos manifest.json reales del repositorio saba-chan-extensions y en el sistema de extensiones del lado del demonio (src/extension/mod.rs).


1. Estructura de archivos

%APPDATA%\saba-chan\extensions\<extension_id>\
  • manifest.jsonobligatorio. Declara hooks, dependencias y camposobligatorio. Declara hooks, dependencias y campos
  • __init__.pypermite que los módulos la importen como extensions.<name>permite que los módulos la importen como extensions.<name>
  • <python_modules>.pyarchivos referenciados por python_modules en manifest.jsonarchivos referenciados por python_modules en manifest.json
  • icon.pngopcionalopcional
  • gui/opcional. Código fuente y salida de compilación del paquete GUI (UMD)opcional. Código fuente y salida de compilación del paquete GUI (UMD)
  • i18n/opcional. Se define con i18n_dir en el manifiesto (<locale>.json)opcional. Se define con i18n_dir en el manifiesto (<locale>.json)
  • test_<name>.pyrecomendado. Pruebas con pytestrecomendado. Pruebas con pytest
  • El nombre de la carpeta debe coincidir con el id del manifiesto. También se acepta el id con los guiones sustituidos por guiones bajos (p. ej., id ue4-ini → carpeta ue4_ini). Si no, el demonio no la carga y la lista en failed en GET /api/extensions.
  • Un id solo puede contener letras, dígitos, - y _.

2. Especificación de manifest.json

El manifiesto real de la extensión SteamCMD:

{
  "schema_version": 1,                    // con 1, las claves desconocidas y los hooks que nunca se disparan son errores
  "id": "steamcmd",                       // coincide con el nombre de la carpeta
  "name": "SteamCMD",
  "version": "0.1.0",
  "description": "Installs and updates game servers with SteamCMD",
  "descriptions": { "ko": "SteamCMD를 사용한 게임 서버 설치 및 업데이트 자동화" },
  "author": "WareAoba",
  "min_app_version": "0.1.0",
  "dependencies": [],                     // dependencias de otras extensiones (array o { "id": ">=x.y.z" })

  "python_modules": {
    "steamcmd": "steamcmd.py"             // nombre lógico → ruta del archivo
  },

  "hooks": {
    "server.check_update": {
      "module": "steamcmd",
      "function": "check_update",
      "condition": "instance.ext_data.install_method_steamcmd"
    }
  },

  "instance_fields": {
    "install_method_steamcmd": { "type": "boolean", "default": false },
    "steamcmd_app_id": { "type": "number", "optional": true },
    "steamcmd_anonymous": { "type": "boolean", "default": true },
    "steamcmd_beta": { "type": "string", "optional": true },
    "steamcmd_platform": { "type": "string", "optional": true }
  },
  "permissions": { "network": true, "spawn_process": true }
}

Resumen de campos:

  • schema_version: Con 1, las claves desconocidas, los nombres de hook que no están en FIRED_HOOKS y las referencias a python_modules inexistentes son errores. Sin él (0), solo son advertencias.
  • id, name, version: Obligatorios. version se usa para comparar actualizaciones y dependencias.
  • description / descriptions: Descripción en inglés y descripciones por idioma. La API de listado elige la que corresponde al idioma de la GUI.
  • min_app_version: La extensión no se puede activar ni instalar en un Saba-chan más antiguo.
  • dependencies: Dependencias de otras extensiones (o de saba-core). Solo se admiten requisitos de versión >=. Al activarla se comprueba que las dependencias estén activadas; no las activa automáticamente.
  • python_modules: Registra por nombre lógico los archivos Python a los que hacen referencia los hooks y los comandos. Los archivos no registrados aquí no pueden ser llamados por los hooks.
  • hooks.<nombre del hook>
    • module: un nombre lógico declarado en python_modules
    • function: el nombre de la función dentro de ese archivo
    • condition (opcional): solo se admite la forma instance.ext_data.<key>. El hook solo se ejecuta para las instancias en las que ese valor es verdadero, un número distinto de cero o una cadena no vacía.
  • instance_fields: Valores por instancia que usa esta extensión (extension_data). Si alguna instancia tiene un valor definido, se rechaza desactivar o eliminar la extensión (in_use).
  • config_fields: Campos de ajustes globales de la extensión. Los valores se guardan en extensions.settings.<id> de config.json.
  • gui: bundle (ruta del paquete UMD), styles (ruta del CSS). Vea la sección 5 más abajo.
  • cli: Declaraciones de slots de la CLI (cli.slots).
  • commands: Comandos añadidos a la lista de comandos de la instancia (name, label, risk, inputs, module, function, condition).
  • priority: Orden cuando varias extensiones tienen el mismo hook (se ejecuta primero el valor más bajo; 100 por defecto).
  • i18n_dir: Carpeta de archivos de traducción.
  • permissions: Declara las capacidades de riesgo que usa el código (la misma tabla que [permissions] de un módulo).

No hay campo async en los hooks ni manifest_url en el manifiesto. La lista de extensiones y sus actualizaciones solo proceden del manifiesto de versiones firmado de Saba-chan.


3. Los 10 hooks reales

Las funciones de hook se ejecutan igual que los módulos. El demonio lanza python <file>.py <nombre de función>, escribe el JSON de contexto en stdin y lee como resultado el JSON de stdout (completo o la última línea). El código de salida debe ser 0. La lista siguiente coincide con FIRED_HOOKS en el código del demonio.

Nombre del hookCuándo se llamaCómo se usa el resultadoEjecución
daemon.startupJusto después de arrancar el demonio / justo después de activar una extensión (solo esa extensión)success/message pasan al estado de inicialización (/api/extensions/init-status)Segundo plano
daemon.shutdownJusto antes de apagar el demonioSolo se registra en el logSíncrona
server.pre_startJusto antes de que arranque un servidorhandled: true sustituye el arranque predeterminado (si entonces success no es verdadero, el arranque falla)Síncrona
server.stopJusto antes de que se detenga un servidorhandled: true se encarga de la paradaSíncrona
server.statusAl consultar el estado de un servidor concretohandled: true devuelve ese resultado tal cualSíncrona
server.list_enrichAl listar las instanciashandled: true rellena status y extension_status. Tiempo límite de 10 s, caché TTL de 30 sSíncrona
server.post_createJusto después de crear una instanciaEl resultado no se usaSegundo plano
server.pre_deleteJusto antes de eliminar una instanciaSi hay handled, espera brevemente a que se liberen los bloqueos de archivosSíncrona
server.settings_changedDespués de guardar los ajustes de una instanciaEl resultado no se usaSíncrona
server.check_updateCuando se solicita una comprobación de actualizacionesEl primer resultado correcto pasa a ser la respuestaSíncrona

Nombres como server.pre_create, server.pre_install, server.post_install, server.post_start, module.parse_settings y module.write_settings no existen; usarlos en un manifiesto con schema_version = 1 hace fallar la carga.

3.1 Contexto y punto de entrada

Una función de hook recibe un diccionario de contexto y devuelve un diccionario. Según el hook, el contexto contiene instance_id, instance_name, module, instance_dir, extension_data, etc., y todos los hooks reciben además los ajustes globales de las extensiones como extension_config. El archivo Python debe gestionar por sí mismo el nombre de la función y stdin en __main__. Un ejemplo abreviado de la estructura de steamcmd.py:

import json, sys, traceback

def check_update(ctx: dict) -> dict:
    """
    ctx example (server.check_update):
      {
        "instance_id": "…",
        "instance_name": "My Palworld",
        "module": "palworld",
        "instance_dir": "…",
        "install_dir": "…",
        "app_id": 2394010,
        "extension_data": {"install_method_steamcmd": true, ...},
        "extension_config": {...}
      }
    """
    ...
    return {"success": True, "update_available": False}

FUNCTIONS = {"check_update": check_update}

if __name__ == "__main__":
    name = sys.argv[1] if len(sys.argv) > 1 else ""
    try:
        raw = sys.stdin.read()
        ctx = json.loads(raw) if raw.strip() else {}
        result = FUNCTIONS[name](ctx) if name in FUNCTIONS else \
            {"success": False, "message": f"Unknown function: {name}"}
    except Exception as e:
        traceback.print_exc(file=sys.stderr)      # los logs van a stderr
        result = {"success": False, "message": str(e)}
    print(json.dumps(result, ensure_ascii=False))  # los fallos también: JSON + código de salida 0

3.2 handled y orden de ejecución

  • Las extensiones con el mismo hook se ejecutan de una en una, ordenadas por priority y después por id.
  • Si un resultado contiene handled: true, se omiten las extensiones restantes. No incluya handled salvo que esté sustituyendo el comportamiento predeterminado de ese hook.
  • Si una extensión falla, se registra el error y se ejecuta la siguiente extensión.
  • El límite de tiempo predeterminado es de 120 segundos. La ruta de los hooks no muestra progreso (PROGRESS:).

3.3 Caché TTL de server.list_enrich

Este hook puede llamarse para cada instancia que tenga extension_data, una tras otra, cada vez que se solicita la lista de instancias, así que el demonio guarda en caché los resultados correctos durante 30 segundos. Mientras la caché es válida, reutiliza el resultado anterior sin lanzar un proceso de Python. Cada llamada tiene un tiempo límite de 10 segundos, así que diséñelo para que termine rápido. El status_line del resultado es un estado breve de una línea que se muestra en la visualización de estado de Discord, así que no ponga en él rutas ni secretos.


4. Las 3 extensiones incluidas

steamcmd

  • id: steamcmd
  • Python: steamcmd.py (clase SteamCMD: instalación portable de SteamCMD, instalación/actualización del servidor de juego, comprobación de actualizaciones)
  • Hook: solo server.check_update (condition: instance.ext_data.install_method_steamcmd).
  • La instalación propiamente dicha la hace directamente el install_server del módulo mediante from extensions.steamcmd import SteamCMD.
  • instance_fields: install_method_steamcmd, steamcmd_app_id, steamcmd_anonymous, steamcmd_beta, steamcmd_platform. El demonio los rellena a partir de la sección [install] del módulo con una regla genérica (install_method_<method>, <method>_<field>).
  • Sin GUI.

ue4-ini

  • id: ue4-ini (nombre de carpeta ue4_ini)
  • Python: ue4_ini.py (parse_option_settings, write_option_settings)
  • Propósito: proporciona a los módulos utilidades para leer y escribir el OptionSettings=(...) de los INI de juegos UE4 como Palworld.
  • Es una biblioteca pura que no declara hooks; los módulos la importan como extensions.ue4_ini.

xna

  • id: xna
  • Python: xna.py (install, present, XnaError)
  • Propósito: coloca la versión fija de Microsoft XNA Framework 4.0 Refresh junto a la carpeta del servidor de juego, sin instalarla en el PC. La usa el servidor de Terraria para Windows. Descarga una vez el MSI de distribución oficial, lo verifica con un SHA-256 fijo y extrae solo los archivos necesarios.
  • Es una biblioteca pura que no declara hooks; los módulos la usan con from extensions.xna import install, present.

Los módulos no pueden importar extensiones desactivadas. La protección de importación del demonio bloquea la importación de cualquier extensions.<name> que no esté en SABA_ENABLED_EXTENSIONS.


5. Paquete de la GUI (inyección de slots)

Si manifest.json declara gui.bundle, la GUI obtiene ese archivo mediante GET /api/extensions/:id/gui y lo ejecuta (y también inyecta el CSS si se ha definido gui.styles).

"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" }   // rutas de ejemplo
  • El paquete está en formato UMD y debe crear la variable global window.SabaExt<id en PascalCase>. Quite - y _ del id y ponga en mayúscula la letra siguiente (p. ej., steamcmd → window.SabaExtSteamcmd, ue4-ini → window.SabaExtUe4Ini).
  • Cuando registerSlots() de esa variable global devuelve { slotId: Component | Component[] }, la GUI los monta en esos slots.
  • React se referencia como dependencia externa desde el window.React del host. Los componentes deben funcionar solo con las props que les pasa el slot.
  • Las traducciones se cargan mediante GET /api/extensions/:id/i18n/:locale en el espacio de nombres ext_<id>.
Id del slotUbicaciónprops
ServerCard.badgeInsignia de la tarjeta del servidorserver
ServerCard.headerGaugeIndicador de la cabecera de la tarjeta del servidorserver
ServerCard.provisionTarjeta del servidor durante el aprovisionamientoserver, provisionProgress, onDismiss, t
ServerCard.expandedStatsEstadísticas de la tarjeta del servidor desplegadaserver, t
ServerSettings.tabPestaña de ajustes del servidorserver, activeTab, setActiveTab, settings, onSettingsChange, t
AddServer.optionsOpciones de añadir servidort

server es la información del servidor procedente de /api/servers; los componentes pueden leer extension_data y extension_status[<extension_id>] (el resultado de server.list_enrich).


6. Gestionar extensiones mediante la API REST

GET    /api/extensions                   Lista instalada (+ fallos de carga)
GET    /api/extensions/init-status       Resultados de daemon.startup
POST   /api/extensions/rescan            Volver a leer la carpeta
GET    /api/extensions/manifest          Catálogo remoto (manifiesto de versiones firmado)
GET    /api/extensions/updates           Lista de actualizaciones
POST   /api/extensions/:id/install       Instalar (desde el catálogo, con verificación sha256)
POST   /api/extensions/:id/enable        Activar → ejecuta el daemon.startup de esa extensión
POST   /api/extensions/:id/disable       Desactivar
POST   /api/extensions/:id/mount         Registrar en memoria
POST   /api/extensions/:id/unmount       Quitar de la memoria
DELETE /api/extensions/:id               Eliminar
GET    /api/extensions/:id/config        Valores de config_fields
PUT    /api/extensions/:id/config        Actualizar valores
GET    /api/extensions/:id/gui           Paquete de la GUI (JS)
GET    /api/extensions/:id/gui/styles    Estilos de la GUI (CSS)
GET    /api/extensions/:id/icon          Icono
GET    /api/extensions/:id/audit         Comparar las capacidades que usa el código con los permisos
GET    /api/extensions/:id/i18n/:locale  JSON de idioma

La lista de extensiones activadas se guarda en extensions.enabled de config.json, y los valores de los ajustes globales en extensions.settings.


7. Reglas de desarrollo

  • Las extensiones tampoco deben depender del código del demonio. Use solo el contexto y las variables de entorno que les pasa el demonio.
  • Construya las rutas con os.path.join; no las escriba a fuego.
  • Las funciones de hook también responden a los fallos con JSON (success: false y un motivo) y código de salida 0, y envían los logs y las trazas a stderr.
  • Use solo la forma instance.ext_data.<key> para condition. Cualquier otra forma se evalúa siempre como falsa.
  • Las dependencias de Python usan el entorno compartido del demonio. No hay declaración de requisitos por extensión.
  • Extensiones no verificadas: las extensiones que no se descargaron del catálogo firmado, o que se modificaron después de descargarlas, se ejecutan, igual que los módulos, en un entorno aislado (AppContainer en Windows, bubblewrap en Linux). No se analizan con el antivirus. Lo que sigue vale para Windows. No pueden acceder al loopback (como la API del demonio), no reciben SABA_TOKEN_PATH y solo pueden leer las carpetas de instancia. Guarde los datos que necesite escribir en la carpeta dedicada que indica la variable de entorno SABA_EXTENSION_DATA_DIR.
  • Ejecute las pruebas con pytest desde la raíz del repositorio.