Skip to content

Releases

Guarana nightly 2026-11-22 (0aa1d2d)

Pre-release

Choose a tag to compare

@github-actions github-actions released this 22 Nov 04:37
0aa1d2d

Automatic build of main at 0aa1d2d (2026-11-22 03:29 UTC).

Not a release. Nightly builds change every day and can break. Report problems with the commit above.

Changes since the previous nightly

  • deps: update cpp-httplib to 0.66.0 for its security fixes (c5dc5bf)
  • deps: update xxHash to 0.8.4 (5184cac)
  • deps: update Catch2 to 3.16.1 (5e748d8)
  • deps: update Vulkan-Headers and Utility-Libraries to 1.4.368 (459b5d4)
  • launcher: start every build that knows it in a launcher session (9a7bf0d)
  • launcher: hide while the game plays, come back when it stops (36f2ee2)
  • launcher: set the mode in one place, not beside the settings page's (0f7bba5)
  • frontend: hand Help > Check for Updates to the launcher (34ce79d)
  • android: list NUP games in the library (10fcb41)
  • bench: compare a run with the one that drew the same output size (38a200c)
  • site: a download chooser that matches what was published (97f7639)
  • vulkan: record warm direct draws on an ordered GPU follower (#2319) (41119ac)
  • List game-directory titles in HOME Menu as virtual forwarders (#2148) (15f5ada)
  • nx2: hold an unpaced frame-rate-unlocked game to 240 fps (#2178) (75832a4)
  • Ocarina: round up the physics solver's steps with FPS Unlock (#2179) (f65e123)
  • texture_cache: collect a host spill as at the critical threshold, not as out of memory (#2167) (be37029)
  • common: record unloaded modules in the crash minidump (#2177) (58a0672)
  • video_core: honor declared sizes of native NVN storage descriptors (#2262) (df46b37)
  • texture_cache: honor the Maxwell GOB hint for BC7 textures (#2305) (9f0d969)
  • video_core: sleep while the GPU front waits for ring space or the idle hook (#2237) (94caf4d)
  • video_core: park the GPU front while a command list copy finishes (#2247) (4a3dbf6)
  • service: wake host waiters when a service registers (#2250) (fd54370)
  • vulkan: cap legacy AMD driver pipeline workers at two (#2311) (118a52a)
  • spirv: keep single-candidate routes in NVIDIA compute (#2291) (d62a361)
  • hid: set Single assignment for newly added lone Joy-Cons (#2292) (00b28d5)
  • [AIO only] Ocarina: add an opt-in texture heap compaction interval (#2323) (95c469b)
  • tests: lock EmitMeshPrologue payload and primitive-count stores (#2117) (1e89206)
  • tests: serve one BCAT package where a check expects Unchanged (#2285) (01fe4e3)
  • common/range_map: look up each end of a Map once instead of twice (#1858) (c6dd1d0)
  • ci: build macOS against the OpenSSL Homebrew installs (#2309) (50e903e)
  • Shader recompiler: iterative TrackAddend (#2301) (19dcffe)
  • textures: swizzle 16-byte units GOB by GOB (#1898) (3f7cb26)
  • acc: only treat user ID folders as orphaned profiles (#2265) (68caf5a)
  • nx2: run the Duskbloods network test a frame ahead by default (#2288) (75c3f06)
  • nx2: accept page-aligned format-2 window images (#2304) (2ba129f)
  • common: read the HDR state through a new DXGI factory each time (#2176) (5abc27a)
  • kernel: expand Xenoblade 2 Switch 2 alias space (#2327) (3e124c2)
  • qt: show bundled NUP updates in Add-Ons (#2326) (67f1028)
  • vulkan: clamp texel buffer views and contain creation failures (#2296) (5dbd2a7)
  • shader: search StorageBufferAddr lists with a predicate (MSVC 14.51 build, #1420) (#1763) (d083ed3)
  • Add an opt-in to skip Switch 2 mesh draws with pending pipelines (#2289) (86b9e57)
  • memory: throttle unmapped-write logging like the read side (#2151) (528dae4)
  • tests: make the system data font and version test's services on the heap (#2219) (25cbaeb)
  • vulkan: recognize core Vulkan 1.2 buffer device address for FSR 4 on RADV (#1540) (77ecf75)
  • frontend_common: save play times on destruction only from an instance that changed them (#1971) (9ff4c75)
  • tests: give each test's temporary folder a name of its own (#2294) (b95a089)
  • nextendo: don't save a sign-in for a profile cleared while it ran (#2217) (5b9507b)
  • tests: make the keys install tests forget the keys they load (#2283) (41acf9f)
  • common, file_sys: don't pass null pointers to memcpy (#2282) (1d142cc)
  • contributing: 100x the on-ramp (6231672)
  • Merge main (legacy-marker fix) into contributing on-ramp (4a6a9ef)
  • Merge main (canonical hall-of-fame regeneration) (30c0731)
  • Merge remote-tracking branch 'lichii/nx2' into merge/upstream-20261120-b (6be66f1)
  • Merge main (v20.7.1 platform fixes + hall-of-fame regen) into the nx2 sync (9205558)
  • changelog: nx2 sync to 1d142cc fragment (84195a4)
  • docs: Hall of fame from the git history (a2cd7e5)
  • feat(cli): JSON harness for guarana-cli + debug RPC (CLI-Anything trial) (031c329)
  • feat(launcher): ARM64-native assets, resumable downloads, version auto-prune, crisp iGPU pacing (4a28f6f)
  • fix(video_core): repair the nx2 merge seams in the graphics pipeline bind path (83faba2)
  • fix(video_core): binding.rescaling push constants and the stage-set byte cast (e87e464)
  • fix(video_core): close LogPrepassRefusal before the direct-draw helpers (d65aa0c)
  • fix(tests): the TryTakeReady test calls the sized ScheduledPrebuild::Add (061a633)
  • fix(core): drop the duplicated anonymous-namespace closer in patch_manager (f67f7eb)
  • fix(core/tests): restore anonymous-namespace boundary before BuiltinPatchRanges; align gpu_trace no-presents test with merged Reader/TempDir API (058af9b)
  • buffer_cache: stop protecting pages the CPU rewrites each frame (switch) (5afd7e3)
  • docs: readback lever classification + evidence (1028/read-traps covered, hot-pages ported) (899de5c)
  • fix(core): give the internal 4-arg FindBuiltinCheatOverlaps internal linkage (0847017)
  • fix(core): restore the built-in hook placement loop dropped by the nx2 sync (92691eb)
  • Merge pull request #313 from karimalsalah/feat/readback-annihilation (22f4357)
  • Merge pull request #264 from karimalsalah/deps/httplib (bb06ab2)
  • Merge pull request #270 from karimalsalah/deps/xxhash (605ced6)
  • Merge pull request #271 from karimalsalah/deps/catch2 (ff0ce0c)
  • Merge pull request #273 from karimalsalah/deps/vulkan-headers (1984dc3)
  • Merge pull request #292 from karimalsalah/capy/list-nup-games-in (0ea05ef)
  • Merge pull request #310 from karimalsalah/feat/cli-json-harness (09de12b)
  • Merge pull request #311 from karimalsalah/feat/installer-100x (2627142)
  • Merge pull request #287 from karimalsalah/feat/updates-handoff (2e3d814)
  • Merge pull request #286 from karimalsalah/feat/one-place-per-setting (5d68963)
  • Merge pull request #307 from karimalsalah/merge/upstream-20261120-b (638b981)
  • feat(jit): inline the A64 guest counter on x64 (Lichii #2315 port) (a2e83b9)
  • release: v20.7.2 (e2dab5d)
  • feat(android): S25 Ultra performance booster (wake lock + ADPF + Adreno OoT preset) (e32a7c8)
  • Merge pull request #294 from karimalsalah/capy/compare-a-run-with (e1e300a)
  • Merge pull request #316 from karimalsalah/feat/jit-inline-counter (fc3a991)
  • Merge pull request #317 from karimalsalah/feat/android-booster (4691fcd)
  • video_core: fix Metal surface build with Vulkan-Headers 1.4.368 (a160514)
  • docs: restore the README on-ramp contract the rewrite dropped (4a087c3)
  • Merge pull request #318 from karimalsalah/fix/macos-metal-layer-const (fa60368)
  • Merge pull request #319 from karimalsalah/fix/readme-onramp-contract (9a59d76)
  • Merge branch 'main' into docs/contributing-onramp-1120 (2baed64)
  • Merge branch 'main' into bot/legacy (6047000)
  • Merge pull request #306 from karimalsalah/docs/contributing-onramp-1120 (6628e34)
  • Merge pull request #309 from karimalsalah/bot/legacy (4c93bc6)
  • vulkan: snapshot descriptors for deferred stage-set draws (1632093)
  • vulkan: keep stage-set draws on the direct record path (f8aca6c)
  • Merge pull request #322 from karimalsalah/fix/deferred-stage-set-binding (275cb9f)
  • Merge pull request #293 from karimalsalah/capy/a-download-chooser-that (67e9756)
  • Merge pull request #279 from karimalsalah/feat/launcher-hides-while-playing (50e456c)
  • Merge pull request #276 from karimalsalah/feat/launcher-session-by-build (0aa1d2d)

Thanks to @danieljesus, @GoatTech-42, @goof787lord, @karimalsalah, @kraibse, @RomainROCH, @the-cashman, @tomvita, @zortos293, Frizti and Mcm190.

Changelog entries not yet in a release

Added

  • Android: performance booster for Snapdragon 8 Elite / Galaxy S25 Ultra (Adreno 830) — a partial wake lock held during emulation, an ADPF PerformanceHintManager session targeting 120 fps (8.33 ms) that reports actual frame work and throttles to 60/30 fps on thermal pressure, and a conservative Qualcomm OoT preset. WAKE_LOCK permission added; existing foreground-service/game-mode manifest unchanged.

Changed

  • CONTRIBUTING: a find-work label guide with live issue queues, hand-build pointers
    (Build.md, Deps.md), the changelog fragment format at a glance, and what happens after
    a device report is submitted.
  • Inline the A64 guest counter (CNTPCT) read on x64 when EDEN_NX2_JIT_INLINE_CNTPCT=1, porting Lichii #2315 (Frizti). Avoids the GetCNTPCT HLE round-trip for counter-poll-heavy titles such as Ocarina of Time; opt-in, default off.
  • Launcher: while a game plays the launcher's window hides, so the game is the one window, Alt+Tab
    entry and taskbar button; it comes back to the front when the game exits, as before. It hides at
    the game's first frame (for builds without a launcher session, when the game's window takes the
    foreground), so the loading progress stays reachable until then and a load error before the game
    starts leaves the launcher where it was. Starting the launcher again shows it at any time.

Fixed

  • Benchmark comparisons match windowed or fullscreen runs at the same output size, so running
    at a lower resolution no longer looks like a speedup. The results page keeps both sizes.
  • Fixed a deterministic GPU-render-thread crash (access violation in the descriptor dedup memcmp) on draws whose graphics pipeline uses per-stage descriptor sets: the deferred draw preparation now snapshots their descriptor entries, which RecordBinding reads at the stage offsets.
  • Launcher: nightlies and ...
Read more

Guarana v20.7.2

Choose a tag to compare

@github-actions github-actions released this 21 Nov 23:32

Added

  • Add tools/cli-harness: a machine-readable JSON harness around guarana-cli and the nx2 debug RPC (status/switches/bench/screenshot/launch/log-tail/input/rpc/warm-pipelines/nup-pack/nup-unpack/version), with a draft agent SKILL.md and 18 standard-library unit tests (CLI-Anything trial).
  • EDEN_NX2_HOT_PAGES (experimental, off): guest pages the CPU rewrites every frame stay
    unprotected and are uploaded at most once a frame, instead of being write-protected after each
    upload and faulting on the next write. Ported from Eglantine (f27522bfb9), where Ocarina of
    Time's frame went from 25.9 to 24.7 ms.
  • The launcher now downloads the native Windows ARM64 build on ARM64 PCs (it sees through x64 emulation), and falls back to the x86_64 build when a release has no ARM64 asset.
  • Old installed versions are pruned automatically after an install, keeping the current version and the two newest others, and the Updates screen gained a "Clean up old versions" button (prune_versions).
  • Help > Check for Updates in the emulator (Windows) opens the Guarana launcher's Updates screen,
    which checks for an update and installs it, so there is one updater, the launcher's
    (#44). The menu item goes through a new
    guarana://updates link (optionally ?channel=stable or ?channel=nightly), which only shows
    the screen and never installs by itself. Without the launcher installed it opens the releases
    page.

Changed

  • Tests: Catch2 3.16.1, up from 3.13.0.
  • Install downloads resume from the bytes already on disk after an interruption and retry up to three times; the finished file is still checked against the release's SHA-256 before anything is unpacked.
  • Upstream nx2 sync to 1d142cc (38 commits): warm direct draws recorded on an ordered GPU
    follower (#2319), unpaced FPS-unlocked games held to 240 fps (#2178), OoT physics solver steps
    rounded up with FPS Unlock (#2179), host VRAM spill collected at the critical threshold instead
    of OOM (#2167), unloaded modules recorded in the crash minidump (#2177), native NVN storage
    descriptor sizes honored (#2262), Maxwell GOB hint for BC7 textures (#2305), service waiters
    woken on registration (#2250), legacy AMD driver pipeline workers capped at two (#2311),
    single-candidate NVIDIA compute routes kept (#2291), lone Joy-Con assignment fix (#2292),
    game-directory titles listed in the HOME Menu as virtual forwarders (#2148), and more.
  • Vulkan-Headers and Vulkan-Utility-Libraries 1.4.368, up from 1.4.345: newer extension
    definitions for future work. No renderer behaviour changes.
  • xxHash 0.8.4, up from 0.8.3, for the shader cache v2 and GPU trace checksums. Hash values are
    unchanged; arm64 builds use NEON instead of SVE for XXH3.

Fixed

  • Android: folder scans and Open With now recognize .nup games. NUPs in configured content
    folders are also considered for add-ons, and the library uses the version in a container's own
    control data when no installed metadata is available. Thanks to Webmaster-25
    (Lichii #1150)
    and Aidan Kinzett
    (Eglantine #383)
    .
  • Integrated-GPU profiles now default to crisp repeated real frames at even 120 Hz pacing (EDEN_NX2_FLUID_INTERP=0, CADENCE=3, SHOWN_RATE=120) instead of interpolated in-betweens, which ghost every moving edge at low real fps; a new "Interpolated in-betweens" toggle turns prediction back on for GPUs that hold 60+ real fps.
  • Launcher: the mode is set in one place. When the launcher applies a mode (at every Play, and
    Advanced > Apply), it removes the mode block the emulator's own Guarana settings page wrote into
    nx2_switches.txt and sets that page back to Custom. The two blocks used to mix: the page's Smooth
    added frame-pacing lines under the launcher's mode, its Battery added a second autopilot, and its
    EDEN_NX2_EXTRAPOLATE=1 survived on Intel integrated GPUs where the launcher leaves that line to
    the emulator (#119). A hand-made profile
    (Custom in the launcher) leaves the page's block as it is.

Security

  • Network: cpp-httplib 0.66.0, up from 0.46.0, for the updater, the DLSS and FSR4 runtime
    downloads, icon search and the Nextendo sign-in. It brings the security fixes of 18 releases,
    among them one that sent the Cookie header on to another host after a redirect
    (GHSA-22mf-w2v3-r2jv).

Thanks to @danieljesus, @GoatTech-42, @goof787lord, @karimalsalah, @kraibse, @RomainROCH, @the-cashman, @tomvita, @zortos293, Frizti and Mcm190.

Downloads

Platform Standard PGO (recommended)
Windows x86_64 zip zip
Linux x86_64 AppImage · tar.gz AppImage · tar.gz
Linux aarch64 AppImage · tar.gz AppImage · tar.gz
macOS arm64
Windows ARM64 (Snapdragon X) zip
Android arm64 (13 or newer) apk

Windows on ARM (Snapdragon X laptops): guarana-20.7.2-windows-arm64.zip is a native ARM64 build without PGO. Nobody on the project has booted it on a device yet: please tell us how it runs with a device report.

Android (Snapdragon handhelds and phones, Android 13 or newer): open guarana-20.7.2-android-arm64.apk on the device to install it. Nobody on the project has booted it on a device yet: please tell us how it runs with a device report.

  • Windows: extract the whole zip into a folder you can write to and run guarana.exe (guarana-cli.exe from a terminal). Both are clang-cl ThinLTO builds; the PGO zip adds a profile trained on Ocarina of Time, so other games gain less.
  • Linux: make the AppImage executable (chmod +x) and run it. The tar.gz holds the same files for systems without FUSE: extract it and run guarana/guarana. Both need glibc 2.39 or newer. The PGO builds use clang with Eglantine's profile.
  • macOS 15 or newer, Apple Silicon. Not notarized: right-click and choose Open the first time, or run xattr -dr com.apple.quarantine guarana.app.
  • Checksums: SHA256SUMS.txt. Check with sha256sum -c SHA256SUMS.txt (Linux), shasum -a 256 -c SHA256SUMS.txt (macOS) or Get-FileHash <file> (PowerShell).
  • Provenance: every file has a signed build provenance attestation; check a download with gh attestation verify <file> --repo karimalsalah/guarana. Signatures and the other checks: docs/SIGNING.md.

No keys, firmware or games are included or provided. Dump your own from hardware you own; see LEGAL.md.

Built by the Guarana project — github.com/karimalsalah/guarana (yuzu → Eden → Eglantine → Lichii lineage, GPL-3.0-or-later).

Guarana v20.7.1

Choose a tag to compare

@github-actions github-actions released this 21 Nov 17:51

Fixed

  • Windows ARM64 release builds link again: the Switch 2 BLE WinRT code now compiles against the
    exact C++/WinRT version the Qt arm64 package was built with (2.0.250303.1, fetched from NuGet),
    instead of the Windows SDK's newer 2.0.250303.5 that lld-link's /failifmismatch rejects.
  • macOS release builds no longer fail when the runner's freetype bottle still links
    libhvf.dylib (which macOS 15.0-15.3 lack): freetype is rebuilt from source on the runner.

Thanks to @karimalsalah.

Downloads

Platform Standard PGO (recommended)
Windows x86_64 zip zip
Linux x86_64 AppImage · tar.gz AppImage · tar.gz
Linux aarch64 AppImage · tar.gz AppImage · tar.gz
macOS arm64 zip · dmg
Windows ARM64 (Snapdragon X) zip
Android arm64 (13 or newer) apk

Windows on ARM (Snapdragon X laptops): guarana-20.7.1-windows-arm64.zip is a native ARM64 build without PGO. Nobody on the project has booted it on a device yet: please tell us how it runs with a device report.

Android (Snapdragon handhelds and phones, Android 13 or newer): open guarana-20.7.1-android-arm64.apk on the device to install it. Nobody on the project has booted it on a device yet: please tell us how it runs with a device report.

  • Windows: extract the whole zip into a folder you can write to and run guarana.exe (guarana-cli.exe from a terminal). Both are clang-cl ThinLTO builds; the PGO zip adds a profile trained on Ocarina of Time, so other games gain less.
  • Linux: make the AppImage executable (chmod +x) and run it. The tar.gz holds the same files for systems without FUSE: extract it and run guarana/guarana. Both need glibc 2.39 or newer. The PGO builds use clang with Eglantine's profile.
  • macOS 15 or newer, Apple Silicon. Not notarized: right-click and choose Open the first time, or run xattr -dr com.apple.quarantine guarana.app.
  • Checksums: SHA256SUMS.txt. Check with sha256sum -c SHA256SUMS.txt (Linux), shasum -a 256 -c SHA256SUMS.txt (macOS) or Get-FileHash <file> (PowerShell).
  • Provenance: every file has a signed build provenance attestation; check a download with gh attestation verify <file> --repo karimalsalah/guarana. Signatures and the other checks: docs/SIGNING.md.

No keys, firmware or games are included or provided. Dump your own from hardware you own; see LEGAL.md.

Built by the Guarana project — github.com/karimalsalah/guarana (yuzu → Eden → Eglantine → Lichii lineage, GPL-3.0-or-later).

Guarana v20.7.0

Choose a tag to compare

@github-actions github-actions released this 20 Nov 19:34

Guarana v20.7.0 — the Switch 2 OoT remake, on the laptop you already own

The headline: the 2026 Nintendo Switch 2 remake of Ocarina of Time boots and plays in Guarana on an Intel Arc 140T laptop iGPU — the same title that current Eden and Citron builds cannot boot at all. Open source, Lichii/yuzu lineage, Windows/Linux/macOS/Android, x64 + ARM64.

What's in this release

  • Upstream nx2 sync (31 commits) — including the OoT FPS-unlock correctness series: Deku Tree web fractional steps (softlock fix), day/night clock carry, Epona fence-jump animation, cloth step below 60 fps.
  • OoT tonemap bypass fix (#275) — restores the correct source image on the Intel no-sharpening path (measured PSNR 29.9 → 36.0 dB).
  • Microphone open gate (#249) — no more crash when a game opens a mic that isn't there.
  • Eden ports — async-guard, F2I and friends (#290/#283/#278/#281), Android nightly identity, dependabot group updates.
  • Honest README rewrite — every claim carries its machine, its scene and its measurement.

Measured on this project's laptop (Core Ultra 9 285H, Arc 140T, driver 32.0.101.9175)

Scene-gated A/B, same save, same config, Lon Lon Ranch gameplay (paired runs, vision-verified frames, debug-RPC frame telemetry):

v20.6-era baseline v20.7.0
Real fps (tuned 120 Hz mode) 20.0 20.0–22.0
Frame pacing p99 59.5 ms 52.5 ms
Worst frame 97.5 ms 53.3 ms
Stutters / 30 s 0 0
Render edge ghosting + halo + washed terrain cleaner; crisp with EDEN_NX2_FLUID_INTERP=0

New default for iGPUs: EDEN_NX2_FLUID_INTERP=0 — crisp repeated real frames at even 120 Hz pacing. Predicted in-betweens ghost at ~20 real fps; re-enable interpolation on GPUs that sustain 60+ real fps. The 20 real fps figure is this iGPU's honest sustain, not a cap — stronger GPUs scale up, and every number we publish names its machine.

Downloads

Windows x64 (±PGO), Linux x64/arm64 (±PGO), macOS arm64, Android arm64 APK. Windows ARM64 and the macOS fix land in v20.7.1 (both release builds were blocked by toolchain issues now fixed: cppwinrt version alignment for Qt arm64, freetype source-build fallback for macOS 15.0–15.3).

SHA256SUMS + build provenance attached. BYO keys/firmware/games — nothing copyrighted ships here.

Test it on YOUR machine (5 minutes, no code)

We have exactly one tested device so far. That's the honest number, and it's why this release asks:
Fill the device-report form — your GPU, your scene, your fps. Every report becomes a row in the device matrix. Radeon handhelds, RTX laptops, Snapdragon X, Steam Deck — we want your numbers.

Credits

Lichii/nx2 upstream (zortos293), Frizti/Fritchii and Eglantine community fixes, Eden ports, and the yuzu/ryujinx lineage this project stands on. Full list in docs/CREDITS.md.

Full changelog below.

Added

  • EDEN_NX2_ASYNC_GUARD (experimental, off): with asynchronous shaders, draws that write memory,
    use transform feedback, rasterize nothing or render into a small target wait for their pipeline
    instead of being skipped, so effects later draws depend on are not lost until a restart. From
    Eden (6a767ac43a).
  • EDEN_NX2_F2I_ABS_NEG (experimental, off): F2I's absolute value and negation modifiers are
    decoded the right way round, a shader fix Eden made for Disco Elysium
    (Eden 6e24dcb4b5).

Changed

  • Bump the launcher cargo group: sysinfo 0.40.1 to 0.40.3 and zip 9.4.1 to 9.5.1.
  • Bump actions/checkout from 5 to 7 in the bench-rows and switch-registry workflows.
  • Windows: the launcher and a game it starts are one app to Windows. In a launcher session the
    emulator takes the launcher's AppUserModelID (the one on its Start menu shortcut), and the
    launcher sets it for itself also when it starts from a game file or a link. They share one taskbar
    button, and pinning the game's button pins the launcher instead of guarana.exe.
  • Bump rfd from 0.17.2 to 0.18.0 in the launcher.
  • Bump actions/setup-java from 4 to 5 in the Android workflow.
  • Upstream sync (zortos293/Lichii nx2 to 6708d24, 31 commits): Ocarina of Time FPS Unlock
    carry fixes — cloth below 60 fps, Epona's fence jump, fractional day/night seconds and Deku
    web steps; nvdrv small-GPFIFO-submit allocation churn; texture cache recovery from failed
    host scratch allocations and bounded descriptor lookups; Vulkan borrows a cached sampler
    when the driver refuses allocation; core_timing drops due events whose owner expired;
    Windows zero-page unlocks capped at 1 MiB; sysmix purges output streams too (Xenoblade DE
    docked/handheld crash); Yoshi 2.0.0 full-scene-resolution FXAA option; macOS bundle ships
    nx2_switches.txt in Resources; scratch HOME profile state; ARM64 NCE validation and
    Dynarmic defaults. Text speed stays the shipped JSON pack; Guarana's shutdown telemetry,
    portable switch loading and built-in metadata are kept across the new upstream code.
  • Bump vite from 8.3.6 to 8.3.8 in the launcher UI.

Fixed

  • Android nightlies install beside the stable app instead of updating it. The APK build checks the packaged app ID before uploading it, and the upstream update checker stays off on both channels.
  • A game the launcher starts no longer opens the debug console (when "Show Log in Console" is on in
    Configure > Debug) or the What's New dialog after an update: the game is the one window, and the
    launcher's Updates screen has the notes. Creating a folder link on Windows (the Link choice of the
    data import, Link to Ryujinx) no longer flashes a console window.
  • Audio: while Windows' microphone prompt is unanswered, capture streams wait for the one open
    already waiting instead of starting one each, and the SDL backend opens the microphone on the
    calling thread again, so a stuck open cannot hold SDL's next playback open
    (#199).
  • Ocarina of Time with No sharpening, the default on Intel integrated GPUs: the picture is no
    longer hazier and flatter than in v20.4.0. Since v20.5.0's upstream merge the bypass copied the
    image the network's output pass samples, which on Hyrule Field is not the tonemapped picture
    (26 dB from the network's own output, against 32 dB). It copies the tonemap drawn that frame
    again, and the sampled image only when no known tonemap was drawn (Lichii #1688's case).

Guarana v20.6.0

Choose a tag to compare

@github-actions github-actions released this 18 Nov 21:53

Added

  • Android: release and nightly builds include guarana-<version>-android-arm64.apk (Android 13 or
    newer): the app under Guarana's own id, io.github.karimalsalah.guarana, which reads the player's
    nx2_switches.txt from its user folder as the desktop builds do. Until the release key is set up
    (docs/SIGNING.md, "Android") it is a preview build,
    io.github.karimalsalah.guarana.preview. Nobody on the project has booted it on a device yet.
  • docs/ARM64.md: Guarana on Snapdragon X laptops and Android handhelds: what runs
    where, how CI builds the Windows ARM64 and Android packages, what the renderer needs from Adreno
    drivers (mesh shaders above all), the expected gains, and the call for testers.
  • Issue forms for ARM64 testers: Snapdragon X laptops (Adreno X1 / X2) and Android devices (Adreno
    6xx to 8xx, other Android GPUs) in every "Graphics card" list, "Windows 11 on ARM" and "Android" in
    the operating system lists, and "Phone or tablet" as a device report form factor. New issues get the
    QUALCOMM, arm64 and android labels, and the benchmarks page filters reports by Qualcomm GPUs
    and by phones and tablets.
  • EDEN_NX2_ASYNC_DISCARD=2 (experimental, off): with asynchronous shaders, a native draw whose
    pipeline is still building is skipped only when it draws into render targets the game clears
    and redraws every frame, and waits otherwise, so title text, chat bubbles and lighting drawn
    once are not lost on an empty shader cache. Ported from Fritchii (a962f20533).
  • Benchmark: boot suites. tools/bench/suites/console-boot.json measures launch to gameplay and
    first-visit hitches in one command, every boot and shader switch against the baseline with a
    cold, a second and a warm shader cache (and the GPU driver's cache with --driver-cache-dir),
    three times; each row has the boot phases, the held draws and builds to the scene and the
    stutter frames, and is invalid when its cache was not in the state it claims
    (docs/console-boot.md).
  • Device reports: each report gets the engine's GPU family (Arrow Lake-H, Lunar Lake, Radeon 780M,
    Steam Deck LCD and the others) when it names its GPU exactly, and the new
    site/data/community-evidence.json counts reports and devices per family, game and build, with
    the effects that paired tools/bench rows measured. Nothing reads it to change a default yet
    (#24).
  • Experimental EDEN_NX2_DLSS_SKIP_PASSES (ports of zortos293/Lichii#864 and #1985): a game's own
    DLSS network passes are skipped while a replacement upscale draws over their output (drew) or
    while the network cannot be shown (blocked). Off by default; upstream measured The Duskbloods
    on a Steam Deck at 56.6 to 40.4 ms of GPU time a frame.
  • Experimental EDEN_NX2_FG_GAME_MOTION: with EDEN_NX2_FLUID_INTERP, in-between frames are
    warped from the game's motion (Ocarina of Time's motion guide: the camera from the scene depth,
    and Link) instead of optical flow, and what one real frame no longer shows is filled from the
    other by depth. Off by default and not measured yet; tools/bench/suites/game-motion-fg.json
    measures it against the optical-flow interpolation the game ships with at 120 Hz.
  • Design for the game's own reconstruction network and motion on integrated GPUs
    (docs/design/game-reconstruction-and-motion.md), and the bench suite of its first step:
    tools/bench/suites/game-network.json measures Ocarina of Time's anti-aliasing network with
    each existing way of running its tensor instructions (software, the shared-memory gather,
    Intel's 8x16x16 cooperative matrices), with the game presets off so the network actually runs.
  • Experimental EDEN_NX2_INTEL_COOP_MATRIX_8X8: the game's tensor networks on the Arc 140T's own
    cooperative matrices (8x8x16 with fp32 accumulators, the only fp16 shape its driver lists), two
    products per guest HMMA through shared memory, rounded to fp16 once. Off by default, not measured
    and not yet run on the hardware; tools/bench/suites/game-network-a1b.json measures it.
  • Experimental switches for the game's own tensor networks on matrix units that go through shared
    memory (AMD's 16x16x16, Intel's 8x16x16): EDEN_NX2_HMMA_ZERO_C starts an HMMA whose accumulator
    is zero from a zero matrix instead of a stored C tile (bit-exact), and EDEN_NX2_HMMA_K16_ONCE
    runs a K=16 HMMA as one 8x16x16 product per row half, rounding once. The diagnostic
    EDEN_NX2_TENSOR_LOG logs each tensor program's HMMA counts and the path they take, and
    tools/bench/suites/game-network-a1.json measures the two switches on Ocarina of Time. All off by
    default and not measured yet.
  • Debug server input_latency: holds a right-stick step and times, from when the game first
    reads it, the first shown frame whose picture moved (generated frames included) and the first
    real one, so frame generation's input latency can be measured against no generation.
  • EDEN_NX2_INTEL_COMPUTE_SIMD16 (experimental, off): on Intel GPUs, compute shaders without warp
    operations can be built at 16 lanes, which built Ocarina of Time's large global-memory programs
    about 2.6 times faster on an Arc B580 at the cost of some frame rate. From Fritchii-Intel-Fixes
    (patch 0011).
  • EDEN_NX2_LOAD_SAVE=1 (experimental, off by default): on Intel's Windows driver the boot load
    saves the driver pipeline cache once its builds have ended and starts the background prebuild
    after it, so a crash or kill later in the session no longer loses that boot's driver builds
    (port of Lichii #1838; step B6 of
    docs/console-boot.md).
  • EDEN_NX2_IR_POOL_CAP_MIB (experimental, off): the shader recompiler's object pools free
    their memory after a shader once it passes the cap instead of keeping their largest shader's
    worth, which can return host RAM an integrated GPU shares. Ported from Fritchii (c99790b878).
  • EDEN_NX2_NCE_REPORT=1 (diagnostic): one log line per module a game loads, on any host, with
    what native code execution (NCE) on ARM64 hosts would rewrite and which system registers it
    would leave to the host CPU, so Switch 2 titles can be checked for NCE without an ARM64 device.
    docs/NCE.md has the plan for NCE on Linux ARM64, Android, Windows on ARM and macOS.
  • Performance overlay: a memory row with the RAM Guarana holds and the RAM the PC has free, and the
    GPU memory it uses with the room the driver still gives it, amber when either runs low. On an
    integrated GPU the GPU memory is marked shared and its room is bounded by the free RAM. Ported
    from Fritchii (Frizti/Fritchii 58f55cb7d9, 8627ff4233).
  • Built-in patches can be data: a patch pack (dist/patch-packs/*.json, see
    docs/patch-packs.md) adds built-in add-ons for any game without C++.
    They are checked as the compiled-in ones are: build id, the game's original bytes (by
    SHA-256), code caves in executable padding, zero-filled state, user mods first. Ocarina of
    Time's three Text Speed add-ons are the first pack and work as before. The packs ship in a
    patch-packs folder next to the program and are compiled into it as well, so Android and a
    program without the folder keep them; a file in the folder replaces the compiled-in copy of its
    name. The unit tests reject a pack with a field the format does not have, a patch without a
    description, or bytes another built-in writes.
  • Presenter telemetry for pacing A/Bs (#8):
    a Present setup line at each swapchain creation names the window's display and its refresh
    rate, the present mode and image count, EDEN_NX2_FLUID and Windows' hardware-accelerated GPU
    scheduling; EDEN_NX2_SHOWN_STATS also counts the intervals between presents in refreshes
    (under one, one, two, three or more) and the refreshes missed against the median; the
    diagnostic EDEN_NX2_PRESENT_MODE=immediate|fifo|fifo_relaxed|mailbox asks for one present
    mode, falling back with a warning when the surface lacks it; and
    tools/bench/suites/presenter-ab.json runs FIFO against IMMEDIATE with frame generation off
    and on.
  • GPU trace bench: on a driver that does not replay bit for bit (Intel's Windows driver), the
    baseline's own run-to-run difference becomes a noise floor, and a variant within it is reported
    as within noise instead of failing the comparison (trace_replay.py bench --noise-margin).
  • Device reports name the GPU's PCI ID: tools/bench rows record it (hardware.gpus[].pci, from
    Windows' PNP device ID or lspci -nn), and the launcher's "Share my numbers" writes it after the
    GPU's name. The report bot uses it for the engine's GPU family, so Meteor Lake and Panther Lake
    GPUs that their drivers name only "Intel Graphics" count for their family
    (#24).
  • The boot Resolution: line and the debug server's status.resolution cite the community's paired
    tools/bench measurements (site/data/community-evidence.json, which each build now carries) where
    a preset or switch default sets a value measured on the player's GPU family and game. No value
    changes (#24).
  • EDEN_NX2_SKIP_REDRAWN=1 (experimental, off by default): with asynchronous shaders on, a Switch 2
    draw into a target the game redraws every frame is skipped while its pipeline builds instead of
    stopping the frame (port of Eglantine #874;
    step F4 of docs/console-boot.md).
  • EDEN_NX2_STARTUP_CHECK_ASYNC=1 (experimental, off by default): the startup Vulkan check's child
    process runs while the frontend starts, and the frontend waits for its verdict only before it
    first uses V...
Read more

Guarana v20.5.1

Choose a tag to compare

@github-actions github-actions released this 16 Nov 20:24

Fixed

  • Ocarina of Time with No sharpening, the default on Intel integrated GPUs: the picture is no
    longer hazier and flatter than in v20.4.0. Since v20.5.0's upstream merge the bypass copied the
    image the network's output pass samples, which on Hyrule Field is not the tonemapped picture
    (26 dB from the network's own output, against 32 dB). It copies the tonemap drawn that frame
    again, and the sampled image only when no known tonemap was drawn (Lichii #1688's case).

Thanks to @karimalsalah.

Downloads

Platform Standard PGO (recommended)
Windows x86_64 zip zip
Linux x86_64 AppImage · tar.gz AppImage · tar.gz
Linux aarch64 AppImage · tar.gz AppImage · tar.gz
macOS arm64 zip · dmg
Android arm64 (13 or newer) apk

Android (Snapdragon handhelds and phones, Android 13 or newer): open guarana-20.5.1-android-arm64.apk on the device to install it. Nobody on the project has booted it on a device yet: please tell us how it runs with a device report.

  • Windows: extract the whole zip into a folder you can write to and run guarana.exe (guarana-cli.exe from a terminal). Both are clang-cl ThinLTO builds; the PGO zip adds a profile trained on Ocarina of Time, so other games gain less.
  • Linux: make the AppImage executable (chmod +x) and run it. The tar.gz holds the same files for systems without FUSE: extract it and run guarana/guarana. Both need glibc 2.39 or newer. The PGO builds use clang with Eglantine's profile.
  • macOS 15 or newer, Apple Silicon. Not notarized: right-click and choose Open the first time, or run xattr -dr com.apple.quarantine guarana.app.
  • Checksums: SHA256SUMS.txt. Check with sha256sum -c SHA256SUMS.txt (Linux), shasum -a 256 -c SHA256SUMS.txt (macOS) or Get-FileHash <file> (PowerShell).
  • Provenance: every file has a signed build provenance attestation; check a download with gh attestation verify <file> --repo karimalsalah/guarana. Signatures and the other checks: docs/SIGNING.md.

No keys, firmware or games are included or provided. Dump your own from hardware you own; see LEGAL.md.

Guarana v20.5.0

Choose a tag to compare

@github-actions github-actions released this 16 Nov 19:37

Added

  • Tests: the built-in patch tests fail when two built-in patches that can be applied together
    write, check or keep their state in the same bytes of a game's module: code caves, hooks and
    state blocks. A patch and the one it replaces, and the alternatives of one group, may share
    bytes, because only one of them is applied. The table is read through
    FileSys::BuiltinPatchRanges.
  • Ocarina of Time: three new built-in add-ons, "Text Speed 2x", "Text Speed 4x" and "Text Speed
    Instant", speed up the letters and pauses of dialogue, the fairy's hints and signs. They are
    unchecked by default (Properties > Add-Ons), and with more than one checked the fastest
    applies. A built-in add-on can now be off until it is checked: [DisabledAddOns] then holds
    +<name> for it (Lichii #1422).
  • Android: release and nightly builds include guarana-<version>-android-arm64.apk (Android 13 or
    newer): the app under Guarana's own id, io.github.karimalsalah.guarana, which reads the player's
    nx2_switches.txt from its user folder as the desktop builds do. Until the release key is set up
    (docs/SIGNING.md, "Android") it is a preview build,
    io.github.karimalsalah.guarana.preview. Nobody on the project has booted it on a device yet.
  • docs/ARM64.md: Guarana on Snapdragon X laptops and Android handhelds: what runs
    where, how CI builds the Windows ARM64 and Android packages, what the renderer needs from Adreno
    drivers (mesh shaders above all), the expected gains, and the call for testers.
  • Issue forms for ARM64 testers: Snapdragon X laptops (Adreno X1 / X2) and Android devices (Adreno
    6xx to 8xx, other Android GPUs) in every "Graphics card" list, "Windows 11 on ARM" and "Android" in
    the operating system lists, and "Phone or tablet" as a device report form factor. New issues get the
    QUALCOMM, arm64 and android labels, and the benchmarks page filters reports by Qualcomm GPUs
    and by phones and tablets.
  • Benchmark: boot suites. tools/bench/suites/console-boot.json measures launch to gameplay and
    first-visit hitches in one command, every boot and shader switch against the baseline with a
    cold, a second and a warm shader cache (and the GPU driver's cache with --driver-cache-dir),
    three times; each row has the boot phases, the held draws and builds to the scene and the
    stutter frames, and is invalid when its cache was not in the state it claims
    (docs/console-boot.md).
  • Device reports: each report gets the engine's GPU family (Arrow Lake-H, Lunar Lake, Radeon 780M,
    Steam Deck LCD and the others) when it names its GPU exactly, and the new
    site/data/community-evidence.json counts reports and devices per family, game and build, with
    the effects that paired tools/bench rows measured. Nothing reads it to change a default yet
    (#24).
  • Experimental EDEN_NX2_FG_GAME_MOTION: with EDEN_NX2_FLUID_INTERP, in-between frames are
    warped from the game's motion (Ocarina of Time's motion guide: the camera from the scene depth,
    and Link) instead of optical flow, and what one real frame no longer shows is filled from the
    other by depth. Off by default and not measured yet; tools/bench/suites/game-motion-fg.json
    measures it against the optical-flow interpolation the game ships with at 120 Hz.
  • Design for the game's own reconstruction network and motion on integrated GPUs
    (docs/design/game-reconstruction-and-motion.md), and the bench suite of its first step:
    tools/bench/suites/game-network.json measures Ocarina of Time's anti-aliasing network with
    each existing way of running its tensor instructions (software, the shared-memory gather,
    Intel's 8x16x16 cooperative matrices), with the game presets off so the network actually runs.
  • Experimental switches for the game's own tensor networks on matrix units that go through shared
    memory (AMD's 16x16x16, Intel's 8x16x16): EDEN_NX2_HMMA_ZERO_C starts an HMMA whose accumulator
    is zero from a zero matrix instead of a stored C tile (bit-exact), and EDEN_NX2_HMMA_K16_ONCE
    runs a K=16 HMMA as one 8x16x16 product per row half, rounding once. The diagnostic
    EDEN_NX2_TENSOR_LOG logs each tensor program's HMMA counts and the path they take, and
    tools/bench/suites/game-network-a1.json measures the two switches on Ocarina of Time. All off by
    default and not measured yet.
  • EDEN_NX2_LOAD_SAVE=1 (experimental, off by default): on Intel's Windows driver the boot load
    saves the driver pipeline cache once its builds have ended and starts the background prebuild
    after it, so a crash or kill later in the session no longer loses that boot's driver builds
    (port of Lichii #1838; step B6 of
    docs/console-boot.md).
  • Performance overlay: a memory row with the RAM Guarana holds and the RAM the PC has free, and the
    GPU memory it uses with the room the driver still gives it, amber when either runs low. On an
    integrated GPU the GPU memory is marked shared and its room is bounded by the free RAM. Ported
    from Fritchii (Frizti/Fritchii 58f55cb7d9, 8627ff4233).

Changed

  • Add-Ons: a built-in patch is labelled "Built-in" in the Version column (it was "IPS"), with
    "recommended" or "experimental" where that applies, and listed without "(built-in)" after its
    name. A box under the list says in plain words what the selected built-in does and, once the
    game has been started, whether it was applied. A ticked built-in that was not applied gets a
    warning sign and its reason: made for another version of the game, a mod changes the same part
    of the game, or the game's code is not what it expects. The game list shows a built-in by its
    name alone and leaves out built-in options that nobody ticked.
  • Settings: the Mario Kart World frame-rate options (30 FPS mode, 60 FPS mode, drop to 30 FPS
    when slow, dynamic FPS) and the Hyrule Warriors: Age of Imprisonment ones (dynamic FPS, 30 FPS
    mode) are listed only in their own game's properties, under Adv. Graphics. They were listed in
    Configure > Graphics > Advanced and in every other game's properties, where they do nothing. A
    value set globally before still applies, and shows on the game's page until it is changed there.
    The list of such settings is Eglantine's game_tweaks (Eglantine #837 and #844).
  • Performance overlay: the trace scrolls in real time. Each bar is one present, as wide as the
    gap since the one before and as tall as that gap, coloured against the 120, 60 and 30 Hz
    budgets. A 1% low sits beside the frame rate, the bars under the trace show how the gaps
    spread, and a strip shows each guest core and the GPU threads. Readouts ease on a spring, and
    the border flashes when a present runs past 1.2 times the median. Right-click the overlay for
    the detailed trace (5 seconds, named cores, min, median and max fps);
    guarana_overlay_compact=false is the same setting.
  • Add-Ons: importing a mod asks before it replaces a mod of the same name, which it did without
    a word. The new mod is copied completely before the installed one goes, so a copy that fails
    leaves the installed mod as it was. Importing from a folder no longer renames that folder, or
    deletes a folder next to it that has the name chosen for the mod.
  • Add-Ons: each imported mod gets a mod.json with its name, the zip or folder it was imported
    from and the date, shown under the list when the mod is selected. The game never reads the
    file, and a mod that brings a mod.json of its own keeps it.
  • Add-Ons: an "Open Mods Folder" button opens the game's mod folder, and makes it for a game
    that has no mods yet.
  • Add-Ons: a warning under the list names the game files that more than one ticked mod replaces
    and the mod whose file the game gets, which is the first one in name order.
  • The game network suites now log each tensor program's path (EDEN_NX2_TENSOR_LOG in
    game-network.json too) and say which GPUs their matrix arms apply to: the Arc 140T's driver lists
    only 8x8x16 shapes with fp32 accumulators and 8x8x32 8-bit shapes, so EDEN_NX2_INTEL_COOP_MATRIX
    and the A1 switches do nothing there (they apply to Xe2 and RDNA 3). The design gains step A1b, an
    8x8x16 path for the 140T, and says to read only each suite's second pass (every arm compiles cold).
  • CI: only pushes save the build's dependency and compiler cache; pull requests restore the
    newest one of their base. A day of pull requests had filled the repository's 10 GB of Actions
    cache with caches only their own pull request could read, which evicted main's and made its
    next Windows build start cold (65 minutes instead of about 9).
  • Upstream: merged zortos293/Lichii nx2 from 99e89096cb to 7c7f723b68 (50 commits).
    Among them: Nextendo online play no longer needs a special build and follows Configure >
    Network, still off by default (Lichii #1979); with it on, a game's signed NPLN patch is checked
    before boot ("Checking online patches") and applied after mods (Lichii #1358), with Nextendo's
    network rules and signed game catalogue (Lichii #1984) and Splatoon 3's network requests
    (Lichii #1988). Ocarina of Time's No sharpening copies the image the output pass samples, which
    ends a frozen 3D under a live HUD (Lichii #1875), and skips the unused heavy dispatch while the
    output is replaced (Lichii #1941). A lost Vulkan device ends the process with a log line instead
    of an unhandled exception (Lichii #1938); a buffer without memory frees staging memory and
    retries (Lichii #1963, #1931); padded depth targets are drawn as the square they are (Lichii
    #1868); terminated threads and a stopped game's kernel objects close safely (Lichii #1957,
    #1932); and bounds fixes in the NSO, KIP, NPDM, NCZ, ticket and XTS readers. Help > Check for
    Updates stays hidden in our releases, which are built wi...
Read more

Guarana v20.5.0-rc1

Guarana v20.5.0-rc1 Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 16 Nov 15:20
7b71387

Pre-release of 20.5.0. Test it and report problems before the final release.

Added

  • Tests: the built-in patch tests fail when two built-in patches that can be applied together
    write, check or keep their state in the same bytes of a game's module: code caves, hooks and
    state blocks. A patch and the one it replaces, and the alternatives of one group, may share
    bytes, because only one of them is applied. The table is read through
    FileSys::BuiltinPatchRanges.
  • Ocarina of Time: three new built-in add-ons, "Text Speed 2x", "Text Speed 4x" and "Text Speed
    Instant", speed up the letters and pauses of dialogue, the fairy's hints and signs. They are
    unchecked by default (Properties > Add-Ons), and with more than one checked the fastest
    applies. A built-in add-on can now be off until it is checked: [DisabledAddOns] then holds
    +<name> for it (Lichii #1422).

Changed

  • Add-Ons: a built-in patch is labelled "Built-in" in the Version column (it was "IPS"), with
    "recommended" or "experimental" where that applies, and listed without "(built-in)" after its
    name. A box under the list says in plain words what the selected built-in does and, once the
    game has been started, whether it was applied. A ticked built-in that was not applied gets a
    warning sign and its reason: made for another version of the game, a mod changes the same part
    of the game, or the game's code is not what it expects. The game list shows a built-in by its
    name alone and leaves out built-in options that nobody ticked.
  • Settings: the Mario Kart World frame-rate options (30 FPS mode, 60 FPS mode, drop to 30 FPS
    when slow, dynamic FPS) and the Hyrule Warriors: Age of Imprisonment ones (dynamic FPS, 30 FPS
    mode) are listed only in their own game's properties, under Adv. Graphics. They were listed in
    Configure > Graphics > Advanced and in every other game's properties, where they do nothing. A
    value set globally before still applies, and shows on the game's page until it is changed there.
    The list of such settings is Eglantine's game_tweaks (Eglantine #837 and #844).
  • Performance overlay: the trace scrolls in real time. Each bar is one present, as wide as the
    gap since the one before and as tall as that gap, coloured against the 120, 60 and 30 Hz
    budgets. A 1% low sits beside the frame rate, the bars under the trace show how the gaps
    spread, and a strip shows each guest core and the GPU threads. Readouts ease on a spring, and
    the border flashes when a present runs past 1.2 times the median. Right-click the overlay for
    the detailed trace (5 seconds, named cores, min, median and max fps);
    guarana_overlay_compact=false is the same setting.
  • Add-Ons: importing a mod asks before it replaces a mod of the same name, which it did without
    a word. The new mod is copied completely before the installed one goes, so a copy that fails
    leaves the installed mod as it was. Importing from a folder no longer renames that folder, or
    deletes a folder next to it that has the name chosen for the mod.
  • Add-Ons: each imported mod gets a mod.json with its name, the zip or folder it was imported
    from and the date, shown under the list when the mod is selected. The game never reads the
    file, and a mod that brings a mod.json of its own keeps it.
  • Add-Ons: an "Open Mods Folder" button opens the game's mod folder, and makes it for a game
    that has no mods yet.
  • Add-Ons: a warning under the list names the game files that more than one ticked mod replaces
    and the mod whose file the game gets, which is the first one in name order.

Fixed

  • GPU traces: guarana-cli --replay refuses a trace that holds no presents (the trace has no frame to replay, exit status 1) instead of writing an empty frames.json and exiting 0. The
    recorder logs an error and sets last_error when a recording ends before its first present,
    which closing the game during the snapshot does, and logs a warning when it ends short of the
    presents asked for. trace_status gains last_presents. trace_replay.py check runs corpus
    entries the replay must refuse (expect_failure), and CI replays the sample trace written
    without its presents (--gpu-trace-sample <trace> --no-presents).

Thanks to @BrunoSilvestre00, @karimalsalah, @kraibse and Rhys Denno.

Downloads

Platform Standard PGO (recommended)
Windows x86_64 zip zip
Linux x86_64 AppImage · tar.gz AppImage · tar.gz
Linux aarch64 AppImage · tar.gz AppImage · tar.gz
macOS arm64 zip · dmg
  • Windows: extract the whole zip into a folder you can write to and run guarana.exe (guarana-cli.exe from a terminal). Both are clang-cl ThinLTO builds; the PGO zip adds a profile trained on Ocarina of Time, so other games gain less.
  • Linux: make the AppImage executable (chmod +x) and run it. The tar.gz holds the same files for systems without FUSE: extract it and run guarana/guarana. Both need glibc 2.39 or newer. The PGO builds use clang with Eglantine's profile.
  • macOS 15 or newer, Apple Silicon. Not notarized: right-click and choose Open the first time, or run xattr -dr com.apple.quarantine guarana.app.
  • Checksums: SHA256SUMS.txt. Check with sha256sum -c SHA256SUMS.txt (Linux), shasum -a 256 -c SHA256SUMS.txt (macOS) or Get-FileHash <file> (PowerShell).
  • Provenance: every file has a signed build provenance attestation; check a download with gh attestation verify <file> --repo karimalsalah/guarana. Signatures and the other checks: docs/SIGNING.md.

No keys, firmware or games are included or provided. Dump your own from hardware you own; see LEGAL.md.

Guarana V3 (v20.4.0)

Choose a tag to compare

@github-actions github-actions released this 16 Nov 08:41
4fabf93

For players

  • In step with upstream Lichii, 67 more commits. Loading Shaders waits only for the pipelines your last two sessions used and builds the older ones in the background. Ocarina of Time no longer locks at 11 to 17 game fps at 240 Hz with 4x frame generation, and the 16 GB memory growth in its Skulltula House is gone.
  • Fixes ported from upstream pull requests. Ocarina of Time's 3D view no longer comes out white or in false colours after a load. Resolution scaling stays within the device's image limits, which lost the device on AMD at 1.5x and 2x. An upload list no longer grows for the whole session.
  • The locked 120 Hz and 144 Hz sets out of the box for Ocarina of Time on Intel integrated GPUs, with interpolated in-between frames.
  • A driver verdict at boot in the log, and a new launcher interface whose Home shows your last measured session.

How it was checked. On one laptop (Core Ultra 9 285H, Arc 140T, Intel driver 32.0.101.9175, 120 Hz), in Ocarina of Time's Hyrule Field with nothing else running, two local builds of this code, one of them this tag's, showed 119.6 to 120.0 frames a second and missed 0 to 4 of 1200 display slots per 10 s. The files published here are built by CI and were not part of those runs. The code from just before the upstream merge showed 119.8 to 119.9 and 0 to 3 in the same session, so catching up with upstream cost no pacing. No gain is claimed. These were three runs and one, read from the presenter's own counters, not benchmark rows.

Known in this version. A boot can fail to show a frame while the host microphone opens (#199). It happened twice in 22 boots on that laptop, once on the first start from a new folder. Close Guarana and start the game again.

Which file. On Windows, Guarana-Setup-20.4.0.exe installs the launcher, which sets the game up for your device. The windows-x86_64-pgo zip is the emulator alone. The table at the end lists every platform.

Added

  • Issue forms: the crash, gameplay bug and visual bug forms now ask for the GPU driver (required, with where to find it on Intel, AMD and Linux), and the UI bug form asks for it as an optional field, as the device report form already did (issue #42).
  • EDEN_NX2_FLUID_COMPOSE=1 (experiment, off by default): with EDEN_NX2_FLUID and the screen copy on a compute-capable queue family, the swapchain images are also created with STORAGE usage (the sRGB view format is left out of their format list), and the slot's frame is composed into the image by a compute pass on that queue (one dispatch that also draws the letterbox bars) instead of vkCmdCopyImage. Frames, frame generation and interpolation are drawn at the game's internal size (the largest guest size seen) and the pass scales them bilinear into the swapchain image with the letterbox, so the configured scaling filter (FSR 3 and the others) does not run; a window much smaller than the guest returns to the classic path, as do the following cases. EDEN_NX2_FLUID_COMPOSE_NATIVE=1 (diagnostic) keeps the frames at the window's size and the pass copies them 1:1, to measure the compute store alone. Back to the classic path on HDR output, extrapolation, DLSS Frame Generation, a surface without storage images (or a driver that refuses them), the watchdog's fallback, the debug server's shown_frames pictures and frame generation without EDEN_NX2_FLUID_INTERP. Not measured; every other composite stays as it was.
  • EDEN_NX2_MESH_BEFORE_PASS=1 (experiment, off by default): on drivers without VK_EXT_mesh_shader (AMD), the compute dispatches of an emulated task or mesh draw run right before the render pass they draw in begins, instead of ending the pass and beginning it again for every such draw (about 70 cuts a frame in Hyrule Field on a Radeon 890M). It applies only when no draw in the pass wrote storage and the draw does not sample its own render targets; ported from the patch in zortos293/Lichii issue 1431 by ronaldpena007-ops, not measured here (issue #22).
  • EDEN_NX2_MESH_BEFORE_PASS=1 (experiment, off by default): on drivers without VK_EXT_mesh_shader (AMD), the compute dispatches of an emulated task or mesh draw run right before the render pass they draw in begins, instead of ending the pass and beginning it again for every such draw (about 70 cuts a frame in Hyrule Field on a Radeon 890M). It applies only when no draw in the pass wrote storage, the current draw writes no storage and does not sample its own render targets; ported from the patch in zortos293/Lichii issue 1431 by ronaldpena007-ops, not measured here (issue #22).
  • Launcher Doctor: four rows that look at Guarana's own settings and only report (issue #125). "Switch file" says when the launcher's block in nx2_switches.txt is not what this launcher writes (an EDEN_NX2_EXTRAPOLATE=1 from a launcher before #122 on an Intel integrated GPU), when its EDEN_NX2_FLUID=1 wins over Ocarina of Time's measured value, when two blocks set the same switch, when a line is read wrongly (a byte-order mark, a # note after the value), and when an EDEN_NX2_ variable is set in Windows. "Settings" says when a shader cache setting is off. "Shader cache files" says when a cache log is of another format than the installed Guarana's (once a build says which it writes) and when Prepare shaders marked a game done but the driver's cache file is missing on an Intel GPU (#106). "Settings folder" says when settings were left behind in %APPDATA%\lichii (#107). Nothing is changed, and keys, firmware, saves and games are never read.
  • gpu_costs times the frame generation passes: three new emu rows, frame_gen_process (once per interpolated real frame), frame_gen_interpolate and frame_gen_extrapolate (one per generated frame), recorded only in the frames the existing cost sampling times (EDEN_NX2_COST_SAMPLING, the debug server's gpu_costs enable, EDEN_NX2_VRS_AUTO, EDEN_DKB_FRAME_TRACE); their GPU time was in no row before (docs/nx2/debug-mcp.md).
  • EDEN_NX2_FLUID_MAILBOX=1 (experiment, off by default): with EDEN_NX2_FLUID, the swapchain presents with MAILBOX instead of FIFO when the surface offers it, so a present that misses its vblank no longer queues ahead of the later ones (a later present that arrives before it is shown replaces it); one log line per swapchain says which mode it got. Image counts are unchanged. Not measured; plan in docs/switches.md.
  • EDEN_NX2_FLUID_IMMEDIATE=1 (experiment, off by default): with EDEN_NX2_FLUID, the swapchain presents with IMMEDIATE instead of FIFO when the surface offers it (the Intel driver on the reference laptop lists IMMEDIATE and FIFO, no MAILBOX), so a present is shown as soon as its copy is done and nothing queues behind a late one; MAILBOX still wins when EDEN_NX2_FLUID_MAILBOX is on and listed. A present lands during scan-out (not at a vblank), so a tear line can show, at a height that follows the copy's finish; one log line per swapchain says which mode it got. Not measured; plan in docs/switches.md.
  • EDEN_NX2_OOT_BYPASS_STEP_GUARD=1 and EDEN_NX2_OOT_BYPASS_SHAPE=1 (experiments, off by default, read only with EDEN_NX2_OOT_BYPASS_ANY=1): Ocarina of Time's No sharpening bypass skips the anti-aliasing network only while the tonemap is the image and drawn area it last replaced, so a resolution step whose output pass it does not know runs the network instead of leaving the scene black (#98); and it can know the output pass of any step by its shape. Not measured; plan in docs/switches.md.
  • EDEN_NX2_OOT_RENDER_SCALE=75 or =50 (experiment, off by default): Ocarina of Time with the Max Resolution add-on draws its scene at 75% or 50% of the output resolution without NVIDIA DLSS, by applying the render-scale records that applied only with DLSS on a Streamline build; the applied render scale stays unset, so FSR stays off and the network bypass stays on. Emulator-side resolution handling only, ignored for other values or when DLSS chooses the scale. Not measured; plan in docs/switches.md.
  • EDEN_NX2_FLUID_MODE_PERIOD=1 (experiment, off by default): with EDEN_NX2_FLUID, the display mode's refresh period is kept when the present thread's wakes slip, instead of the median of the last wake intervals replacing it whenever they differ by more than 10%. A present thread that sleeps through every other vblank at 144 Hz no longer halves the clock to 72 Hz and doubles the copy deadline; the vblanks it slept through are counted at the mode's rate, and whole slots slept through show as overslept. Windows only, where the display mode's period is known. A median that is not a whole multiple of the mode period, with a lower quartile that differs too (a display whose refresh really changed), is still followed (issue #136). Not measured; plan in docs/switches.md.
  • EDEN_NX2_FG_PINGPONG=1 (experiment, off by default): the FSR3 frame generation chain copies one full-size frame per real frame instead of two. Its two images swap roles each real frame and the new frame goes into the one that held the older frame, where today the current image is first copied into history (#136). Not measured; plan in docs/switches.md.
  • EDEN_NX2_SEED_FILTER=1 (experiment, off by default): a new global config is written without the Fsr3 scaling-filter seed, so the filter stays at its default, ScaleForce, and a game preset could choose one (none does yet); Fsr3 costs 3.4 to 3.7 ms of GPU time per shown frame on the Panther Lake laptop against 1.7 ms for ScaleForce. Not measured; part of #136.
  • Debug server: boot_timing returns, next to the boot phases, the cumulative dra...
Read more

Guarana v20.4.0-rc1

Guarana v20.4.0-rc1 Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 16 Nov 02:34
4fabf93

Pre-release of 20.4.0. Test it and report problems before the final release.

Added

  • Issue forms: the crash, gameplay bug and visual bug forms now ask for the GPU driver (required, with where to find it on Intel, AMD and Linux), and the UI bug form asks for it as an optional field, as the device report form already did (issue #42).
  • EDEN_NX2_FLUID_COMPOSE=1 (experiment, off by default): with EDEN_NX2_FLUID and the screen copy on a compute-capable queue family, the swapchain images are also created with STORAGE usage (the sRGB view format is left out of their format list), and the slot's frame is composed into the image by a compute pass on that queue (one dispatch that also draws the letterbox bars) instead of vkCmdCopyImage. Frames, frame generation and interpolation are drawn at the game's internal size (the largest guest size seen) and the pass scales them bilinear into the swapchain image with the letterbox, so the configured scaling filter (FSR 3 and the others) does not run; a window much smaller than the guest returns to the classic path, as do the following cases. EDEN_NX2_FLUID_COMPOSE_NATIVE=1 (diagnostic) keeps the frames at the window's size and the pass copies them 1:1, to measure the compute store alone. Back to the classic path on HDR output, extrapolation, DLSS Frame Generation, a surface without storage images (or a driver that refuses them), the watchdog's fallback, the debug server's shown_frames pictures and frame generation without EDEN_NX2_FLUID_INTERP. Not measured; every other composite stays as it was.
  • EDEN_NX2_MESH_BEFORE_PASS=1 (experiment, off by default): on drivers without VK_EXT_mesh_shader (AMD), the compute dispatches of an emulated task or mesh draw run right before the render pass they draw in begins, instead of ending the pass and beginning it again for every such draw (about 70 cuts a frame in Hyrule Field on a Radeon 890M). It applies only when no draw in the pass wrote storage and the draw does not sample its own render targets; ported from the patch in zortos293/Lichii issue 1431 by ronaldpena007-ops, not measured here (issue #22).
  • EDEN_NX2_MESH_BEFORE_PASS=1 (experiment, off by default): on drivers without VK_EXT_mesh_shader (AMD), the compute dispatches of an emulated task or mesh draw run right before the render pass they draw in begins, instead of ending the pass and beginning it again for every such draw (about 70 cuts a frame in Hyrule Field on a Radeon 890M). It applies only when no draw in the pass wrote storage, the current draw writes no storage and does not sample its own render targets; ported from the patch in zortos293/Lichii issue 1431 by ronaldpena007-ops, not measured here (issue #22).
  • Launcher Doctor: four rows that look at Guarana's own settings and only report (issue #125). "Switch file" says when the launcher's block in nx2_switches.txt is not what this launcher writes (an EDEN_NX2_EXTRAPOLATE=1 from a launcher before #122 on an Intel integrated GPU), when its EDEN_NX2_FLUID=1 wins over Ocarina of Time's measured value, when two blocks set the same switch, when a line is read wrongly (a byte-order mark, a # note after the value), and when an EDEN_NX2_ variable is set in Windows. "Settings" says when a shader cache setting is off. "Shader cache files" says when a cache log is of another format than the installed Guarana's (once a build says which it writes) and when Prepare shaders marked a game done but the driver's cache file is missing on an Intel GPU (#106). "Settings folder" says when settings were left behind in %APPDATA%\lichii (#107). Nothing is changed, and keys, firmware, saves and games are never read.
  • gpu_costs times the frame generation passes: three new emu rows, frame_gen_process (once per interpolated real frame), frame_gen_interpolate and frame_gen_extrapolate (one per generated frame), recorded only in the frames the existing cost sampling times (EDEN_NX2_COST_SAMPLING, the debug server's gpu_costs enable, EDEN_NX2_VRS_AUTO, EDEN_DKB_FRAME_TRACE); their GPU time was in no row before (docs/nx2/debug-mcp.md).
  • EDEN_NX2_FLUID_MAILBOX=1 (experiment, off by default): with EDEN_NX2_FLUID, the swapchain presents with MAILBOX instead of FIFO when the surface offers it, so a present that misses its vblank no longer queues ahead of the later ones (a later present that arrives before it is shown replaces it); one log line per swapchain says which mode it got. Image counts are unchanged. Not measured; plan in docs/switches.md.
  • EDEN_NX2_FLUID_IMMEDIATE=1 (experiment, off by default): with EDEN_NX2_FLUID, the swapchain presents with IMMEDIATE instead of FIFO when the surface offers it (the Intel driver on the reference laptop lists IMMEDIATE and FIFO, no MAILBOX), so a present is shown as soon as its copy is done and nothing queues behind a late one; MAILBOX still wins when EDEN_NX2_FLUID_MAILBOX is on and listed. A present lands during scan-out (not at a vblank), so a tear line can show, at a height that follows the copy's finish; one log line per swapchain says which mode it got. Not measured; plan in docs/switches.md.
  • EDEN_NX2_OOT_BYPASS_STEP_GUARD=1 and EDEN_NX2_OOT_BYPASS_SHAPE=1 (experiments, off by default, read only with EDEN_NX2_OOT_BYPASS_ANY=1): Ocarina of Time's No sharpening bypass skips the anti-aliasing network only while the tonemap is the image and drawn area it last replaced, so a resolution step whose output pass it does not know runs the network instead of leaving the scene black (#98); and it can know the output pass of any step by its shape. Not measured; plan in docs/switches.md.
  • EDEN_NX2_OOT_RENDER_SCALE=75 or =50 (experiment, off by default): Ocarina of Time with the Max Resolution add-on draws its scene at 75% or 50% of the output resolution without NVIDIA DLSS, by applying the render-scale records that applied only with DLSS on a Streamline build; the applied render scale stays unset, so FSR stays off and the network bypass stays on. Emulator-side resolution handling only, ignored for other values or when DLSS chooses the scale. Not measured; plan in docs/switches.md.
  • EDEN_NX2_FLUID_MODE_PERIOD=1 (experiment, off by default): with EDEN_NX2_FLUID, the display mode's refresh period is kept when the present thread's wakes slip, instead of the median of the last wake intervals replacing it whenever they differ by more than 10%. A present thread that sleeps through every other vblank at 144 Hz no longer halves the clock to 72 Hz and doubles the copy deadline; the vblanks it slept through are counted at the mode's rate, and whole slots slept through show as overslept. Windows only, where the display mode's period is known. A median that is not a whole multiple of the mode period, with a lower quartile that differs too (a display whose refresh really changed), is still followed (issue #136). Not measured; plan in docs/switches.md.
  • EDEN_NX2_FG_PINGPONG=1 (experiment, off by default): the FSR3 frame generation chain copies one full-size frame per real frame instead of two. Its two images swap roles each real frame and the new frame goes into the one that held the older frame, where today the current image is first copied into history (#136). Not measured; plan in docs/switches.md.
  • EDEN_NX2_SEED_FILTER=1 (experiment, off by default): a new global config is written without the Fsr3 scaling-filter seed, so the filter stays at its default, ScaleForce, and a game preset could choose one (none does yet); Fsr3 costs 3.4 to 3.7 ms of GPU time per shown frame on the Panther Lake laptop against 1.7 ms for ScaleForce. Not measured; part of #136.
  • Debug server: boot_timing returns, next to the boot phases, the cumulative draw time held for unbuilt pipelines, the pipelines built by kind and the guest file read time, sampled at the first presented frame and at each {"mark": "<label>"} a client takes, to split boot to gameplay (#136). Counted only when EDEN_NX2_DEBUG_SERVER is set.
  • EDEN_NX2_GPL_PARALLEL_PARTS=1 (experiment, off by default): with EDEN_NX2_GPL=1, a pipeline builds its fragment shader library as a job of its own on the shader job workers while its building thread builds the pre-rasterization library, and runs the job itself when no worker is free; not measured yet (#136).
  • EDEN_NX2_FG_MEDIAN_ONCE=1 (experiment, off by default): the FSR3 frame generation chain computes the 3x3 median of the motion field once per real frame, at flow resolution, in one extra pass after the optical flow, and the interpolation shader reads it with one fetch, where today each of the up to five interpolation dispatches recomputes it for every output pixel (#136). Not measured; plan in docs/switches.md.
  • EDEN_NX2_INTEL_COOP_MATRIX=1 (experiment, off by default): on an Intel device whose driver lists an 8x16x16 fp16 cooperative matrix shape, guest HMMA runs on those matrices through shared memory instead of shuffles, a K=16 HMMA as two products so the fp16 accumulator rounds after each K=8 group as the guest does (Fritchii-Intel-Fixes 0007 and 0008 on top of Lichii#779; the author's figure is 13.5 ms of GPU time per frame saved on an Arc B580, not measured here). Not measured on the Arc 140T or Panther Lake.
  • EDEN_NX2_GPL_OPTIMIZE_CACHED=1 (experiment, off by default): with EDEN_NX2_GPL=1, pipelines loaded from the shader cache get the optimized link in the background at their first draw, as pipelines built during play do, instead of drawing fast-linked until they are evicted and rebuilt (is...
Read more