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

%APPDATA%\saba-chan\modules\<module_name>\
  • 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].name no module.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].entry esteja ausente.
  • Para começar, recomendamos copiar __example/__example__module.toml para module.toml e __example/__example__lifecycle.py para lifecycle.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, version e entry são obrigatórios. log_pattern extrai o nível de log de uma linha do console por meio de um grupo (?P<level>…). As chaves em [module.dependencies] são saba-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]: supported aceita "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 declarar rcon_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_mode decide 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ão stop), 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, group etc.). 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 com install = true sã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 por server add na CLI. O install_options de um item select lista só os valores que o Saba-chan pode instalar de novo (o restante de options só serve para reconhecer um servidor importado).
  • [[commands.fields]]: Comandos do jogo. Com method = "console" (+ console_template) o comando vai para o console (stdin), com "rest" para a REST API do jogo, e com "module" (padrão) para command() no lifecycle.py. risk (safe/caution/danger) e description sã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) e hook = true quando 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, veja docs/module-spec.md no repositório saba-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 com config_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 devolva extra_args_placed: true. Caso contrário, o daemon os acrescenta ao fim de args.
  • preview: true significa 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çãoQuando o daemon a chamaRetorno
validateVerificação antes do iníciosuccess, issues[] (o servidor não inicia se algum tiver severity: "critical")
stopParada de servidores sem console e de servidores não gerenciadossuccess
statusConsulta de status não gerenciadastatus, pid
commandComandos com method = "module"success, message
get_credentialsQuando as informações de conexão REST são necessáriasrest_username, rest_password
configure / read_properties / reset_properties / reset_serverSalvar / ler / redefinir na tela de configuraçõessuccess (+ valores lidos)
import_settingsImportação de um servidor existente, leitura das configuraçõessettings{}
list_versions / get_version_detailsLista de versões / detalhesInformações de versão
install_serverInstalação e atualizaçãosuccess, executable_path, install_path
get_installed_versionConsulta da versão instaladaversion
accept_agreementsDepois que o usuário aceita os [[agreements]]success
diagnose_logDiagnóstico de logsuccess
backup_pathsBackups (quando [backup] hook = true)success, paths[]
instance_commandsLista de comandos (quando [commands] hook = true)success, commands[]

Regras comuns:

  • Toda resposta inclui success: bool e message: str. Se for necessária uma ação do usuário, inclua action_required: "<code>".
  • Se faltar uma extensão necessária, responda com error_code: "extension_required" e missing_extensions: [...].
  • Para um nome de função desconhecido, responda {"success": false, "message": "Unknown function: X"} (o run_lifecycle() trata disso).

Para um servidor gerenciado com console, o daemon o para enviando [config].stop_command ao console (stdin) e aguardando. O stop() 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 no pid que 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:

  1. Ele inicia python lifecycle.py <nome da função>, usando o ambiente Python gerenciado pelo daemon.
  2. Variáveis de ambiente injetadas:
    • PYTHONIOENCODING=utf-8, PYTHONUNBUFFERED=1
    • PYTHONPATH: a pasta de módulos que contém os arquivos compartilhados (i18n.py, daemon_rcon.py) e a pasta pai da pasta de extensões
    • SABA_IPC_URL, SABA_IPC_PORT: endereço da API do daemon
    • SABA_TOKEN_PATH: caminho do arquivo que contém o token da API do daemon
    • SABA_LANG: idioma da GUI
    • SABA_ENABLED_EXTENSIONS: ids das extensões ativadas, separados por vírgula (por exemplo, steamcmd,ue4-ini)
  3. Ele grava um objeto JSON de config no stdin e o fecha.
  4. Ele interpreta todo o stdout como JSON; se isso falhar, usa a última linha não vazia como resultado.
  5. 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.
  6. 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.
  7. O processo encerra após cada chamada. O tempo limite padrão é de 120 segundos; só install_server durante 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_PATH e só pode gravar nas pastas da instância, de trabalho e de instalação, e nas pastas de data_roots. Ele também não pode usar msiexec nem pastas criadas por tempfile.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çãoFinalidade
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_killVerificaçã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óduloPorta padrãoProtocoloExtensões necessáriasObservações
minecraft25565stdin (console)NenhumaInstalação download, detecção/download automático do Java, RCON forçado como desligado
palworld8211REST APIsteamcmd, ue4-iniJogo sem console. credential_map mapeia rest_password ↔ AdminPassword
zomboid16261stdin (console)steamcmdstop_command = "quit", [backup] hook = true
terraria7777stdin (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.

  1. Sem dependência do código do daemon. Use apenas o config, as variáveis de ambiente e as APIs que o daemon fornece.
  2. Toda falha é JSON + código de saída 0. Responda com success: false e um motivo.
  3. 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.
  4. 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" em supported.
  5. Trate processos apenas pelo pid que o daemon lhe dá. Finalizar pelo nome do executável também encerra outras instâncias do mesmo jogo.
  6. Monte caminhos com os.path.join; não os deixe fixos no código.
  7. Verifique os mapeamentos de nomes de campos. Confira para qual chave de configuração do jogo cada nome de [[settings.fields]] é mapeado, tanto em configure quanto em import_settings.
  8. Testes. Mantenha testes unitários em test_lifecycle.py e 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 ao PYTHONPATH para que o daemon_rcon seja encontrado.
    echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command
    
  • Verifique o module.toml com 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ório saba-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 o module.toml, faça-o recarregar com POST /api/modules/refresh.