문서화된 모든 Hookshot v2.0.11 런타임 크래시, GPU 드라이버 멈춤 현상, 텍스처 그래픽 깨짐 및 빌더 추출 오류를 진단하고 해결하세요. 이슈 태그(#1161, #817, #57, #1176)나 증상으로 아래 10개 검증된 결함 시트를 검색하거나 필터링하고, 세 가지 진단 패널(증상, 환경 플래그, 해결 방법)을 확인한 뒤 알맞은 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 덤프, Switch 2 타이틀 ID 0400486024DEC000가 아닌 N64/3DS ROM을 입력하거나 v2.0.11 이전 버전에서 비-ASCII 문자가 포함된 Windows 경로를 사용할 경우 에셋 빌더가 중단됩니다.
하나 이상의 64비트 NVN2 셰이더 해시에 대한 드로우 콜을 건너뛰어, 플레이어와 기여자가 드라이버 크래시나 그래픽 결함을 유발하는 SPIR-V 파이프라인을 정확히 찾아낼 수 있도록 합니다.
개별 게스트 함수 주소(`0x7100xxxxxx`) 또는 바이너리 전체를 정적 C 변환 대신 소프트웨어 ARM64 인터프리터를 통해 라우팅합니다.
출력 로그 상세도를 trace부터 error까지 제어하고, GitHub 이슈를 제출할 때 대상 게스트 함수의 진입/종료 레지스터 상태(`X0`–`X7`)를 기록합니다.
메시 셰이더를 지원하지 않는 기기의 개발자가 RomFS 마운트, 오디오, 세이브 파싱을 verify할 수 있도록 no-op 널 렌더러와 RX_BOOT_DIRECT=1을 초기화합니다.
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)를 설정하여 정적 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 커뮤니티 지원 문의의 대부분은 하드웨어별 특이 이슈 세 가지에 기인합니다. 첫째, 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 메뉴의 Graphics Preset을 Low(1.5 GB 풀) 또는 Medium(2.5 GB 풀)로 낮추면 VRAM 고갈을 방지할 수 있습니다.
둘째, Issue #817은 24.3 이전 버전 Mesa를 실행하는 Steam Deck LCD/OLED 및 Linux AMD RADV 시스템에 영향을 줍니다. 데쿠나무 내부나 거미줄 방에 진입하면 오디오는 계속 재생되지만 GPU 커맨드 버퍼가 멈춥니다. 이 멈춤 현상은 NVN2 메시 셰이더 2c56dc1006942f74 내부의 서브그룹 메시렛 컬링으로 인해 유발됩니다. 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을 export하면 무손실 소프트웨어 RGBA8 디코딩으로 전환됩니다.
에셋 추출이나 C 컴파일 도중 HookshotBuilder가 실패할 경우 다음 세 가지 전제 조건을 verify하세요. (1) 덤프가 베이스 v0 덤프나 N64/3DS ROM이 아니라 패치 v131072이 적용된 Switch 2 타이틀 ID 0400486024DEC000 및 ExeFS main NSO SHA-1 접두사 e0f3ccfa(e0f3ccfa56256410941279ef0b2501356be2222c)와 일치하는지 확인; (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과 함께 사용할 수 있습니다.
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 복원을 검증합니다.