RetroNX - Libretro/RetroArch for Nintendo Switch
Courtesy of m4xw
For more information regarding RetroArch, the location/names of BIOS files, and compatibility with ROMs, please refer to the official Libretro documentation at:
Use the sidebar under "Core Documentation" to read more about the core you're looking for.
To install, transfer the files as-is to the root of your Switch SD Card -- that is, 'retroarch_switch.nro' should be in /switch, and the main RetroArch directory should be in /retroarch.
To update/add cores as they are released, place the respective .nro in /retroarch/cores/switch.
For the cores that need BIOS files, the system directory to place them in is located at /retroarch/cores/system.
For overlays, place a 1280x720px PNG formatted image with true transparency support (i.e. 32bit) in /retroarch/overlays; A good example would be the overlay images provided in most of the Stable Master or Unstable Nightly cores. Make sure it is named with respect to the name of the core in question, sans version number and such.
E.x. An overlay for SNES9x 2010 whose core is represented in rgui as "SNES9x 2010 1.52.1" would be named "SNES9x 2010". Make sure there is no 'gradient transparency', or half-transparencies -- either a pixel is on or off, and there is no current support for non-whole transparency values. Currently, these are hardcoded and cannot be disabled. If you wish to disable an overlay currently in use, you must either (re)move the file, or name it to something not matching any core.
DISCLAIMER (1): If your SD card filesystem is set to ExFAT, you will unfortunately encounter spurious crashes, file corruption, and general instability with regards to what's on your SD card while using homebrew -- unofficial or official apps/games. To prevent this from causing problems in the future, we HIGHLY recommend formatting your Switch's SD Card under the FAT32 (or otherwise known as FAT) filesystem. On Windows, this will require a third-party application for cards larger than 32GB; on MacOS or *nix based systems, a simple format will suffice.
DISCLAIMER (2): If you are using Team Xecutor's SX OS in any form, we sadly cannot provide support as SX OS is known to have compatibility problems with currently existing homebrew. Please switch to a Hekate-based payload if possible.
- Globally, the content scanner does not function; it will hardcrash the system if attempting a scan. Playlists must be created manually, or utilize the Favorites/Recent Content systems already implemented. NOTE: This will launch the associated core by filename, so if the core name is changed, the recent content entry will likely cause a crash.
- If you have any configuration files used in the past, we HIGHLY recommend cleaning out your RetroArch folder of any and all content, and replace it with the files provided as-is in this package. Refusing to do so may lead to some variance in stability.
- NXEngine does not work as of the writing of this file (7/7/2018), and will crash before the title screen regardless of the version of Douketsu Monogotari used (original Japanese, AeonGenesis's English translation, etc.)
- Wonderswan's threaded video (currently the default) does not work properly as of the writing of this file. You may turn off threaded video in Settings -> Video -> Threaded Video, but the performance will be unsatisfactory. This is currently being worked on, and is only an issue in Wonderswan.
- PCE-Fast and Supergrafx (two versions of the same PC-Engine emulator) will have problems rendering the screen upon loading a second ROM (stretched, squashed, etc.). This can be improved somewhat by setting the core overrided aspect ratio to 4:3 from the default 1:1 PAR.
- Certain cores (namely MAME 2003 and, in some cases, PCE-Fast/Supergrafx) will hardcrash the system when using a non-1:1 aspect ratio. Avoid changing this for these specific emulators. MAME in particular will also crash if the file is not part of the specifically labeled 0.78 ROMset, or otherwise corrupted.
- MAME 2003 currently crashes upon closing larger ROMs (around the 20mb mark?). Press the Switch's home button (taskkill) to get around this.
- SNES9x (Mainline/no date/non-2010) will hardcrash the system when attempting to load more than one MSU-1 enabled game (ROMs that are modded to play CD-quality music/redbook audio). Mitigate this by closing Retro-NX via the menu or pressing the Switch's home button (taskkill) if you want to play another MSU-1 enabled game. Loading normal SNES ROMs is fine, however.
- Also in SNES9x (Mainline or 2010), "Kirby's Dreamland 3" (and other games that utilize the Super NES's High Resolution screenmode) will 'zoom in' awkwardly when the feature is activated; this can be examined in KD3, in the Friend Room of the first level with a high-resolution flowing leaves effect. This CAN be alleviated if activated mid-game by swapping between aspect ratios (thus re-initializing the video and re-orienting it), but will cause the exact opposite effect if the game switches back to normal resolution mode. Alternatively, this can be disabled entirely by the core option "Enable hires mode," but expect graphical inaccuracies in games that use it.
- mGBA only supports Game Boy Advance titles. While the core itself has preliminary support for DMG (monochrome Game Boy), Game Boy Color, and Super Game Boy playback, these will crash the core on RetroNX. Use Gambatte for GB(C) playback instead.
- BlueMSX may or may not work at all, use fMSX
Q: My Switch has crashed/softlocked, and RetroArch doesn't work properly!
A: First, make sure you are on a Horizon OS version (I.E. Nintendo's Switch OS) higher than 1.0.0. Second, no matter which firmware you are on, ALWAYS FORMAT YOUR SD CARD AS FAT32; NO EXCEPTIONS. If you continue to use RetroNX under the ExFAT filesystem, we cannot provide additional support beyond the previously elaborated-upon disclaimer.
Q: I'm trying to save changes to the settings, but it doesn't commit!
A: Save the current configuration with no content loaded. You can do this from any core.
Q: Where do I get updates to the cores?
A: For master/stable builds, the front page on GBATemp (https://gbatemp.net/threads/development-thread-retroarch-libnx.505672/) will have the master links available -- whenever the Master tree is updated, so will the builds in the respective links.
For nightly/unstable builds, you can watch for build activity in the official repository for RetroNX (https://git.m4xw.net/Switch/RetroArch) underneath the respective cores' subdirectory, and selecting "CI/CD -> Pipelines". Downloadable builds will be marked with a download button to the right. Proceed with caution, as we cannot guarantee these to be stable at all times.
Q: My question is not listed here/where can I go for additional support?
A: The fastest method for support and staying up-to-date on progress for RetroNX, you can join the Discord server with the following link:
When you are posting about issues related to the cores (assuming you have read through this readme and identified your problem is uncommon/unrelated to the above), please list the following pieces of information in your report alongside the issue:
- Horizon OS version (I.E. Switch OS firmware version)
- Core used
- Whether core used is a Master/Stable or Nightly/Unstable; what is the builddate of said core?
- Version of the Hekate payload used
Make sure to post in the channel listed #retronx-support.
m4wx - Primary developer of RetroNX/Libretro-NX.
lifajucejo, others - Supporting developers/contributers to the RetroNX project.
Switchbrew - Developers/contributors for the LibNX project and API which RetroNX is built on.
Original Libretro Team - Primary developer of the Libretro/RetroArch project that RetroNX is built upon.
All the testers and users that report notable issues.
An Average Seong - Packaging the build in a convenient pack/writer of the very README you're reading! Thanks for reading to the end.