Toronja is a Nintendo 3DS emulator for the Nintendo Switch 2 and the Nintendo Switch, with a companion app, Toronja Link, that lets a second console show one of the 3DS's two screens and play along.
It is a continuation of Dekopon by PalindromicBreadLoaf, which is itself the Switch port of Azahar. Everything that makes games run is theirs; see Credits.
Caution
Use it at your own risk. Toronja and Toronja Link are unofficial homebrew, given as they are and with no warranty of any kind. The authors are not responsible for any damage or loss that comes from using them: to a console, an SD card, save data, an account, or anything else, a ban included.
Important
Much of this project was written with AI. A lot of the code, the documentation and these notes that are new in Toronja were produced with heavy use of an AI assistant, directed and tested by one person on two consoles. It is said here, up front, so that anyone who would rather not use or support AI-assisted software can decide before downloading.
Status. This is homebrew under active development, built and tested by one person on two consoles. Things marked untested below compile and are believed to work, and that is all that is claimed for them.
On a Switch 2, most games should run at full speed at 4x internal resolution most of the time. That is the author's experience with the games tried, not a compatibility list: expect short dips the first time a place is entered or a shader is built, and heavier games that want a lower resolution. A Switch 1 is slower; lower the resolution there.
- A port to the Switch 2 (kaiHEN + ounce-devkit, Vulkan through OunceVK/NVK), alongside the Switch 1 build, from the same source and with the same version number.
- Performance work found by profiling real games on both consoles:
- Majora's Mask 3D's Sheikah Stone visions list went from 9 fps to 30 on Switch 2
(
std::call_onceon every guestLDREX/STREX, in dynarmic's spin lock). - The slowdown with the sun in view in the Zelda games (a depth-buffer read-back every frame): host-imported download memory on Switch 2; on Switch 1, a copy out of uncached driver memory and a read-back of only the part the game looks at.
- Switch 1: pipelines that had waited too long are built by the draw that needs them, so a game no longer shows an empty level while one slow worker catches up; closing a game no longer builds the whole queue first; shader caches survive app updates.
- Majora's Mask 3D's Sheikah Stone visions list went from 9 fps to 30 on Switch 2
(
- Reset presets that stay correct ("Default", "Default without async shaders").
- Toronja Link, a second homebrew app for another Switch or Switch 2: it shows the top screen, the bottom screen or both, sends its buttons, sticks, touch screen and motion back, and can play the game's sound.
- Console to console over direct wireless (no router), or over the network both are on.
- The link can be made from the library, before any game: Toronja Link then shows the games as a grid of icons, a large Play button with the game's animated banner once one is picked, and in the options what the focused setting does and every value it can take.
- The second console's Amiibo reader can serve the game;
+and-on it open the in-game menu on the main console.
- A shelf of game cases instead of a list: nine styles (Coverflow, Shelf, Carousel, Arc, Stack, Spotlight, Bookshelf, Pile, Showroom), cases drawn in 3D with spine, hinge and seam.
- Covers from GameTDB, downloaded by the console, sent from a PC
(
tools/covers/fetch_covers.py) or shared from one console to another for a console kept off the internet. Abrings the selected case forward to turn and look at before starting - or shows the game's animated 3D banner, the one the 3DS shows in its HOME Menu, read out of the game and drawn in software (src/citra_switch/banner3d.h).- Dark and light themes, menu sounds, touch everywhere.
- Options in a drawer of pages, with the risky ones under Advanced behind a warning, and
an explanation for every setting (
X). - A redesigned in-game menu: screen layouts as tiles, quick actions (save states, GameShare, resolution, FPS, Amiibo, cheats), full settings with the ones that cannot change mid-game locked.
- Amiibo with nothing to set up: the reader turns on when the game asks.
- The screen layout last used is the one the next game starts in.
- Take the zip for your console from the releases:
toronja-switch-2.ziportoronja-switch-1.zip, andtoronja-link-switch-1.ziportoronja-link-switch-2.zipfor a second console. - Extract it to the root of the SD card: it holds a
switchfolder withtoronja.nro(ortoronja-link.nro) in it. Start it from the Homebrew Menu. - Put your own game dumps in the games folder shown under Options > Folders
(
/switch/toronja/roms/by default).
The loose .nro files in each release are the same programs under the names the updater
inside Toronja asks for; Toronja updates itself from them when the console is online.
Coming from Dekopon, or from a build of Toronja that still used /switch/dekopon/: the folder
is renamed to /switch/toronja/ the first time this version starts, with everything in it.
Dekopon itself, if you keep it on the card, starts afresh after that.
No games, keys or system files are included, and none will be provided.
Everything lives under /switch/toronja/ (changeable in the options):
| Folder | What goes in it |
|---|---|
roms/ |
Your games |
covers/, covers/full/ |
Front covers and whole wraps, named by game code (AQEE.jpg) |
cheats/<TITLE_ID>.txt |
Gateway / Action Replay cheats |
load/mods/<TITLE_ID>/ |
LayeredFS mods (romfs, exefs, exheader.bin) |
load/textures/<TITLE_ID>/ |
Texture packs |
amiibo/, camera/ |
Amiibo dumps and still images for the cameras |
log/ |
azahar_log.txt, and crash.txt after a crash. An empty diag.txt put here switches on the diagnostic trace (see below) |
Save backups use Checkpoint's layout under sdmc:/3ds/Checkpoint/, so a real 3DS can read them.
The game runs on one console, the main one. Toronja Link on a second console is a screen and a controller for that game: it shows the top screen, the bottom screen or both, and sends its buttons, sticks, touch screen, motion sensor and Amiibo reader back. It does not emulate anything and needs no games of its own.
Open Toronja Link on the second console and, on the main one, the link button beside the options (right stick click) or Options > GameShare. Choose the same kind of connection on both.
The main console opens a wireless network of its own and the second one joins it: no router, no internet. While linked, the main console is off its usual Wi-Fi.
On a Switch 1, start Toronja Link from the Homebrew Menu opened through the Album: opened over a game, the system refuses to join another title's wireless network. Toronja Link greys the option out where it cannot work and says why.
Both consoles on the same network. The second one finds the main one by itself; if it does
not, write the main console's address in sdmc:/switch/toronja-link.txt. Nothing leaves the
local network, and neither console needs the internet.
| Second console (runs Toronja Link) | Direct wireless | Local network |
|---|---|---|
| Switch 1, Homebrew Menu from the Album | Works | Works |
| Switch 1, Homebrew Menu over a game | Refused by the system (0xc2cb) |
Works |
| Switch 2 | Not available | Untested |
On a Switch 2 homebrew currently runs as an application, never as an applet (there is no
Album route there yet), and in the one attempt made the wireless service would not even start
for Toronja Link (ldnInitialize returned 0x2ecb). Until that changes, use a Switch 1 as
the second console for direct wireless. The Switch 2 as the main console (the one that
opens the network) works; that pair - Switch 2 main, Switch 1 second - is the one this was
developed and tested on.
- It is not a second player. The second console's controls are added to the main console's own: both drive the same 3DS. It is for playing from the other console, or for holding the bottom screen in your hands, not for two-player games.
- One second console at a time.
- Local only. Console to console or the same home network; not over the internet.
- It is a video of the screen. The picture is sent at the 3DS's own size (400 x 240 top, 320 x 240 bottom) as JPEG frames, and enlarged on the second console; a higher internal resolution on the main console does not make it sharper. When the link struggles the picture gets coarser so the frame rate holds, and a lost frame is skipped, not resent.
- A little delay. Barely noticeable on a good link; it grows on a crowded Wi-Fi.
- Sound is optional. It is switched on on the second console, and the main console can refuse it. It is sent uncompressed, so it adds to the traffic.
- Sharing costs the main console some work (it compresses every frame). A game already short of frame rate, on a Switch 1 above all, can lose a little more.
- Direct wireless takes the main console off its Wi-Fi for as long as the link lasts.
- Amiibo go one way. A figure read on the second console is loaded in the game; the game cannot write back to it.
- No USB cable. It is written, but the Switch 2 loader grants neither
usb:dsnorusb:hs. - No PC or phone app.
tools/gameshare/receiver.pyexists for testing only.
There is no local toolchain to set up: every push is built by GitHub Actions
(.github/workflows/), and the .nro files are the artifacts of each run.
| Workflow | Builds |
|---|---|
toronja-switch2 |
Toronja for Switch 2 |
toronja-switch1 |
Toronja for Switch 1 (with the NXVK Vulkan driver) |
toronja-link |
Toronja Link for both consoles |
ui-preview |
The library and options rendered to PNG on a PC, and the two icons |
The toolchain image is described in docker/switch2/Dockerfile; docker/switch2/build.sh and
docker/switch1/build.sh are the builds themselves. SWITCH2_HANDOFF.md has the notes of the
port: what was tried, what the loader does and does not grant, and how each fix was found.
- USB sharing between consoles is written but switched off: the Switch 2 loader grants
neither
usb:dsnorusb:hs. - The 3D banner is drawn with its materials and plays its jingle, but with stand-in lighting and without material animations or the banner's own camera.
- Much of the newest work (the link from the library, cover sharing, the banner on the console and on the second one) is untested beyond compiling and a PC prototype.
- On Switch 1, start Toronja over a game (title takeover); from the Album (applet mode) games do not start.
- The frame rate dips for a moment the first time a place is entered, while its code is compiled.
- The first time a game is started with nothing compiled (a game never played on this console, or every game once after a driver update) it runs a slow minute or two with textures flickering, while its shaders are built. On Switch 1 that used to stop the game for seconds at a time; since 0.9.36 the stops are short.
- While a shader is being built for the first time, the draws that need it are left out. Something a game draws only once can then stay missing until that screen is opened again: seen once, with the Pokémon names of the first battle in Pokémon Omega Ruby.
- A crash on Switch 2 leaves no
crash.txt. To report one, create an empty/switch/toronja/log/diag.txt, repeat the crash and sendazahar_log.txt: with that file present every log line is written to the card at once and the renderer logs each step. It is slow; delete the file afterwards. - Frame generation (LSFG) is not built into these binaries.
- Azahar and, before it, Citra and Lime3DS: the emulator.
- Dekopon by PalindromicBreadLoaf: the Switch port Toronja continues - the frontend it grew from, the Vulkan work on NXVK, save management, the updater, USB storage and much else.
- Olmectron: Toronja - the Switch 2 port, GameShare and Toronja Link, the library, the menus and the performance work listed above.
- Cover art comes from GameTDB at the user's request; none is distributed here.
GPL-2.0-or-later, as Azahar and Dekopon (license.txt). Bundled dependencies keep their own
licences; see THIRD_PARTY_NOTICES.md.
Nintendo 3DS, Nintendo Switch and Nintendo Switch 2 are trademarks of Nintendo. Toronja is not affiliated with, authorised or endorsed by Nintendo.
