EoWRecomp

EoWRecomp is a native PC port of The Legend of Zelda: Echoes of Wisdom that recompiles the game for Linux and Windows with Vulkan graphics and ahead-of-time shader preparation.

README

EoWRecomp

EoWRecomp icon

EoWRecomp

Static recompilation of The Legend of Zelda: Echoes of Wisdom (Nintendo Switch, 2024)
Current development focus: Linux x86-64 + Vulkan

status platform graphics license


EoWRecomp translates the game's ARM64 machine code into C ahead of time and recompiles it for the host PC. Its runtime replaces the Switch operating-system services used by the game and implements the NVN graphics API on top of Vulkan. This fork is built from requiemjota88/EoWRecomp (beta 1) with backported improvements from tcsenpai/EoWRecomp and LAS Recomp, plus Linux-specific fixes.

Important

Linux x86-64 (Vulkan) is the active tested target in this fork. Windows, macOS, and Android builds inherited from upstream are not tested here.

Warning

No game files are included. You must provide your own legally obtained copy of The Legend of Zelda: Echoes of Wisdom v1.0.0 (title ID 01008CF01BAAC000) and your own prod.keys. The repository does not provide game files, keys, or instructions for obtaining them.

Linux progress (v0.5.0)

  • Most of the overworld explored smoothly + playable through the 2nd dungeon (Gerudo Desert): intro, Hyrule Castle Town, Suthorn Village, Still World (Rifts), 2D sections, first dungeon, and Gerudo Desert dungeon with audio, working save/load, and zero freezes.
  • Ahead-of-time shader preparation (shader_prep): pre-translates and compiles 1,173+ known shader variants from your own game files on the start screen (plus automatic cache/shader_seen.txt for newly encountered variants), with Sync shader mode enabled by default for zero pop-in.
  • Dynamic cubemap / IBL lighting fix: fixed image-slot TXQ lookups (stage_tex_handle()) and compute rscale in runtime/nvn/vulkan/exec.c, restoring ambient lighting and metallic reflections across zone transitions (e.g., Hyrule Castle courtyard).
  • Placed-memory guest heap (VK_EXT_map_memory_placed) & CPU draw optimizations: maps host-cached GTT memory directly at HEAP_BASE (eliminating per-submit amdgpu userptr overhead on Linux RADV, ~50x faster vkQueueSubmit2), plus cached stencil_slots() masks, gated debug checks in draw_(), and gw_hit() bounding-box fast-reject + completed-sequence cache (~66 FPS → 91–116 FPS in open areas; 46–50 FPS → 99.8–120 FPS in heavy draw areas on RX 7600).
  • Rift / Void rendering fix: submission-tracked GPU-written buffer lifetimes (gw_tab, ported from tcsenpai/EoWRecomp) fix visual glitches after exiting Rift areas without address-specific workarounds.
  • Kernel condvar & watchdog fixes: fixed svc_wait_process_wide_key() lost wake-up, block_current() TimedWait vs Signal race, atomic CAS arbiter updates in runtime/kernel.c, and duplicate Linux watchdog registration (0 unstick in 272 s+ sessions).
  • GPU-side indirect draws (vkCmdDrawIndirect / vkCmdDrawIndexedIndirect): eliminated mid-frame CPU flush stalls and added live tracking for GPU-written constant buffers.
  • Smart shader compilation & pre-warming: pre-warms shaders on nvnProgramSetShaders using the active window origin/depth mode and waits synchronously on critical fullscreen/compute passes (Smart / Sync / Async selectable in the F1 menu), eliminating lighting/scene flicker.
  • VSync & FPS limit: toggle VSync and cap FPS (30 / 60 / 120 / Unlimited) from the F1 → Display menu.
  • XCI extraction & AppImage: HFS0 .xci support in tools/nca_extract.py and standalone x86-64 AppImages (build/dist/EoWRecomp-v0.5.0-linux-x86_64.AppImage).
Known issues
  • Map screen >120 FPS: keep FPS limit at 60 or 120 (running at 144+ fps currently inverts the analog stick on the map screen).
  • Untested platforms: Windows, macOS, and Android builds are inherited from upstream and untested in this fork (automated Windows x64 builds are generated via GitHub Actions).

Running & Building on Linux

AppImage (recommended)

Download the latest AppImage from Releases:

chmod +x EoWRecomp-v0.5.0-linux-x86_64.AppImage
./EoWRecomp-v0.5.0-linux-x86_64.AppImage

On first launch, select the folder containing your .nsp/.xci and prod.keys. The launcher will extract ExeFS and compile eowgame.so locally.

Building from source

See docs/linux.md and docs/STATUS.md for dependencies, or build the AppImage with podman:

tools/linux/appimage.sh x86_64

How it works

  • Recompiler (tools/): analyzes the game's ARM64 modules, resolves functions and jump tables, and generates C code.
  • Runtime (runtime/): implements the Horizon services used by the game, including threads, synchronization, filesystem, input and audio.
  • Graphics: reimplements NVN on Vulkan and translates Maxwell GPU shaders to GLSL.
  • Game package reader (runtime/nxpkg.c): reads NSP/XCI/NCA packages using the user's keys. The RomFS can be read directly from the package instead of requiring a second multi-gigabyte copy.

Contributing & Debugging

  • docs/STATUS.md is the detailed engineering log (in Portuguese): what works, what broke, hypotheses ruled out, and next steps.
  • CLAUDE.md holds the project rules (no Nintendo files in the repo, never edit generated/ by hand, every patch checks the original instruction word, a fix counts only once seen working).
  • Tests live in tools/ (test_translate, test_shaders, test_simd, test_lift, test_lane.sh, test_stencil.sh).
  • F9 debug capture: press F9 in game to save the next frame's render passes (build/pass_*.png), the draw log, and, with EOWRECOMP_SAVE_MSL=1, the translated GLSL in build/shaders.
  • Debug switches all start with EOWRECOMP_ (search getenv("EOWRECOMP_ in runtime/).

Development status

See docs/STATUS.md for the detailed technical log:

  • Windows test results and performance observations
  • Vulkan/Radeon shader and pipeline investigations
  • SUST and compute-shader progress
  • Remaining graphics bugs and diagnostic instructions

Credits

This fork is developed with AI assistance from Gemini (Google), under human direction and testing (upstream base was developed with Claude).

Legal

EoWRecomp is an independent fan project and is not affiliated with, endorsed by, or sponsored by Nintendo. The Legend of Zelda and Echoes of Wisdom are trademarks of Nintendo. No game files, game code, assets or keys are included. You must provide your own legally obtained copy of the game.

License

EoWRecomp's original code is licensed under MIT. Third-party components retain their respective licenses. This license grants no rights to Nintendo's game or other copyrighted content.