エクステンション開発ガイド

サバちゃんの実際の10個のフックと manifest.json の仕様、GUI の slot 注入、そして同梱エクステンションの実装上のポイント。

エクステンション開発ガイド

エクステンション(プラグイン)は、特定のゲームに結び付かず、デーモンのライフサイクル全体にフックする アドオン、または GUI にコンポーネントを注入するアドオンです。サバちゃんのデーモンは、次の10か所(フック)で有効なエクステンションに制御を渡します。現在の同梱エクステンションは、SteamCMD によるインストール/アップデート(steamcmd)と UE4 INI パーサー(ue4-ini)です。

このドキュメントの内容は、saba-chan-extensions リポジトリの実際の manifest.json ファイルと、デーモン側のエクステンションシステム(src/extension/mod.rs)に基づいています。


1. ファイル構成

%APPDATA%\saba-chan\extensions\<extension_id>\
  • 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 のハイフンをアンダースコアに置き換えた名前も認められます(例:id ue4-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 を実行します。