10 FICHAS DE FALHAS VERIFICADAS (#1161 · #817 · #57)SUBSTITUIÇÕES DE DIAGNÓSTICO: RX_VK_MESH_NOCULL · RX_VK_ASTC_RGBA8 · RX_FORCE_INTERP
Correção de Erros do Hookshot e Variáveis de Diagnóstico
Diagnostique e solucione cada travamento de tempo de execução do Hookshot v2.0.11 documentado, travamento de driver do GPU, defeito de textura e erro de extração do construtor. Pesquise ou filtre as 10 fichas de falhas verificadas abaixo por tag de problema (#1161, #817, #57, #1176) ou sintoma, inspecione os três painéis de diagnóstico delimitados (Sintoma, Parâmetro de ambiente, Resolução) e aplique substituições direcionadas de variáveis de ambiente RX_*.
FIG 6.0 — Triagem de falhas do Hookshot e fluxo de decisão de variáveis de ambiente RX_* (v2.0.11)
ATLAS DIVIDIDO DE FALHAS // 10 FICHAS DE DIAGNÓSTICO VERIFICADAS
Índice interativo de falhas e bancada de diagnóstico em três painéis
Filtre por tag principal de problema (#1161, #817, #57, #1176, diagnósticos RX_*) ou pesquise por palavra-chave de sintoma. Cada ficha apresenta três painéis estruturados — Sintoma observado, Variável de ambiente / Parâmetro de inicialização e Resolução verificada no v2.0.11 —, além de correlações com falhas relacionadas.
Issue nº 1161Esgotamento de Timeout ou VRAM do VK_ERROR_DEVICE_LOST GPU (#1161)
GPUs com 4 GB a 6 GB de VRAM ou drivers com overclock no Vulkan
Ocorre durante transições pesadas em Hyrule Field ou Templos, quando o pool de texturas do ASTC mais as cascatas de sombra excedem a VRAM física ou acionam o tempo limite de TDR do driver.
PAINEL 01 // SINTOMA OBSERVADO
Janela fatal de VK_ERROR_DEVICE_LOST e fechamento inesperado para a área de trabalho ao carregar área
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
graphics_preset=Low/Medium ou RX_SKIP_SHADERS=<hash>
PAINEL 03 // RESOLUÇÃO VERIFICADA
Reduza a predefinição gráfica no menu do Insert/F1 para Low (4 GB) ou Medium (6 GB), diminua a escala de renderização para 1.0x e atualize para a correção do pool de descritores no v2.0.11.
Issue nº 817Congelamento Dentro da Deku Tree no Steam Deck / Linux RADV (#817)
Steam Deck LCD/OLED e RADV Linux AMD (Mesa < 24.3)
Entrar dentro da Deku Tree ou na Web Room com Steam Deck (Mesa RADV) pode travar o buffer de comandos do GPU devido ao descarte de meshlets por subgrupos no shader 2c56dc1006942f74.
PAINEL 01 // SINTOMA OBSERVADO
A tela congela e o áudio entra em loop ao entrar dentro da Deku Tree
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
RX_VK_MESH_NOCULL=2c56dc1006942f74
PAINEL 03 // RESOLUÇÃO VERIFICADA
Defina as opções de inicialização do Steam como RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (ou RX_VK_MESH_NOCULL=1 para desativar o culling de meshlets globalmente).
Certos drivers de AMD Windows Adrenalin e Linux compilam incorretamente o transcodificador de computação de ASTC para BC7, gerando macroblocos coloridos de 4x4 em ícones da HUD e na folhagem dos Kokiri.
PAINEL 01 // SINTOMA OBSERVADO
Blocos 4x4 xadrez ou arco-íris em ícones da UI, grama e superfícies de água
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
RX_VK_ASTC_RGBA8=1
PAINEL 03 // RESOLUÇÃO VERIFICADA
Defina export RX_VK_ASTC_RGBA8=1 antes de iniciar o Hookshot para forçar a descompactação sem perdas de RGBA8 por software em vez de transcodificação via compute BC7.
Issues nº 1176 e nº 990Falha na extração de recursos do HookshotBuilder ou divergência de hash no NSO (#1176 / #990)
Windows x64 e Linux x86_64 HookshotBuilder
O construtor de recursos é abortado ao receber um dump base v0 sem o patch v131072, uma ROM de N64/3DS em vez do Title ID 0400486024DEC000 do Switch 2, ou caminhos no Windows com caracteres não ASCII antes da versão v2.0.11.
PAINEL 01 // SINTOMA OBSERVADO
O Builder relata ExeFS Build ID não suportado ou falha em 99% do reempacotamento de RomFS
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
Exigir Title ID 0400486024DEC000 v131072 (e0f3ccfa)
PAINEL 03 // RESOLUÇÃO VERIFICADA
Update para o Hookshot v2.0.11 (corrige o bug #1176 no caminho de Windows em UTF-8) e forneça o dump de Switch 2 v131072 mesclado correspondente ao prefixo e0f3ccfa de SHA-1.
docs/DEVELOPMENT.mdIsolando Shaders Quebrado Personalizado ou Específico do Driver (RX_SKIP_SHADERS)
Todas as plataformas com Vulkan 1.3
Ignora chamadas de desenho para um ou mais hashes de 64 bits de shaders NVN2, permitindo identificar com precisão qual pipeline de SPIR-V causa travamento de driver ou falhas visuais.
PAINEL 01 // SINTOMA OBSERVADO
Um efeito de partículas específico ou passe de pós-processamento trava ou cega a visão do jogo
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
RX_SKIP_SHADERS=<hash1>,<hash2>
PAINEL 03 // RESOLUÇÃO VERIFICADA
Execute com RX_LOG_LEVEL=debug para registrar o hash do shader ativo antes do travamento e, em seguida, passe RX_SKIP_SHADERS=<hash> para contornar esse pipeline.
docs/DESIGN.md e docs/DEVELOPMENT.mdIgnorando Regressões de Funções C Convertidas via ARM64 Interpreter (RX_FORCE_INTERP)
Windows x64 e Linux x86_64
Encaminha endereços de funções guest individuais (`0x7100xxxxxx`) ou o binário inteiro pelo interpretador de ARM64 por software em vez das traduções estáticas de C.
PAINEL 01 // SINTOMA OBSERVADO
Anomalia na física de atores ou softlock suspeito em uma função de ARM64 elevada
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
RX_FORCE_INTERP=0x7100123450 ou RX_FORCE_INTERP=all
PAINEL 03 // RESOLUÇÃO VERIFICADA
Defina RX_FORCE_INTERP como o endereço guest suspeito para verify se o bug tem origem no conversor estático de C do nx2/.
docs/DEVELOPMENT.mdHabilitando registros detalhados de chamadas de sistema do Vulkan e HLE (RX_LOG_LEVEL e RX_TRACE_FUNC)
Windows x64 e Linux x86_64
Controla a verbosidade de stdout/stderr de trace a error e registra os estados dos registradores na entrada/saída (`X0`–`X7`) de funções convidadas ao relatar problemas do GitHub.
PAINEL 01 // SINTOMA OBSERVADO
Encerramento silencioso na inicialização ou parada em stub de serviço não implementado do HLE
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
RX_LOG_LEVEL=debug / RX_ABORT_ON_UNIMPL=1
PAINEL 03 // RESOLUÇÃO VERIFICADA
Inicie pelo terminal com RX_LOG_LEVEL=debug (e opcionalmente RX_TRACE_FUNC=0x7100xxxxxx) para coletar registros completos de diagnóstico.
docs/DEVELOPMENT.mdTestando carregamento de recursos e lógica de boot sem Mesh Shaders (RX_GPU_BACKEND=null)
Ambientes de CI headless e máquinas de teste sem mesh shaders
Inicializa o renderizador nulo (no-op) e RX_BOOT_DIRECT=1 para permitir que desenvolvedores em máquinas sem mesh shaders possam verify a montagem de RomFS, áudio e análise de dados salvos.
PAINEL 01 // SINTOMA OBSERVADO
Falha na inicialização do Vulkan com VK_ERROR_EXTENSION_NOT_PRESENT em drivers legados de GPU
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
RX_GPU_BACKEND=null RX_BOOT_DIRECT=1
PAINEL 03 // RESOLUÇÃO VERIFICADA
Use RX_GPU_BACKEND=null para verificação headless de boot/salvamento; o gameplay real em 3D requer suporte por hardware a VK_EXT_mesh_shader GPU.
README.md Linux SetupO Linux AppImage não inicia (chmod +x ou libfuse2 ausente)
Linux x86_64 (Ubuntu, Debian, Fedora, Arch)
No On Ubuntu 22.04/24.04 ou distribuições mínimas sem libfuse2, clicar duas vezes no Hookshot-v2.0.11-Linux-x86_64.AppImage falha silenciosamente, a menos que sejam usadas permissões de execução ou --appimage-extract.
PAINEL 01 // SINTOMA OBSERVADO
O AppImage não abre ou exibe dlopen(): error loading libfuse.so.2
PAINEL 02 // VARIÁVEL DE AMBIENTE OU PARÂMETRO
chmod +x *.AppImage ou --appimage-extract-and-run
PAINEL 03 // RESOLUÇÃO VERIFICADA
Execute chmod +x Hookshot-v2.0.11-Linux-x86_64.AppImage e instale a libfuse2t64 ou passe --appimage-extract-and-run.
docs/SAVES.mdArquivo salvo corrompido ou substituição manual do caminho de salvamento (RX_SAVE_PATH e oot_saves.py)
Windows x64 e Linux x86_64
Recupera arquivos de gravações interrompidas alternando para o autosave.sav ou recalculando o checksum CRC32C do cabeçalho (`0x0008`) com scripts/oot_saves.py.
PAINEL 01 // SINTOMA OBSERVADO
O slot de salvamento aparece vazio ou com Dados corrompidos após queda de energia ou edição hexadecimal manual
SUBSTITUIÇÃO DE DIAGNÓSTICO // RX_FORCE_INTERP E RX_SKIP_SHADERSIsolando Código ARM64 Convertido vs. Regressões de SPIR-V Shader
Quando um travamento ou softlock não puder ser resolvido reduzindo os presets de VRAM, combine RX_LOG_LEVEL=debug com RX_SKIP_SHADERS=<hash> para testar se um pipeline específico de NVN2 SPIR-V é o culpado, ou defina RX_FORCE_INTERP=0x7100xxxxxx (ou RX_FORCE_INTERP=all) para executar funções guest no interpretador de ARM64 por software em vez da C estática.
ESBOÇOS DE ROTAS DE FALHA // PRINCIPAIS 3 ISSUES EM DESTAQUE
Esquemas visuais de caminhos de falha (#1161 · #817 · #57)
ISSUE #1161
VK_ERROR_DEVICE_LOST Queue TimeoutTransição em Hyrule Field / Temple ou envio de Driver no NVIDIA 621
O pool de texturas do ASTC + cascatas de sombra excedem a VRAM física ou uma fila de apresentação separada aciona timeout de TDR → Reduza o preset de Insert/F1 para Low/Medium e execute Hookshot v2.0.11.
ISSUE #817
Travamento na Deku Tree com Steam Deck RADVDeadlock de descarte de meshlets por subgrupos em Mesa RADV
Entrar dentro da Deku Tree executa o mesh shader 2c56dc1006942f74 → a instrução wave64 ballot do RADV bloqueia o buffer de comandos do GPU → Passe RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%.
ISSUES #57 e #1006
Glitch 2/3 com blocos 4×4 de ASTC em AMD RDNAErro de compilação do transcodificador de ASTC para BC7 via computação
O compute shader de Adrenalin / RADV corrompe blocos 4×4 de BC7 na folhagem dos Kokiri e nos ícones da HUD → Exporte RX_VK_ASTC_RGBA8=1 para forçar a decodificação de texturas por software em CPU/RGBA8.
Livro de registro completo de 10 registros de solução de problemas e parâmetros RX_*
Nome da Falha e Ref. de Issue
Plataforma afetada
Variável de ambiente / Parâmetro
Falhas relacionadas
Esgotamento de Timeout ou VRAM do VK_ERROR_DEVICE_LOST GPU (#1161) Issue nº 1161
GPUs com 4 GB a 6 GB de VRAM ou drivers com overclock no Vulkan
graphics_preset=Low/Medium ou RX_SKIP_SHADERS=<hash>
Corrigido no v2.0.9–v2.0.11 · Reduza o preset de Insert/F1 em GPUs de 4–6 GB
KPI-TRB-02 // ISSUE #817
2c56dc1006942f74
Travamento na Deku Tree com Steam Deck
Bypass com RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%
KPI-TRB-03 // ISSUES #57 & #1006
RX_VK_ASTC_RGBA8=1
Folhagem blocada 2/3 com AMD RDNA
Força a descompressão de RGBA8 por software sem perdas em vez da computação via BC7
KPI-TRB-04 // LIFTER FALLBACK
RX_FORCE_INTERP
ARM64 Interpreter Bypass
Redireciona funções 0x7100xxxxxx suspeitas para longe dos fragmentos de C convertidos
ESPECIFICAÇÃO TÉCNICA // DIAGNÓSTICO E VARIÁVEIS RX_*
Solucionando VK_ERROR_DEVICE_LOST (#1161), travamentos na Deku Tree com Steam Deck (#817) e glitches de AMD no ASTC (#57)
Três falhas específicas de hardware representam a maioria dos chamados de suporte da comunidade no Hookshot. Primeiro, o Issue #1161 (VK_ERROR_DEVICE_LOST) ocorre em dois cenários distintos: nos drivers NVIDIA da série 621 logo após a preparação inicial dos shaders quando uma fila de apresentação separada do Vulkan estava ativa (mitigado na v2.0.9 e aprimorado na v2.0.11 mantendo a fila separada desativada ao reativar RX_VK_WB_DIFF=1), ou durante transições pesadas em Hyrule Field / Temple quando o pool de texturas e as cascatas de sombra do ASTC excedem a VRAM física em GPUs de 4 GB a 6 GB. Reduzir o Graphics Preset no menu do Insert / F1 para Low (pool de 1.5 GB) ou Medium (pool de 2.5 GB) evita o esgotamento de VRAM.
Segundo, o Issue #817 afeta sistemas Steam Deck LCD/OLED e Linux AMD RADV com versões do Mesa anteriores à 24.3: entrar em Inside the Deku Tree ou na Web Room trava o buffer de comandos do GPU enquanto o áudio continua em loop. O travamento é causado pelo culling de meshlets em subgrupos no mesh shader 2c56dc1006942f74 do NVN2; configurar as Opções de Inicialização da Steam com RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% ignora o culling desse shader específico sem perda mensurável de FPS. Terceiro, os problemas Issues #57 e #1006 em GPUs AMD Radeon RX 6000 / RX 7000 causam blocos coloridos 4x4 na vegetação e nos ícones da HUD devido a erros de compilação do driver no transcodificador compute de ASTC para BC7; exportar RX_VK_ASTC_RGBA8=1 ativa a descompressão de RGBA8 por software sem perdas.
Erros de extração do HookshotBuilder (#1176 / #990) e parâmetros de diagnóstico RX_* para desenvolvedores
Quando o HookshotBuilder falhar durante a extração de recursos ou a compilação do C, verify três pré-requisitos: (1) seu dump corresponde ao Title ID 0400486024DEC000 do Switch 2 na atualização v131072 com o prefixo e0f3ccfa do ExeFS main NSO SHA-1 (e0f3ccfa56256410941279ef0b2501356be2222c), e não a um dump base v0 ou ROM de N64/3DS; (2) você está executando o Hookshot v2.0.11, que corrige falhas em caminhos de usuário não ASCII no Windows (#1176), conflitos com traduções de C obsoletas (#1197) e cabeçalhos ausentes do Linux AppImage (#990); e (3) você possui ao menos 30 GB de espaço livre em disco para os 26.2 GB do RomFS descompactado mais 1.4 GB de fontes de C geradas.
Para depuração avançada, o Hookshot oferece variáveis de ambiente detalhadas documentadas em docs/DEVELOPMENT.md: RX_LOG_LEVEL=debug e RX_ABORT_ON_UNIMPL=1 exibem chamadas de serviço não implementadas do HLE no Horizon OS; RX_SKIP_SHADERS=<hash1>,<hash2> desativa pipelines específicos de shaders NVN2 de 64 bits para isolar defeitos visuais; RX_FORCE_INTERP=0x7100xxxxxx direciona funções convidadas suspeitas para o interpretador de software do ARM64; e RX_GPU_BACKEND=null opera com RX_BOOT_DIRECT=1 para testes de inicialização em modo headless.
PERGUNTAS FREQUENTES // FALHAS E SAVES
FAQ de solução de problemas e variáveis de ambiente
Onde posso definir RX_VK_MESH_NOCULL ou RX_VK_ASTC_RGBA8 no Windows versus Steam Deck?
Na On Steam Deck ou no Linux Steam, clique com o botão direito em Hookshot -> Propriedades -> Opções de Inicialização e insira: RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (ou combine múltiplas variáveis antes de %command%). No On Windows PowerShell, execute $env:RX_VK_ASTC_RGBA8=1; .\hookshot.exe a partir do diretório de build ou adicione a variável em Propriedades do Windows System -> Variáveis de Ambiente.
Por que a atualização de v2.0.7 para v2.0.9 falhou com símbolos não declarados g_module_b ou f_8 (#1176 / #1197)?
Antes da versão v2.0.10, atualizações interrompidas ou entre versões podiam deixar arquivos residuais de C gerados dentro de work/sa/gen/, causando erros de link no clang/lld. Atualizar para o Hookshot v2.0.11 descarta automaticamente códigos residuais parciais e limpa partes antigas de tradução antes de compilar.
Como recuperar um slot de salvamento se o Hookshot indicar Dados corrompidos após um travamento?
Primeiro, verifique se há o arquivo autosave.sav no diretório de saves e copie-o sobre save_00.sav. Caso tenha editado um save manualmente, execute python -m nx2.oot_saves verify save_00.sav (ou export-json seguido por import-json) para que o Hookshot recalcule o checksum CRC32C exigido no deslocamento de cabeçalho 0x0008.
FONTES PRIMÁRIAS E VERIFICAÇÃO
Referências Oficiais de Diagnóstico e Issue do NotRexed/Hookshot
Verifica a correção para drivers 621 de v2.0.9 NVIDIA (#1161), a limpeza do construtor no v2.0.10 (#1176/#1197) e a restauração de v2.0.11 com RX_VK_WB_DIFF=1.
