Руководство по разработке расширений
10 реальных хуков Saba-chan и спецификация manifest.json, внедрение в слоты GUI и заметки о реализации встроенных расширений.
Руководство по разработке расширений
Расширение (плагин) — это дополнение, которое не привязано к конкретной игре, а глобально встраивается в жизненный цикл демона или внедряет компоненты в GUI. Демон Saba-chan передаёт управление включённым расширениям в следующих 10 точках (хуках). Сейчас в комплекте есть установка/обновление через SteamCMD (steamcmd) и парсер INI для UE4 (ue4-ini).
Содержание этого документа основано на реальных файлах manifest.json из репозитория saba-chan-extensions и на системе расширений на стороне демона (src/extension/mod.rs).
1. Структура файлов
- manifest.jsonобязательно. Объявляет хуки, зависимости, поляобязательно. Объявляет хуки, зависимости, поля
- __init__.pyпозволяет модулям импортировать расширение как extensions.<name>позволяет модулям импортировать расширение как extensions.<name>
- <python_modules>.pyфайлы, на которые ссылается python_modules в manifest.jsonфайлы, на которые ссылается python_modules в manifest.json
- icon.pngнеобязательнонеобязательно
- gui/необязательно. Исходники и результат сборки пакета GUI (UMD)необязательно. Исходники и результат сборки пакета GUI (UMD)
- i18n/необязательно. Задаётся через i18n_dir в манифесте (<locale>.json)необязательно. Задаётся через i18n_dir в манифесте (<locale>.json)
- test_<name>.pyрекомендуется. Тесты pytestрекомендуется. Тесты pytest
- Имя папки должно совпадать с
idв манифесте. Допускается и id, в котором дефисы заменены подчёркиваниями (например, idue4-ini→ папкаue4_ini). Иначе демон не загружает расширение и перечисляет его вfailedв ответеGET /api/extensions. - id может содержать только буквы, цифры,
-и_.
2. Спецификация manifest.json
Реальный манифест расширения SteamCMD:
{
"schema_version": 1, // при 1 неизвестные ключи и никогда не вызываемые хуки — ошибки
"id": "steamcmd", // совпадает с именем папки
"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": [], // зависимости от других расширений (массив или { "id": ">=x.y.z" })
"python_modules": {
"steamcmd": "steamcmd.py" // логическое имя → путь к файлу
},
"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 }
}
Сводка по полям:
schema_version: при1неизвестные ключи, имена хуков, отсутствующие вFIRED_HOOKS, и ссылки на несуществующиеpython_modulesявляются ошибками. Без него (0) это лишь предупреждения.id,name,version: обязательны.versionиспользуется при сравнении для обновлений и зависимостей.description/descriptions: описание на английском и описания по языкам. API списка выбирает то, что соответствует языку GUI.min_app_version: расширение нельзя включить или установить в более старой версии Saba-chan.dependencies: зависимости от других расширений (или отsaba-core). Поддерживаются только требования версии вида>=. При включении проверяется, что зависимости включены; автоматически они не включаются.python_modules: регистрирует по логическим именам Python-файлы, на которые ссылаются хуки и команды. Файлы, не зарегистрированные здесь, хуки вызвать не могут.hooks.<имя хука>module: логическое имя, объявленное вpython_modulesfunction: имя функции в этом файлеcondition(необязательно): поддерживается только формаinstance.ext_data.<key>. Хук выполняется только для экземпляров, у которых это значение истинно, является ненулевым числом или непустой строкой.
instance_fields: значения для каждого экземпляра, которые использует расширение (extension_data). Если хотя бы у одного экземпляра значение задано, выключение или удаление расширения отклоняется (in_use).config_fields: поля глобальных настроек расширения. Значения хранятся вextensions.settings.<id>вconfig.json.gui:bundle(путь к UMD-пакету),styles(путь к CSS). См. раздел 5 ниже.cli: объявления слотов CLI (cli.slots).commands: команды, добавляемые в список команд экземпляра (name,label,risk,inputs,module,function,condition).priority: порядок, когда у нескольких расширений один и тот же хук (меньшее значение выполняется раньше, по умолчанию 100).i18n_dir: папка с файлами переводов.permissions: объявляет рискованные возможности, которые использует код (та же таблица, что и[permissions]модуля).
У хуков нет поля
async, а в манифесте нетmanifest_url. Список расширений и обновления берутся только из подписанного манифеста релизов Saba-chan.
3. 10 реальных хуков
Функции хуков выполняются так же, как модули. Демон запускает python <файл>.py <имя функции>, записывает в stdin JSON контекста и читает JSON из stdout (целиком или последнюю строку) как результат. Код выхода должен быть 0. Список ниже совпадает с FIRED_HOOKS в коде демона.
| Имя хука | Когда вызывается | Как используется результат | Выполнение |
|---|---|---|---|
daemon.startup | Сразу после запуска демона / сразу после включения расширения (только для этого расширения) | success/message попадают в состояние инициализации (/api/extensions/init-status) | В фоне |
daemon.shutdown | Непосредственно перед завершением демона | Только записывается в журнал | Синхронно |
server.pre_start | Непосредственно перед запуском сервера | handled: true заменяет стандартный запуск (если при этом success не истинно, запуск завершается ошибкой) | Синхронно |
server.stop | Непосредственно перед остановкой сервера | handled: true берёт остановку на себя | Синхронно |
server.status | При запросе состояния отдельного сервера | handled: true возвращает этот результат как есть | Синхронно |
server.list_enrich | При выводе списка экземпляров | handled: true заполняет status и extension_status. Тайм-аут 10 с, кеш с TTL 30 с | Синхронно |
server.post_create | Сразу после создания экземпляра | Результат не используется | В фоне |
server.pre_delete | Непосредственно перед удалением экземпляра | При handled демон немного ждёт, чтобы освободились блокировки файлов | Синхронно |
server.settings_changed | После сохранения настроек экземпляра | Результат не используется | Синхронно |
server.check_update | При запросе проверки обновлений | Ответом становится первый успешный результат | Синхронно |
Таких имён, как
server.pre_create,server.pre_install,server.post_install,server.post_start,module.parse_settingsиmodule.write_settings, не существует; их использование в манифесте сschema_version = 1приводит к ошибке загрузки.
3.1 Контекст и точка входа
Функция хука принимает один словарь контекста и возвращает словарь. В зависимости от хука контекст содержит instance_id, instance_name, module, instance_dir, extension_data и т. д., а каждый хук также получает глобальные настройки расширений как extension_config. Python-файл должен сам обрабатывать имя функции и stdin в __main__. Сокращённый пример структуры steamcmd.py:
import json, sys, traceback
def check_update(ctx: dict) -> dict:
"""
пример 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) # журналы — в stderr
result = {"success": False, "message": str(e)}
print(json.dumps(result, ensure_ascii=False)) # ошибки тоже — JSON + код выхода 0
3.2 handled и порядок выполнения
- Расширения с одним и тем же хуком выполняются по одному, по порядку
priority, затем по id. - Если результат содержит
handled: true, оставшиеся расширения пропускаются. Не указывайтеhandled, если вы не заменяете стандартное поведение этого хука. - Если одно расширение завершилось ошибкой, ошибка записывается, и выполняется следующее расширение.
- Лимит времени по умолчанию — 120 секунд. На пути хуков отображения прогресса (
PROGRESS:) нет.
3.3 Кеш с TTL для server.list_enrich
Этот хук может вызываться друг за другом для каждого экземпляра с extension_data при каждом запросе списка экземпляров, поэтому демон кеширует успешные результаты на 30 секунд. Пока кеш действителен, демон повторно использует прежний результат, не запуская процесс Python. У каждого вызова тайм-аут 10 секунд, так что проектируйте хук так, чтобы он завершался быстро. status_line в результате — это короткое однострочное состояние, которое показывается в отображении состояния в Discord, поэтому не помещайте в него пути и секреты.
4. 3 встроенных расширения
steamcmd
- id:
steamcmd - Python:
steamcmd.py(классSteamCMD: портативная установка SteamCMD, установка/обновление игровых серверов, проверка обновлений) - Хук: только
server.check_update(condition: instance.ext_data.install_method_steamcmd). - Саму установку выполняет
install_serverмодуля напрямую черезfrom extensions.steamcmd import SteamCMD. - instance_fields:
install_method_steamcmd,steamcmd_app_id,steamcmd_anonymous,steamcmd_beta,steamcmd_platform. Демон заполняет их из секции[install]модуля по общему правилу (install_method_<method>,<method>_<field>). - GUI нет.
ue4-ini
- id:
ue4-ini(имя папкиue4_ini) - Python:
ue4_ini.py(parse_option_settings,write_option_settings) - Назначение: предоставляет модулям утилиты для чтения и записи
OptionSettings=(...)в INI игр на UE4, например Palworld. - Это чистая библиотека, не объявляющая хуков; модули импортируют её как
extensions.ue4_ini.
xna
- id:
xna - Python:
xna.py(install,present,XnaError) - Назначение: кладёт фиксированную версию Microsoft XNA Framework 4.0 Refresh рядом с папкой игрового сервера, не устанавливая её на ПК. Нужна Windows-серверу Terraria. Один раз загружает официальный MSI, сверяет его по зафиксированному SHA-256 и извлекает только нужные файлы.
- Это чистая библиотека, не объявляющая хуков; модули используют её через
from extensions.xna import install, present.
Модули не могут импортировать выключенные расширения. Защита импорта демона блокирует импорт любого
extensions.<name>, которого нет вSABA_ENABLED_EXTENSIONS.
5. Пакет GUI (внедрение в слоты)
Если в manifest.json объявлен gui.bundle, GUI получает этот файл через GET /api/extensions/:id/gui и выполняет его (а если задан gui.styles, внедряет и CSS).
"gui": { "bundle": "gui/dist/index.umd.js", "styles": "gui/dist/style.css" } // пути для примера
- Пакет должен быть в формате UMD и создавать глобальный объект
window.SabaExt<id в PascalCase>. Уберите из id-и_и сделайте следующую за ними букву заглавной (например,steamcmd→window.SabaExtSteamcmd,ue4-ini→window.SabaExtUe4Ini). - Когда
registerSlots()этого объекта возвращает{ slotId: Component | Component[] }, GUI монтирует их в соответствующие слоты. - React подключается как внешняя зависимость из
window.Reactхоста. Компоненты должны работать, используя только props, которые передаёт слот. - Переводы загружаются через
GET /api/extensions/:id/i18n/:localeв пространство имёнext_<id>.
| Id слота | Где | props |
|---|---|---|
ServerCard.badge | Значок на карточке сервера | server |
ServerCard.headerGauge | Индикатор в заголовке карточки сервера | server |
ServerCard.provision | Карточка сервера во время подготовки | server, provisionProgress, onDismiss, t |
ServerCard.expandedStats | Статистика развёрнутой карточки сервера | server, t |
ServerSettings.tab | Вкладка настроек сервера | server, activeTab, setActiveTab, settings, onSettingsChange, t |
AddServer.options | Параметры добавления сервера | t |
server — это сведения о сервере из /api/servers; компоненты могут читать extension_data и extension_status[<extension_id>] (результат server.list_enrich).
6. Управление расширениями через REST API
GET /api/extensions Список установленных (+ ошибки загрузки)
GET /api/extensions/init-status Результаты daemon.startup
POST /api/extensions/rescan Перечитать папку
GET /api/extensions/manifest Удалённый каталог (подписанный манифест релизов)
GET /api/extensions/updates Список обновлений
POST /api/extensions/:id/install Установить (из каталога, со сверкой sha256)
POST /api/extensions/:id/enable Включить → выполняет daemon.startup этого расширения
POST /api/extensions/:id/disable Выключить
POST /api/extensions/:id/mount Зарегистрировать в памяти
POST /api/extensions/:id/unmount Снять регистрацию в памяти
DELETE /api/extensions/:id Удалить
GET /api/extensions/:id/config Значения config_fields
PUT /api/extensions/:id/config Обновить значения
GET /api/extensions/:id/gui Пакет GUI (JS)
GET /api/extensions/:id/gui/styles Стили GUI (CSS)
GET /api/extensions/:id/icon Значок
GET /api/extensions/:id/audit Сравнить возможности, используемые кодом, с permissions
GET /api/extensions/:id/i18n/:locale JSON локализации
Список включённых расширений хранится в extensions.enabled в config.json, а значения глобальных настроек — в extensions.settings.
7. Правила разработки
- Расширения тоже не должны зависеть от кода демона. Используйте только контекст и переменные окружения, которые передаёт демон.
- Собирайте пути через
os.path.join; не прописывайте их жёстко. - Функции хуков тоже отвечают на ошибки JSON-ом (
success: falseс причиной) и кодом выхода 0, а журналы и трассировки отправляют в stderr. - Для
conditionиспользуйте только формуinstance.ext_data.<key>. Любая другая форма всегда даёт ложь. - Python-зависимости используют общее окружение демона. Отдельного объявления requirements для расширения нет.
- Непроверенные расширения: расширения, загруженные не из подписанного каталога или изменённые после загрузки, работают в той же изолированной среде, что и модули (AppContainer в Windows, bubblewrap в Linux). Антивирусная проверка не выполняется. Далее описана Windows. Им недоступен loopback (например, API демона), они не получают
SABA_TOKEN_PATHи могут только читать папки экземпляров. Данные, которые нужно записывать, кладите в выделенную папку, на которую указывает переменная окруженияSABA_EXTENSION_DATA_DIR. - Тесты запускайте командой
pytestиз корня репозитория.