模組開發指南
如何撰寫 Python 模組為 Saba-chan 新增遊戲。涵蓋 module.toml 結構描述,以及 lifecycle.py 實際的函式約定與通訊協定。
模組開發指南(Python)
Saba-chan 常駐程式並不知道各遊戲的細節。取而代之的是,每款遊戲都由一個 Python 模組 描述。新增一個模組,Saba-chan 就能管理一款新遊戲。
本文件以 saba-chan-modules 儲存庫中的實際模組(minecraft、palworld、zomboid)、附有註解的範本 __example 以及常駐程式程式碼為依據。
1. 模組檔案結構
- 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 |
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. 子程序通訊協定
常駐程式如何呼叫模組函式,實作於 Saba-chan 儲存庫的 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 物件寫入 stdin 後關閉。
- 將整個 stdout 解析為 JSON;若失敗,則以 最後一個非空行 作為結果。
- stderr 是記錄。以
PROGRESS:開頭的行會被解析為進度事件,用於顯示安裝進度。 - 結束代碼必須為 0。 若不是,即使 stdout 含有
success: false,常駐程式也會將這次呼叫視為一般錯誤。 - 程序在每次呼叫後結束。預設時間限制為 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. 參考:內建模組
| 模組 | 預設連接埠 | 通訊協定 | 所需擴充功能 | 備註 |
|---|---|---|---|---|
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 或這四者中最接近的一個開始。
7. 開發規則(必須遵守)
模組 PR 必須遵守這些規則。
- 不依賴常駐程式程式碼。 只使用常駐程式提供的 config、環境變數與 API。
- 所有失敗都以 JSON + 結束代碼 0 回應。 以
success: false與原因回應。 - 記錄寫到 stderr。 stdout 用於結果 JSON。例外追蹤也請輸出到 stderr;不要吞掉錯誤。
- 先用 stdin,再用 REST。 只有兩者都沒有的遊戲才使用 RCON。遊戲有主控台或 REST 時,關閉其 RCON 設定,且不在
supported中放入"rcon"。 - 只依常駐程式提供的
pid處理程序。 依執行檔名稱終止程序也會結束同一款遊戲的其他實例。 - 用
os.path.join組合路徑;不要寫死。 - 確認欄位名稱的對應。 在
configure與import_settings兩者中確認每個[[settings.fields]]名稱對應到哪個遊戲設定鍵。 - 測試。 將單元測試放在
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讓它重新載入。