模組開發指南

如何撰寫 Python 模組為 Saba-chan 新增遊戲。涵蓋 module.toml 結構描述,以及 lifecycle.py 實際的函式約定與通訊協定。

模組開發指南(Python)

Saba-chan 常駐程式並不知道各遊戲的細節。取而代之的是,每款遊戲都由一個 Python 模組 描述。新增一個模組,Saba-chan 就能管理一款新遊戲。

本文件以 saba-chan-modules 儲存庫中的實際模組(minecraft、palworld、zomboid)、附有註解的範本 __example 以及常駐程式程式碼為依據。


1. 模組檔案結構

%APPDATA%\saba-chan\modules\<module_name>\
  • module.toml必要。宣告(schema v1)必要。宣告(schema 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。只有既沒有主控台也沒有 REST API 的遊戲才使用 RCON。這類遊戲還必須宣告 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 程序 來呼叫此檔案中的某個函式。每個函式都接受單一的 config: dict 並回傳 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",伺服器不會啟動)
stop停止沒有主控台的伺服器,以及非受管伺服器success
status非受管狀態查詢status、pid
commandmethod = "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. 子程序通訊協定

常駐程式如何呼叫模組函式,實作於 Saba-chan 儲存庫的 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 物件寫入 stdin 後關閉。
  4. 將整個 stdout 解析為 JSON;若失敗,則以 最後一個非空行 作為結果。
  5. stderr 是記錄。以 PROGRESS: 開頭的行會被解析為進度事件,用於顯示安裝進度。
  6. 結束代碼必須為 0。 若不是,即使 stdout 含有 success: false,常駐程式也會將這次呼叫視為一般錯誤。
  7. 程序在每次呼叫後結束。預設時間限制為 120 秒;只有佈建與更新期間的 install_server 會給予較長時間(1800 秒)。

未驗證的模組:不是從 Saba-chan 簽署目錄取得、或下載後被修改的模組,在 Windows 以 AppContainer、在 Linux 以 bubblewrap 執行。Saba-chan 不會用防毒軟體掃描它。在無法隔離的環境(沒有 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, "Starting download")
# … 實際下載 …
report(2, 3, 70, "Extracting")
# …
report(3, 3, 100, "Install complete")

可辨識的欄位有 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")  # 向伺服器主控台送出一行

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。已停用的擴充功能會被匯入防護擋下(ModuleNotFoundError),因此請在函式內匯入,並在失敗時回應 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 或這四者中最接近的一個開始。


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. 確認欄位名稱的對應。 在 configure 與 import_settings 兩者中確認每個 [[settings.fields]] 名稱對應到哪個遊戲設定鍵。
  8. 測試。 將單元測試放在 test_lifecycle.py 中,並通過一致性測試套件(下方第 8 節)。

8. 除錯技巧

  • 結果是從 stdout 的最後一行讀取,因此請將除錯輸出送到 stderr。在結果 JSON 之後輸出任何東西都會破壞解析。
  • 你可以不透過常駐程式直接執行函式。將 Saba-chan 儲存庫的 modules/ 加入 PYTHONPATH,讓 daemon_rcon 能被找到。
    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 讓它重新載入。