mashup-mods

マッシュアップ：あるゲームの中に別のゲームを入れる

2026年9月、AIが構築したマッシュアップの数々が話題になりました。MW2でスケートボードをするもの、Skyrimや Elden Ringの中にMinecraftを入れるもの、Minecraftの中にBlack Ops 2を入れるものなどです。これらには、いくつかの 定番パターンがあります。アイデアを実現できる最も軽量なものを選び、コードを書く前に検証手段を計画してください。こうしたプロジェクトが失敗するのは、コードが足りないからではなく、方向性がぶれてしまうからです。

パターンを選ぶ前に

マッシュアップのコードを書く前に、以下の手順を進めてください。ここで紹介する経路、パターン、プロジェクトは、実際に存在するマッシュアップに基づいています。最も近い事例から始めるか、別の方法を設計して、その理由を書き留めてください。最後にあるガードレールは、常に適用されます。

1. ゲストゲームに何を求めているのかを明確にします。 実際の挙動（物理、インベントリ、戦闘）なのか、それとも見た目や特定のメカニクスだけなのかを確認します。はっきりしない場合は質問してください。その答えによって、ゲストを実行する必要があるか、またアイデアを実現する最も軽量な経路が決まります。
2. 最も近いマッシュアップの経路を特定します。 knowledge/techniques/choosing-a-mashup-route.md では、マッシュアップを7つの経路に分類しています。「Passthrough」だけでは意味があいまいです。これは、状態交換、合成画像、ホストによるゲストメッシュの描画という、異なる3種類の構築方法を指します。
3. references/mashup-cases.md から最も近い既存プロジェクトを探します（経路、バージョン、プレイヤーの所有者、単位、通信方式）。そのリポジトリにアクセスできる場合は、READMEと設計ドキュメントを読んでください。実際に動かすまでは、そこで読んだ内容を作成者の報告として扱います。また、両方のゲームと両方のエンジンについて um kb search を実行してください。どちらかのゲームに関する他のエージェントのメモも、ここで役立ちます。
4. ゲストを実行せずに再構築する場合（実際のホスト内で、そのエンジンまたはメカニクスの一部を再構築する場合）、再構築する部分をどこで実行すべきか、また元のゲームとどう比較して確認するかについて、knowledge/techniques/rebuilt-guest-engine-inside-a-host.md を読んでください。
5. 2つのゲーム、エンジン、またはプロセス間で状態をやり取りする箇所ごとに、契約を書きます。プレイヤーの所有者と操作をどう戻すか、単位と軸、各チャネルと満杯または遅延時の動作、プロトコルのバージョンとバイト順、ライフサイクルを明記してください。docs/CONTRACT.md に記載してください。詳しくは knowledge/techniques/bridge-contracts-ownership-units-and-lifecycle.md を参照してください。
6. 動作を確認する方法を決めます。 機能を追加する前に、選んだ経路で最初に作る範囲と、それを証明する確認方法を決めてください。knowledge/techniques/choosing-a-mashup-route.md の最初のスライスの表と、knowledge/techniques/oracles-how-agents-know-a-mod-works.md を参照してください。
7. 計画を記録し、構築前にユーザーに伝えます。 mod-any-game スキルで求められているとおり、選んだ経路とその理由を MODLOG.md に記載します。さらに、同じ内容に加えて、各プレイヤーが用意してインストールする必要があるもの（および対象OS）と、最も近い既存プロジェクトから計画がどう異なるかをユーザーに伝えてください。

後でインストーラーやローダーを公開する前に、 knowledge/techniques/installers-load-order-and-loaded-code-checks.md を読んでください（ロード済みコードの確認、ロード順、 ダウンロードの固定、正確なアンインストール）。

パターン1：コンテンツを移植する（最も軽量）

敵、武器、ブロックの種類を、ゲストを模倣した新しいホスト側のコンテンツとしてホストに追加します。 例：「ClaudeがDark Soulsにクリーパーを追加」、MinecraftのブロックをElden Ringのアイテムにする。

• ゲストの挙動を、信頼できる一次情報から確認します。デコンパイルするか、Wikiに記載された正確な数値（速度、 タイマー、ダメージ）を読みます。ホストのMOD APIで再実装します（ホストのAIステートマシン、ホストの飛翔体）。
• アセット： ゲストのファイルをMODにコピーしてはいけません。実行時またはインストール時に、ユーザーのインストール先から変換するか（コンバータースクリプト）、falを使って似た見た目のものを作成します。
• IPCを使わないため、安価で堅牢です。ローダーがあるホストなら、どれでも動作します。
• 変換の実例：Bloons TD 6のアセット（Unity 6）をプライベートなMinecraftリソースパックに変換する例は、 knowledge/games/minecraft/bloons-td-6-in-minecraft.md のアセットパイプラインのセクション6を参照してください。

パターン 2：パススルー（2 つのゲームを同時に動かす）

Minecraft-in-Skyrim についての chasm の説明です。「Minecraft と Skyrim を同時に実行し、両方に通信できる MOD を作ります。次に、表示したいものを適切な場所でレンダラーにパススルーし、衝突データなどを Minecraft に返します。」 ソースは現在、SkyCraft として公開されています。0.1.2 では、Fabric MOD が Minecraft のメッシュとアトラスをエクスポートし、SKSE プラグインが Skyrim 自身の D3D11 ワールドパス内にそれらを描画します（ネイティブの深度、フォグ、ライト、キャプチャされた太陽光の影を使用）。画像としてキャプチャされるのは、手、HUD、画面のみです。Skyrim の Havok シェイプは、三角形とボクセルとして返されます。LibertyCraft はこれをフォークして GTA IV 向けにし、ゲスト側を維持しました。以下の設計が、これを構築する標準的な方法です。

1. ゲストプロセス（例：Fabric MOD を導入した Minecraft、またはヘッドレスの再実装）：シミュレーションを実行し、ティックごとに状態を公開します。これは、プレイヤーの近くのエンティティやブロック、またはレンダリング済みレイヤーです。
2. トランスポート（すべて 127.0.0.1 上）：
   • 状態：共有メモリのリングバッファ（CreateFileMapping）、または UDP／名前付きパイプ。
   • 制御：JSON 行または HTTP。
   • GPU フレーム：DXGI 共有ハンドル（CreateSharedHandle／OpenSharedResource1 とキーミューテックス）、Vulkan 外部メモリ、または Spout2。実際には、フレームブリッジ（このリポジトリの GTA V の例、NewVegasCraft、CrossOver Elden Ring／MHW ブリッジ）は、いずれもピクセルを CPU に読み戻して共有メモリ経由でコピーします。これにより、GPU 間や Wine の境界を越えた通信も可能です。アップロードの予算を見積もってください（knowledge/techniques/frame-compositing-depth-and-pose-sync.md を参照）。
3. ホストへのインジェクション：ホスト側プラグイン（SKSE／xNVSE／UE4SS／REFramework／ReShade アドオン）が、ゲストのジオメトリをホストのパス内に描画します。ホストのビュー・プロジェクション行列（RenderDoc で特定）と深度バッファーを使うか、ホストネイティブのオブジェクトを生成して、ホストのライティングと影を適用します。Skyrim のクリップで Steve に Skyrim のライティングが適用されたことから、フラットなオーバーレイではなく、シーンへの統合であることがわかります。
4. **バックチャネル：**プレイヤーの近くにあるホストの衝突形状（レイキャスト、またはエクスポートされた近傍メッシュ）を、ソリッドブロックまたはコライダーとしてゲストに送ります。入力は一度に 1 つのプロセスにルーティングします。
5. **同期：**すべてのメッセージにタイムスタンプを付け、2 つのフレームレートの差を許容し、どちらかの側が停止した場合に備えてウォッチドッグを設けます。ポーズはピクセルと一緒にのみ公開し、ホスト側で両者を一致させます。ホストのカメラは現在時刻で読み取ります。衝突の処理は方向ごと、コンシューマーごとに異なります。knowledge/techniques/collision-and-combat-bridging.md を参照してください。
6. **小さく始める：**プロセス A の立方体を、適切な位置にプロセス B で描画します。次に毎フレーム位置を更新し、その後に衝突を追加し、実際のコンテンツは最後に扱います。

公開されているブリッジプラグインのテンプレート：chasm-bridge-fnv（軽量な xNVSE プラグイン、ファイルドロップ／HTTP トランスポート、データ駆動型アクション）。examples/terraria-tmodloader/reference/ にある Terraria エージェントブリッジも同じ考え方です。

作業例：GTA V 内で動作する本物の Minecraft

コード：examples/minecraft-gta5-passthrough。各レッスン：knowledge/games/gta-v/minecraft-passthrough.md。

• Minecraft（Fabric mod）： WebSocket を介してホストからカメラ、地面、入力を受け取ります。接続先は 127.0.0.1 です。各フレームで、ワールドの色と深度、および独立した手／HUD オーバーレイを名前付き共有 メモリに書き込みます。
• GTA（ScriptHookV ASI + ReShade add-on）：
  • GTA のカメラと、プレイヤーの下の地面（バリアブロックとして）を送信します。
  • シェーダーで GTA の反転Z深度に合わせて Minecraft の色を合成します。
  • Minecraft の爆発、矢、花火の着弾を GTA の爆発と銃弾に変換します。
• マッピング： 1メートル = 1ブロック。GTA（x, y, z）→ MC（x, z + offset, −y）；yaw = 180 − heading； pitch = −pitch。
• レイテンシー： Minecraft のフレームを GTA のカメラに再投影します。まず回転を合わせ、次に深度を使って 完全な6DoFを合わせます。片方だけが何かを描画するシーン（片側の金色の壁と、もう片側のスカイラインなど）で ポーズの遅延を測定します。
• ゲームなしで開発： その大半はホストゲームをインストールする前に、既知のジオメトリを使う 偽のホストと、実際のコンポジターを実行する偽のD3D11「GTA」を使って開発しました。
• うまくいかなかったこと： ホストゲームの銃をスティーブの手に持たせること（エイムカメラとアニメーションが 合いません）。ホスト側のエフェクトを使うゲストの武器はうまくいきました。

パターン3：デコンプをライブラリとして組み込む

libsm64 は Super Mario 64 のデコンプをライブラリに変換します。衝突情報と入力を渡すと、マリオの状態とメッシュが 返されます。G64 はこれを Garry's Mod に組み込み、ホストからゲストのシミュレーションに衝突情報を渡します。 どのデコンプ／リコンプも（skills/mod-any-game/references/engines/retro-decomp.md を参照）、この方法で ラップできます。アセットにはユーザー自身のROMを使用します。

パターン4：再実装してから融合する（最も大掛かりで、制御性が高い）

• IW4L： LLMが作成したRust製のMW2ランタイム（Bevy + wgpu）です。ユーザーの インストールからMW2のFastFilesを読み込み、D3D9シェーダーをWGSLに変換します。
• Skate 3のRustエンジン： 静的リコンプとIDAデータベースをオラクルとして開発しました。
• マッシュアップ： 両方にMinecraftのRust再実装も加え、1つのプロセスに統合します。スケートのシミュレーションは MW2の兵士を引き継ぐワーカーです。MW2のマップ衝突情報をスケートのワールドに渡します。グラインドレールは 歩行可能な衝突エッジから作成します。スケートのボーンをMW2のスケルトンにリターゲットします。
• 成功につながった要素：
  • オラクルとしてのスクリプト可能なランタイム： spawn; wait 2s; screenshot; dump を使い、ブロッキング動詞と 実行ごとの証拠ファイルを用意しました。
  • 証拠ジャーナル（context/artifacts/<date>/<step>-FINAL|PART）。「成果物にない知識は、存在しないのと同じです。」
  • オーナーが承認したエンドツーエンドテストのみを実施しました。
  • プッシュ前にリテール版のオフセットとデコンパイラーの名前をgrepする公開チェック （um publish check も同様のチェックを行います）。
  • ユーザーのファイル上で動作するコンバーターを使用し、ゲームアセットは一切コミットしませんでした。
• 測定と忠実度： knowledge/techniques/engine-recreation-measures-and-fidelity.md では、各種再構築の測定方法、 スクリプトが忠実度の一部である理由、他のMODに必要なSDKルールを説明しています。

パターン 5：ゲストのルールをヘッドレスで再実装し、ホストはビューとして維持する

ホストは実際のゲームのままです（武器、MOD、マルチプレイヤーなど）。書き換えるのはゲストのルールだけで、ホストから何もインポートしない純粋なシミュレーションとして実装します。ゲームプレイが数値中心のゲスト（タワーディフェンス、カード、パズル、トップダウン2D、ターン制）や、そもそも実行できない、あるいは実行すべきでないゲスト（アンチチートで保護されたクライアントや、オフラインモードのないゲーム）に最適です。例：Minecraft内のBloons TD 6（knowledge/games/minecraft/bloons-td-6-in-minecraft.md）。

• シミュレーションが唯一の信頼できる情報源です。 ゲスト本来のステップレートと単位で実行します（BTD6：毎秒60ステップ、BTD6の単位）。ゲーム速度によって変わるのはホストの1ティックあたりのステップ数であり、dtではありません。
• ゲストの単位とホストの座標を変換する単一のフレーム変換関数を用意し、サーバーとクライアントで共有します（原点、スケール、軸の反転）。
• プレイヤーが触れる必要のあるものにはミラーエンティティを使います。 位置を毎ティック、シミュレーションからコピーし、ダメージ処理やインタラクション処理をシミュレーションに転送するホストエンティティです。ホストがそれらに対して本来行う処理はすべて無効にします：AI、重力、ノックバック、ポーション、火、押し合い。
• 大量に発生するもの（弾、パーティクル）にはホストエンティティを使いません。 ティックごとにバッチ化したスポーンレコードを一度送信し、クライアントでは同じ移動コードを実行します。エフェクトとサウンドも同様にバッチ化し、上限を設けます。
• すべてのUIボタンはコマンドです。 画面にはサーバーのスナップショットを表示し、コマンドを送り返すことで、画面なしでも各アクションをテストできるようにします。
• ホストの機能はシミュレーションに渡し、シミュレーションを迂回させません。 ホストの武器、ブロック、ポーションはシミュレーションのステータスやダメージイベントに変換します。これらがなくてもゲームが同じように進行する必要があります（ヘッドレス実行で確認します）。
• ゲストのアセットは、ユーザー自身のインストールからローカルの非公開リソースパックに変換します。パックがない場合でも、プレースホルダーを使ってMODをプレイできる状態にしておく必要があります。
• オラクル： まずヘッドレスエンジンベンチを実行し（数秒、ホストなし）、次にホスト側のベンチを実行します（knowledge/techniques/oracles-how-agents-know-a-mod-works.mdを参照）。

ガードレール

• オフライン、シングルプレイヤー、またはユーザー自身が運営するサーバーを対象にします。実際のゲームの公式オンラインサービスには、ネットワーク経由で絶対に接続しないでください。
• ゲスト側のものはすべて、ユーザー自身のインストールまたはダンプから取得します。公開するのはコードとコンバーターであり、アセットではありません（um publish check --game）。
• オンライン接続に対応するゲスト（アカウント、協力プレイ、リーダーボードなど）は、ユーザーがオフラインで開始したセッション（オフラインモード、またはそのゲームのネットワークを遮断した状態）に限り起動してフックできます。また、アンチチートを起動してはなりません。フックしたプロセスは、動作中ずっとオフラインに保ちます。オンラインに戻る前に終了し、MODを適用しない状態で起動してください。Setupとanti_cheatにその旨を記載します。フックせずにオフラインでファイルを読み取るだけで十分な場合は、そちらのほうが安全です。オフラインでアンチチートを無効にできないクライアントには、絶対にフックしません（skills/mod-any-game/references/safety.md）。
• AIが作成した部分について正直に伝えます。そうでないと主張したクリエイターは、実際に公の場で批判されました。
• 検証した内容について正直に伝えます。README、設計ドキュメント、合成ピア、または成功したテストは、実際の実行を意味しません（knowledge/techniques/evidence-levels-for-mashup-claims.md）。