O NotRexed/Hookshot é estruturado como um pipeline de recompilação estática em cinco camadas que transforma o remake de The Legend of Zelda: Ocarina of Time para Nintendo Switch 2 (Title ID 0400486024DEC000 v131072) em um executável nativo de x86_64. Ao integrar o lifter nx2/ de AArch64 para C, um runtime nativo Horizon OS SDK 22.2.8 (host/), um gravador de fluxo de comandos NVN2 API 231.40 e um motor de replay de mesh shaders em Vulkan 1.3 com rebaixamento de shaders de Eden SM86 para SPIR-V (gpu/vk/), o Hookshot executa o código do jogo de forma nativa, sem qualquer máquina virtual.
Use a barra de módulos à esquerda para filtrar os 10 subsistemas verificados do repositório por camada de arquitetura (AOT Lifter, ingestão de dumps, Build e Link System, runtime de SO e serviços, front-end de gráficos API, Renderer de Vulkan 1.3, Shader Recompiler, upscaling temporal, Builder UI e ferramentas), ou inspecione a PartListTable completa abaixo.
| Subsistema e camada | Caminhos do Repositório | Linguagem e linhagem upstream | Artefato gerado | Atribuição técnica e relações |
|---|---|---|---|---|
nx2/ Recompilação estática e 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 em 57 blocos de C, 294.450 funções) | Carrega módulos de Switch 2 NSO em 0x80000000 com realocações DT_RELR, resolve tabelas de desvio (1.475 tabelas) e traduz 17.668.191 instruções de ARMv8.2+ (incluindo UDOT) para C. |
Extrator de dumps do nx2/nup.py e nx2/unpack.pyIngestão de dumps | 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 os sete sinais de integridade do dump do Switch 2 para 0400486024DEC000 v131072, extrai arquivos .nup e descompacta os binários principais NSO codificados em ZBIC do firmware 22.0.0+. |
nx2/build.py e Driver do compilador de nx2/make_game.py NativeBuild e 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 + pipeline de PGO split_hot do Hookshot | hookshot.exe (426 MB) / hookshot + image.bin | Divide o código ativo convertido entre 8 unidades de compilação paralelas, aplica perfis de desvio PGO brutos no formato 11 da LLVM, compila trechos secundários com -O1 e trechos críticos com -O2, gerando o executável nativo. |
host/ Native Horizon OS e Runtime HLE SDK 22.2.8Execução de SO e serviços | host/hos_main.c, host/hos_setjmp.c, host/nn_hid.c, host/nn_applet.c, host/posix/ | C11 / Win32 e POSIX Threads / AssemblyTOTKPort hos/ adaptado via mkw-recomp | Vinculado diretamente ao hookshot.exe / hookshot | Substitui os limites da 485 nn:: SDK em tempo de execução, reserva um espaço de endereçamento virtual guest de 512 GB, mapeia fibras nn::os em fibras nativas e gerencia sistema de arquivos, áudio (libopus) e controles HID. |
Gravador de comandos host/nvn_native.c NVN2 (API 231.40)Front-end gráfico do API | host/nvn_native.c, host/nvn2.c, gpu/render/rx_nvn.h | C11Camada mkw-recomp NVN2 | Fluxo de operações de NVN2 em memória para gpu/vk/ | Implementa rotinas do Switch 2 NVN2 API 231.40 diretamente sobre a memória convidada, faz a captura de pools de memória no envio e transmite buffers de comando para o backend Vulkan. |
Backend gpu/vk/ Vulkan 1.3 e 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 + correções de OoT Hookshot | hookshot_vk.dll (Windows) / hookshot_vk.so (Linux) | Reproduz fluxos de comando do NVN2 em Vulkan 1.3 com VK_EXT_mesh_shader, sincroniza WaitEvent entre filas, processa matrizes cooperativas HMMA f16 para upscaling de TAAU/cinemáticas e gerencia réplicas de pools VRAM com write-back diffing. |
Lowering de SM86 para Maxwell do gpu/vk/eden/ Ampere e SPIR-V RecompilerShader Recompiler | gpu/vk/eden/, lower_to_maxwell.h, structured_control_flow.cpp | C++20 (recompilador de shader Eden + sirit)Eden (Eglantine build 181) + correções de fluxo de controle Lichii | hookshot_programs.bin, hookshot_programs.idx, hookshot_pipelines.bin | Converte 10.154 shaders SASS (SM86) Nin_Ounce_NVN2 Ampere do Switch 2 (incluindo programas de vértice/mesh REGMAP_nx2 de 249 GPRs e task shaders) para Maxwell IR e gera código Vulkan SPIR-V. |
Upscalers integrados para gpu/vk/vk_dlss.cpp NVIDIA DLSS e AMD FSR 3.1Upscaling temporal e geração de quadros | gpu/vk/vk_dlss.cpp, gpu/vk/vk_menu.cpp | C++20 (NVIDIA NGX SDK 310.9.16, AMD FidelityFX SDK 1.1.4)Integração nativa no Hookshot | FSR 3.1 integrado + carregador dinâmico de nvngx_dlss.dll | Intercepta o jitter de resolução dinâmica, vetores de movimento e buffers de profundidade do OoT para acionar o AMD FSR 3.1 integrado em todas as GPUs ou o NVIDIA DLSS Super Resolution opcional (predefinições Transformer K/M/L) quando nvngx_dlss.dll estiver presente. |
Builder GUI do builder/ Hookshot (WPF Windows e AppImage Linux)Launcher do jogador e Builder UI | builder/HookshotBuilder.sln, scripts/linux/appimage.sh | C# (.NET 8 WPF no Windows) / Shell e Python no LinuxConstrutor proprietário do Hookshot | HookshotBuilder.exe / Hookshot-x86_64.AppImage | Verifica os dumps .nup ou romfs+exefs fornecidos pelo usuário, orquestra a compilação local de C em 10 a 45 minutos (executada uma única vez) sem distribuir arquivos protegidos por direitos autorais e oferece controles de Jogar/Update. |
Utilitário de transferência de saves, analisadores e testes de regressão do scripts/ e tests/Ferramentas e validação | scripts/oot_saves.py, scripts/prof.py, scripts/framelog.py, tests/run_all.py | Python 3 e PowerShellFerramentas originais do Hookshot | oot-save-backups/, validação de regressão em CI sem arquivos do jogo | Oferece migração bidirecional de saves entre o Hookshot e emuladores do Switch 2 (Lichii, Eglantine, Orchid, NX2navi), análise de amostragem de pilha de 1 ms e testes de regressão de código-fonte independentes dos dados do jogo. |
Colaboradores depurando blocos de código C convertidos ou modificando o renderizador Vulkan 1.3 no gpu/vk/ podem executar o pipeline de compilação de quatro etapas para desenvolvedores diretamente de um clone git.
Valida os sete sinais de integridade de dump para o Title ID 0400486024DEC000 v131072 (SHA-1 do NSO principal ExeFS com prefixo e0f3ccfa), descompacta 26.2 GB de arquivos RomFS e descomprime seções NSO codificadas em ZBIC do firmware 22.0.0+ via third_party/zbic.
python nx2/unpack.py --input <path-to-0400486024DEC000-v131072> --out work/dumpMapeia a imagem NSO do Switch 2 na base guest 0x80000000, aplica realocações relativas DT_RELR, resolve 1.475 jump tables e gera ~1.4 GB de código C distribuídos em 57 blocos (divididos em 399 fragmentos de compilação com separação PGO hot/cold).
python nx2/lift.py --dump work/dump --out work/sa/genCompila fragmentos C cold em -O1 e as 8 unidades de tradução do split_hot.py em -O2 com pesos de perfil de desvio formato raw 11 do LLVM; em seguida, realiza o link com host/hos_main.c usando LLD para gerar hookshot.exe (426 MB) e image.bin.
python nx2/make_game.py --jobs 8 --pgoCompila gpu/vk/ (incluindo o lowerer de shaders de SM86 para Maxwell do Eden, emissor sirit SPIR-V, pools de memória VMA e ganchos FSR 3.1 / DLSS) em hookshot_vk.dll / hookshot_vk.so e valida todos os testes de regressão do código-fonte.
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build build && python tests/run_all.pyO lifter NotRexed/Hookshot baseia-se no mkw-recomp (commit 7336f0a) e no a64-kit do Rexcomp, estendido especificamente para o binário do remake de Ocarina of Time para Switch 2 compilado contra Nintendo SDK 22.2.8 e firmware 22.0.0+. Como o firmware 22.0.0+ compacta segmentos NSO com ZBIC, o nx2/unpack.py integra o decodificador ZBIC do Atmosphere antes de carregar a imagem no endereço guest 0x80000000. O lifter traduz 17.668.191 instruções ARMv8.2+ — incluindo instruções de produto escalar SIMD como UDOT — em funções C, enquanto o nx2/split_hot.py usa perfis PGO formato 11 do LLVM para isolar os caminhos de execução mais exigidos em 8 unidades de tradução compiladas em -O2, garantindo compilações completas em processadores multi-core de 10 a 45 minutos.
Em tempo de execução, o host/hos_main.c reserva uma região de endereçamento virtual contígua de 512 GB para que ponteiros guest de 64 bits sejam desreferenciados com sobrecarga mínima. Em vez de emular o kernel do Horizon OS, o Hookshot intercepta os limites de símbolos SDK da 485 nn:: diretamente — mapeando fibras nn::os em fibras Win32 nativas ou corrotinas POSIX setjmp/ucontext, direcionando leituras de nn::fs para a pasta work/dump/romfs descompactada, decodificando fluxos de áudio ambiente e cutscenes via libopus e convertendo eventos de gamepad/giroscópio SDL3 em estados de controle nn::hid.
Títulos de Switch 2 renderizam por meio da NVN2 (versão API 231.40) direcionada ao hardware NVIDIA Ampere SM86 com cabeçalhos de shader Nin_Ounce_NVN2 proprietários e bancos de registradores REGMAP_nx2 de 249 GPRs. O host/nvn_native.c do Hookshot implementa a gravação de comandos NVN2 diretamente na memória guest e transmite envios para hookshot_vk.dll / hookshot_vk.so. Dentro de gpu/vk/eden/, o Hookshot adapta o recompilador de shader Eden (Eglantine build 181 com correções de fluxo de controle estruturado do Lichii) para converter 10.154 binários SASS de Ampere SM86 — incluindo estágios de task e mesh shader — em IR Maxwell e gerar módulos SPIR-V Vulkan 1.3 padrão (8.243 programas de pipeline ativos armazenados em cache no hookshot_programs.bin).
Além disso, a engine do remake usa instruções tensoriais HMMA.1688.F16 da Ampere em compute shaders para upscaling com anti-aliasing temporal (TAAU) e decodificação de cutscenes pré-renderizadas. O gpu/vk/vk_coopmat.cpp do Hookshot traduz essas operações para VK_KHR_cooperative_matrix quando suportado pela GPU do host e intercepta o jitter e os vetores de movimento da engine em gpu/vk/vk_dlss.cpp para acionar o AMD FSR 3.1 integrado (FidelityFX SDK 1.1.4) ou o NVIDIA DLSS Super Resolution opcional (NGX SDK 310.9.16).
O Hookshot se apoia no mkw-recomp (commit 7336f0a) e no a64-kit do Rexcomp para lifting estático de AArch64 para C, na camada hos/ do TOTKPort para compatibilização em tempo de execução da HLE do Horizon OS e no recompilador de shaders Eden (Eglantine build 181) + Lichii para converter shaders Ampere SM86 de Switch 2 em módulos SPIR-V Vulkan 1.3.
Sim. Executar python tests/run_all.py roda a suíte de regressão de CI sem o jogo, verificando a semântica de instruções do lifter, o empacotamento de cabeçalhos do host (#990) e a inicialização do backend Vulkan sem exigir arquivos protegidos por direitos autorais de RomFS ou ExeFS.
Compilar todas as 294.450 funções convertidas (~1.4 GB de C gerado distribuído em 57 blocos) em -O2 levaria horas e esgotaria a RAM do sistema. O nx2/split_hot.py do Hookshot isola as funções executadas com maior frequência em 8 unidades de tradução hot compiladas em -O2 com pesos PGO do LLVM, enquanto compila os blocos cold restantes em -O1.
Fonte primária de métricas do lifter de nx2/, limites de HLE de 485 nn::, NVN2 API 231.40 e lowering de shaders Eden para SM86.
Fonte primária para o pipeline de build PGO split_hot.py, compilação de hookshot_vk e tests/run_all.py.
Fonte primária para estrutura de diretórios (nx2/, host/, gpu/vk/, builder/, scripts/, tests/) e atribuições upstream.