Luma3DS

Luma3DS
General
Author	LumaTeam
Type	Custom Firmwares
Version	13.0.2
License	Mixed
Last Updated	2023/08/13
Links
Download
Website
Source

Luma3DS is a program to patch the system software of (New) Nintendo (2)3DS handheld consoles "on the fly", adding features such as per-game language settings, debugging capabilities for developers, and removing restrictions enforced by Nintendo such as the region lock.

It also allows you to run unauthorized ("homebrew") content by removing signature checks. To use it, you will need a console capable of running homebrew software on the Arm9 processor.

Features

• Custom Loader.
• Rosalina menu.
• Cheat Engine.
• Service Manager (SM) and PXI.
• Data protection.
• Removal of restrictions:
  • Launch custom Gameboy Advance Virtual Console games without using a homebrew emulator.
  • Region-free patches, without the need to perform region changes.
  • Run homebrews/unsigned codes.
  • Able to boot older flashcarts with homebrew such as NTR Launcher.
• Developer features, useful for debugging and writing homebrew.
• Optional features (enable from the config menu):
  • Default/Autoboot EmuNAND (dual boot firmwares).
  • Screen brightness.
  • Custom splash screen image/duration.
  • PIN lock.
  • Locale Emulation.
• And many more.

Installation

Installing

As of Luma3DS v8.0, boot9strap v1.2 or higher is required for usage and all previous entrypoints are no longer supported. Refer to this for information on how to update from arm9loaderhax, or start from here if you do not yet have arm9loaderhax or boot9strap.

Extract boot.firm from the archive with a tool like 7-zip (Windows/Linux) or Unarchiver (macOS) to the root of your 3DS' SD card.

If your 3DS will not power on after this step or you get an Unsupported Loader error, please try updating boot9strap.

Note: CTRNAND Luma3DS (optional) will allow you to boot your 3DS without having an SD card inserted.

Upgrading

Simply download the latest release from the releases page and replace boot.firm on the SD card. Auto-updaters are not supported.

User guide

Rosalina

In addition to the standard features, Luma3DS has impletmented the custom sysmodule Rosalina, which contains a myriad of features for both developer and end user convenience.

3DSX loading:

• Work just like installed titles; this means you can use the Home Menu and applets while a 3DSX application is running, use the GDB stub, etc.
• By default, the title used to boot boot.3dsx is hblauncher_loader (can be changed from Miscellaneous options> Switch the hb. title to the current app).
  • Simply launch any title, use that option, close the title; the next time you launch that title, it will run boot.3dsx.
  • Note 3DSX applications will freeze if the takeover title is set to Health & Safety.

GDB Stub:

• A fully featured GDB stub for easy debugging.
• Can debug up to 3 processes simultaneously (the process to attach to are to be selected in the process list menu).
  • To use the GDB stub, enable the debugger in the Rosalina menu), navigate to the Process List and select processes you want to attach to.
  • Make sure to disable the debugger when finished, otherwise your 3DS will not be able to cleanly shutdown/reboot/firmlaunch.
  • Compatible with both GDB and IDA Pro ("Use single-step support", in the specific debugger options prompt, should be unchecked).

InputRedirection:

• Allows you to control your 3DS using your PC with, for example, an external controller (Xbox360 controller, etc).
• C-stick/ZL/ZR redirection is N3DS-only, possibly only with newer games.
• Recommended clients are InputRedirectionClient-Qt (compatible with xinput on Windows, evdev on Linux, should be compatible with OSX) or InputClient-SDL.

Rosalina menu

Once the 3DS is booted, you can toggle the Rosalina menu using L+Down+Select (by default; key combo can be changed in the Misc options menu). Many features are available from this menu.

• New 3DS menu:
  • Enable/disable the higher clock speed and extra L2 cache available on the New 3DS/2DS.
  • Note that some games don't work with the extra L2/clock speed and may freeze or crash.
  • You can enable the clock increase and extra L2 cache independent of each other, so if you run into issues try disabling one or both.

• Cheats:
  • A built-in cheat engine. Supports Gateshark-style cheats.
  • Cheats are stored in individual plain text files per game, and should be placed at /luma/titles/titleid/cheats.txt.
  • Please see the dedicated Cheat Engine page for more information.

• Process List:
  • A list of running processes.
  • Used as a selection menu for the RAM viewer/editor and when selecting a process to attach to the debugger, if it's enabled.

• RAM viewer:
  • By selecting a process in the Process List, you can view/edit its RAM.
  • Note that some processes are heapless and thus the L/R heap/code switcher will not show for them.

• Take screenshot:
  • Screenshot is saved to /luma/screenshots.

• Debugger options:
  • Enable/disable the built-in GDB stub.

• System configuration:
  • Toggle LEDs - The power and WiFi LEDs can be toggled on/off in this menu by pressing A (entering sleep mode will reset the LED state).
  • Toggle Wireless - Toggle WiFi on/off without flipping the hardware switch (older 3DSes) or returning to the Home Menu (newer 3DSes).

• Miscellaneous options:
  • Switch the hb. title to the current app - Or Switch the hb. title to hblauncher_loader (if a takeover title is already selected).
  • Change the menu combo - Select this option and then press and hold the combination keys for the Rosalina menu.
  • Start InputRedirection - Enables/disables InputRedirection.
  • Save settings - Saves the Rosalina key combo and takeover title to Luma's config.bin, allowing custom choices to persist through reboots.

• Power off:
  • Powers the system off, bypassing the Return to Home Menu page.

• Reboot:
  • Restarts the system.

• Battery percentage:
  • Remaining battery percentage is displayed in the bottom right of the menu.

• Version info:
  • The Luma3DS version and commit hash is displayed in the bottom left of the menu.

Controls

L+Down+Select - Rosalina in-game menu

Hold Select (while turning 3DS on with the power button) - Configuration menu

Media

2DS/3DS - Luma3DS (KM Zoilus)

Known issues

Please refer to the official page.

Changelog

v13.0.2 2023/08/13

• Fix older system versions (4.x to 8.x) not booting since Luma3DS v13.0
  • On 4.x, Arm11 custom sysmodules have been disabled. This means no Rosalina and no region-free; if you're still on these system versions, please just upgrade after having installed Luma3DS.
• Fix emuNAND support for system version 5.0 (and possibly some other ancient system versions like this one). This was a long-standing issue
• Fix an issue where Arm11 svcBreak exceptions were not displayed as such since Luma3DS v13.0
• Fix an issue with plugins related to Home Menu notification
• Properly grant access to all Arm11-accessible IO to 3DSX homebrew
• Further improvements to overall system stability and other minor adjustments have been made to enhance the user experience

v13.0.1 2023/07/21

• Fix a v13.0 regression where external FIRM module loading (such as TwlBg) was broken.

v13.0.0 2023/07/21

• Merged @PabloMK7 and @Nanquitas 's fork, adding plugin support. This allows mods like CTGP-7 to be played
  • NOTE: Due to planned changes (such as kernel reimplementation) older no longer maintained plugins or closed source ones may suddenly stop working at some point in the future. We advise to use open source and/or actively maintained plugins from trusted sources instead
• Added support to replace the default TWL_FIRM (i.e. DS(i) software) convolution-based upscaling filter by the contents of /luma/twl_upscaling_filter.bin
  • You can find matrix examples here and Python code to convert them to the expected format there
• Added support to allow Left+Right and Up+Down key combos in TWL_FIRM, although commercial DS(i) games usually prevent these combos on their own too
• Added support for arbitrarily-sized and uncompressed TWL_FIRM and AGB_FIRM, when externally loaded from the /luma folder
• Simplify sysmodule CXI loading and IPS/BPS patching: N3DS bit is now cleared when considering which CXI file to load from /luma/sysmodules. The path for IPS/BPS patches for sysmodules, and sysmodules only, has been moved to /luma/sysmodules/<titleId without N3DS bit>.ips (resp. .bps). This is a breaking change
• Remove the "Use EmuNAND FIRM if booting with R" option and all related logic. This was a leftover of the Gateway era that has no place in 2023
• Fixed a rare bug where the console would boot into 2 white screens
• Other minor changes

v12.0.1 2023/03/29

• Hide the "Force routing audio output to headphones" option from bootmenu, and extend it to force-route audio to speakers too
• Fix handling of negative "brightness" values in screen filters advanced options
• Clarify in bootmenu that the "autoboot homebrew" option is meant to launch the Homebrew Menu
• Always crash when processes unexpectedly fail to load, to help troubleshooting
• For sysmodules, code.bin and exheader.bin loading are now deprecated. CXI file loading should be used for those (see 12.0 release notes), and future release will make CXI loading more seamless

v12.0 2023/02/09

• Add a new "advanced configuration" submenu for screen filters, allowing for far more customization (notably, increasing gamma). It allows setting different filters for top and bottom screen separately, and all settings can be saved to the ini configuration file
• Implement autobooting into Homebrew Menu, both in 3DS mode and in DSi mode:
  • DSi modes uses nds-hb-menu bootstrap's TID by default, and is a bit slow to start as it needs to go through the native 3DS OS first no matter what
  • Homebrew needs to be compiled with libctru v2.0.0 at a minimum, and libctru v2.1.2 is highly recommended to a bug fix
• Move "Save settings" to top-level menu
• Add ability to force routing audio to headphones. This is targeted to Bluetooth hardware mod users
  • One limitation is that this option gets undone if you actually insert then remove headphones in the headphones port, closing and re-opening the lid fixes this
• Add ability to redirect application core1 threads to core2, on N3DS:
  • Only useful in very demanding games like Pokémon (Ultra) Sun/Moon where it nets approx. a 10% gain, due to how the 3DS OS works
  • Might break some games and homebrew applications
• Add external *.cxi non-KIP sysmodule loading (from /luma/sysmodules), when the "Enable loading external FIRMs and modules" option is enabled
  • The expected format is {titleId}.cxi (not the name, unlike KIPs), with {titleId} being a string of 16 hexadecimal digits, and with the N3DS bit taken into account
  • code.bin loading for sysmodules is still kept as a feature, but you now need to enable both this option and "Enable game patching" (for non-sysmodules only "Enable game patching" suffices)
• Enable "game patching" features for all applets (not extensively tested), not just games or applications. This being said, LayeredFs might not work on things like the software keyboard, but "locale emulation" is expected to always work
• Remove kernel check for creating core2/core3 threads. This has no bearing on homebrew being able to access core2, as it always has had the proper access bits. Moreover, you should not create threads on core3 as head-tracking takes most of the CPU time there & the graphics driver depends on head-tracking
• Grant full DSP RAM access to all 3dsx homebrew
• Move hb:ldr from Rosalina to loader reimplementation
• Add disabled-by-default PASLR support in our custom loader reimplementation; this should match what the official sysmodule does 1:1
• Fix a bug where an error telling the MCU firmware version was too low, even if this was always incorrect
• Fix a very long-standing bug where sysmodules could incorrectly be killed when using the "Switch the hb. title to the current app." feature followed by closing the current app. This might have been causing issues with this feature and N3DS Health&Safety app in the past
• Display the proper error messages when removing the gamecart or the SD card while playing a game on either medium, instead of a cryptic error code. Also add datetime information to errdisp.txt entries
• General system stability improvements to enhance the user's experience

v11.0 2022/06/05

• Migrate the configuration to INI format (config.bin becomes config.ini).
  • This means that configuration is now human-readable, and makes situations like wanting to modify Rosalina's combo without opening its menu much easier to resolve.
  • The following options have been removed from the config menu and moved to be exclusively in the INI file:
    • "Splash duration": this is because it can now be configured to take any 32-bit value (default: 3 seconds).
    • "Set developer UNITINFO".
    • "Disable Arm11 exception handlers".
    • "Enable Rosalina on SAFE_FIRM".
  • "Show NAND or user string in System Settings" is now enabled by default, when auto-generating a blank configuration file.
• Essential system files (bootROMs, OTP, HWCAL, LCFS, SecureInfo) are now automically backed up to /luma/backups (upon upgrading Luma3DS, if not already present at that location).
• Upon upgrading Luma3DS, boot.firm is now automatically copied to the root of the CTRNAND partition.
• Restore extended-remote support (this was broken with recent versions of GDB). Breaking change: use attach <PID+1> (e.g 1 for fs) to attach to a process, as GDB doesn't support PID 0.
• Add option to toggle card slot (#1202).
• Screen filters can now be saved to config.ini and restored at boot (you need to go to "Miscellaneous options > Save settings"). You can now even manually edit config.ini to use custom values for those (within the 1000 to 25100K range).
• NTP timezone can also now be saved to config.ini; also fix a bug where some timezones would not be reachable.
• Fix a long-standing issue where some system calls took longer than they should, causing lags in some situations (thanks @PabloMK7).
• Fix calculation of displayed battery voltage (thanks nocash).

v10.3 2022/03/17

• Add more detailed battery percentage, plus battery voltage and temperature.
• Add an option to dump the DSP firmware from Home Menu, effectively making programs like DSP1 obsolete.
• Split NTP and user time offset nullification. This means two things:
  • Time changes are immmediately visible and you do not need to reboot your console after using the feature anymore (although Home Menu might not always immmediately display the new time -- just open and close an application in that case).
  • Programs like ctr-no-timeoffset should not be needed anymore. Also, even if 3ds.hacks.guide recommends it and GodMode9 mandates it, time offset nullification should not be done.
• Also improve the precision of the NTP client implementation and fix a few bugs. It can be precise as +- 1ms (usually), although some of this precision is lost when rebooting.
• Do not initialize the screens in the very common case the user has only one payload in the /luma/payloads folder, effectively working around a long-standing bug.
• Fix reading emuNAND sector 0 for RedNAND and Gateway-style emuNAND (#1687, @aspargas2).
• Fix a few bugs in the cheat system (#1623, @s5bug).
• Add ASCII View to Rosalina Process List (#1703, @George-lewis).
• Allow using game-patching on Home Menu (#1634, @gabe565).
• Wait for the user to release the B key when exiting the Rosalina menu. This should prevent games to think the B key has been pressed (#1701, suggestion from @Epicpkmn11).
• gdb: properly handle software breakpoints.
• General system stability improvements to enhance the user's experience.

v10.2.1 2020/11/17

• Fix system version 11.14 not booting.
• Allow out-of-region Download Play functionality (thanks @Pixel-Pop).
• Fix a rare issue where the Rosalina Menu wouldn't be displayed during application launch (thanks @Nanquitas).
• General system stability improvements to enhance the user's experience.

v10.2 2020/07/17

• Massively improved the screenshot feature:
  • Now takes around 100ms instead of 10s (speed may vary, and the first screenshot in a series is slower).
  • 800px top-screen mode is now supported.
  • Rosalina menu options have been reordered to take this into account.
• Added brightness (luminance) selection submenu.
• Screen filters submenu improvements:
  • Changed the filter values, and there are now more of them.
  • The selected filter is now properly restored when the lid is reopened.
• Removed the lag and crash associated to InputRedirection (thanks @Nanquitas):
  • On N3DS, this may cause a key press to be repeated in Home Menu for no reason. Just pressing ZL/ZR on the console is enough to fix this.
• Improved Rosalina menu handling:
  • C-Pad (left pad) can now be used to navigate the menu.
  • You can now easily scroll through the menus by maintaining directional keys.
  • InputRedirection can now be used to access and navigate the menu.
  • New key options for the menu combo: C-Pad Left/Right/Up/Down & "Touch Screen Pressed" (sorry, no ZL/ZR).
• Removed the need for the console to reboot again when switching to homebrew from a higher-memory game (e.g. Pokémon Sun on O3DS -> configured homebrew title).
• Homebrew can now write to the shared config page.
• Fixed the fact that the console would hang if sleep mode was entered when the Rosalina menu was open.
• Enabling either the debugger or InputRedirection will now prevent the console from going to sleep until both are disabled (to prevent the console from hanging).
• Rosalina is now supported on N3DS SAFE_FIRM, including the homebrew launching functionality that comes with it:
  • This is controlled by a new option in the main Luma menu. That option also enables running 11.3-and-below system versions on N2DS and also allows the system to run even with defective head-tracking hardware.
  • The newest release of the Homebrew Menu needs to be used (it comes bundled with Luma3DS in this release archive). You also need to rebuild all your homebrew with the latest libctru release. Some homebrew may not work, nevertheless.
  • Some Rosalina features may not work properly there (e.g. the brightness and New 3DS submenus).
• Separated the exception dump parser script to a new repository.
• In addition, with thanks to @fincs, this release of Luma3DS comes bundled with version 2.2.0 of the Homebrew Menu (EDIT: replaced by hotfixed version).

v10.1.3 2020/04/30

• Fixed a bug that would cause the pxi module to crash on shutdown/reboot/firmlaunch for some people.
• Other minor changes.

v10.1.2 2020/04/28

• Fixed cheats not working at all (v10.1.1 regression).
• Fixed WiFi forcing not working at all (v10.1.1 regression). Also fixed other related bugs, including the mishandling of non-reachable access points.
• Fixed a long-standing issue where the debugger and InputRedirection would hang for a long time and fail to recover if there was no internet.
• Fixed a long-standing issue where the console would take a long time to power off/reboot/firmlaunch if either the debugger or InputRedirection were left enabled. Please note that this still happens if both are left enabled at the same time.

v10.1.1 2020/04/27

• Fixed multiple issues affecting shutdown (and reboot, firmlaunch) time. Shutdown time should be reduced to around 2.5~3.5s (from 16s):
  • A regression from v10.1 that was also potentially affecting startup times.
  • A regression from v10.0.
  • A bug back from 2016 causing shutdown times to be 1.5 to 5.5s longer than normal.
• Fixed an issue where some Luma builds wouldn't boot.
• Fixed most remaining cases where you would get an Arm9 svcBreak with 0xC8804465, in particular if you pressed the SAFE_MODE combo very late (this was a long-standing issue).
• 3DSX: increased the maximum core1 CPU time limit for APT_SetAppCpuTimeLimit from 30% to 89%.

v10.1 2020/04/26

• Fixed booting on 4.x (*).
• Allowed launching 3dsx apps on < 8.x where Rosalina is supported (currently, 4.x and above).
• Added two new options in Rosalina's "System configuration" submenu:
  • The option to force a WiFi network, allowing to use local-network homebrew even if the connection test would fail (@LiquidFenrir).
  • The option to disable short POWER button presses in Rosalina->System configuration (@izzy84075).
• Changed a few things in the NTP submenu:
  • Added the ability to offset the time in the NTP menu by any number of minutes (@nathanhitch).
  • Changed the default IP to that of time.windows.com, not blocked in mainland China.
• Added support for BPS patches (@leoetlino).
• Arm9 menu: check for button combos again after the PIN and/or splash screens.
• Fixed a few bugs in loader sysmodule that were causing crashes (@leoetlino, #1375: @Lizardon1, @muhmuhten).
• Fixed a few bugs in other sysmodules (@lioncash, @piepie62, @Oreo639, @mariohackandglitch), including one that would cause erroneous errdisp screens to show.
• General system stability improvements to enhance the user's experience.
• In addition, with thanks to @fincs, this release of Luma3DS comes bundled with version 2.1.1 of the Homebrew Menu.
• To update, simply drag and drop boot.firm and boot.3dsx to the root of your SD card, as always.
• (*) The space left for Rosalina on this system version (and maybe a few other system versions) is running out; the level of support for it may be reduced to that of 3.x in the future.

Revision changelog.

Credits

Luma3DS is being developed by @AuroraWright and @TuxSH.

See https://github.com/AuroraWright/Luma3DS/wiki/Credits

External links

• GitHub - https://github.com/LumaTeam/Luma3DS