エクステンション開発ガイド
サバちゃんの実際の10個のフックと manifest.json の仕様、GUI の slot 注入、そして同梱エクステンションの実装上のポイント。
エクステンション開発ガイド
エクステンション(プラグイン)は、特定のゲームに結び付かず、デーモンのライフサイクル全体にフックする アドオン、または GUI にコンポーネントを注入するアドオンです。サバちゃんのデーモンは、次の10か所(フック)で有効なエクステンションに制御を渡します。現在の同梱エクステンションは、SteamCMD によるインストール/アップデート(steamcmd)と UE4 INI パーサー(ue4-ini)です。
このドキュメントの内容は、saba-chan-extensions リポジトリの実際の manifest.json ファイルと、デーモン側のエクステンションシステム(src/extension/mod.rs)に基づいています。
1. ファイル構成
- manifest.json必須。フック、依存関係、フィールドを宣言必須。フック、依存関係、フィールドを宣言
- __init__.pyモジュールから extensions.<name> として import できるようにするモジュールから extensions.<name> として import できるようにする
- <python_modules>.pymanifest.json の python_modules で参照するファイルmanifest.json の python_modules で参照するファイル
- icon.png任意任意
- gui/任意。GUI バンドル (UMD) のソースとビルド出力任意。GUI バンドル (UMD) のソースとビルド出力
- i18n/任意。manifest の i18n_dir で指定 (<locale>.json)任意。manifest の i18n_dir で指定 (<locale>.json)
- test_<name>.py推奨。pytest のテスト推奨。pytest のテスト
- フォルダー名は manifest の
idと一致させる必要があります。id のハイフンをアンダースコアに置き換えた名前も認められます(例:idue4-ini→ フォルダーue4_ini)。それ以外の場合、デーモンは読み込まず、GET /api/extensionsのfailedに表示します。 - id に使えるのは英字、数字、
-、_だけです。
2. manifest.json の仕様
SteamCMD エクステンションの実際の manifest です。
{
"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: これより古いサバちゃんでは、エクステンションを有効化もインストールもできません。dependencies: 他のエクステンション(またはsaba-core)への依存。バージョン要件は>=だけに対応しています。有効化するときに依存先が有効かどうかを確認しますが、自動で有効化はしません。python_modules: フックとコマンドが参照する Python ファイルを論理名で登録します。ここに登録されていないファイルはフックから呼び出せません。hooks.<フック名>module:python_modulesで宣言した論理名function: そのファイル内の関数名condition(任意):instance.ext_data.<key>の形式だけに対応しています。その値が true、0 以外の数値、または空でない文字列であるインスタンスでのみフックが実行されます。
instance_fields: このエクステンションが使うインスタンスごとの値(extension_data)。値が設定されたインスタンスが1つでもあると、エクステンションの無効化や削除は拒否されます(in_use)。config_fields: エクステンションのグローバル設定のフィールド。値はconfig.jsonのextensions.settings.<id>に保存されます。gui:bundle(UMD バンドルのパス)、styles(CSS のパス)。下の 5 節を参照してください。cli: CLI の slot の宣言(cli.slots)。commands: インスタンスのコマンド一覧に追加するコマンド(name、label、risk、inputs、module、function、condition)。priority: 複数のエクステンションが同じフックを持つときの順序(小さいほうが先に実行、既定 100)。i18n_dir: 翻訳ファイルのフォルダー。permissions: コードが使う危険な機能を宣言します(モジュールの[permissions]と同じ表)。
フックに
asyncフィールドはなく、manifest にmanifest_urlもありません。エクステンションの一覧とアップデートは、サバちゃんの署名済みリリースマニフェストからのみ提供されます。
3. 実際の10個のフック
フック関数はモジュールと同じ方法で実行されます。デーモンが python <file>.py <関数名> を起動し、コンテキストの JSON を stdin に書き込み、stdout の JSON(全体または最後の行)を結果として読み取ります。終了コードは 0 でなければなりません。下の一覧は、デーモンのコードの FIRED_HOOKS と同じです。
| フック名 | 呼び出されるタイミング | 結果の使われ方 | 実行方式 |
|---|---|---|---|
daemon.startup | デーモン起動直後 / エクステンションの有効化直後(そのエクステンションのみ) | success/message が初期化状態(/api/extensions/init-status)に入る | バックグラウンド |
daemon.shutdown | デーモン終了の直前 | ログに記録するだけ | 同期 |
server.pre_start | サーバー起動の直前 | handled: true で既定の起動を置き換える(その場合 success が true でなければ起動は失敗) | 同期 |
server.stop | サーバー停止の直前 | handled: true で停止を引き受ける | 同期 |
server.status | 個々のサーバーの状態を照会するとき | handled: true でその結果をそのまま返す | 同期 |
server.list_enrich | インスタンス一覧を取得するとき | handled: true で status と extension_status を埋める。10秒のタイムアウト、30秒の TTL キャッシュ | 同期 |
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の manifest で使うと読み込みに失敗します。
3.1 コンテキストとエントリーポイント
フック関数はコンテキストの辞書を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 の順に1つずつ実行されます。 - 結果に
handled: trueが含まれていると、残りのエクステンションはスキップされます。そのフックの既定の動作を置き換えるのでない限り、handledは含めないでください。 - あるエクステンションが失敗した場合、エラーが記録され、次のエクステンションが実行されます。
- 既定の制限時間は120秒です。フックの経路には進行状況(
PROGRESS:)の表示はありません。
3.3 server.list_enrich の TTL キャッシュ
このフックは、インスタンス一覧が要求されるたびに、extension_data を持つすべてのインスタンスについて順に呼び出される可能性があるため、デーモンは成功した結果を30秒間キャッシュします。キャッシュが有効な間は、Python プロセスを起動せずに前回の結果を再利用します。呼び出しごとに10秒のタイムアウトがあるので、すぐに終わるように設計してください。結果の status_line は Discord の状態表示に出る短い1行の状態なので、パスや秘密情報を入れないでください。
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) - 用途:Palworld などの UE4 ゲームの INI
OptionSettings=(...)を読み書きするユーティリティをモジュールに提供します。 - フックを宣言しない 純粋なライブラリ で、モジュールは
extensions.ue4_iniとして import します。
xna
- id:
xna - Python:
xna.py(install、present、XnaError) - 用途:Microsoft XNA Framework 4.0 Refresh の固定版を PC にインストールせず、ゲームサーバーのフォルダーの横に置きます。Terraria の Windows サーバーが使います。公式配布の MSI を一度ダウンロードし、固定した SHA-256 で確認してから必要なファイルだけを取り出します。
- フックを宣言しない 純粋なライブラリ で、モジュールは
from extensions.xna import install, presentとして使います。
モジュールは無効なエクステンションを import できません。デーモンの import ガードが、
SABA_ENABLED_EXTENSIONSにないextensions.<name>の import をブロックします。
5. GUI バンドル(slot の注入)
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<PascalCase の id>を作成する必要があります。id から-と_を取り除き、その次の文字を大文字にします(例:steamcmd→window.SabaExtSteamcmd、ue4-ini→window.SabaExtUe4Ini)。 - そのグローバルの
registerSlots()が{ slotId: Component | Component[] }を返すと、GUI はそれらを該当する slot にマウントします。 - React はホストの
window.Reactを external として参照します。コンポーネントは slot が渡す props だけで動作する必要があります。 - 翻訳は
GET /api/extensions/:id/i18n/:localeでext_<id>名前空間に読み込まれます。
| Slot 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
有効なエクステンションの一覧は config.json の extensions.enabled に、グローバルの設定値は extensions.settings に保存されます。
7. 開発ルール
- エクステンションもデーモンのコードに依存してはいけません。デーモンが渡すコンテキストと環境変数だけを使います。
- パスは
os.path.joinで組み立て、ハードコードしないでください。 - フック関数も、失敗は JSON(
success: falseと理由)と終了コード 0 で応答し、ログとトレースバックは stderr に送ります。 conditionにはinstance.ext_data.<key>の形式だけを使います。それ以外の形式は常に false と評価されます。- Python の依存パッケージはデーモンの共有環境を使います。エクステンションごとの requirements の宣言はありません。
- 未検証のエクステンション:署名済みカタログからダウンロードされていないエクステンションや、ダウンロード後に変更されたエクステンションは、モジュールと同じ隔離環境(Windows は AppContainer、Linux は bubblewrap)で実行されます。ウイルス対策のスキャンは行いません。以下は Windows の場合です。ループバック(デーモン API など)にアクセスできず、
SABA_TOKEN_PATHも渡されず、インスタンスフォルダーは読み取りしかできません。書き込みが必要なデータは、SABA_EXTENSION_DATA_DIR環境変数が指す専用フォルダーに置いてください。 - テストはリポジトリのルートで
pytestを実行します。