Guarana Download

Troubleshooting · shader compilation · frame pacing

Fix stutter in a Switch 2 emulator

Stutter has two causes that need different fixes: shader compilation when you enter a new area, and uneven frame pacing the rest of the time. Here is how to tell which you have, what helps, and the numbers we measured.

Download Guarana Ask in Discord Send a device report

Two different problems

  • Hitches happen when you enter somewhere new: a long frame while the driver compiles a shader. Fixes: let the cache fill, warm it up, skip nothing.
  • Uneven pacing happens all the time with frame generation on: frames reach the screen at irregular intervals even when the average is fine. Fix: a presenter locked to the display’s refresh.

To tell them apart, turn Enable Frame Generation off. If motion is then even, it is pacing; if the long frames remain only in new areas, it is shaders. To confirm a shader hitch, add EDEN_NX2_STUTTER_TRACE=1 to your nx2_switches.txt: the log gets an Nx2Stutter line per slow frame naming its top cause.

What we measured, and on what

One machine: Core Ultra 9 285H laptop, Intel Arc 140T, driver 32.0.101.9175, 120 Hz OLED, 32 GB RAM, plugged in. Game: The Legend of Zelda: Ocarina of Time. “Game fps” counts only frames the game renders, never generated ones.

WhatBeforeAfterStatus
Hyrule Field, one shader fix (EDEN_NX2_GM=11), frame generation off14.8 game fps22.8 game fpsShipped in v20; on by default for Ocarina of Time only
Foliage mesh draw, same runs15.7 ms GPU5.8 ms GPUShipped in v20
Frame pacing, title screen: frames within 2 ms of the median intervaln/a100%Next release
Same measure, Hyrule Field33-54%75%Next release
Headless shader warm-upn/a4,515 pipelines in 155 sNext release
Stutters (intervals over twice the median) per 30 s, same scene37-92 on the old setup19 with v21v21 is a development build, not released
Boot to first frame, with the startup check skippedn/a19.6 sDevelopment build, not released

Method and caveats: benchmarks. Every row is one laptop. Other games, scenes, drivers and machines will give other numbers.

What helps, in order

  1. Give shaders time to compile

    The first visit to an area hitches once; the cache keeps the result. Do not delete the shader cache between sessions. Shader warm-up (compiling ahead of play, headless: 4,515 pipelines in 155 s on the Arc 140T) is in the next release.

  2. Use the frame pacing presenter

    The vblank-locked presenter (EDEN_NX2_FLUID=1, experimental) puts every shown frame on a 16.7 ms slot. To measure your own pacing, set EDEN_NX2_SHOWN_STATS=1: every 10 s the log reports the share of intervals within 2 ms of the median. All switches.

  3. Leave the read-back switches alone

    Guest reads of GPU-written memory (read-backs) are a known cost and an open win. Do not force buffer downloads on (EDEN_NX2_BUFFER_DOWNLOADS=1): the note in the shipped switches file says it costs about 38-63% of fps. EDEN_NX2_NO_REACTIVE=1 is opt-in and its note says it can reduce fps from 29 to 24 in another game.

  4. Power

    Plug in. Our numbers are with the charger connected. Use your device’s highest performance mode, and close other programs, because the GPU shares memory and a power budget with the CPU. EDEN_NX2_POWER_POLICY=igpu (Windows, integrated GPUs) shifts the power budget from CPU boost to the GPU and restores it at exit. Leave it off for Ocarina of Time: the game is CPU-bound on these laptops, and the old setup that used it stuttered more (37-92 stutters per 30 s against 19 without it, together with the other changes on this page).

  5. Memory

    On 16 GB, enlarge the Windows page file and close other programs. Shader builds can fail with out-of-memory errors otherwise. Troubleshooting.

Black screen or crash

  • Install a current stable graphics driver. Our Intel numbers use 32.0.101.9175. Results change between driver versions, so put yours in every report.
  • On Intel, the driver can crash while the pipeline cache is saved during shader builds. This is a known driver issue with a fix in progress; the troubleshooting entry has a workaround to try.
  • Other emulators in this family have open black-screen and crash reports on AMD and Linux. Guarana has not measured those; send a report if you hit one.
  • Report with the Host crash: line from the log. Never attach keys, firmware, game files, saves, shader caches, or logs that show your user name or paths.

Questions people ask

Why does my Switch 2 emulator stutter the first time I enter an area?

The graphics driver is compiling the shaders that area needs, about 0.4 to 1 s per pipeline on Intel's driver. Compiled pipelines are cached, so the second visit is smoother. A headless warm-up compiled 4,515 pipelines in 155 s on our laptop, and it ships in the next release.

Why is motion uneven even when the fps number looks fine?

Average fps hides uneven frame times. With frame generation, each shown frame should stay up for the same 16.7 ms slot on a 60 Hz screen. The old presenter spaced frames on the CPU clock. The vblank-locked presenter put 100% of frames within 2 ms of the median on the title screen and 75% in Hyrule Field, against 33-54% before. It ships in the next release.

How many stutters did the fixes remove?

In the same scene on our test laptop, 37-92 stutters per 30 s on the old setup against 19 with v21, a development build that is not released yet. A stutter here means a frame interval longer than twice the median. One laptop, one scene.

Why is my game fps low in Hyrule Field?

Hyrule Field is the scene we measured it in. One shader fix, EDEN_NX2_GM=11, took it from 14.8 to 22.8 game fps with frame generation off, and the foliage draw from 15.7 ms to 5.8 ms of GPU time. It is on by default for Ocarina of Time only.

Does a black screen or a crash have a quick fix?

Update your graphics driver first and make sure the page file is large enough, because shader builds need a lot of memory. On Intel, a driver pipeline-cache crash has a fix in progress. Whatever the cause, send the Host crash line from the log and your driver version, never the whole log if it shows your user name or paths.

Which settings make stutter worse?

Forcing buffer downloads on. The note in the shipped switches file says it copies back 90-220 MB/s of buffers the CPU never touches and drops fps by about 38-63%. Leave EDEN_NX2_BUFFER_DOWNLOADS unset.

Play it, then help it get better

Guarana is free and open source (GPL-3.0-or-later). It ships no keys, firmware or games: you bring your own, dumped from hardware you own.

  • Download: the latest release is the only official download.
  • Stuck? Ask in the Discord (bugs and device reports stay on GitHub so they are tracked).
  • Test: a device report needs no code and puts your device on the leaderboard.
  • Contribute with your AI agent: one sentence gets Claude Code, Codex, Gemini CLI, Cursor or Copilot to a pull request. Start at the agents page, or see open wins with numbers.

Updated 2026-11-13. Home · FAQ · Benchmarks · Legal