モジュール開発ガイド

サバちゃんに新しいゲームを追加する Python モジュールの作り方。module.toml のスキーマと、lifecycle.py の実際の関数契約とプロトコルを扱います。

モジュール開発ガイド(Python)

サバちゃんのデーモンは、ゲーム固有の詳細を知りません。代わりに、各ゲームは Python モジュール によって記述されます。モジュールを1つ追加すれば、サバちゃんで新しいゲームを管理できるようになります。

このドキュメントは、saba-chan-modules リポジトリにある実際のモジュール(minecraft、palworld、zomboid)、注釈付きテンプレート __example、そしてデーモンのコードに基づいています。


1. モジュールのファイル構成

%APPDATA%\saba-chan\modules\<module_name>\
  • module.toml必須。宣言 (スキーマ v1)必須。宣言 (スキーマ v1)
  • lifecycle.py必須。[module].entry で指定するエントリーファイル必須。[module].entry で指定するエントリーファイル
  • icon.png任意。[module].icon で指定任意。[module].icon で指定
  • locales/
  • en.json基準言語基準言語
  • ko.json
  • ...UI の文字列UI の文字列
  • test_lifecycle.py任意。pytest の単体テスト (推奨)任意。pytest の単体テスト (推奨)
  • フォルダー名は module.toml の [module].name と同じ、英小文字にします。
  • デーモンは、モジュールのルート直下にあり 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"(既定)なら lifecycle.py の command() に送られます。risk(safe/caution/danger)と description は、AI によるコマンド解釈で読まれます。
  • [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>] もあります。全キーの一覧は、saba-chan-modules リポジトリの docs/module-spec.md を参照してください。

3. lifecycle.py の関数契約

デーモンは必要になるたびに 新しい Python プロセスを起動 し、このファイルの関数を1つ呼び出します。すべての関数は config: dict を1つ受け取って 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" が1つでもあるとサーバーは起動しない)
stopコンソールのないサーバーの停止と、管理外のサーバーsuccess
status管理外のサーバーの状態照会status、pid
commandmethod = "module" のコマンドsuccess、message
get_credentialsREST の接続情報が必要なとき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 に実装されています。要約すると次のとおりです。

  1. デーモンが管理する Python 環境で python lifecycle.py <関数名> を起動します。
  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. config の JSON オブジェクトを1つ stdin に書き込んで閉じます。
  4. stdout 全体を JSON として解析し、失敗した場合は 最後の空でない行 を結果として使います。
  5. stderr はログです。PROGRESS: で始まる行は進行状況イベントとして解析され、インストールの進行状況の表示に使われます。
  6. 終了コードは 0 でなければなりません。 0 でない場合、stdout に success: false が含まれていても、デーモンは呼び出しを一般的なエラーとして扱います。
  7. プロセスは呼び出しごとに終了します。既定の制限時間は120秒で、プロビジョニングとアップデート中の install_server だけはより長い時間(1800秒)が与えられます。

未検証のモジュール:サバちゃんの署名付きカタログから取得していない、または取得後に変更されたモジュールは、Windows は AppContainer、Linux は bubblewrap の中で実行されます。ウイルス対策ソフトによる検査は行いません。隔離できない環境(bubblewrap がない、または使えない Linux、macOS)では、現在のファイルにユーザーが同意した後にだけ実行します。隔離実行では、モジュールはループバックに直接接続できず(共通ヘルパーを使うとデーモンが中継します)、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, "ダウンロード開始")
# … 実際のダウンロード …
report(2, 3, 70, "展開中")
# …
report(3, 3, 100, "インストール完了")

認識されるフィールドは 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")  # サーバーのコンソールに1行送る

daemon_rcon.py という名前は歴史的な理由で残っているだけで、RCON のソケットを開くことはありません。主なヘルパー:

関数用途
daemon_stdin_command(instance_id, line)デーモンが管理するサーバーのコンソールにコマンドを送る
daemon_post(path, payload)他のデーモン API を呼び出す(トークンは自動で付与)
is_process_alive、wait_for_exit、force_killPID ごとの確認 / 待機 / 強制終了
config_value(config, key, default)config から設定値を探す
run_lifecycle(FUNCTIONS)python lifecycle.py <function> のエントリーポイント

有効なエクステンションは、from extensions.steamcmd import SteamCMD や import extensions.ue4_ini のように import できます。無効なエクステンションは import ガードでブロックされる(ModuleNotFoundError)ため、関数の中で import し、失敗したら 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 か、この4つのうち最も近いものから始めることをおすすめします。


7. 開発ルール(必須)

モジュールの PR は次のルールに従う必要があります。

  1. デーモンのコードに依存しない。 デーモンが提供する config、環境変数、API だけを使います。
  2. すべての失敗は JSON + 終了コード 0。 success: false と理由で応答します。
  3. ログは stderr へ。 stdout は結果の JSON 用です。例外のトレースバックも stderr に出力し、エラーを握りつぶさないでください。
  4. まず stdin、次に REST を使います。 RCON はどちらもないゲームでだけ使います。コンソールか REST があるゲームでは RCON 設定をオフにし、supported に "rcon" を入れません。
  5. プロセスはデーモンから渡された pid だけで扱う。 実行ファイル名で終了させると、同じゲームの他のインスタンスまで終了してしまいます。
  6. パスは os.path.join で組み立て、ハードコードしないでください。
  7. フィールド名の対応を確認する。 各 [[settings.fields]] の名前がどのゲーム設定キーに対応するかを、configure と import_settings の両方で確認します。
  8. テスト。 単体テストは test_lifecycle.py に置き、適合性キット(下の 8 節)をパスさせます。

8. デバッグのヒント

  • 結果は stdout の最後の行から読み取られるため、デバッグ出力は stderr に送ってください。結果の JSON の後に何かを出力すると解析が壊れます。
  • デーモンなしで関数を直接実行できます。daemon_rcon が見つかるよう、サバちゃんリポジトリの modules/ を PYTHONPATH に追加してください。
    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 で再読み込みさせてください。