Руководство по разработке модулей
Как создать Python-модуль, добавляющий в Saba-chan новую игру. Описывает схему module.toml, а также реальный контракт функций и протокол lifecycle.py.
Руководство по разработке модулей (Python)
Демон Saba-chan не знает особенностей конкретных игр. Вместо этого каждая игра описывается Python-модулем. Добавив один модуль, вы позволяете Saba-chan управлять новой игрой.
Этот документ основан на реальных модулях из репозитория saba-chan-modules (minecraft, palworld, zomboid), шаблоне с комментариями __example и коде демона.
1. Структура файлов модуля
- 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. Вкратце:
- Он запускает
python lifecycle.py <имя функции>в окружении Python, которым управляет демон. - Передаваемые переменные окружения:
PYTHONIOENCODING=utf-8,PYTHONUNBUFFERED=1PYTHONPATH: папка модулей с общими файлами (i18n.py,daemon_rcon.py) и родительская папка папки расширенийSABA_IPC_URL,SABA_IPC_PORT: адрес API демонаSABA_TOKEN_PATH: путь к файлу с токеном API демонаSABA_LANG: язык GUISABA_ENABLED_EXTENSIONS: id включённых расширений через запятую (например,steamcmd,ue4-ini)
- Он записывает в stdin один JSON-объект config и закрывает его.
- Он разбирает весь stdout как JSON; если это не удаётся, результатом считается последняя непустая строка.
- stderr — это журнал. Строки, начинающиеся с
PROGRESS:, разбираются как события прогресса и используются для отображения хода установки. - Код выхода должен быть 0. Иначе демон считает вызов общей ошибкой, даже если в stdout есть
success: false. - Процесс завершается после каждого вызова. Лимит времени по умолчанию — 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. Справка: встроенные модули
| Модуль | Порт по умолчанию | Протокол | Нужные расширения | Примечания |
|---|---|---|---|---|
minecraft | 25565 | stdin (консоль) | Нет | Установка download, автоопределение/загрузка Java, RCON принудительно выключен |
palworld | 8211 | REST API | steamcmd, ue4-ini | Игра без консоли. credential_map сопоставляет rest_password ↔ AdminPassword |
zomboid | 16261 | stdin (консоль) | steamcmd | stop_command = "quit", [backup] hook = true |
terraria | 7777 | stdin (псевдоконсоль pty) | xna (Windows) | Установка download, серверы для Windows и Linux, [backup] hook = true |
Все они построены вокруг module.toml и lifecycle.py. Создавая новый модуль, рекомендуем начинать с __example или с наиболее похожего из этих четырёх.
7. Правила разработки (обязательные)
PR с модулями должны соблюдать эти правила.
- Никакой зависимости от кода демона. Используйте только config, переменные окружения и API, которые предоставляет демон.
- Любая ошибка — это JSON + код выхода 0. Отвечайте
success: falseс указанием причины. - Журналы — в stderr. stdout предназначен для JSON-результата. Трассировки исключений тоже выводите в stderr; не глушите ошибки.
- Сначала stdin, затем REST. RCON используйте только для игры, где нет ни того, ни другого. Если у игры есть консоль или REST, выключите её настройку RCON и не указывайте
"rcon"вsupported. - Работайте с процессами только по
pid, который передаёт демон. Завершение по имени исполняемого файла остановит и другие экземпляры той же игры. - Собирайте пути через
os.path.join; не прописывайте их жёстко. - Проверяйте сопоставление имён полей. Убедитесь, с каким ключом игровой настройки сопоставлено каждое имя из
[[settings.fields]], и вconfigure, и вimport_settings. - Тесты. Держите модульные тесты в
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.