モジュールの作り方:調査からリリースまで
信頼できるゲームモジュールを作る全手順。調査、実サーバーでの計測、ポータブルなランタイム、隔離実行、コンソール方式、実際の PC での確認を扱います。
モジュールの作り方:調査からリリースまで
モジュール開発ガイド はモジュールに何が入るかを説明します。このページは、実際の PC で動くモジュールを作る手順を説明します。
単体テストをすべて通ったモジュールでも、実際のサーバーでは失敗することがあります。テラリアのモジュールがその例です。単体テストと適合性チェックをすべて通りましたが、実際のサーバーでは欠陥が 9 つ見つかりました。このページは、そのような欠陥をリリース前に見つける手順を示します。
1. 設計の原則
すべてのモジュールに適用する原則です。
- 仕事をするのはデーモンです。 モジュールはゲームを説明するだけです。デーモンの契約を迂回しません。必要な機能が契約にない場合は、先にデーモンに汎用の拡張ポイントを作ります。
- ゲーム名で分岐しません。 デーモンと共通ヘルパーにはゲーム名を入れません。
module.tomlのキー、フック、スロットを使います。 - どこでも同じ実行環境を使います。 PC にインストールされたランタイムは使いません。モジュールが固定版のランタイムをダウンロードし、サーバーフォルダーに置きます(5 章)。
- 値は 1 か所に置きます。 設定の既定値は 1 つのファイルから取ります。ゲームが作るファイル、またはダウンロードに同梱された例のファイルです。
- ユーザー向けの文言はすべて
locales/に置きます。en.jsonが基準ファイルです。
2. ゲームを調査する
コードを書く前に、<game>/RESEARCH.md に調査表を作ります。項目ごとに出典を書き、出典が文書か実測かも書きます。出典が見つからない項目は空欄にして「未確認」と書きます。値を推測しません。
| 項目 | 調べる場所 |
|---|---|
| サーバー実行ファイル、起動引数、既定のポート | 公式文書、サーバーのヘルプ、ダウンロード内の起動スクリプト |
| すべてのコマンドと引数 | 公式のコマンド文書と、サーバーの help コマンドの出力。両方を 1 行ずつ照合します |
| すべての設定(キー、形式、範囲、既定値) | サーバーが作る既定の設定ファイル。作らない場合はダウンロード内の例のファイル |
| 設定ファイルの文法とエンコーディング | そのファイルの元のバイト列 |
| ワールドのセーブと、ゲームが作るバックアップ | サーバーを起動してワールドを保存した後のファイル一覧 |
| 準備完了・停止・参加・退出のメッセージ | コンソールの生の出力。サーバーの言語設定がメッセージを翻訳するかも確認します |
| インストール方法とファイル検証 | 公式のダウンロードアドレスと公式チェックサム。チェックサムがなければ「なし」と出典を書きます |
| 実行の前提(ランタイム) | サーバー実行ファイルの参照一覧と公式文書。ダウンロードに含まれないものを探します |
| インスタンスフォルダー外のファイル | サーバー実行後のホームフォルダーとドキュメントフォルダーの変化 |
Wiki は古いバージョンを説明している場合があります。テラリアの Wiki には death コマンドが載っていますが、テラリア 1.4.5.8 サーバーはこのコマンドに「Invalid command.」と答えます。
3. 実際のファイルを調べる
サーバーをダウンロードできるなら、ファイルを自分で調べます。
- アーカイブの全エントリーを表示します。OS ごとのフォルダーがあるか、同じ実行ファイル名が複数のフォルダーにあるかを確認します。テラリアのアーカイブには、
Linux/フォルダーとWindows/フォルダーの両方にTerrariaServer.exeがあります。 - 既定のファイルをバイト単位で読みます。エンコーディング(UTF-8、BOM、cp1252)、改行(LF、CRLF)、コメントになっている例のキー、コメントではない行を確認します。
- コメントになっている例のキーも設定一覧に入れます。コメントではない行の値が既定値です。
4. 実際のサーバーを起動する
デーモンと同じ方法でサーバーを起動します。stdin と stdout をパイプでつなぎ、生の出力を記録します。ビルド環境で別の OS 向けのサーバーしか動かせなくても、それを動かします。ゲームのコードが同じなら、コマンド、メッセージ、保存の動作は同じです。
次を記録します。
- 準備完了の行、停止コマンドの後の行、保存にかかる時間
helpの出力。文書にだけ載っているコマンドは 1 つずつ送り、返答を記録します- コンソールのプロンプト。改行なしでプロンプトを出すサーバーでは、次の行がプロンプトで始まります。テラリアは
: Server startedと出します - パイプで送ったコマンドへの返答。返答がなければ、疑似コンソールで再度試します(7 章)
- サーバーの言語ごとの準備完了・停止メッセージ
- 起動時と保存時にサーバーが作るファイル。テラリアは
world.wld.bakとworld.wld.bak2を作ります
参加メッセージやキックの対象など、ゲームクライアントが必要な項目は空欄にして「未計測」と書きます。
5. 実行の前提:固定版のポータブル
ダウンロードに含まれないランタイムを必要とするサーバーがあります。Java、XNA Framework、Visual C++ ランタイムなどです。PC にインストールされたランタイムは使いません。PC ごとにバージョンが違う可能性があるためです。
次の手順に従います。
- 公式ランタイムファイルのアドレス、サイズ、署名、SHA-256 を調査表に書きます。
- サーバーに必要な最小限のファイルを見つけます。そのファイルだけでサーバーを起動して確認します。テラリアでは XNA アセンブリ 4 つ(
Microsoft.Xna.Framework、.Game、.Graphics、.Xact)、XnaNative.dll、msvcr100.dll、msvcp100.dllです。 install_serverで固定版をダウンロードします。公式チェックサムと比較します。公式チェックサムがなければ、有効な発行元署名のあるファイルから記録した SHA-256 と比較します。- 必要なファイルだけをサーバーフォルダーかインスタンスフォルダーに置き、そのパスでサーバーを起動します。
validateでこれらのファイルを探します。1 つでも欠けていれば、severity: "critical"と専用のcodeで問題を返し、サーバーの再インストールを案内します。
管理者権限、システム全体へのインストール、Windows サービスは使いません。
制限: .NET Framework は、同じ名前とバージョンのアセンブリがグローバルアセンブリキャッシュ(GAC)にあると、GAC のものを先に読み込みます。ネイティブ DLL はサーバーフォルダーのものが先に読み込まれます。
6. 隔離実行
Windows では、署名付きのサバちゃんカタログにないモジュールは Windows AppContainer の中で動きます。新しく作ったモジュールはすべてこの隔離の中で動きます。プルリクエストを開く前に、隔離実行でモジュールを試します。
隔離実行では次のものが使えません。
| 使えないもの | 代わりに使うもの |
|---|---|
| ループバック接続(デーモン API、ゲームサーバーの REST API) | daemon_stdin_command、daemon_rest、loopback_http、loopback_exchange。デーモンが要求を中継します |
Windows Installer(msiexec がエラー 1601 で失敗)とその他のサービス | インストールファイル(MSI、CAB)を Python で直接読みます |
tempfile.mkdtemp がインスタンスフォルダーに作るフォルダー | tempfile.mkstemp、または os.mkdir で作ったフォルダー。Python 3.13 以降の mkdtemp は現在のユーザーにだけ権限を与えるため、隔離アカウントはそのフォルダーに書き込めません |
| 許可されたフォルダー外への書き込み | インスタンスフォルダー、作業フォルダー、インストールフォルダー、data_roots で宣言したフォルダー |
隔離実行で共通ヘルパーが失敗したら、モジュールで迂回しません。デーモンの問題として報告します。
7. コンソール方式
デーモンは既定で、サーバーの stdin と stdout をパイプでつなぎます([launch] console = "pipe")。stdin がパイプのときに動作が変わるサーバーがあります。
- パルワールドは終了するまで出力をためます。
- テラリアの Windows サーバーはパイプからの入力を読みません。コマンドにも
exitにも返答せず、デーモンが 60 秒後に保存なしで強制終了しました。
このようなサーバーには [launch] console = "pty" を設定します。デーモンはサーバーを疑似コンソール(Windows ConPTY、Unix pty)で起動します。
疑似コンソールは送ったコマンドを表示し直します。改行の位置が変わることもあります。疑似コンソールのテラリアは、プロンプト : と Server started を別の行に出します。パターンは両方の場合に合うように書きます。
8. コンソールパターン
準備完了・参加・退出・停止のパターンは、実測した生の出力だけから書きます。
- 準備完了・参加・退出のパターンは
[extensions.saba-core](ready_patterns、player_join_patterns、player_leave_patterns)に、停止のパターンは[detection] graceful_exit_patternsに置きます。 - パターンを行の先頭と末尾に固定します。同じ語を含むチャット行(
<Server> Server started)に一致してはいけません。 - メッセージの前にプロンプトが付く場合は
^(?:<プロンプト>)?で受けます。 - サーバーの言語設定がメッセージを翻訳する場合は、言語ごとに実測したメッセージをすべて入れます。英語だけでは、別の言語に設定したサーバーの準備完了をデーモンが認識できません。
- テストを入れます。実測した行はプロンプトの有無にかかわらず一致し、チャット行は一致しないことを確認します。
9. インストールと設定ファイル
インストール:
- アーカイブに OS ごとのフォルダーがある場合は、OS の名前でフォルダーを選びます。実行ファイル名、パスの長さ、最初のエントリーでは選びません。フォルダーがない、または 2 つ以上ある場合は失敗を返します。
- 既存の設定とワールドを上書きしません。例の設定ファイルは、設定ファイルがないときだけ展開します。
- ダウンロードしたファイルをすべて検証します。バイナリごとに公式チェックサムを使います。公式チェックサムがなければ、固定した公式ホストへの HTTPS、アーカイブの CRC、期待する実行ファイルの存在で確認します。調査表に「公式チェックサムなし」と出典を書きます。チェックサムを作り上げたり、コミュニティのハッシュを使ったりしません。
設定ファイル:
- その形式の公式の文法で読み書きします。たとえば Java の
.propertiesファイルには\:と\=のエスケープがあり、行末の\は行を続けます。 - エンコーディングを仮定しません。実際のエンコーディングで読み、同じエンコーディングと同じ改行で書き戻します。テラリアの Windows 版
serverconfig.txtは cp1252 で、コメントに 0x92 のバイトがあります。UTF-8 でしか読まないモジュールは、このサーバーの起動も、設定の保存も、取り込みもできません。 - 変わったキーだけを直します。ほかのキー、コメント、順序はそのまま残します。
- ファイルを読めなかったら書き込みません。ファイルがない場合、読めない場合、解析できない場合はそれぞれ別のケースです。
10. テスト
単体テストと適合性キットは、隔離なしでサンプルファイルを使って動きます。そのため、実際のダウンロード、隔離実行、コンソール方式、Windows でだけ起きる問題は見つけられません。3 段階のテストをすべて行います。
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 実サーバーでのテスト(プルリクエストの前)
4 章を終えたら、実際のサーバーフォルダーでモジュールの関数を呼びます。
- 実際のダウンロードで
install_serverを実行します。この OS のファイルだけがフォルダーにあることを確認します。 get_launch_commandが返したコマンドでサーバーを起動します。準備完了のパターンが一致することを確認します。- コマンドテンプレートを 1 つずつ送ります。サーバーが受け付けることを確認します。
- 停止コマンドを送ります。サーバーが保存して終了することを確認します。
backup_pathsとreset_serverのパスを、サーバーが作ったファイルと比較します。
10.3 実際の PC でのテスト
Windows PC の通常のサバちゃんインストールを使います。新しいモジュールは隔離実行で動くため、このテストで隔離実行の問題も見つかります。
- モジュールフォルダーを、サバちゃんのデータフォルダーの
modules\<名前>\にコピーします。 saba-chan-cli module refreshを実行します。saba-chan-cli server add <サーバー> -m <モジュール>を実行します。- サーバーを起動します。サバちゃんが準備完了を表示することを確認します。
saba-chan-cli run <サーバー> <コマンド>でコマンドを送り、saba-chan-cli server console <サーバー> --printで返答を読みます。- 設定を変えてサーバーを再起動します。サーバーが新しい値を使うことを確認します。
saba-chan-cli backup create <サーバー>でバックアップを作り、中のファイルを確認します。- サーバーを停止します。サバちゃんが正常終了を記録し、ワールドのセーブが残っていることを確認します。
- ワールドを初期化します。削除されたファイルと残ったファイルを確認します。
[module.dependencies] saba-core がまだリリースされていないバージョンを要求している場合、通常のインストールはそのモジュールを読み込みません。そのバージョンのリリース後に PC でのテストを行います。依存バージョンを下げません。
11. プルリクエスト前のチェックリスト
-
RESEARCH.mdの項目ごとに出典があり、出典ごとに「文書」か「実測」が書かれている。 - アーカイブのエントリーと既定のファイルの元のバイト列を確認した。
- 実際のサーバーを起動し、生の出力、
helpの出力、保存後のファイルを記録した。 - 宣言したコマンドがすべて
helpの出力にある。 - サーバーがコマンドに返答する。返答しない場合は
[launch] console = "pty"を設定した。 - コンソールパターンはすべて実測した出力から作り、プロンプトと言語ごとの翻訳を受ける。
- ランタイムはすべて固定版のポータブルで、モジュールがダウンロードしたファイルを検証する。
- インストールはこの OS のフォルダーだけを展開する。
- 設定ファイルのエンコーディングと改行が保たれる。
- ワールドの初期化は、サーバーが作ったファイル(ゲームが作るバックアップを含む)だけを削除する。
- モジュールは
msiexec、Windows サービス、mkdtempのフォルダー、ループバックへの直接接続を使わない。 - 実サーバーでのテストと実際の PC でのテストを行った、またはできなかったテストを書き残した。