NotRexed/Hookshot está diseñado como un pipeline de recompilación estática en cinco capas que transforma el remake para Nintendo Switch 2 de The Legend of Zelda: Ocarina of Time (Title ID 0400486024DEC000 v131072) en un ejecutable nativo para x86_64. Al combinar el lifter de AArch64 a C de nx2/, un runtime nativo Horizon OS SDK 22.2.8 (host/), un grabador de flujo de comandos NVN2 API 231.40 y un motor de reproducción de mesh shaders en Vulkan 1.3 con reducción de shaders de SM86 a SPIR-V mediante Eden (gpu/vk/), Hookshot ejecuta el código del juego de forma nativa sin ninguna máquina virtual.
Usa el panel de módulos izquierdo para filtrar los 10 subsistemas verificados del repositorio según su capa arquitectónica (AOT Lifter, ingesta de volcados, Build y Link System, runtime del SO y servicios, front-end gráfico API, Vulkan 1.3 Renderer, Shader Recompiler, escalado temporal, Builder UI y herramientas), o inspecciona la PartListTable completa a continuación.
| Subsistema y capa | Rutas del Repositorio | Lenguaje y origen upstream | Artefacto de salida generado | Responsabilidad técnica y dependencias |
|---|---|---|---|---|
nx2/ Recompilación estática y 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 (~1.4 GB repartidos en 57 bloques de C, 294 450 funciones) | Carga módulos NSO de Switch 2 en 0x80000000 con reubicaciones DT_RELR, resuelve tablas de salto (1475 tablas) y traduce 17 668 191 instrucciones ARMv8.2+ (incluyendo UDOT) a C. |
Extractor de volcado nx2/nup.py y nx2/unpack.pyIngesta de volcado | nx2/nup.py, nx2/unpack.py, nx2/dump.py, third_party/zbic | Python 3 + C (decodificador Atmosphere ZBIC)Hookshot / mkw-recomp | work/dump/exefs + work/dump/romfs (26.2 GB extraídos) | Valida las siete señales de integridad del volcado de Switch 2 para 0400486024DEC000 v131072, extrae archivos .nup y descomprime los binarios principales NSO codificados en ZBIC para firmware 22.0.0+. |
nx2/build.py y compilador nx2/make_game.py Native DriverBuild y Link System | nx2/build.py, nx2/make_game.py, nx2/split_hot.py, nx2/pgo_pieces.py | Python 3 + Clang / LLD (llvm-mingw con ucrt-x86_64)Pipeline split_hot PGO de mkw-recomp + Hookshot | hookshot.exe (426 MB) / hookshot + image.bin | Divide el código traducido de uso intensivo en 8 unidades de traducción paralelas, aplica perfiles de bifurcación PGO en formato LLVM raw 11, compila bloques secundarios en -O1 y bloques intensivos en -O2, y vincula el binario ejecutable nativo. |
Native Horizon OS y entorno de ejecución HLE de SDK 22.2.8 en host/SO y servicios en tiempo de ejecución | host/hos_main.c, host/hos_setjmp.c, host/nn_hid.c, host/nn_applet.c, host/posix/ | C11 / Win32 y POSIX Threads / AssemblyTOTKPort hos/ adaptado mediante mkw-recomp | Vinculado directamente en hookshot.exe / hookshot | Sustituye los límites de 485 nn:: SDK en tiempo de ejecución, reserva un espacio de direcciones virtuales invitado de 512 GB, mapea fibras de nn::os en fibras nativas y gestiona el sistema de archivos, audio (libopus) y mandos HID. |
Grabador de comandos host/nvn_native.c NVN2 (API 231.40)Interfaz de gráficos API | host/nvn_native.c, host/nvn2.c, gpu/render/rx_nvn.h | C11Capa mkw-recomp NVN2 | Flujo de operaciones NVN2 en memoria para gpu/vk/ | Implementa los procedimientos NVN2 API 231.40 de Switch 2 directamente sobre la memoria de invitado, captura los grupos de memoria en el momento del envío y canaliza los buffers de comandos al backend de Vulkan. |
Backend gpu/vk/ Vulkan 1.3 y 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 + correcciones de Hookshot OoT | hookshot_vk.dll (Windows) / hookshot_vk.so (Linux) | Reproduce los flujos de comandos de NVN2 en Vulkan 1.3 con VK_EXT_mesh_shader, respeta la sincronización WaitEvent entre colas, ejecuta matrices cooperativas HMMA f16 para escalado de TAAU/cinemáticas y gestiona duplicados de grupos en VRAM con diffing de write-back. |
Reducción de gpu/vk/eden/ Ampere SM86 a Maxwell y SPIR-V RecompilerShader Recompiler | gpu/vk/eden/, lower_to_maxwell.h, structured_control_flow.cpp | C++20 (recompilador de shaders Eden + sirit)Eden (Eglantine compilación 181) + correcciones de flujo de control de Lichii | hookshot_programs.bin, hookshot_programs.idx, hookshot_pipelines.bin | Convierte 10,154 shaders SASS de Ampere (SM86) de Nin_Ounce_NVN2 para Switch 2 (incluidos programas de vértices/mesh de 249 GPR REGMAP_nx2 y task shaders) a IR de Maxwell y genera Vulkan SPIR-V. |
Escaladores integrados AMD FSR 3.1 y gpu/vk/vk_dlss.cpp NVIDIA DLSSEscalado temporal y generación de fotogramas | gpu/vk/vk_dlss.cpp, gpu/vk/vk_menu.cpp | C++20 (NVIDIA NGX SDK 310.9.16, AMD FidelityFX SDK 1.1.4)Integración nativa en Hookshot | FSR 3.1 integrado + cargador dinámico de nvngx_dlss.dll | Intercepta el jitter de resolución dinámica, vectores de movimiento y búferes de profundidad de OoT para alimentar AMD FSR 3.1 integrado en cualquier GPU o NVIDIA DLSS Super Resolution opcional (perfiles K/M/L de Transformer) cuando nvngx_dlss.dll está presente. |
builder/ Hookshot Builder GUI (Windows WPF y Linux AppImage)Launcher de jugador y Builder UI | builder/HookshotBuilder.sln, scripts/linux/appimage.sh | C# (.NET 8 WPF en Windows) / Shell y Python en LinuxConstructor oficial de Hookshot | HookshotBuilder.exe / Hookshot-x86_64.AppImage | Verifica volcados .nup o romfs+exefs del usuario, orquesta la compilación local única de C de 10 a 45 minutos sin incluir recursos protegidos por derechos de autor y ofrece controles de Jugar/Update. |
Herramienta de transferencia de partidas, perfiladores y suite de regresión para scripts/ y tests/Herramientas y verificación | scripts/oot_saves.py, scripts/prof.py, scripts/framelog.py, tests/run_all.py | Python 3 y PowerShellHerramientas oficiales de Hookshot | oot-save-backups/, barrera de pruebas CI sin archivos de juego | Permite la migración bidireccional de partidas entre Hookshot y emuladores de Switch 2 (Lichii, Eglantine, Orchid, NX2navi), muestreo de pila con precisión de 1 ms y pruebas de regresión del código fuente sin recursos del juego. |
Los colaboradores que depuren fragmentos extraídos de C o modifiquen el renderizador Vulkan 1.3 en gpu/vk/ pueden ejecutar el flujo de compilación de desarrollo en cuatro fases directamente desde un clon de git.
Valida las siete señales de integridad del volcado para el Title ID 0400486024DEC000 v131072 (prefijo e0f3ccfa de SHA-1 en main de ExeFS NSO), desempaqueta 26.2 GB de archivos RomFS y descomprime secciones NSO codificadas en ZBIC de firmware 22.0.0+ mediante third_party/zbic.
python nx2/unpack.py --input <path-to-0400486024DEC000-v131072> --out work/dumpMapea la imagen NSO de Switch 2 en la base invitada 0x80000000, aplica reubicaciones relativas DT_RELR, resuelve 1475 tablas de salto y emite ~1.4 GB de código C distribuidos en 57 bloques (divididos en 399 fragmentos de compilación con separación PGO hot/cold).
python nx2/lift.py --dump work/dump --out work/sa/genCompila fragmentos cold de C con -O1 y las 8 unidades de traducción split_hot.py con -O2 usando ponderaciones de perfiles de bifurcación formato 11 en bruto de LLVM, para luego enlazarlos con host/hos_main.c mediante LLD produciendo hookshot.exe (426 MB) y image.bin.
python nx2/make_game.py --jobs 8 --pgoCompila gpu/vk/ (incluyendo el reductor de shaders de Eden SM86 a Maxwell, el emisor SPIR-V de sirit, los depósitos de memoria VMA y los ganchos de FSR 3.1 / DLSS) en hookshot_vk.dll / hookshot_vk.so y verifica todas las barreras de regresión del código fuente.
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build build && python tests/run_all.pyEl lifter de NotRexed/Hookshot deriva de mkw-recomp (commit 7336f0a) y del a64-kit de Rexcomp, ampliado específicamente para el binario del remake de Ocarina of Time en Switch 2 compilado contra el SDK 22.2.8 de Nintendo y firmware 22.0.0+. Dado que el firmware 22.0.0+ comprime segmentos NSO con ZBIC, nx2/unpack.py integra el decodificador ZBIC de Atmosphere antes de cargar la imagen en la dirección de invitado 0x80000000. El lifter traduce 17 668 191 instrucciones ARMv8.2+ —incluidas operaciones SIMD de producto escalar como UDOT— a funciones en C, mientras que nx2/split_hot.py emplea perfiles PGO de LLVM en formato 11 para aislar las rutas de ejecución más críticas en 8 unidades de traducción con -O2, logrando que las compilaciones multinúcleo completas tarden entre 10 y 45 minutos.
En ejecución, host/hos_main.c reserva una región contigua de direcciones virtuales de 512 GB para desreferenciar punteros de 64 bits invitados con una sobrecarga mínima. En lugar de emular el kernel de Horizon OS, Hookshot intercepta directamente los límites de símbolos de 485 nn:: SDK: mapea fibras de nn::os en fibras nativas de Win32 o corrutinas setjmp/ucontext de POSIX, redirige lecturas de nn::fs al directorio descomprimido work/dump/romfs, decodifica flujos de audio ambiental y cinemáticas mediante libopus y traduce eventos de mando/giroscopio de SDL3 en estados de mando de nn::hid.
Los títulos de Switch 2 renderizan mediante NVN2 (versión 231.40 de API) orientada a hardware NVIDIA Ampere SM86 con encabezados de shaders propietarios Nin_Ounce_NVN2 y archivos de registros REGMAP_nx2 de 249 GPR. El host/nvn_native.c de Hookshot implementa la grabación de comandos NVN2 directamente sobre la memoria invitada y envía los envíos a hookshot_vk.dll / hookshot_vk.so. Dentro de gpu/vk/eden/, Hookshot adapta el recompilador de shaders Eden (Eglantine compilación 181 con correcciones de flujo de control estructurado de Lichii) para reducir 10 154 binarios SASS de Ampere SM86 —incluidas fases de shaders de tareas y mallas— a IR de Maxwell y emitir módulos estándar SPIR-V de Vulkan 1.3 (8243 programas de pipeline en ejecución activos almacenados en caché en hookshot_programs.bin).
Además, el motor del remake se apoya en instrucciones tensoriales HMMA.1688.F16 de Ampere en compute shaders para el escalado con antialiasing temporal (TAAU) y la decodificación de cinemáticas pre-renderizadas. El gpu/vk/vk_coopmat.cpp de Hookshot traduce estas operaciones a VK_KHR_cooperative_matrix cuando la GPU host lo admite, e intercepta en gpu/vk/vk_dlss.cpp el jitter y los vectores de movimiento del motor para alimentar AMD FSR 3.1 integrado (FidelityFX SDK 1.1.4) o NVIDIA DLSS Super Resolution opcional (NGX SDK 310.9.16).
Hookshot se basa en mkw-recomp (commit 7336f0a) y el a64-kit de Rexcomp para la elevación estática de AArch64 a C, la capa hos/ de TOTKPort para los calces de ejecución HLE de Horizon OS y el recompilador de shaders de Eden (Eglantine compilación 181) + Lichii para reducir shaders Ampere SM86 de Switch 2 a Vulkan 1.3 SPIR-V.
Sí. Al ejecutar python tests/run_all.py se lanza la suite de pruebas de regresión de CI sin juego, la cual verifica la semántica de instrucciones del extractor, el empaquetado de encabezados del host (#990) y la inicialización del backend Vulkan sin requerir archivos protegidos por derechos de autor de RomFS o ExeFS.
Compilar las 294 450 funciones elevadas (~1.4 GB de C generado en 57 bloques) a -O2 requeriría horas y agotaría la RAM del sistema. El nx2/split_hot.py de Hookshot aísla las funciones más ejecutadas en 8 unidades de traducción frecuentes compiladas a -O2 con ponderaciones de PGO de LLVM, mientras compila los bloques fríos restantes a -O1.
Fuente principal de métricas del lifter nx2/, límites de 485 nn:: HLE, NVN2 API 231.40 y reducción de shaders Eden SM86.
Fuente principal para la canalización de compilación split_hot.py PGO, la compilación de hookshot_vk y tests/run_all.py.
Fuente principal para la estructura de carpetas (nx2/, host/, gpu/vk/, builder/, scripts/, tests/) y las atribuciones a proyectos base.