製作模組:從調查到發布

製作可靠遊戲模組的完整流程:調查、用真實伺服器測試、可攜式執行環境、隔離執行、主控台模式,以及在真實 PC 上測試。

製作模組:從調查到發布

模組開發指南 說明模組包含什麼。本頁說明如何製作能在真實 PC 上運作的模組。

通過全部單元測試的模組,在真實伺服器上仍可能失敗。Terraria 模組就是一個例子。它通過了全部單元測試與一致性檢查,但在真實伺服器上出現了 9 個缺陷。本頁提供在發布前找出這類缺陷的流程。


1. 設計原則

以下原則適用於所有模組。

  • 工作由常駐程式完成。 模組只描述遊戲。不要繞過常駐程式的契約。如果契約缺少你需要的功能,先在常駐程式中加入通用擴充點。
  • 不要依遊戲名稱分支。 常駐程式與共用輔助函式中沒有遊戲名稱。使用 module.toml 的鍵、掛鉤與插槽。
  • 處處使用相同的執行環境。 不要使用 PC 上已安裝的執行環境。模組下載固定版本的執行環境並放到伺服器資料夾中(第 5 節)。
  • 每個值只放在一個地方。 設定的預設值來自一個檔案:遊戲產生的檔案,或下載包中附帶的範例檔案。
  • 所有面向使用者的文字都放在 locales/。 en.json 是基準檔案。

2. 調查遊戲

撰寫程式碼之前,在 <game>/RESEARCH.md 中建立調查表。為每一項寫出來源,並註明來源是文件還是實測。找不到來源的項目留空,寫上「未確認」。不要猜測數值。

項目去哪裡找
伺服器執行檔、啟動參數、預設連接埠官方文件、伺服器說明、下載包中的啟動指令碼
全部命令及其參數官方命令文件與伺服器 help 命令的輸出。逐行對照兩者
全部設定(鍵、格式、範圍、預設值)伺服器產生的預設設定檔。伺服器不產生時,使用下載包中的範例檔案
設定檔的語法與編碼該檔案的原始位元組
世界存檔與遊戲產生的備份啟動伺服器並儲存世界後的檔案清單
就緒、停止、加入、離開訊息主控台的原始輸出。也要確認伺服器的語言設定是否會翻譯這些訊息
安裝方式與檔案驗證官方下載位址與官方總和檢查碼。沒有總和檢查碼時,寫「無」與來源
執行前提(執行環境)伺服器執行檔的參考清單與官方文件。找出下載包中沒有的東西
執行個體資料夾以外的檔案執行伺服器後主資料夾與文件資料夾的變化

Wiki 可能描述的是舊版本。Terraria Wiki 列出了 death 命令,但 Terraria 1.4.5.8 伺服器對它的回答是「Invalid command.」。


3. 檢查真實檔案

如果能下載伺服器,就親自檢查檔案。

  1. 列出壓縮檔的全部項目。確認是否每個作業系統各有一個資料夾,以及同一個執行檔名稱是否出現在多個資料夾中。Terraria 的壓縮檔在 Linux/ 與 Windows/ 資料夾中都有 TerrariaServer.exe。
  2. 逐位元組讀取預設檔案。確認編碼(UTF-8、BOM、cp1252)、換行字元(LF、CRLF)、註解掉的範例鍵,以及不是註解的行。
  3. 把註解掉的範例鍵也加入設定清單。不是註解的行提供預設值。

4. 執行真實伺服器

用與常駐程式相同的方式啟動伺服器:透過管道連接 stdin 與 stdout,並記錄原始輸出。即使建置環境只能執行其他作業系統版本的伺服器,也要執行它。遊戲程式碼相同時,命令、訊息與儲存行為都相同。

記錄以下內容:

  • 就緒行、停止命令之後的行,以及儲存所需時間。
  • help 的輸出。逐一傳送只有文件提到的命令,並記錄回答。
  • 主控台提示字元。有些伺服器輸出提示字元時不換行,下一行就以提示字元開頭。Terraria 輸出 : Server started。
  • 透過管道傳送命令後的回答。伺服器不回答時,用虛擬主控台再試(第 7 節)。
  • 伺服器每種語言下的就緒與停止訊息。
  • 伺服器啟動與儲存時產生的檔案。Terraria 會產生 world.wld.bak 與 world.wld.bak2。

加入訊息、踢出對象等需要遊戲用戶端才能測的項目留空,寫上「未實測」。


5. 執行前提:固定版本、可攜式

有些伺服器需要下載包中沒有的執行環境,例如 Java、XNA Framework 或 Visual C++ 執行環境。不要使用 PC 上已安裝的執行環境,因為每台 PC 上的版本可能不同。

依以下步驟操作:

  1. 在調查表中寫下官方執行環境檔案的位址、大小、簽章與 SHA-256。
  2. 找出伺服器所需的最小檔案集合。只放這些檔案啟動伺服器來確認。Terraria 需要 4 個 XNA 組件(Microsoft.Xna.Framework、.Game、.Graphics、.Xact)、XnaNative.dll、msvcr100.dll 與 msvcp100.dll。
  3. 在 install_server 中下載固定版本,並與官方總和檢查碼比較。沒有官方總和檢查碼時,與從發行者簽章有效的檔案記錄下來的 SHA-256 比較。
  4. 只把需要的檔案放到伺服器資料夾或執行個體資料夾,並用該路徑啟動伺服器。
  5. 在 validate 中尋找這些檔案。缺少任何一個時,回傳帶有 severity: "critical" 與專用 code 的問題,並提示使用者重新安裝伺服器。

不要使用系統管理員權限、全系統安裝或 Windows 服務。

限制: 當全域組件快取(GAC)中有同名同版本的組件時,.NET Framework 會先從 GAC 載入。原生 DLL 會先從伺服器資料夾載入。


6. 隔離執行

在 Windows 上,不是來自 Saba-chan 簽署目錄的模組會在 Windows AppContainer 中執行。新製作的模組都在這種隔離中執行。開啟 pull request 之前,先在隔離執行中測試模組。

隔離執行中不能使用以下內容:

不能使用改用
回送連線(常駐程式 API、遊戲伺服器 REST API)daemon_stdin_command、daemon_rest、loopback_http、loopback_exchange。由常駐程式轉送請求
Windows Installer(msiexec 以錯誤 1601 失敗)與其他服務用 Python 直接讀取安裝檔(MSI、CAB)
tempfile.mkdtemp 在執行個體資料夾中建立的資料夾tempfile.mkstemp,或用 os.mkdir 建立的資料夾。從 Python 3.13 起,mkdtemp 只給目前使用者權限,隔離帳戶無法寫入該資料夾
在允許的資料夾之外寫入執行個體資料夾、工作資料夾、安裝資料夾,以及 data_roots 中宣告的資料夾

如果共用輔助函式在隔離執行中失敗,不要在模組裡繞過,把它當作常駐程式的問題回報。


7. 主控台模式

常駐程式預設透過管道連接伺服器的 stdin 與 stdout([launch] console = "pipe")。有些伺服器在 stdin 是管道時行為不同:

  • Palworld 會把輸出累積到停止時才輸出。
  • Terraria 的 Windows 伺服器不讀取管道輸入。它對命令與 exit 都沒有回答,常駐程式在 60 秒後未儲存就強制結束了它。

對這類伺服器,設定 [launch] console = "pty"。常駐程式會在虛擬主控台(Windows ConPTY、Unix pty)中啟動伺服器。

虛擬主控台會回顯傳送的每條命令,換行位置也可能改變。在虛擬主控台中,Terraria 把提示字元 : 與 Server started 輸出在不同的行。撰寫模式時要兼顧兩種情況。


8. 主控台比對模式

就緒、加入、離開、停止的模式只根據實測的原始輸出撰寫。

  • 就緒、加入、離開的模式放在 [extensions.saba-core](ready_patterns、player_join_patterns、player_leave_patterns),停止的模式放在 [detection] graceful_exit_patterns。
  • 把每個模式錨定在行首與行尾。包含相同文字的聊天行(例如 <Server> Server started)不能符合。
  • 如果訊息前可能有提示字元,用 ^(?:<提示字元>)? 接受它。
  • 如果伺服器的語言設定會翻譯訊息,就加入每種語言實測到的訊息。只加英文的話,常駐程式無法辨識設定為其他語言之伺服器的就緒狀態。
  • 加入測試。實測行無論有沒有提示字元都應符合,聊天行不應符合。

9. 安裝與設定檔

安裝:

  • 壓縮檔中每個作業系統各有一個資料夾時,依作業系統名稱選擇資料夾。不要依執行檔名稱、路徑長度或第一個項目來選。找不到資料夾或找到多個時,回傳失敗。
  • 不要覆寫既有的設定與世界。只有在還沒有設定檔時,才解壓縮範例設定檔。
  • 驗證每個下載的檔案。每個二進位檔都使用官方總和檢查碼。沒有官方總和檢查碼時,用指向固定官方主機的 HTTPS、壓縮檔 CRC 與預期執行檔是否存在來確認,並在調查表中寫上「無官方總和檢查碼」與來源。不要捏造總和檢查碼,也不要使用社群來源的總和檢查碼。

設定檔:

  • 用該格式的官方語法讀寫檔案。例如 Java .properties 檔案有 \: 與 \= 跳脫,行尾的 \ 表示接續下一行。
  • 不要假定編碼。用檔案的真實編碼讀取,並用相同的編碼與換行字元寫回。Terraria 的 Windows 版 serverconfig.txt 使用 cp1252,註解中有位元組 0x92。只用 UTF-8 讀取的模組既無法啟動該伺服器,也無法儲存或匯入其設定。
  • 只修改有變化的鍵,保留其他鍵、註解與順序。
  • 讀不了檔案就不要寫。檔案不存在、無法讀取、無法解析是三種不同的情況。

10. 測試

單元測試與一致性套件在沒有隔離的情況下用範例檔案執行,因此找不到只在真實下載、隔離執行、主控台模式或 Windows 上出現的問題。三個層次的測試都要做。

10.1 單元測試

  1. 在撰寫函式之前,先在 test_lifecycle.py 中為它撰寫測試。
  2. 執行測試,確認它失敗。
  3. 撰寫函式。
  4. 執行以下檢查:
saba-core module validate mygame
saba-core module audit mygame
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules

10.2 真實伺服器測試(pull request 之前)

完成第 4 節後,在真實的伺服器資料夾上呼叫模組函式。

  1. 用真實下載執行 install_server。確認資料夾中只有本作業系統的檔案。
  2. 用 get_launch_command 提供的命令啟動伺服器。確認就緒模式能符合。
  3. 逐一傳送命令範本。確認伺服器接受。
  4. 傳送停止命令。確認伺服器儲存後結束。
  5. 把 backup_paths 與 reset_server 的路徑與伺服器產生的檔案比較。

10.3 真實 PC 測試

使用 Windows PC 上一般安裝的 Saba-chan。新模組在隔離中執行,所以這項測試也能發現隔離執行的問題。

  1. 把模組資料夾複製到 Saba-chan 資料資料夾的 modules\<名稱>\。
  2. 執行 saba-chan-cli module refresh。
  3. 執行 saba-chan-cli server add <伺服器> -m <模組>。
  4. 啟動伺服器。確認 Saba-chan 顯示就緒狀態。
  5. 用 saba-chan-cli run <伺服器> <命令> 傳送命令,用 saba-chan-cli server console <伺服器> --print 查看回答。
  6. 修改一項設定並重新啟動伺服器。確認伺服器使用了新值。
  7. 用 saba-chan-cli backup create <伺服器> 建立備份,檢查備份中的檔案。
  8. 停止伺服器。確認 Saba-chan 記錄為正常停止,世界存檔仍在。
  9. 重設世界。檢查刪除了哪些檔案、保留了哪些檔案。

如果 [module.dependencies] saba-core 要求尚未發布的版本,一般安裝不會載入該模組。等該版本發布後再做 PC 測試。不要降低相依版本。


11. pull request 前的檢查清單

  • RESEARCH.md 的每一項都有來源,且每個來源都標明「文件」或「實測」。
  • 檢查過壓縮檔項目與預設檔案的原始位元組。
  • 執行過真實伺服器,並記錄了原始輸出、help 輸出與儲存後的檔案。
  • 宣告的每條命令都在 help 輸出中。
  • 伺服器會回答命令。如果不回答,已設定 [launch] console = "pty"。
  • 每個主控台模式都來自實測輸出,並接受提示字元與各語言的翻譯。
  • 每個執行環境都是固定版本的可攜式檔案,模組會驗證下載的檔案。
  • 安裝只解壓縮本作業系統的資料夾。
  • 設定檔保持原有編碼與換行字元。
  • 重設世界只刪除伺服器產生的檔案(包括遊戲產生的備份)。
  • 模組不使用 msiexec、Windows 服務、mkdtemp 資料夾或直接的回送連線。
  • 做過真實伺服器測試與真實 PC 測試,或記錄了沒能做的測試。