Guia de desenvolvimento de módulos
Como criar um módulo Python que adiciona um novo jogo ao Saba-chan. Cobre o esquema do module.toml e o contrato e o protocolo reais das funções do lifecycle.py.
Guia de desenvolvimento de módulos (Python)
O daemon do Saba-chan não conhece os detalhes de cada jogo. Em vez disso, cada jogo é descrito por um módulo Python. Adicionar um módulo permite que o Saba-chan gerencie um novo jogo.
Este documento se baseia nos módulos reais do repositório saba-chan-modules (minecraft, palworld, zomboid), no modelo comentado __example e no código do daemon.
1. Estrutura de arquivos do módulo
- module.tomlobrigatório. Declarações (schema v1)obrigatório. Declarações (schema v1)
- lifecycle.pyobrigatório. Arquivo de entrada indicado por [module].entryobrigatório. Arquivo de entrada indicado por [module].entry
- icon.pngopcional. Definido com [module].iconopcional. Definido com [module].icon
- locales/
- en.jsonidioma de referênciaidioma de referência
- ko.json
- ...textos da interfacetextos da interface
- test_lifecycle.pyopcional. Testes unitários com pytest (recomendado)opcional. Testes unitários com pytest (recomendado)
- Dê à pasta o mesmo nome de
[module].namenomodule.toml, em inglês minúsculo. - O daemon só lê as pastas de primeiro nível sob a raiz de módulos que contêm um
module.toml, e não carrega um módulo cujo arquivo[module].entryesteja ausente. - Para começar, recomendamos copiar
__example/__example__module.tomlparamodule.tomle__example/__example__lifecycle.pyparalifecycle.py, e então apagar o que não precisar.
2. Especificação do module.toml
Um exemplo resumido do início do minecraft/module.toml real:
[module]
schema_version = 1 # obrigatório. Chaves desconhecidas ou valores inválidos fazem o carregamento falhar
name = "minecraft" # igual ao nome da pasta
version = "0.1.0"
display_name = "Minecraft"
game_name = "Minecraft"
entry = "lifecycle.py" # arquivo Python que o daemon executa
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 → versão mínima (apenas ">=")
[permissions]
network = true # capacidades que o código usa
spawn_process = true
[protocols]
supported = ["stdin"] # entre "stdin" / "rest"
default = "stdin"
interaction_mode = "console" # "console" ou "commands"
[config]
server_executable = "server.jar"
process_name = "java.exe"
default_port = 25565
announce_command = "say" # nome em [[commands.fields]] usado para avisos
# stop_command assume "stop" quando omitido
[backup]
paths = ["{level_name}", "{level_name}_nether", "{level_name}_the_end"]
save_command = "save-all"
[install]
method = "download" # "manual" (padrão) / "download" / um id de extensão (por exemplo, "steamcmd")
[detection]
dir_signatures = ["server.jar"]
graceful_exit_patterns = ["Stopping the server"]
crash_artifacts = ["crash-reports/*.txt", "hs_err_pid*.log"]
O que cada seção significa:
[module]: Metadados.name,versioneentrysão obrigatórios.log_patternextrai o nível de log de uma linha do console por meio de um grupo(?P<level>…). As chaves em[module.dependencies]sãosaba-core,ext-<id da extensão>e assim por diante.[permissions]: Declara as capacidades de risco que o código usa (network,spawn_process,native_code,dynamic_code,env_secrets,fs_outside_instance).[protocols]:supportedaceita"stdin","rest"e"rcon". A ordem dos caminhos de comando é stdin, depois REST, depois RCON. Use RCON só em um jogo que não tem console nem API REST. Esse jogo também precisa declararrcon_port, e o daemon define uma porta e uma senha aleatória para cada instância. Se o jogo tem console ou REST, o módulo desliga a configuração de RCON.interaction_modedecide se aparece uma tela de console (console) ou só botões de comando (commands).[config]:server_executable,executable_path,process_name,default_port,stop_command(comando de parada enviado ao console, padrãostop),stop_timeout(segundos, padrão 30),announce_command. As configurações do jogo vão em[[settings.fields]], não aqui.[[settings.fields]]: Itens da tela de configurações da instância (name,type,label,default,options,groupetc.). Os valores que o usuário altera são guardados como configurações da instância e chegam no config de cada chamada de função. Os itens cominstall = truesão valores escolhidos ao criar um servidor (tipo de servidor, configurações de um mundo novo etc.), perguntados pela tela de criação, pelo web e porserver addna CLI. Oinstall_optionsde um item select lista só os valores que o Saba-chan pode instalar de novo (o restante deoptionssó serve para reconhecer um servidor importado).[[commands.fields]]: Comandos do jogo. Commethod = "console"(+console_template) o comando vai para o console (stdin), com"rest"para a REST API do jogo, e com"module"(padrão) paracommand()nolifecycle.py.risk(safe/caution/danger) edescriptionsão lidos pela interpretação de comandos por IA.[install]: Método de instalação,app_id,requires_extensions(lista de ids de extensões necessárias) etc. O Palworld exige["steamcmd", "ue4-ini"].[detection]: Reconhecimento de pastas de servidor existentes (dir_signatures), localização de processos (process_patterns,cmd_patterns) e detecção de crashes (graceful_exit_patterns,crash_artifacts). Só as saídas consideradas crashes são reiniciadas automaticamente.[backup]: Caminhos a incluir nos backups (paths), o comando a executar logo antes de um backup (save_command) ehook = truequando os caminhos são calculados em código.[credential_map]: Mapeia as chaves padrão do daemon para as chaves de configuração do jogo. Exemplo do Palworld:rest_password = "AdminPassword".- Também existem
[launch],[[agreements]],[[presets]],[[queries]],[aliases],[errors],[[syntax_highlight.rules]]e[extensions.<id>]. Para a lista completa de chaves, vejadocs/module-spec.mdno repositóriosaba-chan-modules.
3. Contrato das funções do lifecycle.py
Sempre que precisa, o daemon inicia um novo processo Python para chamar uma função deste arquivo. Toda função recebe um único config: dict e devolve um dict, e precisa estar registrada na tabela FUNCTIONS no fim do arquivo. Os módulos não têm uma função start: o próprio daemon inicia o servidor a partir do resultado de get_launch_command.
3.1 Funções obrigatórias
A única função obrigatória é get_launch_command.
import os
from daemon_rcon import config_value, run_lifecycle
def get_launch_command(config: dict) -> dict:
"""Devolve como iniciar o servidor. O daemon cria o processo."""
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)
- O daemon espalha as configurações da instância (
module_settings) no nível superior do config. Lê-las comconfig_value(config, key, default)é o jeito seguro. - Se o config contiver
extra_args(argumentos de inicialização que o usuário adicionou), coloque-os onde devem ficar e devolvaextra_args_placed: true. Caso contrário, o daemon os acrescenta ao fim deargs. preview: truesignifica uma prévia dos argumentos de inicialização. Não grave arquivos de configuração; apenas devolva as informações de inicialização.
3.2 Funções opcionais
Implemente apenas os recursos que você suporta e, se implementar um, sempre o adicione à tabela FUNCTIONS.
| Função | Quando o daemon a chama | Retorno |
|---|---|---|
validate | Verificação antes do início | success, issues[] (o servidor não inicia se algum tiver severity: "critical") |
stop | Parada de servidores sem console e de servidores não gerenciados | success |
status | Consulta de status não gerenciada | status, pid |
command | Comandos com method = "module" | success, message |
get_credentials | Quando as informações de conexão REST são necessárias | rest_username, rest_password |
configure / read_properties / reset_properties / reset_server | Salvar / ler / redefinir na tela de configurações | success (+ valores lidos) |
import_settings | Importação de um servidor existente, leitura das configurações | settings{} |
list_versions / get_version_details | Lista de versões / detalhes | Informações de versão |
install_server | Instalação e atualização | success, executable_path, install_path |
get_installed_version | Consulta da versão instalada | version |
accept_agreements | Depois que o usuário aceita os [[agreements]] | success |
diagnose_log | Diagnóstico de log | success |
backup_paths | Backups (quando [backup] hook = true) | success, paths[] |
instance_commands | Lista de comandos (quando [commands] hook = true) | success, commands[] |
Regras comuns:
- Toda resposta inclui
success: boolemessage: str. Se for necessária uma ação do usuário, incluaaction_required: "<code>". - Se faltar uma extensão necessária, responda com
error_code: "extension_required"emissing_extensions: [...]. - Para um nome de função desconhecido, responda
{"success": false, "message": "Unknown function: X"}(orun_lifecycle()trata disso).
Para um servidor gerenciado com console, o daemon o para enviando
[config].stop_commandao console (stdin) e aguardando. Ostop()do módulo só é chamado quando não há console; ele precisa seguir a ordem pedido de parada graciosa → espera → encerramento forçado, e só mexer nopidque o daemon passou.
4. Protocolo de subprocesso
A forma como o daemon chama as funções do módulo está implementada em src/plugin/mod.rs do repositório do Saba-chan. Em resumo:
- Ele inicia
python lifecycle.py <nome da função>, usando o ambiente Python gerenciado pelo daemon. - Variáveis de ambiente injetadas:
PYTHONIOENCODING=utf-8,PYTHONUNBUFFERED=1PYTHONPATH: a pasta de módulos que contém os arquivos compartilhados (i18n.py,daemon_rcon.py) e a pasta pai da pasta de extensõesSABA_IPC_URL,SABA_IPC_PORT: endereço da API do daemonSABA_TOKEN_PATH: caminho do arquivo que contém o token da API do daemonSABA_LANG: idioma da GUISABA_ENABLED_EXTENSIONS: ids das extensões ativadas, separados por vírgula (por exemplo,steamcmd,ue4-ini)
- Ele grava um objeto JSON de config no stdin e o fecha.
- Ele interpreta todo o stdout como JSON; se isso falhar, usa a última linha não vazia como resultado.
- O stderr é o log. Linhas que começam com
PROGRESS:são interpretadas como eventos de progresso e usadas para exibir o andamento da instalação. - O código de saída precisa ser 0. Se não for, o daemon trata a chamada como um erro genérico, mesmo que o stdout contenha
success: false. - O processo encerra após cada chamada. O tempo limite padrão é de 120 segundos; só
install_serverdurante o provisionamento e as atualizações recebe mais (1800 segundos).
Módulos não verificados: um módulo que não vem do catálogo assinado do Saba-chan, ou que mudou depois do download, roda no AppContainer do Windows ou no bubblewrap do Linux. O Saba-chan não o verifica com antivírus. Onde não é possível isolar (Linux sem bubblewrap ou em que ele não funciona, e macOS), o Saba-chan só o executa depois que você concorda com os arquivos atuais. No isolamento, o módulo não pode se conectar ao loopback (use os utilitários compartilhados, e o daemon repassa a solicitação), não recebe
SABA_TOKEN_PATHe só pode gravar nas pastas da instância, de trabalho e de instalação, e nas pastas dedata_roots. Ele também não pode usarmsiexecnem pastas criadas portempfile.mkdtemp. Veja a lista completa em Criar um módulo: da pesquisa à publicação.
4.1 Exemplo de relatório de progresso
# 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")
# … download de fato …
report(2, 3, 70, "Extracting")
# …
report(3, 3, 100, "Install complete")
Os campos reconhecidos são percent, message, step, total e label.
5. Utilitários compartilhados
O daemon coloca os arquivos compartilhados i18n.py e daemon_rcon.py na pasta de módulos e a adiciona ao PYTHONPATH. Não os copie para a pasta do seu 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="…") # substitui {{error}} na string
daemon_stdin_command(config["instance_id"], "save-all") # envia uma linha ao console do servidor
O daemon_rcon.py mantém esse nome apenas por motivos históricos; ele nunca abre um socket RCON. Principais funções auxiliares:
| Função | Finalidade |
|---|---|
daemon_stdin_command(instance_id, line) | Envia um comando ao console de um servidor gerenciado pelo daemon |
daemon_post(path, payload) | Chama outras APIs do daemon (token adicionado automaticamente) |
is_process_alive, wait_for_exit, force_kill | Verificação / espera / encerramento forçado por PID |
config_value(config, key, default) | Encontra um valor de configuração no config |
run_lifecycle(FUNCTIONS) | Ponto de entrada de python lifecycle.py <function> |
Extensões ativadas podem ser importadas, por exemplo, from extensions.steamcmd import SteamCMD ou import extensions.ue4_ini. Extensões desativadas são bloqueadas por uma proteção de import (ModuleNotFoundError), então importe dentro da função e responda extension_required em caso de falha.
6. Referência: módulos embutidos
| Módulo | Porta padrão | Protocolo | Extensões necessárias | Observações |
|---|---|---|---|---|
minecraft | 25565 | stdin (console) | Nenhuma | Instalação download, detecção/download automático do Java, RCON forçado como desligado |
palworld | 8211 | REST API | steamcmd, ue4-ini | Jogo sem console. credential_map mapeia rest_password ↔ AdminPassword |
zomboid | 16261 | stdin (console) | steamcmd | stop_command = "quit", [backup] hook = true |
terraria | 7777 | stdin (pseudoconsole pty) | xna (Windows) | Instalação download, servidor Windows e Linux, [backup] hook = true |
Todos são construídos em torno de module.toml e lifecycle.py. Ao criar um novo módulo, recomendamos partir do __example ou do que for mais parecido entre esses quatro.
7. Regras de desenvolvimento (obrigatórias)
PRs de módulos precisam seguir estas regras.
- Sem dependência do código do daemon. Use apenas o config, as variáveis de ambiente e as APIs que o daemon fornece.
- Toda falha é JSON + código de saída 0. Responda com
success: falsee um motivo. - Os logs vão para o stderr. O stdout é para o JSON de resultado. Imprima tracebacks de exceções no stderr também; não engula erros.
- Use primeiro stdin, depois REST. Use RCON só em um jogo que não tem nenhum dos dois. Se o jogo tem console ou REST, desligue a configuração de RCON e não coloque
"rcon"emsupported. - Trate processos apenas pelo
pidque o daemon lhe dá. Finalizar pelo nome do executável também encerra outras instâncias do mesmo jogo. - Monte caminhos com
os.path.join; não os deixe fixos no código. - Verifique os mapeamentos de nomes de campos. Confira para qual chave de configuração do jogo cada nome de
[[settings.fields]]é mapeado, tanto emconfigurequanto emimport_settings. - Testes. Mantenha testes unitários em
test_lifecycle.pye passe no kit de conformidade (seção 8 abaixo).
8. Dicas de depuração
- O resultado é lido da última linha do stdout, então envie a saída de depuração para o stderr. Imprimir qualquer coisa depois do JSON de resultado quebra a interpretação.
- Você pode executar uma função diretamente sem o daemon. Adicione o
modules/do repositório do Saba-chan aoPYTHONPATHpara que odaemon_rconseja encontrado.echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command - Verifique o
module.tomlcom o mesmo parser que o daemon usa:saba-core module validate <pasta do módulo> - Kit de conformidade:
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules(no repositóriosaba-chan-modules) - Se o progresso não aparecer na GUI, confira se a linha do stderr começa exatamente com
PROGRESS:e se o JSON depois dela é válido. - Depois de editar um módulo, aplique a mudança também em
modules\<name>\na pasta de dados para que o daemon use o código mais recente. O daemon mantém a lista de módulos em cache, então, se você alterou omodule.toml, faça-o recarregar comPOST /api/modules/refresh.