PLANO N.º: HS-2011-06 // REV: v2.0.11 // ESCALA: ATLAS-ERRORES // HOJA 6 DE 6
10 FICHAS DE ERRORES VERIFICADAS (#1161 · #817 · #57)ANULACIONES DE DIAGNÓSTICO: RX_VK_MESH_NOCULL · RX_VK_ASTC_RGBA8 · RX_FORCE_INTERP
Solución de Errores de Hookshot y Variables de Diagnóstico
Diagnostica y soluciona cada fallo de ejecución documentado de Hookshot v2.0.11, cuelgues del controlador de GPU, artefactos de texturas y errores de extracción en el compilador. Busca o filtra las 10 fichas de errores verificadas a continuación por etiqueta de incidencia (#1161, #817, #57, #1176) o síntoma, inspecciona los tres paneles de diagnóstico reglamentarios (Síntoma, Parámetro de entorno, Solución) y aplica anulaciones específicas de entorno RX_*.
FIG. 6.0 — Triaje de fallos de Hookshot y flujo de decisión para variables de entorno RX_* (v2.0.11)
ATLAS DE FALLOS DIVIDIDO // 10 FICHAS DE DIAGNÓSTICO VERIFICADAS
Índice interactivo de fallos y banco de trabajo diagnóstico de tres paneles
Filtra por etiqueta de problema principal (#1161, #817, #57, #1176, diagnósticos RX_*) o busca por palabra clave del síntoma. Cada ficha de fallos presenta tres paneles con líneas divisorias —Síntoma observado, Variable de entorno / Parámetro de lanzamiento y Solución verificada en v2.0.11— junto con referencias cruzadas entre fallos.
Issue #1161Agotamiento de VRAM o Timeout en VK_ERROR_DEVICE_LOST GPU (#1161)
GPU de 4 GB a 6 GB de VRAM o controladores Vulkan con overclock
Ocurre durante transiciones de carga pesada en Hyrule Field o templos cuando el grupo de texturas de ASTC más las cascadas de sombras superan la VRAM física o agotan el tiempo de espera TDR del controlador.
PANEL 01 // SÍNTOMA OBSERVADO
Aviso emergente crítico de VK_ERROR_DEVICE_LOST y cierre inesperado al escritorio al cargar un área
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
graphics_preset=Low/Medium o RX_SKIP_SHADERS=<hash>
PANEL 03 // RESOLUCIÓN VERIFICADA
Reduce el Ajuste gráfico en el menú de Insert/F1 a Low (4 GB) o Medium (6 GB), baja la escala de resolución a 1.0x y actualiza a la corrección del pool de descriptores de v2.0.11.
Issue #817Cuelgue dentro del Árbol Deku en Steam Deck / Linux RADV (#817)
Steam Deck LCD/OLED y RADV Linux AMD (Mesa < 24.3)
Entrar en Inside the Deku Tree o en Web Room en Steam Deck (Mesa RADV) puede colgar el búfer de comandos de GPU debido al descarte de meshlets en subgrupos en el sombreador 2c56dc1006942f74.
PANEL 01 // SÍNTOMA OBSERVADO
La pantalla se congela con el audio en bucle al entrar en Inside the Deku Tree
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
RX_VK_MESH_NOCULL=2c56dc1006942f74
PANEL 03 // RESOLUCIÓN VERIFICADA
Configura los parámetros de inicio de Steam con RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (o RX_VK_MESH_NOCULL=1 para desactivar el culling de meshlets de forma global).
Issues #57 y #1006Vegetación pixelada y fallos de textura HUD en AMD RDNA 2 / RDNA 3 (#57 / #1006)
Series AMD Radeon RX 6000 / RX 7000 (Windows y Linux)
Determinados controladores de AMD Windows Adrenalin y Linux compilan de forma incorrecta el transcodificador por cómputo de ASTC a BC7, generando artefactos de macrobloques 4x4 de colores en los iconos de HUD y el follaje de Kokiri.
PANEL 01 // SÍNTOMA OBSERVADO
Bloques 4x4 con patrón de tablero o arcoíris en iconos de UI, hierba y superficies de agua
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
RX_VK_ASTC_RGBA8=1
PANEL 03 // RESOLUCIÓN VERIFICADA
Ejecuta export RX_VK_ASTC_RGBA8=1 antes de iniciar Hookshot para forzar la descompresión sin pérdida por software de RGBA8 en lugar de la transcodificación de BC7 por shaders de cómputo.
Issues #1176 y #990Fallo de extracción de recursos o discrepancia de hash en NSO con HookshotBuilder (#1176 / #990)
Windows en x64 y Linux x86_64 HookshotBuilder
El constructor de recursos se detiene si recibe un volcado v0 base sin el parche v131072, una ROM de N64/3DS en lugar del Title ID 0400486024DEC000 de Switch 2, o rutas de Windows con caracteres no ASCII en versiones anteriores a v2.0.11.
PANEL 01 // SÍNTOMA OBSERVADO
Builder informa de ExeFS Build ID no compatible o falla al 99 % del reempaquetado de RomFS
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
Requiere Title ID 0400486024DEC000 v131072 (e0f3ccfa)
PANEL 03 // RESOLUCIÓN VERIFICADA
Update a Hookshot v2.0.11 (corrige el error #1176 de rutas en UTF-8 en Windows) y suministra el volcado combinado de Switch 2 v131072 correspondiente al prefijo e0f3ccfa de SHA-1.
docs/DEVELOPMENT.mdAislar Shaders rotos personalizados o específicos de Driver (RX_SKIP_SHADERS)
Todas las plataformas con Vulkan 1.3
Omite las llamadas de dibujado de uno o varios hashes de 64 bits de sombreadores NVN2 para que jugadores y colaboradores puedan aislar qué canalización de SPIR-V causa un cuelgue del controlador o un fallo gráfico.
PANEL 01 // SÍNTOMA OBSERVADO
Un efecto de partículas específico o un pase de posprocesamiento cuelga el juego o deja en blanco el visor
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
RX_SKIP_SHADERS=<hash1>,<hash2>
PANEL 03 // RESOLUCIÓN VERIFICADA
Ejecuta con RX_LOG_LEVEL=debug para registrar el hash del sombreador activo antes del cuelgue, luego pasa RX_SKIP_SHADERS=<hash> para omitir esa canalización.
docs/DESIGN.md y docs/DEVELOPMENT.mdEvitar regresiones en funciones de C generadas mediante ARM64 Interpreter (RX_FORCE_INTERP)
Windows x64 y Linux x86_64
Dirige direcciones individuales de funciones invitadas (`0x7100xxxxxx`) o el binario completo al intérprete de ARM64 por software en lugar de usar las traducciones de C estáticas.
PANEL 01 // SÍNTOMA OBSERVADO
Anomalía de física de actores o bloqueo de progreso sospechoso en una función generada de ARM64
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
RX_FORCE_INTERP=0x7100123450 o RX_FORCE_INTERP=all
PANEL 03 // RESOLUCIÓN VERIFICADA
Establece RX_FORCE_INTERP en la dirección invitada bajo sospecha para verify si el error proviene del generador de C estático de nx2/.
docs/DEVELOPMENT.mdHabilitar registros detallados de llamadas al sistema de Vulkan y HLE (RX_LOG_LEVEL y RX_TRACE_FUNC)
Windows x64 y Linux x86_64
Controla el nivel de detalle de stdout/stderr desde trace hasta error y registra los estados de registros de entrada/salida (`X0`–`X7`) para funciones huésped concretas al reportar problemas en GitHub.
PANEL 01 // SÍNTOMA OBSERVADO
Cierre silencioso al inicio o captura por stub de servicio no implementado de HLE
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
RX_LOG_LEVEL=debug / RX_ABORT_ON_UNIMPL=1
PANEL 03 // RESOLUCIÓN VERIFICADA
Inicia desde la terminal con RX_LOG_LEVEL=debug (y de forma opcional RX_TRACE_FUNC=0x7100xxxxxx) para recopilar registros de diagnóstico completos.
docs/DEVELOPMENT.mdProbar lógica de arranque y carga de recursos sin Mesh Shaders (RX_GPU_BACKEND=null)
Entornos de ejecución CI sin interfaz y equipos de prueba sin sombreadores de malla
Inicializa el renderizador nulo no-op y RX_BOOT_DIRECT=1 para que los desarrolladores en equipos sin sombreadores de malla puedan probar en verify el montaje de RomFS, el audio y el análisis de partidas guardadas.
PANEL 01 // SÍNTOMA OBSERVADO
La inicialización de Vulkan falla con VK_ERROR_EXTENSION_NOT_PRESENT en hardware heredado de GPU
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
RX_GPU_BACKEND=null RX_BOOT_DIRECT=1
PANEL 03 // RESOLUCIÓN VERIFICADA
Usa RX_GPU_BACKEND=null para comprobaciones de arranque y guardado sin interfaz; jugar en 3D real requiere un VK_EXT_mesh_shader GPU por hardware.
README.md Linux SetupLinux AppImage no arranca (falta chmod +x o libfuse2)
Linux x86_64 (Ubuntu, Debian, Fedora, Arch)
On Ubuntu 22.04/24.04 o distribuciones mínimas sin libfuse2, hacer doble clic en Hookshot-v2.0.11-Linux-x86_64.AppImage falla silenciosamente salvo que se asignen permisos de ejecución o se use --appimage-extract.
PANEL 01 // SÍNTOMA OBSERVADO
AppImage no se abre o muestra dlopen(): error loading libfuse.so.2
PANEL 02 // VARIABLE DE ENTORNO O PARÁMETRO
chmod +x *.AppImage o --appimage-extract-and-run
PANEL 03 // RESOLUCIÓN VERIFICADA
Ejecuta chmod +x Hookshot-v2.0.11-Linux-x86_64.AppImage e instala libfuse2t64 o bien pasa --appimage-extract-and-run.
docs/SAVES.mdRanura de guardado corrupta o anulación manual de la ruta de guardado (RX_SAVE_PATH y oot_saves.py)
Windows x64 y Linux x86_64
Recupera escrituras interrumpidas recurriendo a autosave.sav o recalculando la suma de comprobación CRC32C de la cabecera (`0x0008`) mediante scripts/oot_saves.py.
PANEL 01 // SÍNTOMA OBSERVADO
La ranura de guardado aparece vacía o como Datos dañados tras un corte de energía o una edición hexadecimal manual
ANULACIÓN DE DIAGNÓSTICO // RX_FORCE_INTERP Y RX_SKIP_SHADERSCómo aislar regresiones de código de ARM64 generado frente a SPIR-V Shader
Cuando no sea posible resolver un cuelgue o bloqueo parcial reduciendo los ajustes predeterminados de VRAM, combina RX_LOG_LEVEL=debug con RX_SKIP_SHADERS=<hash> para comprobar si la causa es un pipeline de NVN2 SPIR-V concreto, o define RX_FORCE_INTERP=0x7100xxxxxx (o RX_FORCE_INTERP=all) para ejecutar las funciones invitadas en el intérprete por software de ARM64 en vez de la C estática.
BOCETOS GRÁFICOS DE RUTAS DE ERROR // TOP 3 ISSUES PRINCIPALES
Esquemas visuales de rutas de fallo (#1161 · #817 · #57)
ISSUE #1161
VK_ERROR_DEVICE_LOST Queue TimeoutTransición en Hyrule Field / Templo o envío de Driver en NVIDIA 621
El búfer de texturas de ASTC y las cascadas de sombras superan la VRAM física o la cola de presentación independiente provoca un timeout TDR → Reduce el ajuste predeterminado de Insert/F1 a Low/Medium y ejecuta Hookshot v2.0.11.
ISSUE #817
Cuelgue en Deku Tree en Steam Deck RADVBloqueo mutuo por descarte de meshlets en subgrupos en Mesa RADV
Entrar a Inside the Deku Tree ejecuta el sombreador de malla 2c56dc1006942f74 → El sondeo wave64 de RADV detiene el búfer de comandos de GPU → Pasa RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%.
ISSUES #57 y #1006
Error de ASTC de bloques 4×4 en 2/3 de AMD RDNACompilación errónea del transcodificador por cómputo de ASTC a BC7
El sombreador de cómputo de Adrenalin / RADV corrompe bloques 4×4 de BC7 en el follaje de Kokiri y los iconos de HUD → Exporta RX_VK_ASTC_RGBA8=1 para forzar la descodificación de texturas por CPU/software en RGBA8.
Registro completo de 10 entradas de resolución de problemas y parámetros RX_*
Nombre del fallo y ref. de Issue
Plataforma afectada
Variable de entorno / Parámetro
Fallos relacionados
Agotamiento de VRAM o Timeout en VK_ERROR_DEVICE_LOST GPU (#1161) Issue #1161
GPU de 4 GB a 6 GB de VRAM o controladores Vulkan con overclock
graphics_preset=Low/Medium o RX_SKIP_SHADERS=<hash>
Solucionado en v2.0.9–v2.0.11 · Reduce el ajuste predeterminado de Insert/F1 en GPUs de 4–6 GB
KPI-TRB-02 // ISSUE #817
2c56dc1006942f74
Cuelgue en Deku Tree en Steam Deck
Bypass con RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%
KPI-TRB-03 // ISSUES #57 & #1006
RX_VK_ASTC_RGBA8=1
Follaje pixelado en bloques de 2/3 en AMD RDNA
Fuerza la descompresión de RGBA8 por software sin pérdidas en vez de cómputo en BC7
KPI-TRB-04 // LIFTER FALLBACK
RX_FORCE_INTERP
ARM64 Interpreter Bypass
Desvía las funciones 0x7100xxxxxx dudosas fuera de los fragmentos de C generados
ESPECIFICACIÓN TÉCNICA // DIAGNÓSTICO Y VARIABLES RX_*
Solución para VK_ERROR_DEVICE_LOST (#1161), cuelgues en Deku Tree en Steam Deck (#817) y fallos gráficos de AMD ASTC (#57)
Tres problemas vinculados al hardware concentran la mayoría de avisos de asistencia de la comunidad en Hookshot. En primer lugar, Issue #1161 (VK_ERROR_DEVICE_LOST) ocurre en dos situaciones concretas: con controladores NVIDIA de la serie 621 justo tras preparar los shaders de inicio si estaba activa una cola de presentación independiente en Vulkan (mitigado en v2.0.9 y pulido en v2.0.11 manteniendo dicha cola desactivada mientras se vuelve a habilitar RX_VK_WB_DIFF=1), o durante transiciones exigentes en Hyrule Field o templos cuando el búfer de texturas de ASTC y las cascadas de sombras exceden la VRAM física en GPUs de 4 GB a 6 GB. Reducir el ajuste predeterminado de gráficos en el menú de Insert / F1 a Low (búfer de 1.5 GB) o Medium (búfer de 2.5 GB) evita agotar la VRAM.
En segundo lugar, Issue #817 afecta a sistemas Steam Deck LCD/OLED y Linux AMD RADV que utilizan versiones de Mesa anteriores a la 24.3: al entrar en el interior del Deku Tree o en la sala de las telarañas, el búfer de comandos de GPU se cuelga mientras el audio continúa en bucle. El bloqueo se debe al descarte (culling) de meshlets por subgrupos dentro del 2c56dc1006942f74 de mesh shaders de NVN2; configurar las opciones de lanzamiento de Steam con RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% elude el descarte para ese shader concreto sin ninguna penalización apreciable de FPS. En tercer lugar, Issues #57 y #1006 en GPUs AMD Radeon RX 6000 / RX 7000 provocan bloques multicolores de 4x4 en la vegetación y en los iconos de HUD debido a un fallo de compilación del controlador en el transcodificador por cómputo de ASTC a BC7; exportar RX_VK_ASTC_RGBA8=1 conmuta a la descompresión sin pérdidas de RGBA8 por software.
Errores de extracción en HookshotBuilder (#1176 / #990) y parámetros de diagnóstico RX_* para desarrolladores
Si HookshotBuilder falla durante la extracción de recursos o la compilación de C, verify estos tres requisitos: (1) que tu volcado corresponda al Title ID 0400486024DEC000 de Switch 2 con la actualización v131072 y el prefijo SHA-1 e0f3ccfa en el main NSO de ExeFS (e0f3ccfa56256410941279ef0b2501356be2222c), descartando volcados base v0 o ROMs de N64/3DS; (2) que estés ejecutando Hookshot v2.0.11, que corrige los fallos por rutas de usuario no ASCII en Windows (#1176), los conflictos de fragmentos de traducción de C antiguos generados (#1197) y la ausencia de cabeceras de Linux AppImage (#990); y (3) que dispongas de al menos 30 GB de espacio libre en disco para los 26.2 GB del RomFS descomprimido y 1.4 GB de código fuente de C generado.
Para depuración avanzada, Hookshot ofrece variables de entorno detalladas y documentadas en docs/DEVELOPMENT.md: RX_LOG_LEVEL=debug y RX_ABORT_ON_UNIMPL=1 revelan llamadas de servicio de HLE sin implementar en Horizon OS; RX_SKIP_SHADERS=<hash1>,<hash2> deshabilita canalizaciones de sombreador de 64 bits específicas en NVN2 para aislar errores visuales; RX_FORCE_INTERP=0x7100xxxxxx envía funciones huésped sospechosas a través del intérprete por software de ARM64; y RX_GPU_BACKEND=null se combina con RX_BOOT_DIRECT=1 para verificar el arranque sin interfaz gráfica.
PREGUNTAS FRECUENTES // FALLOS Y PARTIDAS
Preguntas frecuentes sobre resolución de problemas y parámetros de entorno (FAQ)
¿Dónde configuro RX_VK_MESH_NOCULL o RX_VK_ASTC_RGBA8 en Windows frente a Steam Deck?
On Steam Deck o Linux Steam, haz clic derecho en Hookshot -> Propiedades -> Opciones de lanzamiento e introduce: RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (o combina varias variables antes de %command%). On Windows PowerShell, ejecuta $env:RX_VK_ASTC_RGBA8=1; .\hookshot.exe desde la carpeta de compilación, o añade la variable en Propiedades del System de Windows -> Variables de entorno.
¿Por qué falló la actualización de v2.0.7 a v2.0.9 indicando símbolos g_module_b o f_8 no declarados (#1176 / #1197)?
Antes de v2.0.10, las actualizaciones interrumpidas o entre distintas versiones podían dejar archivos de C generados obsoletos dentro de work/sa/gen/, provocando errores de enlace con clang/lld. Actualizar a Hookshot v2.0.11 descarta automáticamente el código generado parcial que haya quedado obsoleto y limpia los fragmentos de traducción antiguos antes de compilar.
¿Cómo recupero una ranura de guardado si Hookshot indica Datos dañados tras un cierre inesperado?
Primero revisa la carpeta de guardados en busca de autosave.sav y cópialo sobre save_00.sav. Si modificaste un archivo de guardado de forma manual, ejecuta python -m nx2.oot_saves verify save_00.sav (o export-json seguido de import-json) para que Hookshot vuelva a calcular la suma de comprobación obligatoria CRC32C en el desplazamiento 0x0008 de la cabecera.
FUENTES PRINCIPALES Y VERIFICACIÓN
Referencias oficiales de diagnóstico de NotRexed/Hookshot y Issue
Especifica la disposición de 64 KB de save_00.sav, la suma de comprobación CRC32C en el desplazamiento 0x0008, el mecanismo de respaldo de autosave.sav y scripts/oot_saves.py.
Verifica el parche urgente para el controlador 621 en v2.0.9 NVIDIA (#1161), la limpieza del compilador en v2.0.10 (#1176/#1197) y la restauración de v2.0.11 RX_VK_WB_DIFF=1.
