NotRexed/Hookshot는 The Legend of Zelda: Ocarina of Time의 Nintendo Switch 2 리메이크(타이틀 ID 0400486024DEC000 v131072)를 네이티브 x86_64 실행 파일로 변환하는 5계층 정적 재컴파일 파이프라인으로 설계되었습니다. nx2/ AArch64-C 리프터, 네이티브 Horizon OS SDK 22.2.8 런타임(host/), NVN2 API 231.40 커맨드 스트림 레코더, 그리고 Eden SM86-SPIR-V 셰이더 로어링(gpu/vk/)을 갖춘 Vulkan 1.3 메시 셰이더 리플레이 엔진을 결합함으로써, Hookshot는 가상 머신 없이도 게임 코드를 네이티브 속도로 구동합니다.
왼쪽 모듈 레일을 사용하여 검증된 10개의 리포지토리 하위 시스템을 아키텍처 계층별(AOT Lifter, 덤프 수집, Build 및 Link System, OS 및 서비스 런타임, 그래픽 API 프런트엔드, Vulkan 1.3 Renderer, Shader Recompiler, 시간적 업스케일링, Builder UI, 툴링)로 필터링하거나 아래의 전체 PartListTable을 확인하세요.
| 서브시스템 및 레이어 | 저장소 경로 | 언어 및 업스트림 계통 | 생성된 출력 아티팩트 | 엔지니어링 담당 역할 및 관계 |
|---|---|---|---|---|
nx2/ 정적 재컴파일 및 AArch64 LifterAOT Lifter | nx2/lift.py, nx2/insn.py, nx2/nso2.py, nx2/image.py | Python 3 (Capstone, Unicorn 2.1, LZ4, Zstandard)mkw-recomp (7336f0a) + Rexcomp a64-kit | work/sa/gen/*.c (57개 C 청크에 걸친 약 1.4 GB, 294,450개 함수) | Switch 2 NSO 모듈을 DT_RELR 재배치와 함께 0x80000000에 로드하고, 점프 테이블(1,475개 테이블)을 분석하며, 17,668,191개의 ARMv8.2+ 명령(UDOT 포함)을 C로 번역합니다. |
nx2/nup.py 및 nx2/unpack.py 덤프 추출기덤프 인제스천 | nx2/nup.py, nx2/unpack.py, nx2/dump.py, third_party/zbic | Python 3 + C (Atmosphere ZBIC 디코더)Hookshot / mkw-recomp | work/dump/exefs + work/dump/romfs (26.2 GB 추출됨) | 0400486024DEC000 v131072에 대한 7가지 Switch 2 덤프 신호를 검증하고, .nup 아카이브를 추출하며, 펌웨어 22.0.0+ ZBIC 인코딩된 main NSO 바이너리의 압축을 풉니다. |
nx2/build.py 및 nx2/make_game.py Native 컴파일러 DriverBuild 및 Link System | nx2/build.py, nx2/make_game.py, nx2/split_hot.py, nx2/pgo_pieces.py | Python 3 + Clang / LLD (llvm-mingw ucrt-x86_64)mkw-recomp + Hookshot split_hot PGO 파이프라인 | hookshot.exe (426 MB) / hookshot + image.bin | 핫 리프팅 코드를 8개의 병렬 번역 단위로 분할하고, LLVM 원시 포맷 11 PGO 분기 프로파일을 적용하며, 콜드 청크는 -O1, 핫 청크는 -O2로 컴파일하여 네이티브 실행 파일을 링크합니다. |
host/ Native Horizon OS 및 SDK 22.2.8 HLE 런타임OS 및 서비스 런타임 | host/hos_main.c, host/hos_setjmp.c, host/nn_hid.c, host/nn_applet.c, host/posix/ | C11 / Win32 및 POSIX Threads / Assemblymkw-recomp를 통해 변형된 TOTKPort hos/ | hookshot.exe / hookshot 내에 직접 링크됨 | 런타임에 485 nn:: SDK 경계를 대체하고, 512 GB 게스트 가상 주소 공간을 예약하며, nn::os 파이버를 네이티브 파이버에 매핑하고 파일 시스템, 오디오(libopus) 및 HID 컨트롤러를 처리합니다. |
host/nvn_native.c NVN2 (API 231.40) 커맨드 레코더그래픽 API 프론트엔드 | host/nvn_native.c, host/nvn2.c, gpu/render/rx_nvn.h | C11mkw-recomp NVN2 레이어 | gpu/vk/용 인메모리 NVN2 op 스트림 | 게스트 메모리 상에서 직접 Switch 2 NVN2 API 231.40 프로시저를 구현하고, 제출 시점에 메모리 풀을 캡처하며, 커맨드 버퍼 제출을 Vulkan 백엔드로 스트리밍합니다. |
gpu/vk/ Vulkan 1.3 Backend 및 Queue Replay EngineVulkan 1.3 Renderer | gpu/vk/vk_main.cpp, gpu/vk/vk_replay.cpp, gpu/vk/vk_memory.cpp, gpu/vk/vk_draw.cpp, gpu/vk/vk_coopmat.cpp | C++20 (Vulkan 1.3, VMA, Dear ImGui)mkw-recomp gpu/vk + Hookshot OoT 수정 사항 | hookshot_vk.dll (Windows) / hookshot_vk.so (Linux) | VK_EXT_mesh_shader와 함께 Vulkan 1.3에서 NVN2 커맨드 스트림을 재생하고, 큐 간 WaitEvent 동기화를 처리하며, TAAU/영상 업스케일링을 위한 HMMA f16 코오퍼레이티브 매트릭스를 실행하고, 라이트백 diff 기능을 통해 VRAM 풀 미러를 관리합니다. |
gpu/vk/eden/ Ampere SM86-to-Maxwell 낮추기 및 SPIR-V RecompilerShader Recompiler | gpu/vk/eden/, lower_to_maxwell.h, structured_control_flow.cpp | C++20 (Eden 셰이더 재컴파일러 + sirit)Eden (Eglantine 빌드 181) + Lichii 제어 흐름 수정 | hookshot_programs.bin, hookshot_programs.idx, hookshot_pipelines.bin | 10,154개의 Switch 2 Nin_Ounce_NVN2 Ampere SASS(SM86) 셰이더(249-GPR REGMAP_nx2 버텍스/메시 프로그램 및 태스크 셰이더 포함)를 Maxwell IR로 로어링하고 Vulkan SPIR-V를 생성합니다. |
gpu/vk/vk_dlss.cpp NVIDIA DLSS 및 내장 AMD FSR 3.1 업스케일러템포럴 업스케일링 및 프레임 생성 | gpu/vk/vk_dlss.cpp, gpu/vk/vk_menu.cpp | C++20 (NVIDIA NGX SDK 310.9.16, AMD FidelityFX SDK 1.1.4)Hookshot 네이티브 연동 | 내장 FSR 3.1 + 런타임 nvngx_dlss.dll 로더 | OoT의 동적 해상도 지터, 모션 벡터 및 뎁스 버퍼를 가로채 모든 GPU에서 기본 내장된 AMD FSR 3.1을 구동하거나, nvngx_dlss.dll이 감지될 때 선택적 NVIDIA DLSS 초해상도(트랜스포머 프리셋 K/M/L)를 구동합니다. |
builder/ Hookshot Builder GUI (Windows WPF 및 Linux AppImage)플레이어 Launcher 및 Builder UI | builder/HookshotBuilder.sln, scripts/linux/appimage.sh | C# (Windows 기반 .NET 8 WPF) / Linux 기반 셸 및 PythonHookshot 자체 제작(퍼스트 파티) 빌더 | HookshotBuilder.exe / Hookshot-x86_64.AppImage | 사용자가 제공한 .nup 또는 romfs+exefs 덤프를 검증하고, 저작권 자산을 포함하지 않은 채 10~45분 소요되는 최초 1회 로컬 C 빌드를 조율하며, 실행/Update 컨트롤을 제공합니다. |
scripts/ 및 tests/ 세이브 변환 유틸리티, 프로파일러 및 회귀 테스트 스위트도구 및 검증 | scripts/oot_saves.py, scripts/prof.py, scripts/framelog.py, tests/run_all.py | Python 3 및 PowerShellHookshot 자체 제작(퍼스트 파티) 툴링 | oot-save-backups/, CI 게임 파일 미포함 회귀 게이트 | Hookshot와 Switch 2 에뮬레이터(Lichii, Eglantine, Orchid, NX2navi) 간의 양방향 세이브 이전, 1 ms 스택 샘플링 분석, 게임 파일이 필요 없는 소스 회귀 테스트를 제공합니다. |
변환된 C 청크를 디버깅하거나 gpu/vk/에서 Vulkan 1.3 렌더러를 수정하는 기여자는 git clone에서 4단계 개발자 빌드 파이프라인을 직접 실행할 수 있습니다.
타이틀 ID 0400486024DEC000 v131072(ExeFS 메인 NSO SHA-1 접두사 e0f3ccfa)의 7가지 덤프 무결성 신호를 검증하고, 26.2 GB의 RomFS 아카이브를 풀며, 펌웨어 22.0.0+의 ZBIC 인코딩된 NSO 섹션을 third_party/zbic을 통해 압축 해제합니다.
python nx2/unpack.py --input <path-to-0400486024DEC000-v131072> --out work/dumpSwitch 2 NSO 이미지를 게스트 베이스 0x80000000에 매핑하고, DT_RELR 상대 재배치를 적용하며, 1,475개의 점프 테이블을 해석하고, 57개 청크에 걸쳐 약 1.4 GB의 C 코드를 내보냅니다(핫/콜드 PGO 분리를 거쳐 399개 컴파일 샤드로 분할).
python nx2/lift.py --dump work/dump --out work/sa/gen콜드 C 샤드는 -O1으로, 8개의 split_hot.py 변환 단위는 LLVM raw 포맷 11 분기 프로필 가중치를 적용하여 -O2로 컴파일한 뒤, LLD를 사용해 host/hos_main.c와 링크하여 hookshot.exe(426 MB) 및 image.bin을 생성합니다.
python nx2/make_game.py --jobs 8 --pgogpu/vk/(Eden SM86-to-Maxwell 셰이더 변환기, sirit SPIR-V 이미터, VMA 메모리 풀, FSR 3.1 / DLSS 훅 포함)를 hookshot_vk.dll / hookshot_vk.so로 컴파일하고 모든 소스 회귀 게이트를 검증합니다.
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build build && python tests/run_all.pyNotRexed/Hookshot 리프터는 mkw-recomp(커밋 7336f0a) 및 Rexcomp의 a64-kit을 기반으로 하며, 닌텐도 SDK 22.2.8 및 펌웨어 22.0.0+ 환경에서 컴파일된 Switch 2 Ocarina of Time 리메이크 바이너리에 맞춰 특화 확장되었습니다. 펌웨어 22.0.0+은 NSO 세그먼트를 ZBIC로 압축하므로, nx2/unpack.py는 이미지를 게스트 주소 0x80000000에 로드하기 전에 Atmosphere의 ZBIC 디코더를 통합합니다. 리프터는 UDOT과 같은 SIMD 내적 명령어를 포함한 17,668,191개의 ARMv8.2+ 명령어를 C 함수로 변환하며, nx2/split_hot.py은 LLVM 포맷 11 PGO 프로필을 사용해 가장 빈번하게 실행되는 경로를 8개의 -O2 변환 단위로 격리함으로써 전체 멀티코어 빌드가 10~45분 내에 완료되도록 합니다.
런타임에 host/hos_main.c는 연속된 512 GB 가상 주소 영역을 예약하여 최소한의 오버헤드로 게스트 64비트 포인터를 역참조할 수 있도록 합니다. Hookshot은 Horizon OS 커널을 에뮬레이트하는 대신 485 nn:: SDK 심볼 경계를 직접 가로챕니다. 즉, nn::os 파이버를 네이티브 Win32 파이버 또는 POSIX setjmp/ucontext 코루틴에 매핑하고, nn::fs 읽기를 압축 해제된 work/dump/romfs 디렉터리로 라우팅하며, 환경음 및 컷신 오디오 스트림을 libopus로 디코딩하고, SDL3 게임패드/자이로스코프 이벤트를 nn::hid 컨트롤러 상태로 변환합니다.
Switch 2 타이틀은 독점 Nin_Ounce_NVN2 셰이더 헤더 및 249-GPR REGMAP_nx2 레지스터 파일을 갖추고 NVIDIA Ampere SM86 하드웨어를 타깃으로 하는 NVN2(API 버전 231.40)을 통해 렌더링됩니다. Hookshot의 host/nvn_native.c은 게스트 메모리 위에서 인플레이스로 NVN2 커맨드 기록을 구현하고 제출 스트림을 hookshot_vk.dll / hookshot_vk.so로 전달합니다. gpu/vk/eden/ 내부에서 Hookshot는 Eden 셰이더 재컴파일러(Lichii 구조적 제어 흐름 수정이 포함된 Eglantine 빌드 181)를 개조하여 태스크 및 메시 셰이더 단계를 포함한 10,154개의 Ampere SM86 SASS 바이너리를 Maxwell IR로 낮추고 표준 Vulkan 1.3 SPIR-V 모듈을 생성합니다(hookshot_programs.bin에 캐시된 8,243개의 활성 런타임 파이프라인 프로그램).
또한 리메이크 엔진은 시간적 안티에일리어싱 업스케일링(TAAU) 및 프리렌더링 컷신 디코딩을 위해 컴퓨트 셰이더 내에서 Ampere HMMA.1688.F16 텐서 명령어에 의존합니다. Hookshot의 gpu/vk/vk_coopmat.cpp는 호스트 GPU에서 지원할 경우 이러한 연산을 VK_KHR_cooperative_matrix로 변환하고, gpu/vk/vk_dlss.cpp에서 엔진의 지터 및 모션 벡터를 가로채 기본 내장된 AMD FSR 3.1(FidelityFX SDK 1.1.4) 또는 선택적 NVIDIA DLSS 초해상도(NGX SDK 310.9.16)를 구동합니다.
Hookshot은 AArch64-to-C 정적 리프팅을 위해 mkw-recomp(커밋 7336f0a) 및 Rexcomp의 a64-kit을 기반으로 구축되었으며, Horizon OS HLE 런타임 심을 위해 TOTKPort의 hos/ 레이어를, Switch 2 Ampere SM86 셰이더를 Vulkan 1.3 SPIR-V로 낮추기 위해 Eden(Eglantine 빌드 181) + Lichii 셰이더 재컴파일러를 사용합니다.
네. python tests/run_all.py를 실행하면 게임 없는 CI 리그레션 스위트가 실행되어, 저작권 보호 대상인 RomFS 또는 ExeFS 파일 없이도 리프터 명령어 시맨틱, 호스트 헤더 패키징(#990), Vulkan 백엔드 초기화를 검증합니다.
57개 청크에 걸쳐 생성된 C 약 1.4 GB, 총 294,450개의 리프팅된 함수 전체를 -O2로 컴파일하면 수 시간이 소요되고 시스템 RAM이 고갈됩니다. Hookshot의 nx2/split_hot.py는 가장 자주 실행되는 함수들을 LLVM PGO 가중치가 적용된 -O2 컴파일 대상 8개 핫 변환 단위로 격리하고, 나머지 콜드 청크는 -O1으로 컴파일합니다.
nx2/ 리프터 지표, 485 nn:: HLE 경계, NVN2 API 231.40 및 Eden SM86 셰이더 낮추기에 대한 주요 출처입니다.
split_hot.py PGO 빌드 파이프라인, hookshot_vk 컴파일 및 tests/run_all.py의 1차 출처.
디렉터리 레이아웃(nx2/, host/, gpu/vk/, builder/, scripts/, tests/) 및 업스트림 기여 정보의 1차 출처.