キャプテン・バイブルのリバースエンジニアリング
Captain Bible Reverse Engineering (github.com)
要約
本リポジトリは、1990年代のDOSゲーム「Captain Bible in the Dome of Darkness」のリバースエンジニアリングのための再現可能な環境と調査ノートを提供します。FreeDOS/QEMU環境と静的・動的解析の計画が完了しており、ゲームのメカニクスやポータブル互換性契約を定義するクリーンルームエンジン仕様も含まれています。記事では、ゲームの実行方法、FreeDOSイメージの再構築、実行可能ファイルの解析、リソースアーカイブの抽出、グラフィックのレンダリング、シーンバイトコードの検査について詳細に解説しています。
全文翻訳
Captain Bible リバースエンジニアリング
[画像: リバースエンジニアリングのドキュメント] [画像: クリーンルーム仕様]
このリポジトリには、1990年代のDOSゲーム「Captain Bible in the Dome of Darkness」のリバースエンジニアリングのための再現可能な環境と研究ノートが含まれています。元のゲームファイルは CB/ にあることを想定しており、Gitでは意図的に無視されています。
FreeDOS/QEMU環境、および計画されている静的・動的解析は完了しています。公開されている2冊の書籍のソースは docs/ および spec/ にあります。進行中のチェックリストについては PLAN.md を、完全なアクティビティログについては docs/src/progress-log.md を参照してください。
ドキュメント
- リバースエンジニアリングドキュメント は、研究プロセス、証拠、回収されたフォーマット、実行可能ファイル解析、およびプロジェクトの進捗を記録します。
- クリーンルームエンジン仕様 は、DOSプログラムの内部に依存せずにエンジンを実装するためのゲームメカニクスとポータブル互換性契約を定義します。
要件
- QEMU (
qemu-system-i386およびqemu-imgを含む) - mtools (
mformat,mcopy,mmd,mdir,mtype) unzip- Python 3
- Pillow (
ART/PALレンダリング用) - Cコンパイラ、
pkg-config、およびDOSトレース用のGLib開発ヘッダー - POSIXシェル
- mdBook (研究および仕様書用)
- Rizin (提供されたシンボルスクリプトおよびさらなる逆アセンブリ用)
- 最新の安定版Rustツールチェーン、SDL3、および
pkg-config(クリーンルームエンジン用)
セットアップは、macOS/Apple Silicon上のQEMU 11.0.2およびmdBook 0.5.3で開発・テストされています。
ゲームの実行
リポジトリのルートから以下を実行します:
./run.sh
このスクリプトはQEMUを開き、Captain Bibleを自動的に起動します。初回実行時には、build/captain-bible/captain-bible.img に永続的なプレイイメージを作成します。セーブデータはこのイメージに書き込まれ、後続の実行でも利用可能です。macOSでは、ゲームはQEMUの表示可能なCocoaディスプレイを使用し、zoom-to-fit=on が有効になります。QEMUを開く前に、スクリプトはホストイメージのファイル名とゲストパス C:\CBDOME\CB.EXE の両方を出力します。
ゲームはマウスとキーボードの両方の入力をサポートします。QEMUがポインタをキャプチャした場合、macOSでは Control-Option-G で解放できます。QEMUを閉じる前にゲームのエスケープメニューから終了すると、保留中のセーブ書き込みがクリーンに完了します。
QEMUは引き続きSound Blaster 16およびAdLibハードウェアをゲームに提示しますが、サイレントな none オーディオバックエンドを使用します。ゲームオーディオがホストで抑制されている間、Cocoaウィンドウは表示されたままです。
QEMUを開かずにイメージを準備またはチェックするには:
./run.sh --setup-only
現在の CB/ ディレクトリからプレイイメージを再作成するには:
./run.sh --rebuild
--rebuild は永続的なプレイイメージを置き換えるため、それに含まれるセーブデータはすべてリセットされます。
RNGに合わせた、同じゲームデータとセーブステートに対するアクションごとのDOS/Rust比較を行うには、符号なし16ビットの初期状態でDOSを起動します:
./run.sh --rng-seed 1
ランチャーは build/ 配下にパッチ済みの実行可能ファイルを再構築し、それをプレイイメージのユニークな使い捨てクローンにのみ配置し、ゲストコピーを検証し、QEMUスナップショット書き込みでクローンを実行します。CB/CB.EXE を変更することはありません。通常のプレイイメージが存在する場合、--rebuild が明示的に要求されない限り、決定論的な実行はそれを変更しません。比較でプレイイメージの既存コピーではなく CB/ の新しいファイルを使用する必要がある場合は、まずリビルドしてください。通常の起動は、QEMU終了後に実行ごとのクローンを削除します。--setup-only は検査のために表示されたディレクトリを保持します。
Rustエンジン
クリーンルームネイティブ実装は rust-engine にあります。これは同じ元の CB/ データディレクトリを消費し、標準ライブラリのみのエンジンコアと、ターミナルおよびSDL3フロントエンドを含みます。SDL3とpkg-configは必須のビルド要件です。出荷済みの完全なリソースセットを検証し、デフォルトのSDL3フロントエンドを開始するには:
cd rust-engine
cargo run --release -- --data ../CB --validate
cargo run --release -- --data ../CB
cargo run --release -- --data ../CB --rng-seed 1
ターミナルまたは決定論的ティックフロントエンドの場合は `--headless` を渡します。SDL3のセットアップ、コントロール、決定論的なスモークテスト、テキストエクスポート、テスト、および現在のホストフロントエンドの制限については、エンジンREADMEを参照してください。
## FreeDOSの再構築
ベースオペレーティングシステムイメージは、公式のFreeDOS 1.4 LiteUSBディストリビューションから非対話的に構築されます:
tools/setup_freedos_image.py
結果は `build/freedos/freedos.img` です。ビルダーは公開されているSHA-256を検証し、ソースブートコードを保持し、新しいFAT16パーティションを構築し、mtoolsを使用してFreeDOSファイルシステムをコピーします。FreeDOSインストーラーを実行したり自動化したりはしません。
現在のワークスペースイメージには、`C:\CBDOME` に完全なゲームも含まれています。これはベースイメージ構築後に追加されたものです。そのイメージを直接起動する場合、以下を実行します:
CD \CBDOME
CB
ベースイメージを再構築すると、この手動のゲームコピーは削除されます。`./run.sh` を実行すると、ゲームを含む別のプレイイメージが自動的に作成または使用されます。
集中的な単体テストを実行するには:
python3 -m unittest discover -s tests -v
## 実行可能ファイル解析
`CB.EXE` はMicrosoft EXEPACKで圧縮された16ビットMZ実行可能ファイルです。独立して検証された展開済み実行可能ファイルを生成し、記録されたQEMUダンプが存在する場合は、それをリロケートされたプロセスイメージと比較します:
tools/analyze_cb_exe.py CB/CB.EXE
--output build/analysis/CB_UNPACKED.EXE
--memory-dump build/dumps/title-physical-1m.bin
--load-segment 0x627
現在の高信頼度名をRizinにロードするには:
rizin -b 16 -i analysis/cb.rz build/analysis/CB_UNPACKED.EXE
Rizinスクリプトに対し、エントリごとの信頼度と証拠を使用して、140個の名前付き関数、134個の異なるBINハンドラー、および9個のデータシンボルを監査します:
tools/inspect_symbol_map.py
デコーダー、134個の異なるハンドラーシンボル、および25,829個の出荷済みコマンドすべてと、145個のオペコードディスパッチエントリおよびオペランドリーダーパスを独立して比較します:
tools/audit_bin_opcodes.py
チェックされたオペコードごとの結果は `analysis/opcode-audit.tsv` です。
生成された実行可能ファイルとメモリダンプは、無視される `build/` ディレクトリの下に残ります。研究結果、アドレス規約、関数名、コマンドライン動作、および回収されたセーブレイアウトは、mdBookのソースにあります。
インストールされているMiles AIL/MIDPAK OPLティンバーライブラリを検査するには:
tools/inspect_midpak_ad.py CB/SOUND.4
tools/inspect_midpak_ad.py CB/SOUND.4 --list
サウンドドライバーの章では、ゲーム側のすべての34個の `int 66h` サイトと、DIGPAKおよびMIDPAKサービス契約をマッピングします。`./run.sh --trace-dos` は、Cocoaウィンドウを表示したままホストオーディオをサイレントに保ちながら、DOS `int 21h` およびドライバー `int 66h` の両方の呼び出しと戻りを記録します。
## `DD1.DAT` の抽出
メインリソースアーカイブには、回収された24バイトのディレクトリフォーマットとカスタムLZWファミリー圧縮があります。369個のメンバーをリストまたは抽出するには:
tools/extract_dd1.py --list CB/DD1.DAT
tools/extract_dd1.py
--extract RUN.ART
--output build/dd1/RUN.ART
CB/DD1.DAT
tools/extract_dd1.py --extract-all build/dd1/all CB/DD1.DAT
全メンバー出力には各ディレクトリインデックスがプレフィックスとして付けられるため、重複するアーカイブ名も区別されます。抽出ツールは、ディレクトリ、ペイロードマジック、圧縮ストリーム、展開サイズ、および正確な入力消費を検証します。フォーマットの詳細と対応する実行可能ルーチンは、mdBookの `DD1.DAT` 章にあります。
## アートワークのレンダリング
抽出された `ART` リソースには、12バイトのフレーム記述子と、その後に続く行優先の8ビットピクセルが含まれています。それらの色は、個別の768バイトVGA `PAL` リソースから取得されます。それらを検査またはレンダリングするには:
tools/render_art.py build/dd1/all/003_LOGO.ART --list
tools/render_art.py
build/dd1/all/003_LOGO.ART
--palette build/dd1/all/002_LOGO.PAL
--canvas --scale 2
--output build/graphics/logo.png
レンダラーは `--frame` で1フレーム、または `--all-frames` で全フレームを書き出すこともできます。パレットインデックス0はデフォルトで透明(スプライトプレビュー用)です。不透明な描画を再現する場合は `--opaque-zero` を使用してください。mdBookのグラフィックス章では、フォーマットとそのQEMU VGAメモリとのバイト単位の相関関係を文書化しています。
シーンプログラムから推測されるPAL関連付けとともに、すべてのフルスクリーンARTフレームのアノテーション付きコンタクトシートを生成します:
tools/render_fullscreen_gallery.py
CB/DD1.DAT
--output build/graphics/full-screen-gallery.png
nearest-neighborで拡大されたシートには `--scale 2` を使用します。
## シーンバイトコードの検査
抽出された62個の `BIN` リソースにはシーンプログラムが含まれています。回収されたデコーダーは、145個のオペコードすべてに対するオペランドレイアウトとディスパッチ効果を認識しています。出荷済みスクリプトに存在しない23個の値に対しても、保守的な低レベルの名前を割り当てています:
tools/inspect_bin.py build/dd1/all/005_INTRO.BIN
tools/inspect_bin.py build/dd1/all/001_LOGO.BIN --objects
tools/inspect_bin.py build/dd1/all/327_BOSS.BIN --choices
tools/inspect_bin.py
build/dd1/all/337_COMBAT7.BIN --animations --actions
tools/inspect_bin.py
build/dd1/all/334_ROOM3.BIN --start 0x0c96 --limit 0x1754
ほとんどのリソースは最初から最後までコードです。`CP2.BIN` はデータトレーラーを持ち、`ROOM3.BIN` はゼロで埋められた予約ブロックによって区切られた3つのコマンド領域を持つため、それらの領域には明示的な `--start` および `--limit` 値が必要です。mdBookのシーンバイトコード章では、インタープリター、コマンドスキーマ、起動シーケンス、QEMUメモリ相関、および完全なオペコードカタログを説明しています。また、オペコード `0x69` の修正された2ワードレイアウト(線形コーパスから11個のファントムコマンドを削除する)と、宣言されたすべてのオペランドパスの独立した実行可能CFG監査も記録しています。`--objects` ビューは、スレッド/アニメーションタイプや直接オブジェクトの座標、スケール、フラグ、フレーム、ARTスロットを含む、線形コマンド順序で定義された表示レコードを要約します。ライブの10バイトレイアウトと制御フローの注意点については、シーン表示オブジェクト章を参照してください。`--choices` ビューは、ダイアログ選択ソースオフセット、絶対分岐ターゲット、およびインラインテキストをリストします。会話フロー章では、その6バイト実行時テーブル、聖書学習統合、およびライブQEMU相関について説明しています。`--animations` ビューは、各アニメーションヘッダーとその連続する9バイトステップをグループ化します。`--actions` は、画面座標、絶対ターゲット、セレクター、および回収された戦闘とホールの行動ラベルをリストします。戦闘実行時章では、それらの実行時テーブル、BINスケジューラ、行動結果分岐、信仰効果、共有勝利/撤退エピローグ、およびマップ遷移について文書化しています。
制御されたシーンエントリー実験のために、使い捨ての2,752バイトステートでシーン名フィールド(および必要に応じて両方の座標コピー)をパッチし、物理メモリキャプチャをBIN定義と比較するには:
tools/patch_save_scene.py input.SVQ COMBAT1 output.SVQ
tools/patch_save_scene.py input.SVQ ROOM3 output.SVQ --coordinate 13 6
tools/inspect_runtime_tables.py memory.bin
--data-segment 0x14e1
--bin build/dd1/all/343_COMBAT1.BIN
`--coordinate` なしでは、パッチャーは2つの保存された20バイトシーン名フィールドのみを変更します。オプションの座標は、チェックポイントブロックとライブ変数ブロックの両方で変数11と12を置き換えます。これは研究コピーでのみ使用してください。実行時インスペクターは、カウントされたアクションおよびアニメーションテーブルと10個のBINスレッドレコードをデコードします。`--bin` を使用すると、アクションターゲットとアニメーション定義フィールドを静的コマンドストリームと比較します。
`CP2.BIN` は、完全な16ノードのUnibotナビゲーショングラフで終わります。その4つのヘッディング出口、7つのパイロンノード、タワー、右下のマップ座標、およびノードごとの遷移値を検査するには:
tools/inspect_unibot.py build/dd1/all/315_CP2.BIN
Unibotとエンディングの章では、7つの救助ボーディングゲートから、すべてのパイロン遭遇、一度きりのAnnoy Cyberイベント、タワーゲート、そして成功および失敗したエンディングチェーンまでを追います。
## オーディオリソースの検査
41個の `ABT` メンバーは、圧縮された9,000 Hzの符号なし8ビットモノラルサウンドエフェクトです。1つを検査するか、標準のWAVファイルに変換するには:
tools/convert_abt.py build/dd1/all/306_D003.ABT
tools/convert_abt.py
build/dd1/all/306_D003.ABT
--output build/audio/d003.wav
32個の `XMI` メンバーは、1シーケンスのIFF/XMIDIミュージックリソースです。それらのコンテナ、ティンバー、およびイベントストリームを検証および要約するには:
tools/inspect_xmi.py build/dd1/all/267_MUS001.XMI
## ゲームテキストの検査
`DD1.DAT` の拡張子なしのリソースには、翻訳固有の詩のインデックスが含まれています。これらは、嘘、言い換え、質問、説明、および会話を含む `DDLA` から `DDLR` ファイルとペアになります。結合されたレコードを検査するには:
tools/inspect_text_resources.py
CB/DD1.DAT --data-dir CB
--translation N --bank A --record 0
翻訳は `K`, `N`, `R`, `T`、バンクは `A` から `G` および `R` です。mdBookのテキストフォーマット章では、バイナリレイアウトと、ゲームに組み込まれたスタディファイルエクスポートに対するそれらの検証の両方を文書化しています。
両方のツールは構造的な不整合を拒否し、入力を正確に消費します。mdBookのオーディオ章では、フォーマット、実行可能デコーダー、およびホストデコードされた `D003.ABT` とそのライブQEMU PCMバッファとのバイト単位の比較について文書化しています。
## セーブゲームの検査
各プレイヤープレフィックスには、243バイトの `.SV0` ラベルインデックス、9つの通常状態ファイル、および個別の `.SVQ` クイックセーブがあります。固定フォーマットのいずれかを検査するには:
tools/inspect_save.py CB/DDGAMES.SV0
tools/inspect_save.py CB/DDGAMES.SV3 --descriptors
tools/inspect_save.py CB/DDGAMES.SV9 --variables
インスペクターは正確なサイズを検証し、9つの固定C文字列ラベルバッファをデコードし、ライブ状態ブロックとチェックポイント状態ブロックを分離し、保存された設定とテキスト記述子を公開します。mdBookのセーブフォーマット章では、2,752バイトの状態レイアウト、プレイヤープレフィックスの動作、クイックセーブ接尾辞の変更、スナップショットコピー、エラー動作、および提供されたすべてのセーブからの証拠について文書化しています。`--variables` ビューは、100個の符号付きスクリプトワード、名前付きマップおよび信仰フィールド、埋め込まれた128ビットフラグバンク、パワーアップ、および犠牲者救助フラグをデコードします。
## ワールドマップの検査
アーカイブには21個のワールドマップが含まれています:Easy、Normal、Difficult設定でのレベルAからGまで。それぞれが3バイトの変更可能なセルからなる行優先の16×16グリッドです。ロケーションタイプのグリッドを表示し、オプションでゼロ以外のセルをリストします:
tools/inspect_map.py CB/DD1.DAT --map CE
tools/inspect_map.py CB/DD1.DAT --map CE --cells
tools/inspect_map.py CB/DD1.DAT --map CE --rooms
tools/inspect_map.py CB/DD1.DAT --map CE --hall-features
セルビューは4つの接続方向を命名します。ルームビューは、5つのルームクラス(犠牲者、トラップ、祈り、通信、ジャンプトンネル)と、各ルームのエントランスサイドおよび変更可能なパラメータをデコードします。ホールフィーチャービューは、7つのサイバータイプ、隠されたスパイダートリガー、聖書ステーション、クリアされた遭遇、およびレベル出口を識別し、未解決の環境状態は名前を付けずに残します。
元のマップとセーブでシリアライズされたライブグリッドを比較します:
tools/inspect_map.py
CB/DD1.DAT --map CE --compare-save CB/DDGAMES.SV3
mdBookのワールドマップ章では、リソース命名、セルアドレス指定、パックフィールド、ルームディスパッチとオリエンテーションエンコーディング、シーンコマンド、ホワイエエンティティと遷移、探索ビット、マップ画面動作、および提供されたセーブグリッドのバイトレベル識別について文書化しています。
## QEMU DOSコールトレーシング
QEMU TCGトレーサーとモニターソケットを有効にしてゲームを実行します:
./run.sh --trace-dos
Cocoaウィンドウは表示されたままで、ホストオーディオはミュートされたままです。トレースモードは、TCG翻訳ブロックごとに1つのゲスト命令を使用するため、レジスタ値をDOSおよびドライバー割り込み境界でサンプリングできます。したがって、通常の実行よりも遅くなります。生成されたプラグイン、トレース、モニターソケット、スクリーンショット、およびメモリダンプは、無視される `build/qemu-trace/` ディレクトリの下に保持されます。
トレースは、再構築されたエントリポイント `0627:CB5C` でアクティブ化され、コードセグメント `0627` からのBIOSキーボード `int 16h`、DOS `int 21h`、マウス `int 33h`、およびサウンドドライバー `int 66h` の呼び出しと戻りを記録します。これにはライブAXおよびその他の引数/結果レジスタが含まれます。これらのアドレスは、現在の決定論的なFreeDOSイメージに対して安定しています。DOS環境またはブート構成が変更された場合、フィルターに依存する前にロードセグメントを再確立してください。
## ドキュメント
ドキュメントの整合性チェックを実行し、両方のブックをビルドします:
tools/check_documentation.py
mdbook build docs
mdbook build spec
チェッカーは、SUMMARYの網羅性、ローカルチャプターリンクとアンカー、および両方のブックのシェル例で使用されているリポジトリコマンドを検証します。研究ブックの「結果の再現」章には、回収されたすべてのフォーマットとシステムに対する単一のエンドツーエンドコマンドシーケンスが記載されています。「既知のギャップと証拠の境界」では、確認された結果を意図的に名前が付けられていないフィールドや、制御されたシーンエントリーキャプチャの限界から分離しています。レンダリングされたブックは `docs/book/` に書き込まれます。カスタムスタイルシートは、mdBookの固定750ピクセルのコンテンツ制限を削除するため、テーブルや逆アセンブリリストは利用可能なブラウザ幅を使用します。
クリーンルーム仕様は `spec/book/` に書き込まれます。そのソースは `spec/src/SUMMARY.md` から始まり、実装契約として編成されています:プレイヤーメカニクス、ライフサイクルと入力、すべてのリソースフォーマット、すべての145のシーンオペコード、ランタイムサービス、マップ、ダイアログ、戦闘、進行とエンディング、セーブ、設定、適合性テスト、および明示的に境界付けられた未指定の詳細。
研究ブックまたはその公開ワークフローを変更する `main` へのプッシュは、GitHub Actionsでその出力をビルドおよび公開します。仕様は、個別のローカルビルドとして残ります。ワークフローは、アクションタブから手動で開始することもできます。テスト済みのmdBook 0.5.3 Linuxバイナリをインストールし、公開されているSHA-256を検証し、`docs/book/` をPagesアーティファクトとしてアップロードし、以下にデプロイします:
[https://peterkelly.github.io/captain-bible-re/](https://peterkelly.github.io/captain-bible-re/)
リポジトリのPagesソースはGitHub Actions用に構成されており、最初のデプロイは正常に完了しました。関連する後続のプッシュは自動的に公開されます。生成されたブックファイルはコミットされません。