文書化されたすべてのHookshot v2.0.11ランタイムクラッシュ、GPUドライバーハング、テクスチャ異常、ビルダー抽出エラーを診断・解決します。問題タグ（#1161、#817、#57、#1176）や症状で以下の10件の検証済み障害シートを検索・絞り込み、3つの診断ペイン（症状、環境変数フラグ、解決策）を確認して、適切なRX_*環境変数を適用してください。
代表的な問題タグ（#1161、#817、#57、#1176、RX_*診断）で絞り込むか、症状のキーワードで検索してください。各障害シートには、関連する障害へのリンクとともに、確認された症状、環境変数/起動フラグ、検証済みのv2.0.11解決策の3つの区分ペインが表示されます。
ハイラル平原や神殿への重いエリア遷移時に、ASTCテクスチャプールとシャドウカスケードが物理VRAMをオーバーフローするか、ドライバーのTDRタイムアウトをトリガーすると発生します。
Steam Deck（Mesa RADV）環境でデクの樹の中や蜘蛛の巣の部屋に入ると、シェーダー2c56dc1006942f74のメッシュレットサブグループカリングが原因でGPUコマンドバッファがハングすることがあります。
一部のAMD Windows AdrenalinおよびLinuxドライバーがコンピュートASTC-to-BC7トランスコーダを誤コンパイルし、HUDアイコンやコキリの草木にカラフルな4x4マクロブロックノイズを発生させます。
パッチ v131072 が適用されていないベース v0 ダンプ、Switch 2 Title ID 0400486024DEC000 以外の N64/3DS ROM、または v2.0.11 より前のバージョンで非ASCII文字を含む Windows パスが指定された場合、アセットビルダーは処理を中断します。
1つ以上の64ビットNVN2シェーダーハッシュのドローコールをスキップし、プレイヤーや開発者がどのSPIR-Vパイプラインがドライバーのクラッシュや描画異常を引き起こしているかを特定できるようにします。
個別のゲスト関数アドレス（`0x7100xxxxxx`）またはバイナリ全体を、静的 C 変換コードではなくソフトウェア ARM64 インタプリタ経由で実行します。
stdout/stderrの出力詳細度をtraceからerrorまで制御し、GitHubで不具合を報告する際に対象ゲスト関数の開始/終了レジスタ状態（`X0`～`X7`）を記録します。
メッシュシェーダー非対応環境の開発者がRomFSのマウント、オーディオ、およびセーブデータの解析をverifyできるよう、no-op nullレンダラーおよびRX_BOOT_DIRECT=1を初期化します。
Ubuntu 22.04/24.04またはlibfuse2のない最小構成ディストリビューションでは、実行権限を付与するか--appimage-extractを使用しない限り、Hookshot-v2.0.11-Linux-x86_64.AppImageのダブルクリックは警告なく失敗します。
書き込み中断からの復旧のため、autosave.savへフォールバックするか、scripts/oot_saves.pyを用いてCRC32Cヘッダーチェックサム（`0x0008`）を再計算します。
VRAM プリセットを下げてもクラッシュや進行不能（ソフトロック）が解決しない場合は、RX_LOG_LEVEL=debug と RX_SKIP_SHADERS=<hash> を組み合わせて特定の NVN2 SPIR-V パイプラインに原因があるかをテストするか、RX_FORCE_INTERP=0x7100xxxxxx（または RX_FORCE_INTERP=all）を設定してゲスト関数を静的 C ではなくソフトウェア ARM64 インタプリタ上で実行してください。
ASTC テクスチャプールとシャドウカスケードが物理 VRAM を超過、または分離型プレゼントキューが TDR タイムアウトを誘発 → Insert/F1 プリセットを Low/Medium に下げ、Hookshot v2.0.11 を実行してください。
デクの樹の中に入るとメッシュシェーダー2c56dc1006942f74が実行され、RADVのwave64 ballotがGPUコマンドバッファをストールさせます → RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%を指定してください。
Adrenalin / RADVコンピュートシェーダーがコキリの森の木々やHUDアイコン上の4×4 BC7ブロックを破壊します → RX_VK_ASTC_RGBA8=1をエクスポートしてCPU/ソフトウェアRGBA8テクスチャ復号を強制してください。
| 障害名および Issue 参照 | 影響を受けるプラットフォーム | 環境変数 / フラグ | 関連する障害 |
|---|---|---|---|
VK_ERROR_DEVICE_LOST GPU TimeoutまたはVRAMの枯渇（#1161） Issue #1161 | 4 GB〜6 GBのVRAM GPU、またはオーバークロックされたVulkanドライバー | graphics_preset=Low/Medium または RX_SKIP_SHADERS=<hash> | |
Steam Deck / Linux RADV での「デクの樹サマの中」フリーズ (#817) Issue #817 | Steam Deck LCD/OLED＆Linux AMD RADV（Mesa < 24.3） | RX_VK_MESH_NOCULL=2c56dc1006942f74 | |
AMD RDNA 2 / RDNA 3 における草木のブロック化 & HUD テクスチャ乱れ (#57 / #1006) Issues #57＆#1006 | AMD Radeon RX 6000 / RX 7000シリーズ（Windows＆Linux） | RX_VK_ASTC_RGBA8=1 | |
HookshotBuilder アセット展開の失敗または NSO ハッシュ不一致 (#1176 / #990) Issues #1176＆#990 | Windows x64 & Linux x86_64 HookshotBuilder | タイトルID 0400486024DEC000 v131072（e0f3ccfa）が必須 | |
破損したカスタムまたは Driver 固有の Shaders の切り分け（RX_SKIP_SHADERS） docs/DEVELOPMENT.md | すべてのVulkan 1.3 プラットフォーム | RX_SKIP_SHADERS=<hash1>,<hash2> | |
ARM64 Interpreter によるリフト済み C 関数のリグレッション回避（RX_FORCE_INTERP） docs/DESIGN.md＆docs/DEVELOPMENT.md | Windows x64＆Linux x86_64 | RX_FORCE_INTERP=0x7100123450 または RX_FORCE_INTERP=all | |
詳細なVulkanおよびHLEシステムコールログの有効化（RX_LOG_LEVEL＆RX_TRACE_FUNC） docs/DEVELOPMENT.md | Windows x64＆Linux x86_64 | RX_LOG_LEVEL=debug / RX_ABORT_ON_UNIMPL=1 | |
メッシュシェーダーなしでのアセットロード＆ブート処理テスト（RX_GPU_BACKEND=null） docs/DEVELOPMENT.md | ヘッドレスCIランナーおよびメッシュシェーダー非対応テスト環境 | RX_GPU_BACKEND=null RX_BOOT_DIRECT=1 | |
Linux AppImageが起動しない（chmod +xまたはlibfuse2の欠落） README.md Linux Setup | Linux x86_64 (Ubuntu, Debian, Fedora, Arch) | chmod +x *.AppImage または --appimage-extract-and-run | |
セーブスロット破損または手動セーブパス指定（RX_SAVE_PATH＆oot_saves.py） docs/SAVES.md | Windows x64＆Linux x86_64 | python3 scripts/oot_saves.py verify save_00.sav / RX_SAVE_PATH |
Hookshot におけるコミュニティサポート報告の大半は、ハードウェア固有の3つの問題に起因しています。第1に、Issue #1161（VK_ERROR_DEVICE_LOST）は2つの明確な状況で発生します。NVIDIA 621系ドライバー環境において独立した Vulkan プレゼントキューが有効な状態で起動時シェーダー準備を完了した直後（v2.0.9 で緩和され、v2.0.11 で独立プレゼントキューを無効にしつつ RX_VK_WB_DIFF=1 を再有効化して改善）、あるいは 4 GB〜6 GB GPU 環境でハイラル平原や神殿の大規模なエリア遷移時に ASTC テクスチャプールとシャドウカスケードが物理 VRAM を超過した場合です。Insert / F1 メニュー内の Graphics Preset を Low（1.5 GB プール）または Medium（2.5 GB プール）に下げることで、VRAM の枯渇を防止できます。
第2に、Issue #817 はバージョン 24.3 未満の Mesa を実行している Steam Deck LCD/OLED および Linux AMD RADV 環境に影響します。デクの樹の中やクモの巣の部屋に入ると、BGM はループ再生され続けるものの GPU コマンドバッファがハングアップします。このハングは NVN2 メッシュシェーダー 2c56dc1006942f74 内のサブグループメッシュレットカリングに起因します。Steam の起動オプションに RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% を設定することで、測定可能な FPS 低下なしに該当シェーダーのカリングを回避できます。第3に、AMD Radeon RX 6000 / RX 7000 GPU における Issues #57 および #1006 では、コンピュート ASTC-to-BC7 トランスコーダーのドライバー誤コンパイルにより、草木や HUD アイコン上に 4x4 の虹色ブロックノイズが発生します。RX_VK_ASTC_RGBA8=1 をエクスポートすることで、可逆なソフトウェア RGBA8 伸張へと切り替わります。
アセット抽出またはCコンパイル中にHookshotBuilderが失敗する場合、次の3つの前提条件をverifyしてください：(1) ダンプがベースv0ダンプやN64/3DS ROMではなく、アップデートv131072・ExeFS main NSO SHA-1プレフィックスe0f3ccfa（e0f3ccfa56256410941279ef0b2501356be2222c）のSwitch 2 Title ID 0400486024DEC000と一致していること；(2) 非ASCII Windowsユーザーパスによるエラー（#1176）、古い生成済みC変換の競合（#1197）、不足していたLinux AppImageヘッダー（#990）が修正されたHookshot v2.0.11を実行していること；(3) 展開された26.2 GBのRomFSと、生成される1.4 GBのCソース用に、最低30 GBの空きディスク容量があること。
高度なデバッグのために、Hookshotにはdocs/DEVELOPMENT.mdで文書化された詳細な環境変数が用意されています。RX_LOG_LEVEL=debugおよびRX_ABORT_ON_UNIMPL=1は未実装のHorizon OS HLEサービスコールを浮き彫りにし、RX_SKIP_SHADERS=<hash1>,<hash2>は描画破壊を切り分けるために特定の64ビットNVN2シェーダーパイプラインを無効化します。RX_FORCE_INTERP=0x7100xxxxxxは問題の疑われるゲスト関数をソフトウェアARM64インタプリタ経由で実行し、RX_GPU_BACKEND=nullはRX_BOOT_DIRECT=1と組み合わせてヘッドレスブート検証に使用できます。
Steam DeckまたはLinux Steamでは、Hookshotを右クリックして「プロパティ」→「起動オプション」を開き、RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%と入力します（複数の変数を指定する場合は%command%の前に並べます）。Windows PowerShellでは、ビルドディレクトリから$env:RX_VK_ASTC_RGBA8=1; .\hookshot.exeを実行するか、Windowsの「Systemのプロパティ」→「環境変数」に変数を追加してください。
v2.0.10 より前のバージョンでは、中断やバージョン間のアップデートにより work/sa/gen/ 内に古い生成済み C ファイルが残り、clang/lld のリンクエラーが発生することがありました。Hookshot v2.0.11 にアップデートすると、コンパイル前に古い中間生成コードが自動的に破棄され、旧バージョンの変換シャードがクリーンアップされます。
まずセーブディレクトリでautosave.savを確認し、それをsave_00.savに上書きコピーしてください。手動でセーブファイルを編集した場合は、「python -m nx2.oot_saves verify save_00.sav」（またはexport-jsonに続けてimport-json）を実行し、ヘッダーオフセット0x0008に必要なCRC32CチェックサムをHookshotに再計算させてください。
既知の Issues #57、#817、#990、#1006、#1161、#1176、および動作要件に関する主要ソース。
RX_VK_MESH_NOCULL、RX_VK_ASTC_RGBA8、RX_SKIP_SHADERS、RX_FORCE_INTERP、RX_LOG_LEVEL、およびRX_GPU_BACKEND=nullについて記載。
64 KBのsave_00.sav構造、オフセット0x0008のCRC32Cチェックサム、autosave.savフォールバック、およびscripts/oot_saves.pyを規定。
v2.0.9 NVIDIA 621ホットフィックス（#1161）、v2.0.10 ビルダークリーンアップ（#1176/#1197）、およびv2.0.11 RX_VK_WB_DIFF=1の再実装を検証。