モジュールの作り方:調査からリリースまで

信頼できるゲームモジュールを作る全手順。調査、実サーバーでの計測、ポータブルなランタイム、隔離実行、コンソール方式、実際の 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. 実際のファイルを調べる

サーバーをダウンロードできるなら、ファイルを自分で調べます。

  1. アーカイブの全エントリーを表示します。OS ごとのフォルダーがあるか、同じ実行ファイル名が複数のフォルダーにあるかを確認します。テラリアのアーカイブには、Linux/ フォルダーと Windows/ フォルダーの両方に TerrariaServer.exe があります。
  2. 既定のファイルをバイト単位で読みます。エンコーディング(UTF-8、BOM、cp1252)、改行(LF、CRLF)、コメントになっている例のキー、コメントではない行を確認します。
  3. コメントになっている例のキーも設定一覧に入れます。コメントではない行の値が既定値です。

4. 実際のサーバーを起動する

デーモンと同じ方法でサーバーを起動します。stdin と stdout をパイプでつなぎ、生の出力を記録します。ビルド環境で別の OS 向けのサーバーしか動かせなくても、それを動かします。ゲームのコードが同じなら、コマンド、メッセージ、保存の動作は同じです。

次を記録します。

  • 準備完了の行、停止コマンドの後の行、保存にかかる時間
  • help の出力。文書にだけ載っているコマンドは 1 つずつ送り、返答を記録します
  • コンソールのプロンプト。改行なしでプロンプトを出すサーバーでは、次の行がプロンプトで始まります。テラリアは : Server started と出します
  • パイプで送ったコマンドへの返答。返答がなければ、疑似コンソールで再度試します(7 章)
  • サーバーの言語ごとの準備完了・停止メッセージ
  • 起動時と保存時にサーバーが作るファイル。テラリアは world.wld.bak と world.wld.bak2 を作ります

参加メッセージやキックの対象など、ゲームクライアントが必要な項目は空欄にして「未計測」と書きます。


5. 実行の前提:固定版のポータブル

ダウンロードに含まれないランタイムを必要とするサーバーがあります。Java、XNA Framework、Visual C++ ランタイムなどです。PC にインストールされたランタイムは使いません。PC ごとにバージョンが違う可能性があるためです。

次の手順に従います。

  1. 公式ランタイムファイルのアドレス、サイズ、署名、SHA-256 を調査表に書きます。
  2. サーバーに必要な最小限のファイルを見つけます。そのファイルだけでサーバーを起動して確認します。テラリアでは XNA アセンブリ 4 つ(Microsoft.Xna.Framework、.Game、.Graphics、.Xact)、XnaNative.dll、msvcr100.dll、msvcp100.dll です。
  3. install_server で固定版をダウンロードします。公式チェックサムと比較します。公式チェックサムがなければ、有効な発行元署名のあるファイルから記録した SHA-256 と比較します。
  4. 必要なファイルだけをサーバーフォルダーかインスタンスフォルダーに置き、そのパスでサーバーを起動します。
  5. 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 単体テスト

  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 実サーバーでのテスト(プルリクエストの前)

4 章を終えたら、実際のサーバーフォルダーでモジュールの関数を呼びます。

  1. 実際のダウンロードで install_server を実行します。この OS のファイルだけがフォルダーにあることを確認します。
  2. get_launch_command が返したコマンドでサーバーを起動します。準備完了のパターンが一致することを確認します。
  3. コマンドテンプレートを 1 つずつ送ります。サーバーが受け付けることを確認します。
  4. 停止コマンドを送ります。サーバーが保存して終了することを確認します。
  5. backup_paths と reset_server のパスを、サーバーが作ったファイルと比較します。

10.3 実際の PC でのテスト

Windows PC の通常のサバちゃんインストールを使います。新しいモジュールは隔離実行で動くため、このテストで隔離実行の問題も見つかります。

  1. モジュールフォルダーを、サバちゃんのデータフォルダーの modules\<名前>\ にコピーします。
  2. saba-chan-cli module refresh を実行します。
  3. saba-chan-cli server add <サーバー> -m <モジュール> を実行します。
  4. サーバーを起動します。サバちゃんが準備完了を表示することを確認します。
  5. saba-chan-cli run <サーバー> <コマンド> でコマンドを送り、saba-chan-cli server console <サーバー> --print で返答を読みます。
  6. 設定を変えてサーバーを再起動します。サーバーが新しい値を使うことを確認します。
  7. saba-chan-cli backup create <サーバー> でバックアップを作り、中のファイルを確認します。
  8. サーバーを停止します。サバちゃんが正常終了を記録し、ワールドのセーブが残っていることを確認します。
  9. ワールドを初期化します。削除されたファイルと残ったファイルを確認します。

[module.dependencies] saba-core がまだリリースされていないバージョンを要求している場合、通常のインストールはそのモジュールを読み込みません。そのバージョンのリリース後に PC でのテストを行います。依存バージョンを下げません。


11. プルリクエスト前のチェックリスト

  • RESEARCH.md の項目ごとに出典があり、出典ごとに「文書」か「実測」が書かれている。
  • アーカイブのエントリーと既定のファイルの元のバイト列を確認した。
  • 実際のサーバーを起動し、生の出力、help の出力、保存後のファイルを記録した。
  • 宣言したコマンドがすべて help の出力にある。
  • サーバーがコマンドに返答する。返答しない場合は [launch] console = "pty" を設定した。
  • コンソールパターンはすべて実測した出力から作り、プロンプトと言語ごとの翻訳を受ける。
  • ランタイムはすべて固定版のポータブルで、モジュールがダウンロードしたファイルを検証する。
  • インストールはこの OS のフォルダーだけを展開する。
  • 設定ファイルのエンコーディングと改行が保たれる。
  • ワールドの初期化は、サーバーが作ったファイル(ゲームが作るバックアップを含む)だけを削除する。
  • モジュールは msiexec、Windows サービス、mkdtemp のフォルダー、ループバックへの直接接続を使わない。
  • 実サーバーでのテストと実際の PC でのテストを行った、またはできなかったテストを書き残した。