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
- 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
iddel manifiesto. También se acepta el id con los guiones sustituidos por guiones bajos (p. ej., idue4-ini→ carpetaue4_ini). Si no, el demonio no la carga y la lista enfailedenGET /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: Con1, las claves desconocidas, los nombres de hook que no están enFIRED_HOOKSy las referencias apython_modulesinexistentes son errores. Sin él (0), solo son advertencias.id,name,version: Obligatorios.versionse 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 desaba-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 enpython_modulesfunction: el nombre de la función dentro de ese archivocondition(opcional): solo se admite la formainstance.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 enextensions.settings.<id>deconfig.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
asyncen los hooks nimanifest_urlen 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 hook | Cuándo se llama | Cómo se usa el resultado | Ejecución |
|---|---|---|---|
daemon.startup | Justo 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.shutdown | Justo antes de apagar el demonio | Solo se registra en el log | Síncrona |
server.pre_start | Justo antes de que arranque un servidor | handled: true sustituye el arranque predeterminado (si entonces success no es verdadero, el arranque falla) | Síncrona |
server.stop | Justo antes de que se detenga un servidor | handled: true se encarga de la parada | Síncrona |
server.status | Al consultar el estado de un servidor concreto | handled: true devuelve ese resultado tal cual | Síncrona |
server.list_enrich | Al listar las instancias | handled: true rellena status y extension_status. Tiempo límite de 10 s, caché TTL de 30 s | Síncrona |
server.post_create | Justo después de crear una instancia | El resultado no se usa | Segundo plano |
server.pre_delete | Justo antes de eliminar una instancia | Si hay handled, espera brevemente a que se liberen los bloqueos de archivos | Síncrona |
server.settings_changed | Después de guardar los ajustes de una instancia | El resultado no se usa | Síncrona |
server.check_update | Cuando se solicita una comprobación de actualizaciones | El primer resultado correcto pasa a ser la respuesta | Síncrona |
Nombres como
server.pre_create,server.pre_install,server.post_install,server.post_start,module.parse_settingsymodule.write_settingsno existen; usarlos en un manifiesto conschema_version = 1hace 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
priorityy después por id. - Si un resultado contiene
handled: true, se omiten las extensiones restantes. No incluyahandledsalvo 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(claseSteamCMD: 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_serverdel módulo mediantefrom 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 carpetaue4_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é enSABA_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.Reactdel host. Los componentes deben funcionar solo con las props que les pasa el slot. - Las traducciones se cargan mediante
GET /api/extensions/:id/i18n/:localeen el espacio de nombresext_<id>.
| Id del slot | Ubicación | props |
|---|---|---|
ServerCard.badge | Insignia de la tarjeta del servidor | server |
ServerCard.headerGauge | Indicador de la cabecera de la tarjeta del servidor | server |
ServerCard.provision | Tarjeta del servidor durante el aprovisionamiento | server, provisionProgress, onDismiss, t |
ServerCard.expandedStats | Estadísticas de la tarjeta del servidor desplegada | server, t |
ServerSettings.tab | Pestaña de ajustes del servidor | server, activeTab, setActiveTab, settings, onSettingsChange, t |
AddServer.options | Opciones de añadir servidor | t |
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: falsey 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>paracondition. 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_PATHy solo pueden leer las carpetas de instancia. Guarde los datos que necesite escribir en la carpeta dedicada que indica la variable de entornoSABA_EXTENSION_DATA_DIR. - Ejecute las pruebas con
pytestdesde la raíz del repositorio.