モジュール開発ガイド
サバちゃんに新しいゲームを追加する Python モジュールの作り方。module.toml のスキーマと、lifecycle.py の実際の関数契約とプロトコルを扱います。
モジュール開発ガイド(Python)
サバちゃんのデーモンは、ゲーム固有の詳細を知りません。代わりに、各ゲームは Python モジュール によって記述されます。モジュールを1つ追加すれば、サバちゃんで新しいゲームを管理できるようになります。
このドキュメントは、saba-chan-modules リポジトリにある実際のモジュール(minecraft、palworld、zomboid)、注釈付きテンプレート __example、そしてデーモンのコードに基づいています。
1. モジュールのファイル構成
- 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 |
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 に実装されています。要約すると次のとおりです。
- デーモンが管理する Python 環境で
python lifecycle.py <関数名>を起動します。 - 注入される環境変数:
PYTHONIOENCODING=utf-8、PYTHONUNBUFFERED=1PYTHONPATH: 共有ファイル(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)
- config の JSON オブジェクトを1つ stdin に書き込んで閉じます。
- stdout 全体を JSON として解析し、失敗した場合は 最後の空でない行 を結果として使います。
- stderr はログです。
PROGRESS:で始まる行は進行状況イベントとして解析され、インストールの進行状況の表示に使われます。 - 終了コードは 0 でなければなりません。 0 でない場合、stdout に
success: falseが含まれていても、デーモンは呼び出しを一般的なエラーとして扱います。 - プロセスは呼び出しごとに終了します。既定の制限時間は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_kill | PID ごとの確認 / 待機 / 強制終了 |
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. 参考:組み込みモジュール
| モジュール | 既定のポート | プロトコル | 必要なエクステンション | 備考 |
|---|---|---|---|---|
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 か、この4つのうち最も近いものから始めることをおすすめします。
7. 開発ルール(必須)
モジュールの PR は次のルールに従う必要があります。
- デーモンのコードに依存しない。 デーモンが提供する config、環境変数、API だけを使います。
- すべての失敗は JSON + 終了コード 0。
success: falseと理由で応答します。 - ログは stderr へ。 stdout は結果の JSON 用です。例外のトレースバックも stderr に出力し、エラーを握りつぶさないでください。
- まず stdin、次に REST を使います。 RCON はどちらもないゲームでだけ使います。コンソールか REST があるゲームでは RCON 設定をオフにし、
supportedに"rcon"を入れません。 - プロセスはデーモンから渡された
pidだけで扱う。 実行ファイル名で終了させると、同じゲームの他のインスタンスまで終了してしまいます。 - パスは
os.path.joinで組み立て、ハードコードしないでください。 - フィールド名の対応を確認する。 各
[[settings.fields]]の名前がどのゲーム設定キーに対応するかを、configureとimport_settingsの両方で確認します。 - テスト。 単体テストは
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で再読み込みさせてください。