Guia de desenvolvimento de extensões
Os 10 hooks reais do Saba-chan e a especificação do manifest.json, a injeção em slots da GUI e notas de implementação das extensões incluídas.
Guia de desenvolvimento de extensões
Uma extensão (plugin) é um complemento que não está ligado a um jogo específico e, em vez disso, se encaixa globalmente no ciclo de vida do daemon, ou que injeta componentes na GUI. O daemon do Saba-chan passa o controle às extensões ativadas nos 10 pontos (hooks) a seguir. As extensões incluídas hoje são a instalação/atualização via SteamCMD (steamcmd) e o parser de INI do UE4 (ue4-ini).
O conteúdo deste documento se baseia nos arquivos manifest.json reais do repositório saba-chan-extensions e no sistema de extensões do lado do daemon (src/extension/mod.rs).
1. Estrutura de arquivos
- manifest.jsonobrigatório. Declara hooks, dependências, camposobrigatório. Declara hooks, dependências, campos
- __init__.pypermite que os módulos a importem como extensions.<name>permite que os módulos a importem como extensions.<name>
- <python_modules>.pyarquivos referenciados por python_modules no manifest.jsonarquivos referenciados por python_modules no manifest.json
- icon.pngopcionalopcional
- gui/opcional. Código-fonte e saída de build do pacote da GUI (UMD)opcional. Código-fonte e saída de build do pacote da GUI (UMD)
- i18n/opcional. Definido com i18n_dir no manifesto (<locale>.json)opcional. Definido com i18n_dir no manifesto (<locale>.json)
- test_<name>.pyrecomendado. Testes com pytestrecomendado. Testes com pytest
- O nome da pasta precisa corresponder ao
iddo manifesto. O id com os hifens trocados por sublinhados também é aceito (por exemplo, idue4-ini→ pastaue4_ini). Caso contrário, o daemon não a carrega e a lista emfailednoGET /api/extensions. - Um id só pode conter letras, dígitos,
-e_.
2. Especificação do manifest.json
O manifesto real da extensão SteamCMD:
{
"schema_version": 1, // com 1, chaves desconhecidas e hooks que nunca disparam são erros
"id": "steamcmd", // corresponde ao nome da pasta
"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": [], // dependências de outras extensões (array ou { "id": ">=x.y.z" })
"python_modules": {
"steamcmd": "steamcmd.py" // nome lógico → caminho do arquivo
},
"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 }
}
Resumo dos campos:
schema_version: Com1, chaves desconhecidas, nomes de hook que não estão emFIRED_HOOKSe referências apython_modulesinexistentes são erros. Sem ele (0), são apenas avisos.id,name,version: Obrigatórios.versioné usado nas comparações de atualização e de dependências.description/descriptions: Descrição em inglês e descrições por idioma. A API de listagem escolhe a que corresponde ao idioma da GUI.min_app_version: A extensão não pode ser ativada nem instalada em um Saba-chan mais antigo.dependencies: Dependências de outras extensões (ou dosaba-core). Só requisitos de versão>=são suportados. A ativação verifica se as dependências estão ativadas; ela não as ativa automaticamente.python_modules: Registra, por nome lógico, os arquivos Python que os hooks e comandos referenciam. Arquivos não registrados aqui não podem ser chamados pelos hooks.hooks.<nome do hook>module: um nome lógico declarado empython_modulesfunction: o nome da função dentro desse arquivocondition(opcional): só a formainstance.ext_data.<key>é suportada. O hook roda apenas para instâncias em que esse valor é verdadeiro, um número diferente de zero ou uma string não vazia.
instance_fields: Valores por instância que esta extensão usa (extension_data). Se alguma instância tiver um valor definido, desativar ou remover a extensão é recusado (in_use).config_fields: Campos de configuração global da extensão. Os valores são guardados emextensions.settings.<id>noconfig.json.gui:bundle(caminho do pacote UMD),styles(caminho do CSS). Veja a seção 5 abaixo.cli: Declarações de slots da CLI (cli.slots).commands: Comandos adicionados à lista de comandos da instância (name,label,risk,inputs,module,function,condition).priority: Ordem quando várias extensões têm o mesmo hook (menor roda primeiro, padrão 100).i18n_dir: Pasta dos arquivos de tradução.permissions: Declara as capacidades de risco que o código usa (a mesma tabela do[permissions]de um módulo).
Não existe campo
asyncnos hooks nemmanifest_urlno manifesto. A lista de extensões e as atualizações vêm apenas do manifesto de release assinado do Saba-chan.
3. Os 10 hooks reais
As funções de hook rodam da mesma forma que os módulos. O daemon inicia python <arquivo>.py <nome da função>, grava o JSON de contexto no stdin e lê o JSON do stdout (inteiro ou a última linha) como resultado. O código de saída precisa ser 0. A lista abaixo é a mesma de FIRED_HOOKS no código do daemon.
| Nome do hook | Quando é chamado | Como o resultado é usado | Execução |
|---|---|---|---|
daemon.startup | Logo após o início do daemon / logo após uma extensão ser ativada (somente essa extensão) | success/message vão para o estado de inicialização (/api/extensions/init-status) | Em segundo plano |
daemon.shutdown | Logo antes de o daemon encerrar | Apenas registrado em log | Síncrona |
server.pre_start | Logo antes de um servidor iniciar | handled: true substitui o início padrão (se success não for verdadeiro nesse caso, o início falha) | Síncrona |
server.stop | Logo antes de um servidor parar | handled: true assume a parada | Síncrona |
server.status | Ao consultar o status de um servidor específico | handled: true devolve esse resultado como está | Síncrona |
server.list_enrich | Ao listar instâncias | handled: true preenche status e extension_status. Tempo limite de 10 s, cache com TTL de 30 s | Síncrona |
server.post_create | Logo após uma instância ser criada | O resultado não é usado | Em segundo plano |
server.pre_delete | Logo antes de uma instância ser excluída | Se handled, espera um pouco para que os bloqueios de arquivo sejam liberados | Síncrona |
server.settings_changed | Depois que as configurações da instância são salvas | O resultado não é usado | Síncrona |
server.check_update | Quando uma verificação de atualização é pedida | O primeiro resultado bem-sucedido vira a resposta | Síncrona |
Nomes como
server.pre_create,server.pre_install,server.post_install,server.post_start,module.parse_settingsemodule.write_settingsnão existem; usá-los em um manifesto comschema_version = 1faz o carregamento falhar.
3.1 Contexto e ponto de entrada
Uma função de hook recebe um dicionário de contexto e devolve um dicionário. Dependendo do hook, o contexto contém instance_id, instance_name, module, instance_dir, extension_data e assim por diante, e todo hook também recebe as configurações globais das extensões como extension_config. O arquivo Python precisa tratar sozinho o nome da função e o stdin no __main__. Um exemplo resumido da estrutura do steamcmd.py:
import json, sys, traceback
def check_update(ctx: dict) -> dict:
"""
exemplo de ctx (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) # os logs vão para o stderr
result = {"success": False, "message": str(e)}
print(json.dumps(result, ensure_ascii=False)) # falhas também são JSON + código de saída 0
3.2 handled e ordem de execução
- Extensões com o mesmo hook rodam uma de cada vez, ordenadas por
prioritye depois por id. - Se um resultado contiver
handled: true, as extensões restantes são puladas. Deixehandledde fora, a menos que você esteja substituindo o comportamento padrão daquele hook. - Se uma extensão falhar, o erro é registrado e a próxima extensão roda.
- O tempo limite padrão é de 120 segundos. O caminho dos hooks não tem exibição de progresso (
PROGRESS:).
3.3 Cache com TTL do server.list_enrich
Este hook pode ser chamado, um após o outro, para cada instância que tenha extension_data, a cada vez que a lista de instâncias é pedida, então o daemon guarda em cache os resultados bem-sucedidos por 30 segundos. Enquanto o cache é válido, ele reaproveita o resultado anterior sem iniciar um processo Python. Cada chamada tem um tempo limite de 10 segundos, então projete-a para terminar rápido. O status_line do resultado é um status curto de uma linha mostrado na exibição de status do Discord, então não coloque caminhos nem segredos nele.
4. As 3 extensões incluídas
steamcmd
- id:
steamcmd - Python:
steamcmd.py(classeSteamCMD: instalação portátil do SteamCMD, instalação/atualização de servidores de jogo, verificação de atualizações) - Hook: apenas
server.check_update(condition: instance.ext_data.install_method_steamcmd). - A instalação de fato é feita diretamente pelo
install_serverdo módulo viafrom extensions.steamcmd import SteamCMD. - instance_fields:
install_method_steamcmd,steamcmd_app_id,steamcmd_anonymous,steamcmd_beta,steamcmd_platform. O daemon os preenche a partir da seção[install]do módulo usando uma regra genérica (install_method_<method>,<method>_<field>). - Sem GUI.
ue4-ini
- id:
ue4-ini(nome da pastaue4_ini) - Python:
ue4_ini.py(parse_option_settings,write_option_settings) - Finalidade: fornece aos módulos utilitários para ler e gravar o
OptionSettings=(...)do INI de jogos UE4, como o Palworld. - É uma biblioteca pura que não declara hooks; os módulos a importam como
extensions.ue4_ini.
xna
- id:
xna - Python:
xna.py(install,present,XnaError) - Finalidade: mantém uma versão fixa do Microsoft XNA Framework 4.0 Refresh ao lado da pasta do servidor de jogo, sem instalá-la no PC. É usada pelo servidor Windows do Terraria. Baixa uma vez o MSI de distribuição oficial, confere com um SHA-256 fixo e extrai só os arquivos necessários.
- É uma biblioteca pura que não declara hooks; os módulos a usam com
from extensions.xna import install, present.
Os módulos não podem importar extensões desativadas. A proteção de import do daemon bloqueia a importação de qualquer
extensions.<name>que não esteja emSABA_ENABLED_EXTENSIONS.
5. Pacote da GUI (injeção em slots)
Se o manifest.json declarar gui.bundle, a GUI busca esse arquivo por GET /api/extensions/:id/gui e o executa (e também injeta o CSS se gui.styles estiver definido).
"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" } // caminhos de exemplo
- O pacote está no formato UMD e precisa criar o global
window.SabaExt<id em PascalCase>. Remova-e_do id e deixe em maiúscula a letra seguinte (por exemplo,steamcmd→window.SabaExtSteamcmd,ue4-ini→window.SabaExtUe4Ini). - Quando o
registerSlots()desse global devolve{ slotId: Component | Component[] }, a GUI os monta nesses slots. - O React é referenciado como externo a partir do
window.Reactdo host. Os componentes precisam funcionar usando apenas as props que o slot passa. - As traduções são carregadas por
GET /api/extensions/:id/i18n/:localeno namespaceext_<id>.
| Id do slot | Local | props |
|---|---|---|
ServerCard.badge | Selo do cartão do servidor | server |
ServerCard.headerGauge | Medidor no cabeçalho do cartão do servidor | server |
ServerCard.provision | Cartão do servidor durante o provisionamento | server, provisionProgress, onDismiss, t |
ServerCard.expandedStats | Estatísticas do cartão do servidor expandido | server, t |
ServerSettings.tab | Aba das configurações do servidor | server, activeTab, setActiveTab, settings, onSettingsChange, t |
AddServer.options | Opções de adicionar servidor | t |
server são as informações do servidor vindas de /api/servers; os componentes podem ler extension_data e extension_status[<extension_id>] (o resultado do server.list_enrich).
6. Gerenciando extensões pela REST API
GET /api/extensions Lista de instaladas (+ falhas de carregamento)
GET /api/extensions/init-status Resultados do daemon.startup
POST /api/extensions/rescan Relê a pasta
GET /api/extensions/manifest Catálogo remoto (manifesto de release assinado)
GET /api/extensions/updates Lista de atualizações
POST /api/extensions/:id/install Instala (a partir do catálogo, sha256 conferido)
POST /api/extensions/:id/enable Ativa → executa o daemon.startup dessa extensão
POST /api/extensions/:id/disable Desativa
POST /api/extensions/:id/mount Registra na memória
POST /api/extensions/:id/unmount Remove o registro da memória
DELETE /api/extensions/:id Remove
GET /api/extensions/:id/config Valores de config_fields
PUT /api/extensions/:id/config Atualiza os valores
GET /api/extensions/:id/gui Pacote da GUI (JS)
GET /api/extensions/:id/gui/styles Estilos da GUI (CSS)
GET /api/extensions/:id/icon Ícone
GET /api/extensions/:id/audit Compara as capacidades usadas pelo código com as permissions
GET /api/extensions/:id/i18n/:locale JSON de idioma
A lista de ativadas é guardada em extensions.enabled no config.json, e os valores de configuração global em extensions.settings.
7. Regras de desenvolvimento
- As extensões também não podem depender do código do daemon. Use apenas o contexto e as variáveis de ambiente que o daemon passa.
- Monte caminhos com
os.path.join; não os deixe fixos no código. - As funções de hook também respondem às falhas com JSON (
success: falsee um motivo) e código de saída 0, e enviam logs e tracebacks para o stderr. - Use apenas a forma
instance.ext_data.<key>emcondition. Qualquer outra forma sempre é avaliada como falsa. - As dependências Python usam o ambiente compartilhado do daemon. Não há declaração de requirements por extensão.
- Extensões não verificadas: extensões que não foram baixadas do catálogo assinado, ou que foram alteradas depois do download, rodam no mesmo ambiente isolado dos módulos (AppContainer no Windows, bubblewrap no Linux). Não há verificação por antivírus. O que segue vale para o Windows. Elas não alcançam o loopback (como a API do daemon), não recebem
SABA_TOKEN_PATHe só podem ler as pastas das instâncias. Coloque os dados que precisar gravar na pasta dedicada indicada pela variável de ambienteSABA_EXTENSION_DATA_DIR. - Execute os testes com
pytesta partir da raiz do repositório.