# BOTWRecompAndroid

**English** | [Português](README.pt-BR.md)

A port of *The Legend of Zelda: Breath of the Wild* (Nintendo Switch, versions **1.0.0, 1.6.0, 1.8.2 and 1.9.0**) for
Android. This is **not Switch emulation**: the game code can be recompiled into C for the phone or, in the experimental
Native Mode, run directly on its ARM64 CPU. The game's graphics API (NVN) is translated to Vulkan.

It is built on the engine of **[LAS Recomp](https://github.com/peiikai/LASRecomp)** by peiikai (a recompilation of
*Link's Awakening*) and its Android port, **[LASRecompAndroid](https://github.com/mamcjr/LASRecompAndroid)**.

> [!WARNING]
> **Beta.** Tested primarily on one phone (POCO F7 Ultra, Adreno 830, Mesa Turnip driver). Performance and compatibility
> vary by device; expect bugs, especially on GPUs that have not been tested on physical hardware. See the
> [0.2.3-beta release notes](https://github.com/mamcjr/BOTWRecompAndroid/releases/tag/v0.2.3-beta) and the
> [development notes](docs/BOTW-PORT.md) (in Portuguese).

## Supported platform

Android is the only application target. Desktop ports and packaging were discontinued on 2026-10-22.
Windows, Linux or macOS may still be used as development hosts with the Android SDK/NDK.

## Status

- **Playable** from the title screen into the world, with saves, on the tested POCO F7 Ultra. All four listed game
  versions are supported in Recompiled Mode. Native Mode has been tested with 1.0.0 and 1.9.0; 1.6.0 and 1.8.2 still
  need testing in that mode.
- **Game code:** choose Recompiled Mode (build the code once on the phone) or experimental Native Mode (skip that
  build). You can switch a Recompiled setup to Native Mode later.
- **Game files:** copy the extracted files into app storage or, since **0.2.3-beta**, use them in place without an
  additional copy of about 16 GB. In-place use requires Android all-files access and the source folder must remain
  available.
- **DLC, saves and mods:** install your own extracted Expansion Pass data; import and export saves as ZIP or import an
  emulator save folder; use mods, including mods that add files and DLC mod folders. In-place mod use needs more testing.
- **Video and controls:** optional 60 fps on supported game versions and experimental 60 fps in-engine cutscenes,
  unlocked aspect ratio, internal/output resolution, FSR 1 or Snapdragon GSR 1 upscaling, FXAA/SMAA, touch controls,
  physical controllers and gyro. The app offers a Vulkan driver selector and compatibility settings.
- **0.2.3 fixes:** dark dots and lines on grassy ground, smoke spikes on hits, partial GAME OVER text, white water
  with Sync lag enabled before loading, several unlocked aspect-ratio UI issues, and some crashes. The Mali shared
  memory fix has not yet been confirmed on a physical Mali device.
- **Known issues:** short grass appears only up close; water reflections can move with the camera; the pause menu
  background can be black on Qualcomm's stock driver; Link may flicker on the first hit in Native Mode. After a
  Sheikah Tower activation, terrain may stretch into vertical "curtains"; reload a save made after activation.

> [!IMPORTANT]
> Like LAS Recomp, this project is made almost entirely with AI (Claude, by Anthropic, through Claude Code), directed,
> tested and reviewed by a human.

> [!NOTE]
> **No game files or DLC are included.** You need your own legally obtained game: an extracted folder (`exefs`
> and `romfs`), or an NSP/XCI dumped from your own console together with that console's keys (see
> [Importing from NSP/XCI](#importing-from-nspxci)). Instructions on obtaining game files or keys are not provided.

## Installing (beta)

1. Download the APK from [Releases](https://github.com/mamcjr/BOTWRecompAndroid/releases) and install it (Android 11+,
   ARM64 and Vulkan). You need your own extracted game folder containing `exefs` and `romfs`.
2. In **Game Files**, choose **Game code**: **Native (experimental)** skips the on-phone code build; **Recompiled**
   builds it once. Under **Game files**, choose **Copy them** or **Use them in place**, then select the extracted folder.
   In-place use asks for Android all-files access; keep that folder where it is. Copying needs roughly 16 GB more
   storage for the game data, while Recompiled Mode also needs space for generated code.
3. If you own the Expansion Pass, install its extracted DLC `romfs` through **Settings > DLC > Install DLC**. To bring
   over saves, use **Settings > Saves** to import a ZIP or emulator save folder.
4. On Adreno phones, a Mesa Turnip driver can perform better than the system driver. Select it under **Settings >
   Files > Vulkan driver**. If the app reports that the Vulkan driver is too old at startup, long-press the app icon
   and choose **Choose driver** before launching the game.

Updating from 0.2.x to 0.2.3-beta does not require rebuilding game code. Shaders compile again once, so the first
minutes may stutter. To report a problem, open an [issue](https://github.com/mamcjr/BOTWRecompAndroid/issues) with
your phone, GPU, driver, game version and a log from **Settings > Files > Save a log file**.

## Importing from NSP/XCI

The app (and the `nximport` tool on a PC) can set the game up straight from an NSP or XCI, with an update NSP and DLC
NSP/XCI too, using the `prod.keys` (and, when the package has no ticket, `title.keys`) from **your own console**. No
keys come with this project, and none are downloaded.

- **In the app:** **Game Files > Import from NSP/XCI > Game package** (and **Update**), then **prod.keys** / **title.keys**, then
  **Import**. The previous setup stays playable until the new one is complete and checked. **Remember the keys**
  keeps them in the app's private storage, excluded from backups and device transfer; **Forget the keys** deletes
  them. **Verify packages** checks each NCA against its SHA-256 in the package's metadata, useful when an import
  reports damaged data. DLC: **Settings > DLC > Install from NSP/XCI**.
- **On a PC:** `tools/nximport` builds a CLI that writes `Dump/01007EF00011E000/{exefs,romfs}`;
  `android/build_gamelib.sh` and `android/push_game.sh` accept `--nsp/--xci … [--update …] --keys … [--title-keys …]`.
- Every block read is checked against the hashes in the package (and the update's patched RomFS against the update's
  own hashes), so a successful import is the game's data exactly. NSZ/XCZ are not supported.

Details, formats and tests: [docs/IMPORT-NSP-XCI.md](docs/IMPORT-NSP-XCI.md).

## Testing on Android (developers)

With the Android SDK / NDK, a phone on adb and your dump in `Dump/`:

```bash
cd android/botwrecompandroid && ./gradlew assembleDebug    # the app
android/build_gamelib.sh Dump/01007EF00011E000/exefs  # the game code (about an hour)
android/push_game.sh Dump/01007EF00011E000           # game files and game code onto the phone
android/run_boot.sh 120                               # start the game, log to android/out/boot.log
```

## Support the project

BOTWRecompAndroid is a free, independent project. If you enjoy it and would like to support its development, you can
sponsor me on GitHub. Your support helps me dedicate time to fixing bugs, improving performance and compatibility, and
working on future releases. Sponsorship is entirely optional: it does not unlock features or guarantee specific fixes.
Bug reports, device tests, and contributions are also greatly appreciated.

[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-on%20GitHub-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/mamcjr)

## Credits

- [peiikai](https://github.com/peiikai) for [LAS Recomp](https://github.com/peiikai/LASRecomp), the recompiler and
  runtime this project starts from (MIT, see [LICENSE](LICENSE)). The original README is kept in [docs/las/](docs/las/).
- [LASRecompAndroid](https://github.com/mamcjr/LASRecompAndroid), its Android port: the app, the phone-side game code
  build, touch controls, mods, driver compatibility and the Portuguese menus.
- [Revivedx](https://github.com/Revivedx) for [SavageWindRecomp](https://github.com/Revivedx/SavageWindRecomp) (MIT),
  the reference for 1.8.2: frame pacing, internal resolution, the SDK 20 kernel fixes, setjmp.
- [Nycolazs](https://github.com/Nycolazs) for LASRecomp-Android-Plus (MIT): Vulkan driver compatibility.
- [ly05010419](https://github.com/ly05010419) for [MacNativeGames](https://github.com/ly05010419/MacNativeGames) (MIT),
  whose fixes and notes for BOTW and TOTK pointed the way for several here: the sync lag (its PR #680), GPU results
  the CPU reads back (PR #239), the terrain's height map texture (PR #511), texture layout, and the gyroscope's drift;
  and for showing that the game's own ARM64 code can run directly (Native game code).
- [OJZen](https://github.com/OJZen) for [totk-mobile](https://github.com/OJZen/totk-mobile), and
  [jhaizhou-ops](https://github.com/jhaizhou-ops) for [d2r-mobile](https://github.com/jhaizhou-ops/d2r-mobile), the
  core it builds on: what the native mode rewrites in the game's code (`svc`, the thread registers, the counter) and
  how - the idea behind ours (no code taken).
- The [zeldaret/botw](https://github.com/zeldaret/botw) decompilation and [open-ead/sead](https://github.com/open-ead/sead),
  for what is known about the game's code.
- Dusklight's launcher, the start screen's style.
- Upscaling and anti-aliasing: [AMD FidelityFX FSR 1](https://github.com/GPUOpen-Effects/FidelityFX-FSR) (MIT),
  [Qualcomm Snapdragon GSR](https://github.com/SnapdragonStudios/snapdragon-gsr) (BSD-3-Clause),
  [SMAA](https://github.com/iryoku/smaa) (MIT).
- Libraries: [SDL](https://libsdl.org) (zlib), [Dear ImGui](https://github.com/ocornut/imgui) (MIT),
  [libadrenotools](https://github.com/bylaws/libadrenotools) (BSD-2-Clause), [volk](https://github.com/zeux/volk) (MIT),
  [Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator) (MIT),
  [shaderc](https://github.com/google/shaderc) (Apache 2.0), [FFmpeg](https://ffmpeg.org) (LGPL),
  [LZ4](https://github.com/lz4/lz4) (BSD-2-Clause), [Capstone](https://www.capstone-engine.org) (BSD-3-Clause),
  [Unicorn](https://www.unicorn-engine.org) (GPLv2, built from its source by `android/deps/build_unicorn.sh`),
  [Mbed TLS](https://github.com/Mbed-TLS/mbedtls) (Apache 2.0, AES and SHA-256 for the NSP/XCI import),
  [Python](https://www.python.org) (PSF) and [Zig](https://ziglang.org) (MIT) for the phone-side build.
- [lsfg-vk](https://lsfg-vk.dev) 1.0.0 by PancakeTAS (MIT) through [GameNative/lsfg-vk-android](https://github.com/GameNative/lsfg-vk-android)
  (MIT), with [DXVK](https://github.com/doitsujin/dxvk)'s dxbc (zlib) and [pe-parse](https://github.com/trailofbits/pe-parse) (MIT):
  the frame generation's shaders, translated on the phone from the user's own Lossless.dll (none included).
- [hactool](https://github.com/SciresM/hactool) by SciresM (ISC), the reference for the Switch package formats
  (no code taken) and for `tools/nximport/verify.sh`.
- [Mesa](https://www.mesa3d.org)'s Turnip driver (MIT), which players load themselves.
- Fonts: [Baloo 2](https://github.com/EkType/Baloo2) (OFL), DejaVu Sans (Bitstream Vera license). The Android robot
  is reproduced or modified from work created and shared by Google (CC BY 3.0).
- Made with [Claude Code](https://claude.com/claude-code) (Anthropic).

*The Legend of Zelda* and *Breath of the Wild* are trademarks of Nintendo. This project is not affiliated with or
endorsed by Nintendo.