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.
- Type: PC port
- Game: The Legend of Zelda: Echoes of Wisdom
- Runs on Windows and Linux
- By patrickksmdev
- Latest release v0.5.0, 2026-11-20
- Source: https://github.com/patrickksmdev/EoWRecomp
README
EoWRecomp
EoWRecomp
Static recompilation of The Legend of Zelda: Echoes of Wisdom (Nintendo Switch, 2024)
Current development focus: Linux x86-64 + Vulkan
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 automaticcache/shader_seen.txtfor newly encountered variants), withSyncshader mode enabled by default for zero pop-in. - Dynamic cubemap / IBL lighting fix: fixed image-slot
TXQlookups (stage_tex_handle()) and computerscaleinruntime/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 atHEAP_BASE(eliminating per-submitamdgpuuserptr overhead on Linux RADV,~50xfastervkQueueSubmit2), plus cachedstencil_slots()masks, gated debug checks indraw_(), andgw_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 fromtcsenpai/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()TimedWaitvsSignalrace, atomic CAS arbiter updates inruntime/kernel.c, and duplicate Linux watchdog registration (0unstickin 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
nvnProgramSetShadersusing the active window origin/depth mode and waits synchronously on critical fullscreen/compute passes (Smart/Sync/Asyncselectable in theF1menu), eliminating lighting/scene flicker. - VSync & FPS limit: toggle VSync and cap FPS (
30/60/120/Unlimited) from theF1→ Display menu. - XCI extraction & AppImage: HFS0
.xcisupport intools/nca_extract.pyand standalone x86-64 AppImages (build/dist/EoWRecomp-v0.5.0-linux-x86_64.AppImage).
Known issues
- Map screen >120 FPS: keep
FPS limitat60or120(running at144+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.mdis the detailed engineering log (in Portuguese): what works, what broke, hypotheses ruled out, and next steps.CLAUDE.mdholds the project rules (no Nintendo files in the repo, never editgenerated/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, withEOWRECOMP_SAVE_MSL=1, the translated GLSL inbuild/shaders. - Debug switches all start with
EOWRECOMP_(searchgetenv("EOWRECOMP_inruntime/).
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
- EoWRecomp original project by Nycolazs — original project and foundation.
- requiemjota88/EoWRecomp —
beta 1base used for this fork (GPU culling, stencil views, watchdog). - tcsenpai/EoWRecomp — backported
gen.pyjump-table, frame-pacing, pipeline cache, and storing-fs fixes. - LAS Recomp by Peiikai and contributors — the foundation for the recompiler, runtime, NVN implementation, Maxwell shader translator and Vulkan renderer.
- SDL 3, FFmpeg, Dear ImGui, Vulkan, volk, Vulkan Memory Allocator, shaderc, SMAA and AMD FidelityFX FSR 1.
- Documentation and research references: Switchbrew, envytools, and the instruction decoders of Ryujinx and yuzu.
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.