Руководство по разработке модулей

Как создать Python-модуль, добавляющий в Saba-chan новую игру. Описывает схему module.toml, а также реальный контракт функций и протокол lifecycle.py.

Руководство по разработке модулей (Python)

Демон Saba-chan не знает особенностей конкретных игр. Вместо этого каждая игра описывается Python-модулем. Добавив один модуль, вы позволяете Saba-chan управлять новой игрой.

Этот документ основан на реальных модулях из репозитория saba-chan-modules (minecraft, palworld, zomboid), шаблоне с комментариями __example и коде демона.


1. Структура файлов модуля

%APPDATA%\saba-chan\modules\<module_name>\
  • module.tomlобязательно. Объявления (schema v1)обязательно. Объявления (schema v1)
  • lifecycle.pyобязательно. Входной файл, указанный в [module].entryобязательно. Входной файл, указанный в [module].entry
  • icon.pngнеобязательно. Задаётся через [module].iconнеобязательно. Задаётся через [module].icon
  • locales/
  • en.jsonэталонный языкэталонный язык
  • ko.json
  • ...строки интерфейсастроки интерфейса
  • test_lifecycle.pyнеобязательно. Модульные тесты pytest (рекомендуется)необязательно. Модульные тесты pytest (рекомендуется)
  • Назовите папку так же, как [module].name в module.toml, строчными латинскими буквами.
  • Демон читает только папки первого уровня в корне модулей, содержащие module.toml, и не загружает модуль, если файла [module].entry нет.
  • Для начала рекомендуем скопировать __example/__example__module.toml в module.toml и __example/__example__lifecycle.py в lifecycle.py, а затем удалить ненужное.

2. Спецификация module.toml

Сокращённый пример начала реального minecraft/module.toml:

[module]
schema_version = 1                # обязательно. Неизвестные ключи или неверные значения приводят к ошибке загрузки
name = "minecraft"                # совпадает с именем папки
version = "0.1.0"
display_name = "Minecraft"
game_name = "Minecraft"
entry = "lifecycle.py"            # Python-файл, который запускает демон
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"             # компонент → минимальная версия (только ">=")

[permissions]
network = true                    # возможности, которые использует код
spawn_process = true

[protocols]
supported = ["stdin"]             # из "stdin" / "rest"
default = "stdin"
interaction_mode = "console"      # "console" или "commands"

[config]
server_executable = "server.jar"
process_name = "java.exe"
default_port = 25565
announce_command = "say"          # имя из [[commands.fields]], используемое для объявлений
# если stop_command не указан, по умолчанию используется "stop"

[backup]
paths = ["{level_name}", "{level_name}_nether", "{level_name}_the_end"]
save_command = "save-all"

[install]
method = "download"               # "manual" (по умолчанию) / "download" / id расширения (например, "steamcmd")

[detection]
dir_signatures = ["server.jar"]
graceful_exit_patterns = ["Stopping the server"]
crash_artifacts = ["crash-reports/*.txt", "hs_err_pid*.log"]

Что означает каждая секция:

  • [module]: метаданные. name, version и entry обязательны. log_pattern извлекает уровень журнала из строки консоли через группу (?P<level>…). Ключи в [module.dependencies] — saba-core, ext-<id расширения> и т. д.
  • [permissions]: объявляет рискованные возможности, которые использует код (network, spawn_process, native_code, dynamic_code, env_secrets, fs_outside_instance).
  • [protocols]: supported принимает "stdin", "rest" и "rcon". Порядок путей для команд: stdin, затем REST, затем RCON. RCON используется только для игры без консоли и без REST API. Такая игра также должна объявить rcon_port, и демон назначает каждому экземпляру порт и случайный пароль. Если у игры есть консоль или REST, модуль выключает её настройку RCON. interaction_mode определяет, показывать ли окно консоли (console) или только кнопки команд (commands).
  • [config]: server_executable, executable_path, process_name, default_port, stop_command (команда остановки, отправляемая в консоль, по умолчанию stop), stop_timeout (секунды, по умолчанию 30), announce_command. Игровые настройки описываются в [[settings.fields]], а не здесь.
  • [[settings.fields]]: элементы экрана настроек экземпляра (name, type, label, default, options, group и т. д.). Значения, которые меняет пользователь, сохраняются как настройки экземпляра и приходят в config при каждом вызове функции.
  • [[commands.fields]]: игровые команды. С method = "console" (+ console_template) команда идёт в консоль (stdin), с "rest" — в REST API игры, а с "module" (по умолчанию) — в command() в lifecycle.py. risk (safe/caution/danger) и description используются при ИИ-интерпретации команд.
  • [install]: способ установки, app_id, requires_extensions (список id нужных расширений) и т. д. Palworld требует ["steamcmd", "ue4-ini"].
  • [detection]: распознавание существующих папок серверов (dir_signatures), поиск процессов (process_patterns, cmd_patterns) и обнаружение сбоев (graceful_exit_patterns, crash_artifacts). Автоматически перезапускаются только завершения, признанные сбоями.
  • [backup]: пути, включаемые в бэкап (paths), команда, выполняемая непосредственно перед бэкапом (save_command), и hook = true, если пути вычисляются в коде.
  • [credential_map]: сопоставляет стандартные ключи демона с ключами игровых настроек. Пример для Palworld: rest_password = "AdminPassword".
  • Есть также [launch], [[agreements]], [[presets]], [[queries]], [aliases], [errors], [[syntax_highlight.rules]] и [extensions.<id>]. Полный список ключей — в docs/module-spec.md репозитория saba-chan-modules.

3. Контракт функций lifecycle.py

Всякий раз, когда это нужно, демон запускает новый процесс Python, чтобы вызвать одну функцию из этого файла. Каждая функция принимает один config: dict и возвращает dict и должна быть зарегистрирована в таблице FUNCTIONS в конце файла. У модулей нет функции start: демон сам запускает сервер по результату get_launch_command.

3.1 Обязательные функции

Единственная обязательная функция — get_launch_command.

import os
from daemon_rcon import config_value, run_lifecycle

def get_launch_command(config: dict) -> dict:
    """Возвращает способ запуска сервера. Процесс создаёт демон."""
    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)
  • Демон раскладывает настройки экземпляра (module_settings) на верхний уровень config. Безопаснее всего читать их через config_value(config, key, default).
  • Если в config есть extra_args (аргументы запуска, добавленные пользователем), поставьте их туда, где им место, и верните extra_args_placed: true. Иначе демон допишет их в конец args.
  • preview: true означает предпросмотр аргументов запуска. Не записывайте файлы настроек; просто верните сведения о запуске.

3.2 Необязательные функции

Реализуйте только те возможности, которые поддерживаете, и, реализовав функцию, обязательно добавьте её в таблицу FUNCTIONS.

ФункцияКогда демон её вызываетЧто возвращает
validateПредстартовая проверкаsuccess, issues[] (сервер не запустится, если у какой-либо проблемы severity: "critical")
stopОстановка серверов без консоли и неуправляемых серверовsuccess
statusЗапрос состояния неуправляемого сервераstatus, pid
commandКоманды с method = "module"success, message
get_credentialsКогда нужны данные REST-подключенияrest_username, rest_password
configure / read_properties / reset_properties / reset_serverСохранение / чтение / сброс на экране настроекsuccess (+ прочитанные значения)
import_settingsИмпорт существующего сервера, чтение настроекsettings{}
list_versions / get_version_detailsСписок версий / подробностиСведения о версии
install_serverУстановка и обновлениеsuccess, executable_path, install_path
get_installed_versionЗапрос установленной версииversion
accept_agreementsПосле того как пользователь принял [[agreements]]success
diagnose_logДиагностика журналаsuccess
backup_pathsБэкапы (при [backup] hook = true)success, paths[]
instance_commandsСписок команд (при [commands] hook = true)success, commands[]

Общие правила:

  • Каждый ответ содержит success: bool и message: str. Если требуется действие пользователя, добавьте action_required: "<code>".
  • Если нужного расширения нет, ответьте с error_code: "extension_required" и missing_extensions: [...].
  • На неизвестное имя функции отвечайте {"success": false, "message": "Unknown function: X"} (это делает run_lifecycle()).

Управляемый сервер с консолью демон останавливает, отправляя [config].stop_command в консоль (stdin) и ожидая завершения. stop() модуля вызывается только при отсутствии консоли; он должен соблюдать порядок «запрос корректной остановки → ожидание → принудительное завершение» и трогать только тот pid, который передал демон.


4. Протокол подпроцесса

То, как демон вызывает функции модуля, реализовано в src/plugin/mod.rs репозитория Saba-chan. Вкратце:

  1. Он запускает python lifecycle.py <имя функции> в окружении Python, которым управляет демон.
  2. Передаваемые переменные окружения:
    • PYTHONIOENCODING=utf-8, PYTHONUNBUFFERED=1
    • PYTHONPATH: папка модулей с общими файлами (i18n.py, daemon_rcon.py) и родительская папка папки расширений
    • SABA_IPC_URL, SABA_IPC_PORT: адрес API демона
    • SABA_TOKEN_PATH: путь к файлу с токеном API демона
    • SABA_LANG: язык GUI
    • SABA_ENABLED_EXTENSIONS: id включённых расширений через запятую (например, steamcmd,ue4-ini)
  3. Он записывает в stdin один JSON-объект config и закрывает его.
  4. Он разбирает весь stdout как JSON; если это не удаётся, результатом считается последняя непустая строка.
  5. stderr — это журнал. Строки, начинающиеся с PROGRESS:, разбираются как события прогресса и используются для отображения хода установки.
  6. Код выхода должен быть 0. Иначе демон считает вызов общей ошибкой, даже если в stdout есть success: false.
  7. Процесс завершается после каждого вызова. Лимит времени по умолчанию — 120 секунд; больше (1800 секунд) получает только install_server при подготовке сервера и обновлениях.

Непроверенные модули: модуль, полученный не из подписанного каталога Saba-chan или изменённый после загрузки, запускается в Windows в AppContainer, в Linux в bubblewrap. Saba-chan не проверяет его антивирусом. Там, где изолировать нельзя (Linux без bubblewrap или с неработающим bubblewrap, macOS), Saba-chan запускает такой модуль только после вашего согласия для текущих файлов. В изоляции модуль не может подключаться к loopback (используйте общие помощники, и демон передаст запрос), не получает SABA_TOKEN_PATH и может писать только в папки экземпляра, рабочую и установки, а также в папки из data_roots. Ему также недоступны msiexec и папки, которые создаёт tempfile.mkdtemp. Полный список: Создание модуля: от исследования до выпуска.

4.1 Пример отчёта о прогрессе

# Внутри 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")
# … сама загрузка …
report(2, 3, 70, "Extracting")
# …
report(3, 3, 100, "Install complete")

Распознаются поля percent, message, step, total и label.


5. Общие утилиты

Демон кладёт общие файлы i18n.py и daemon_rcon.py в папку модулей и добавляет её в PYTHONPATH. Не копируйте их в папку своего модуля.

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="…")  # подставляет значение вместо {{error}} в строке

daemon_stdin_command(config["instance_id"], "save-all")  # отправить одну строку в консоль сервера

daemon_rcon.py носит это имя только по историческим причинам; он никогда не открывает RCON-сокет. Основные вспомогательные функции:

ФункцияНазначение
daemon_stdin_command(instance_id, line)Отправить команду в консоль сервера, которым управляет демон
daemon_post(path, payload)Вызвать другие API демона (токен добавляется автоматически)
is_process_alive, wait_for_exit, force_killПроверка / ожидание / принудительное завершение по PID
config_value(config, key, default)Найти значение настройки в config
run_lifecycle(FUNCTIONS)Точка входа для python lifecycle.py <function>

Включённые расширения можно импортировать, например from extensions.steamcmd import SteamCMD или import extensions.ue4_ini. Выключенные расширения блокируются защитой импорта (ModuleNotFoundError), поэтому импортируйте их внутри функции и при неудаче отвечайте extension_required.


6. Справка: встроенные модули

МодульПорт по умолчаниюПротоколНужные расширенияПримечания
minecraft25565stdin (консоль)НетУстановка download, автоопределение/загрузка Java, RCON принудительно выключен
palworld8211REST APIsteamcmd, ue4-iniИгра без консоли. credential_map сопоставляет rest_password ↔ AdminPassword
zomboid16261stdin (консоль)steamcmdstop_command = "quit", [backup] hook = true
terraria7777stdin (псевдоконсоль pty)xna (Windows)Установка download, серверы для Windows и Linux, [backup] hook = true

Все они построены вокруг module.toml и lifecycle.py. Создавая новый модуль, рекомендуем начинать с __example или с наиболее похожего из этих четырёх.


7. Правила разработки (обязательные)

PR с модулями должны соблюдать эти правила.

  1. Никакой зависимости от кода демона. Используйте только config, переменные окружения и API, которые предоставляет демон.
  2. Любая ошибка — это JSON + код выхода 0. Отвечайте success: false с указанием причины.
  3. Журналы — в stderr. stdout предназначен для JSON-результата. Трассировки исключений тоже выводите в stderr; не глушите ошибки.
  4. Сначала stdin, затем REST. RCON используйте только для игры, где нет ни того, ни другого. Если у игры есть консоль или REST, выключите её настройку RCON и не указывайте "rcon" в supported.
  5. Работайте с процессами только по pid, который передаёт демон. Завершение по имени исполняемого файла остановит и другие экземпляры той же игры.
  6. Собирайте пути через os.path.join; не прописывайте их жёстко.
  7. Проверяйте сопоставление имён полей. Убедитесь, с каким ключом игровой настройки сопоставлено каждое имя из [[settings.fields]], и в configure, и в import_settings.
  8. Тесты. Держите модульные тесты в test_lifecycle.py и проходите набор проверки соответствия (раздел 8 ниже).

8. Советы по отладке

  • Результат читается из последней строки stdout, поэтому отладочный вывод отправляйте в stderr. Любой вывод после JSON-результата ломает разбор.
  • Функцию можно запустить напрямую, без демона. Добавьте modules/ репозитория Saba-chan в PYTHONPATH, чтобы находился daemon_rcon.
    echo '{"server_executable": "C:/Games/MyGame/GameServer.exe", "port": 7777}' | python lifecycle.py get_launch_command
    
  • Проверить module.toml тем же парсером, что использует демон: saba-core module validate <папка модуля>
  • Набор проверки соответствия: pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules (в репозитории saba-chan-modules)
  • Если прогресс не отображается в GUI, проверьте, что строка stderr начинается ровно с PROGRESS: и что JSON после него корректен.
  • После правки модуля примените изменения и в modules\<name>\ в папке данных, чтобы демон использовал свежий код. Демон кеширует список модулей, поэтому если вы изменили module.toml, заставьте его перечитать модули через POST /api/modules/refresh.