Troubleshooting & Crash Fixes

Hyrule Field 16 GB RAM commit fix

Root cause: Streaming Hyrule Field's large terrain and BC3 texture pools alongside Windows desktop processes can exhaust a default auto-managed Windows commit limit (`system commit low`), causing missing ground chunks or sudden exits.

Verified three-part fix:

1. Open System Properties → Advanced → Performance Settings → Advanced → Virtual memory → Change, uncheck automatic management on your NVMe drive, and set a Custom size: Initial size = 32768 MB, Maximum size = 32768 MB, then reboot.
2. Ensure astc_bc = 1, astc_bc1 = 1, texture_detail = reduced, and pipe_release = 1 are set in nx2navi.ini (select the 16 GB RAM preset in our nx2navi.ini generator).
3. Opt into Preview v0.10.2-rc4 via Launcher Settings → Update Channel → Preview, which cuts Hyrule Field's VRAM reservation from 16.7 GB down to 13.2 GB.

Camera-turn VRAM climb fix

Root cause: A regression in v0.10.0 failed to release overwritten render-target images. Fix: Update immediately to Stable v0.10.1 or Preview v0.10.2-rc4.

AMD iGPU host memory heap crash

Root cause: Hybrid laptops (AMD Ryzen iGPU + discrete NVIDIA/Radeon dGPU) or APUs with a small BIOS host-visible memory heap can fail initial host-memory import or pick the integrated adapter first.

Fix: Run ocarina.exe --list-gpus (or check logs/nx2navi.log), force your discrete card via vk_device = 0 (or the discrete GPU's index/name substring) in nx2navi.ini, and update to v0.10.1+ which caps host-heap allocation gracefully on smaller APU heaps.

Shader stutter & 30s session hitch

NVIDIA Shader Cache Size

NVIDIA's default driver disk cache quota can evict NX2navi's prewarmed pipelines. Open NVIDIA Control Panel → Manage 3D Settings → Shader Cache Size and set it to Unlimited (or 10 GB+).

Keep ocarina-shaders.bin intact

Never delete ocarina-shaders.bin from your game folder; the Launcher builds it specifically to pre-link Vulkan Graphics Pipeline Library states.

55-82 ms hitch ~30s after launch

Fixed in Preview v0.10.2-rc4 by moving deferred pipeline housekeeping off the render critical path.

Mesh-shader fallback & white grass

Older GPUs (such as GTX 10-series, RX 5000, or older Mesa builds) that do not expose VK_EXT_mesh_shader use NX2navi's compute/indirect fallback automatically (mesh_fallback = auto). If bushes or grass flash white under mesh fallback on v0.10.1, switch to Preview v0.10.2-rc4 which repairs the indirect draw buffer layout.

SmartScreen, Defender & F8 logs

Freshly compiled local executables (ocarina.exe) and unsigned community installers occasionally trigger heuristic false positives. Always verify your downloaded installer in our local SHA-256 verifier first; once verified, exclude your dedicated C:\Games\NX2navi build folder rather than disabling system protection globally.

When filing an upstream issue on GitHub, press F8 in-game to generate a timestamped bundle under logs/bugs/ and attach logs/nx2navi.log. Never upload .nup dumps, romfs files, or copyrighted assets to GitHub issues.