診斷並解決所有已記錄的 Hookshot v2.0.11 執行階段當機、GPU 驅動程式無回應、紋理破圖以及建置器解包錯誤。在下方 10 份驗證問題清單中，透過問題標籤（#1161、#817、#57、#1176）或症狀搜尋與篩選，檢視三欄診斷面板（症狀、環境變數旗標、解決方法），並套用針對性的 RX_* 環境覆寫變數。
依重大問題標籤（#1161、#817、#57、#1176、RX_* 診斷）篩選或依症狀關鍵字搜尋。每份故障清單均提供三欄分格面板 — 觀察到的症狀、環境變數 / 啟動旗標、經實證的 v2.0.11 解決方案 — 以及相互關聯的故障參照。
發生於負載較高的海拉魯平原或神殿場景切換期間，此時 ASTC 紋理集加上陰影串級超出了實體 VRAM，或觸發了驅動程式 TDR 逾時。
在 Steam Deck（Mesa RADV）上進入德庫樹內部或蜘蛛網房間時，可能會因為著色器 2c56dc1006942f74 上的微網格子群組剔除而造成 GPU 命令緩衝區卡死。
部分 AMD Windows Adrenalin 與 Linux 驅動程式在編譯計算 ASTC 轉 BC7 的轉碼器時出錯，導致 HUD 圖示與柯基利植被出現彩色 4x4 巨區塊破圖。
當輸入未包含補丁 v131072 的 v0 初始傾印檔、輸入 N64/3DS ROM 而非 Switch 2 Title ID 0400486024DEC000，或在 v2.0.11 之前使用了含非 ASCII 字元的 Windows 路徑時，資源建置器將會中止。
跳過一個或多個 64 位元 NVN2 著色器雜湊的繪製呼叫，讓玩家與協作者能精確找出是哪條 SPIR-V 管線引發了驅動程式當機或破圖。
將特定客體函式位址 (`0x7100xxxxxx`) 或整個二進位檔導向軟體 ARM64 解譯器，而非透過靜態 C 轉譯執行。
控制 stdout/stderr 從追蹤到錯誤的詳細記錄層級，並在提交 GitHub 問題回報時，為指定的客戶端函式記錄進出暫存器狀態（`X0`–`X7`）。
初始化空操作的 null 轉譯器並設定 RX_BOOT_DIRECT=1，讓沒有網格著色器硬體的開發者能夠 verify RomFS 掛載、音訊與存檔解析。
在 On 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）以改用軟體 ARM64 解譯器執行客體函式，而非靜態 C 編譯程式碼。
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 | 需要 Title ID 0400486024DEC000 v131072 (e0f3ccfa) | |
隔離損壞的自訂或 Driver 專用 Shaders (RX_SKIP_SHADERS) docs/DEVELOPMENT.md | 所有 Vulkan 1.3 平台 | RX_SKIP_SHADERS=<hash1>,<hash2> | |
透過 ARM64 Interpreter (RX_FORCE_INTERP) 繞過提升後 C 函式退化問題 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 | 無周邊 (Headless) 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 支援問題主要由三種特定硬體狀況引起。第一，Issue #1161 (VK_ERROR_DEVICE_LOST) 會在兩種情況下發生：在 NVIDIA 621 系列驅動程式下，當啟用獨立 Vulkan 呈現佇列且剛啟動完成著色器準備時崩潰（已在 v2.0.9 緩解，並在 v2.0.11 中透過維持關閉獨立呈現佇列且重新啟用 RX_VK_WB_DIFF=1 進行最佳化）；或在海拉魯平原與神殿的大型切換場景中，4 GB 至 6 GB 的 GPU 因 ASTC 貼圖集與階層陰影耗盡實體 VRAM 而崩潰。在 Insert / F1 選單中將畫質預設降至 Low（1.5 GB 貼圖集）或 Medium（2.5 GB 貼圖集）即可避免 VRAM 耗盡。
第二，Issue #817 會影響執行 24.3 以前版本 Mesa 的 Steam Deck LCD/OLED 與 Linux AMD RADV 系統：進入德庫樹內部或蜘蛛網房間時，音訊持續播放但 GPU 命令緩衝區凍結。此卡死現象源自 NVN2 網格著色器 2c56dc1006942f74 內部的子群組 meshlet 剔除邏輯；在 Steam 啟動選項中加入 RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% 即可針對該特定著色器跳過剔除，且完全不影響 FPS 效能。第三，AMD Radeon RX 6000 / RX 7000 GPU 上的 Issues #57 與 #1006 會因驅動程式錯誤編譯運算 ASTC 至 BC7 的轉碼器，導致植被與 HUD 圖示出現 4x4 彩虹色塊；匯出 RX_VK_ASTC_RGBA8=1 即可切換為無損軟體 RGBA8 解壓縮。
當 HookshotBuilder 在資源解包或 C 編譯階段失敗時，請 verify 確認三項先決條件：(1) 您的傾印檔必須符合 Switch 2 Title ID 0400486024DEC000 且包含更新檔 v131072，main NSO 的 ExeFS SHA-1 前綴為 e0f3ccfa（e0f3ccfa56256410941279ef0b2501356be2222c），而非 v0 初始傾印檔或 N64/3DS ROM；(2) 確保您執行的是 Hookshot v2.0.11，該版本修復了非 ASCII Windows 使用者路徑錯誤 (#1176)、殘留產生的 C 轉譯衝突 (#1197) 與缺少 Linux AppImage 標頭問題 (#990)；(3) 至少保留 30 GB 的可用磁碟空間，以容納 26.2 GB 的已解包 RomFS 及 1.4 GB 產生的 C 原始碼。
對於進階除錯，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 搭配則可用於無前端開機驗證。
在 On Steam Deck 或 Linux Steam 中，右鍵點擊 Hookshot -> 內容 -> 啟動選項，並輸入：RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%（亦可在 %command% 前串接多個變數）。在 On 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），讓 Hookshot 重新計算標頭偏移 0x0008 處所需的 CRC32C 校驗和。
已知 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 復原。