Shenmue RTA Scope

Steam版 Shenmue I&II バンドルに含まれる Shenmue I（v1.07想定）向けの、外部読み取り専用デバッグHUD / ロガーです。

できること

• ゲームメモリを書き換えずに読み取ります（OpenProcess / ReadProcessMemory / CloseHandle のみ使用）
• 芭月涼の座標・向き・エリアID・ゲーム内時刻をコンソールHUDに表示します
• 状態変化（エリア遷移、時刻ジャンプ、ロード、メニュー開閉）を検出し、座標付きで記録します
• 解析用に CSV / JSONL ログを出力します
• コンソール上で HUD 切替・ログ切替・マーカー保存・設定再読込のホットキーが使えます

モード

フラグ	説明
--demo	疑似ゲームデータで動作します。実ゲームは不要です
--live	起動中の Shenmue.exe にアタッチします（Windows専用）
--validate-config	address map と area names の JSON を検証します

インストール

必要環境

• .NET SDK 8.0+
• --live モード用に Windows
• Steam版 Shenmue I&II バンドル（対象は Shenmue I v1.07）

セットアップ

git clone <this-repo>
cd hazuki_scope
dotnet build

最初の起動

まずは demo mode で起動確認するのがおすすめです。

dotnet run --project src/ShenmueRtaScope -- --demo

実ゲーム連携を使う場合は、先に src/ShenmueRtaScope/Data/signatures_steam_shenmue1_107.json のオフセットを実値に更新してください。

ビルド

dotnet build
dotnet test

テスト

• テストプロジェクト: tests/ShenmueRtaScope.Tests
• xUnit を使用
• テストケース名は日本語で付与済み

実行方法:

dotnet test ShenmueRtaScope.sln

主な対象:

• アドレスマップ読み込みと必須キー検証
• モジュール相対アドレス解決
• イベント検出
• CSV / JSONL ログ出力
• エリア名解決

実行

dotnet run --project src/ShenmueRtaScope -- --demo
dotnet run --project src/ShenmueRtaScope -- --validate-config
dotnet run --project src/ShenmueRtaScope -- --live

live mode は src/ShenmueRtaScope/Data/signatures_steam_shenmue1_107.json からアドレスを、src/ShenmueRtaScope/Data/area_names.json からエリア名を読み込みます。

ドキュメント

• docs/how-to-find-addresses.md — Cheat Engineで Shenmue I のオフセットを探す手順
• docs/rta-usage.md — 実行方法とホットキー
• docs/memory-map.md — address map JSON の形式と必須キー
• docs/testing-strategy.md — 自動テスト範囲と live mode の手動確認方針

注意点

• live mode には実アドレスが必要です。Cheat Engine でアドレスを見つけてから Data/signatures_steam_shenmue1_107.json を更新してください。
• live mode は Windows と管理者権限を前提にします。
• demo mode はどのプラットフォームでも動作します。

ライセンス

MIT