msr2ds 1.1.1 pre-release (hotfix)

A hotfix pre-release of msr2ds 1.1. Everything in 1.1 is here, plus the fix below.

You need your own decrypted dump of Metroid: Samus Returns (USA, .3ds or .cci). Nothing from the game is included, and no texture pack.

Fixed

• Freeze at boot with a gamepad (#18). The game's window could stop responding while it was starting, most often on the Steam Deck and with an HD texture pack. Two threads that handle the controller (one reading SDL's events, one checking which pads are connected for the button icons) could each wait for the other forever. They now take their locks in the same order.

Downloads

• Windows (x64): msr2ds-1.1.1-pre-windows-x64.zip. Unzip it anywhere and run SamusReturns.exe.
• Linux (x86_64): msr2ds-1.1.1-pre-x86_64.AppImage. Make it executable (chmod +x) and run it. It needs glibc 2.38 or newer (Ubuntu 24.04, Fedora 39, current SteamOS, Arch) and runs on X11 or XWayland.

macOS, ARM64 Linux and Android stay on 1.1 for now.

Settings and saves carry over. On Windows they are in the user folder beside SamusReturns.exe: unzip the new version over the old one, or move user into the new folder. The AppImage keeps them in ~/.local/share/samus-returns-recomp (or a user folder beside it), as before.

Notes

• Tested with the USA release (title 00040000001BB200).
• This release runs the game on Azahar's JIT.
• Not affiliated with Nintendo. Licensed GPLv2 or later, as Azahar is.

msr2ds 1.1; flicker removed, android & mac versions added, randomizer + more

Metroid: Samus Returns as a single-screen PC game, built on the Azahar 3DS emulator. This is msr2ds 1.1, with the new features below.

You need your own decrypted dump of Metroid: Samus Returns (USA, .3ds or .cci). Nothing from the game is included, and no texture pack.

Downloads

• Windows (x64): msr2ds-1.1.0-pre-windows-x64.zip. Unzip it anywhere and run SamusReturns.exe.
• Linux (x86_64): msr2ds-1.1.0-pre-x86_64.AppImage. Make it executable (chmod +x) and run it. It needs glibc 2.38 or newer (Ubuntu 24.04, Fedora 39, current SteamOS, Arch) and runs on X11 or XWayland.
• Linux (ARM64): msr2ds-1.1.0-pre-aarch64.AppImage. The same for 64-bit ARM Linux, with the same requirements and a Vulkan driver.
• macOS (Apple Silicon): msr2ds-1.1.0-pre-macos-arm64.zip. Unzip it and open SamusReturns.app (macOS 13.4 or newer). The app isn't notarized, so the first time macOS won't open it: choose Open Anyway in System Settings → Privacy & Security.
• Android (arm64): msr2ds-1.1.0-pre-android-arm64.apk. Android 10 or newer with Vulkan. In the app's setup, choose a user folder and a games folder that holds your dump (in a folder of its own: Android doesn't let apps use Download itself).

Settings and saves from 1.0 carry over. On Windows they are in the user folder beside SamusReturns.exe: unzip the new version over the old one, or move user into the new folder. The AppImage keeps them in ~/.local/share/samus-returns-recomp (or a user folder beside it) as before. The macOS app keeps them in ~/Library/Application Support/samus-returns-recomp, or in a user folder beside the app if you make one.

New since 1.0

• Texture flickering fixed (#3). Fog, dust and enemies no longer drop out for single frames while a new shader is being prepared, and far fewer shaders need preparing in play. The ones your game has used before are built when it starts.
• Mac, Android, ARM Linux support added (#4)(#5).
• Randomizer. A new Randomizer tab in the launcher sets up Randovania for you (about 200 MB, downloaded from its GitHub releases), then makes a seed from its Starter Preset, from presets you made in Randovania, or from a permalink someone shared. The seed becomes a game mod and is turned on; start a new file to play it. Open the seed in Randovania shows its spoiler log and the tracker. Seeds exported from Randovania itself (for Azahar, or to a folder) load too, and Randovania's game connection works on 127.0.0.1.
• Game mods. Mods made for Citra or Azahar (romfs, romfs_ext, exefs, code.ips, exheader.bin) go in user/mods/game/, one folder each, and are turned on, off and ordered in the new Mods tab (launcher and in-game menu).
• Language. (#6) The launcher's Game tab picks the game's language: English, Français, Español, Deutsch, Italiano or Nederlands.
• Camera zoom in the Display tab, from 0.70 (see more of the level) to 1.50, with the HUD kept at its size.
• Xbox button icons. With an Xbox-style pad, the game's on-screen button prompts show the Xbox letters (the buttons themselves stay where they were), texture packs included.
• Launcher with a gamepad: options can be chosen with A or B, and every row can be reached, the language included.
• Update check. When the launcher opens it looks for a newer msr2ds release on GitHub and, if there is one, shows it at the top with a button to its download page. Nothing is downloaded by itself. The Game tab's Updates row turns the check off or runs it now.

Notes

• macOS, ARM64 Linux and Android were added to this release later, built from 12218aeba; the macOS zip was rebuilt from 84d91ea50 with the Background shaders option and a fix for gamepad navigation in the launcher. The Windows and x86_64 Linux downloads are unchanged.

Important

macOS has jitter. Macs have no native Vulkan, so Azahar's Vulkan renderer runs through MoltenVK, a translation layer to Apple's Metal. MoltenVK turns each shader into Metal source code, and Metal compiles it from scratch. Graphics drivers on Windows and Linux compile the same shaders in a few milliseconds, so there you don't notice.

It pauses the first time each new visual effect appears, while the Mac compiles a shader for it. Once an effect has been seen, it plays smoothly from then on, even after restarting.

Why the game waits: this port tells Azahar to finish each shader before drawing with it. Drawing without it was the "texture flicker" bug fixed in 1.1: fog, dust or enemies disappeared for a frame. So instead of a missing effect, you get a short pause.

Why it goes away: macOS keeps the compiled results for the app, in its cache for io.github.gminustwo.msr2ds. So the pauses only happen the first time each effect appears on a given Mac, and get rarer as you play. A macOS update can clear that cache, bringing the first-time pauses back once.

TL;DR: the Mac version has jitter. The Background shaders option, in the launcher's Display tab, removes it, but effects may flicker instead. That's the tradeoff.

• Android is Azahar's Android app with this port's single 16:9 screen, 60 FPS and the galleries and Fusion Mode open. The launcher, the settings overlay, mods and the randomizer are PC-only for now. Menus show the bottom screen as a panel you can touch, and the on-screen buttons can be moved in the in-game menu.

• On a Mac, the Randomizer tab's download fetches Randovania for Windows or Linux only: use Locate with your own Randovania.

• Tested with the USA release (title 00040000001BB200).

• This release runs the game on Azahar's JIT.

• The Fusion suit option stays off while a randomizer is on: the randomizer has its own.

• Not affiliated with Nintendo. Licensed GPLv2 or later, as Azahar is.

msr2ds 1.0

Metroid: Samus Returns as a single-screen PC game, built on the Azahar 3DS emulator.

You need your own decrypted dump of Metroid: Samus Returns (USA, .3ds or .cci). Nothing from the game is included, and no texture pack.

Downloads

• Windows (x64): msr2ds-1.0.0-windows-x64.zip. Unzip it anywhere and run SamusReturns.exe.
• Linux (x86_64): msr2ds-1.0.0-x86_64.AppImage. Make it executable (chmod +x) and run it. It needs glibc 2.38 or newer (Ubuntu 24.04, Fedora 39, current SteamOS, Arch) and runs on X11 or XWayland.

The launcher asks for your dump the first time and remembers it. After that, SamusReturns-Direct.exe (on Linux, --play) boots straight into the game, which suits a Steam shortcut. A GPU with Vulkan is required. The first start uses a 4K internal resolution: lower it in the launcher's Display tab on a weaker GPU.

What's in it

• One 16:9 screen in the style of Metroid Dread. Energy, missiles, Aeion and the beam slots sit at the upper left, and a minimap that keeps Samus in the middle at the upper right, with the DNA and Metroid counts under it. Start opens the game's own bottom screen (map, inventory, options) as a panel.
• Widescreen, up to 4K internal resolution, at 30, 60, 120 or 144 FPS.
• Gamepads: the right trigger switches between the usual, Ice and Grapple Beams, and the left trigger morphs and unmorphs. Menus use the game's Nintendo button layout. Steam Input works.
• Settings in the launcher and in game (F1 or Select): display, HUD, controls, texture packs (Citra and Azahar packs work as they are), save import from Azahar or Citra, amiibo extras and cheats. Quick save, quick load and restart are in the in-game menu.

Notes

• Tested with the USA release (title 00040000001BB200).
• This release runs the game on Azahar's JIT. The repository also holds an ahead-of-time recompiler for the game's code, which you can build from your own dump for your own use (see the README). It runs at the same speed.
• Not affiliated with Nintendo. Licensed GPLv2 or later, as Azahar is.