製作模組:從調查到發布
製作可靠遊戲模組的完整流程:調查、用真實伺服器測試、可攜式執行環境、隔離執行、主控台模式,以及在真實 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. 檢查真實檔案
如果能下載伺服器,就親自檢查檔案。
- 列出壓縮檔的全部項目。確認是否每個作業系統各有一個資料夾,以及同一個執行檔名稱是否出現在多個資料夾中。Terraria 的壓縮檔在
Linux/與Windows/資料夾中都有TerrariaServer.exe。 - 逐位元組讀取預設檔案。確認編碼(UTF-8、BOM、cp1252)、換行字元(LF、CRLF)、註解掉的範例鍵,以及不是註解的行。
- 把註解掉的範例鍵也加入設定清單。不是註解的行提供預設值。
4. 執行真實伺服器
用與常駐程式相同的方式啟動伺服器:透過管道連接 stdin 與 stdout,並記錄原始輸出。即使建置環境只能執行其他作業系統版本的伺服器,也要執行它。遊戲程式碼相同時,命令、訊息與儲存行為都相同。
記錄以下內容:
- 就緒行、停止命令之後的行,以及儲存所需時間。
help的輸出。逐一傳送只有文件提到的命令,並記錄回答。- 主控台提示字元。有些伺服器輸出提示字元時不換行,下一行就以提示字元開頭。Terraria 輸出
: Server started。 - 透過管道傳送命令後的回答。伺服器不回答時,用虛擬主控台再試(第 7 節)。
- 伺服器每種語言下的就緒與停止訊息。
- 伺服器啟動與儲存時產生的檔案。Terraria 會產生
world.wld.bak與world.wld.bak2。
加入訊息、踢出對象等需要遊戲用戶端才能測的項目留空,寫上「未實測」。
5. 執行前提:固定版本、可攜式
有些伺服器需要下載包中沒有的執行環境,例如 Java、XNA Framework 或 Visual C++ 執行環境。不要使用 PC 上已安裝的執行環境,因為每台 PC 上的版本可能不同。
依以下步驟操作:
- 在調查表中寫下官方執行環境檔案的位址、大小、簽章與 SHA-256。
- 找出伺服器所需的最小檔案集合。只放這些檔案啟動伺服器來確認。Terraria 需要 4 個 XNA 組件(
Microsoft.Xna.Framework、.Game、.Graphics、.Xact)、XnaNative.dll、msvcr100.dll與msvcp100.dll。 - 在
install_server中下載固定版本,並與官方總和檢查碼比較。沒有官方總和檢查碼時,與從發行者簽章有效的檔案記錄下來的 SHA-256 比較。 - 只把需要的檔案放到伺服器資料夾或執行個體資料夾,並用該路徑啟動伺服器。
- 在
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 單元測試
- 在撰寫函式之前,先在
test_lifecycle.py中為它撰寫測試。 - 執行測試,確認它失敗。
- 撰寫函式。
- 執行以下檢查:
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 節後,在真實的伺服器資料夾上呼叫模組函式。
- 用真實下載執行
install_server。確認資料夾中只有本作業系統的檔案。 - 用
get_launch_command提供的命令啟動伺服器。確認就緒模式能符合。 - 逐一傳送命令範本。確認伺服器接受。
- 傳送停止命令。確認伺服器儲存後結束。
- 把
backup_paths與reset_server的路徑與伺服器產生的檔案比較。
10.3 真實 PC 測試
使用 Windows PC 上一般安裝的 Saba-chan。新模組在隔離中執行,所以這項測試也能發現隔離執行的問題。
- 把模組資料夾複製到 Saba-chan 資料資料夾的
modules\<名稱>\。 - 執行
saba-chan-cli module refresh。 - 執行
saba-chan-cli server add <伺服器> -m <模組>。 - 啟動伺服器。確認 Saba-chan 顯示就緒狀態。
- 用
saba-chan-cli run <伺服器> <命令>傳送命令,用saba-chan-cli server console <伺服器> --print查看回答。 - 修改一項設定並重新啟動伺服器。確認伺服器使用了新值。
- 用
saba-chan-cli backup create <伺服器>建立備份,檢查備份中的檔案。 - 停止伺服器。確認 Saba-chan 記錄為正常停止,世界存檔仍在。
- 重設世界。檢查刪除了哪些檔案、保留了哪些檔案。
如果 [module.dependencies] saba-core 要求尚未發布的版本,一般安裝不會載入該模組。等該版本發布後再做 PC 測試。不要降低相依版本。
11. pull request 前的檢查清單
-
RESEARCH.md的每一項都有來源,且每個來源都標明「文件」或「實測」。 - 檢查過壓縮檔項目與預設檔案的原始位元組。
- 執行過真實伺服器,並記錄了原始輸出、
help輸出與儲存後的檔案。 - 宣告的每條命令都在
help輸出中。 - 伺服器會回答命令。如果不回答,已設定
[launch] console = "pty"。 - 每個主控台模式都來自實測輸出,並接受提示字元與各語言的翻譯。
- 每個執行環境都是固定版本的可攜式檔案,模組會驗證下載的檔案。
- 安裝只解壓縮本作業系統的資料夾。
- 設定檔保持原有編碼與換行字元。
- 重設世界只刪除伺服器產生的檔案(包括遊戲產生的備份)。
- 模組不使用
msiexec、Windows 服務、mkdtemp資料夾或直接的回送連線。 - 做過真實伺服器測試與真實 PC 測試,或記錄了沒能做的測試。