From 3c03e4a877b1391223e523e9d97b304025bd1291 Mon Sep 17 00:00:00 2001 From: Jesse Talavera Date: Mon, 6 Jan 2025 15:50:11 -0500 Subject: [PATCH] Add a documentation page for melonDS DS (#1019) * Add an entry for melonDS DS - Also retitle the older core as "melonDS 2021" * First draft of melonDS DS doc page * Update some melonDS DS doc links * Update docs about melonDS DS's BIOs usage * Add the melonDS 2021 migration guide * Update info about the core geometry * Fix incorrect info about DSiWare metadata * Add details about subsystems * Fix some incorrect footnotes * Add more info about melonDS DS * Add a line about the virtual cursor * Actually, it looks nicer here --- docs/development/licenses.md | 5 +- docs/guides/core-list.md | 3 +- docs/guides/retroachievements.md | 3 +- docs/guides/softpatching.md | 6 + docs/library/bios.md | 1 + docs/library/desmume.md | 3 +- docs/library/desmume_2015.md | 9 +- docs/library/melonds.md | 7 + docs/library/melonds_ds.md | 279 +++++++++++++++++++++++++++++++ docs/meta/see-also.md | 3 +- mkdocs.yml | 3 +- 11 files changed, 312 insertions(+), 10 deletions(-) create mode 100644 docs/library/melonds_ds.md diff --git a/docs/development/licenses.md b/docs/development/licenses.md index 690b474325..9baa6391aa 100644 --- a/docs/development/licenses.md +++ b/docs/development/licenses.md @@ -147,7 +147,8 @@ See below for a summary of the licenses behind RetroArch and its cores: | MAME 2010 | [MAME (Non-commercial)](https://github.com/libretro/mame2010-libretro/blob/master/docs/mame.txt) | Non-commercial | | MAME 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | | MAME 2016 | [BSD-3-Clause & GNU GPLv2](http://mamedev.org/legal.html) | | -| [melonDS](../library/melonds.md) | [GPLv3](https://github.com/libretro/melonDS/blob/master/LICENSE) | | +| [melonDS 2021](../library/melonds.md) | [GPLv3](https://github.com/libretro/melonDS/blob/master/LICENSE) | | +| [melonDS DS](../library/melonds_ds.md) | [GPLv3](https://github.com/JesseTG/melonds-ds/blob/main/LICENSE) | | | [Mesen](../library/mesen.md) | [GPLv3](https://github.com/SourMesen/Mesen/blob/master/README.md) | | | [Mesen-S](../library/mesen-s.md) | [GPLv3](https://github.com/SourMesen/Mesen-S/blob/master/README.md) | | | MESS 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | @@ -202,7 +203,7 @@ See below for a summary of the licenses behind RetroArch and its cores: | [TyrQuake](../library/tyrquake.md) | [GPLv2](https://github.com/libretro/tyrquake/blob/master/gnu.txt) | | | UME 2014 | [MAME (Non-commercial)](https://github.com/libretro/mame2014-libretro/blob/master/docs/license.txt) | Non-commercial | | [Uzem](../library/uzem.md) | [GPLv3](https://github.com/Uzebox/uzebox/blob/master/gpl-3.0.txt) | | -| [VaporSpec](../library/vaporspec.md) | [MIT](https://github.com/minkcv/vm/blob/master/LICENSE.md) +| [VaporSpec](../library/vaporspec.md) | [MIT](https://github.com/minkcv/vm/blob/master/LICENSE.md) | [VBA-M](../library/vba_m.md) | [GPLv2](https://github.com/libretro/vbam-libretro/blob/master/doc/gpl.txt) | | | [VBA Next](../library/vba_next.md) | [GPLv2](https://github.com/libretro/vba-next/blob/master/LICENSE) | | | [vecx](../library/vecx.md) | [GPLv3](https://github.com/libretro/libretro-vecx/blob/master/LICENSE.md) | | diff --git a/docs/guides/core-list.md b/docs/guides/core-list.md index 691296d9c7..000f98a32a 100644 --- a/docs/guides/core-list.md +++ b/docs/guides/core-list.md @@ -121,7 +121,8 @@ | MAME 2010 | Arcade/Console/various | (See MAME note) | | MAME 2015 | Arcade/Console/various | (See MAME note) | | MAME 2016 | Arcade/Console/various | (See MAME note) | -| melonDS | Nintendo DS | | +| melonDS 2021 | Nintendo DS | | +| melonDS DS | Nintendo DS/DSi | Enhanced remake of the melonDS core based on a newer version of the emulator. | | Mesen | Nintendo NES/Famicom | | | Mesen-S | Nintendo SNES/SFC/Game Boy/Color | | | MESS 2015 | Multi (various) | (See MAME note) | diff --git a/docs/guides/retroachievements.md b/docs/guides/retroachievements.md index 93643f10a2..071d46f249 100644 --- a/docs/guides/retroachievements.md +++ b/docs/guides/retroachievements.md @@ -181,7 +181,8 @@ You can also check the progress of your friends and add comments on their trophi | Core | Supported | Notes | |---------------------------------------------------------|:---------:|:------| -| [MelonDS](https://github.com/libretro/melonDS) | ✔ | External BIOS recommended, but no longer required. RetroArch 1.9.14 nightly or newer required for hashing to work. DSi mode currently is not supported for achievements. | +| [MelonDS 2021](https://github.com/libretro/melonDS) | ✔ | External BIOS recommended, but no longer required. RetroArch 1.9.14 nightly or newer required for hashing to work. DSi mode currently is not supported for achievements. | +| [MelonDS DS](https://github.com/JesseTG/melonds-ds) | ✔ | Achievements supported for DS and DSi mode. | | [DeSmuME](https://github.com/libretro/desmume) | ✔ | External BIOS recommended, needs to be enabled in core options | | [DeSmuME 2015](https://github.com/libretro/desmume2015) | ✔ | | diff --git a/docs/guides/softpatching.md b/docs/guides/softpatching.md index 2a67637dbc..9a4204dbf6 100644 --- a/docs/guides/softpatching.md +++ b/docs/guides/softpatching.md @@ -27,6 +27,12 @@ rom.ips2 |--------------------------------------------|:---------:| | [Gearcoleco](../library/gearcoleco.md) | ✔ | +### Nintendo - DS + +| Core | Supported | +|------------------------------------|:---------:| +| [melonDS DS](../library/melonds_ds.md) | ✔ | + ### Nintendo - Game Boy / Color | Core | Supported | diff --git a/docs/library/bios.md b/docs/library/bios.md index 6b8e2a3d1c..6a8d2128a6 100644 --- a/docs/library/bios.md +++ b/docs/library/bios.md @@ -53,6 +53,7 @@ Arcade | SAME_CDI | [BIOS information](same_cdi ColecoVision | Gearcoleco | [BIOS information](gearcoleco.md#bios) Dreamcast | Flycast | [BIOS information](flycast.md#bios) DS | DeSmuME | [BIOS information](desmume.md#bios) +DS | melonDS DS | [BIOS information](melonds_ds.md#bios) Elektronika - BK-0010/BK-0011 | bk | [BIOS information](bk.md#bios) Enterprise 128 | ep128emu | [BIOS information](ep128emu.md#bios) GameBoy/GameBoy Color | Emux GB | [BIOS information](emux_gb.md#bios) diff --git a/docs/library/desmume.md b/docs/library/desmume.md index 9ff1125872..05e89f853e 100644 --- a/docs/library/desmume.md +++ b/docs/library/desmume.md @@ -406,4 +406,5 @@ Same as upstream standalone. #### Nintendo - Nintendo DS + Decrypted + (Download Play) - [Nintendo - DS (DeSmuME 2015)](desmume_2015.md) -- [Nintendo - DS (melonDS)](melonds.md) +- [Nintendo - DS (melonDS 2021)](melonds.md) +- [Nintendo - DS (melonDS DS)](melonds_ds.md) diff --git a/docs/library/desmume_2015.md b/docs/library/desmume_2015.md index 6652e18f27..6f9ff66a50 100644 --- a/docs/library/desmume_2015.md +++ b/docs/library/desmume_2015.md @@ -377,14 +377,17 @@ The DeSmuME 2015 core supports the following device type(s) in the controls menu #### Nintendo - Nintendo DS (Download Play) - [Nintendo - DS (DeSmuME)](desmume.md) -- [Nintendo - DS (melonDS)](melonds.md) +- [Nintendo - DS (melonDS 2021)](melonds.md) +- [Nintendo - DS (melonDS DS)](melonds_ds.md) #### Nintendo - Nintendo DS Decrypted - [Nintendo - DS (DeSmuME)](desmume.md) -- [Nintendo - DS (melonDS)](melonds.md) +- [Nintendo - DS (melonDS 2021)](melonds.md) +- [Nintendo - DS (melonDS DS)](melonds_ds.md) #### Nintendo - Nintendo DS - [Nintendo - DS (DeSmuME)](desmume.md) -- [Nintendo - DS (melonDS)](melonds.md) \ No newline at end of file +- [Nintendo - DS (melonDS 2021)](melonds.md) +- [Nintendo - DS (melonDS DS)](melonds_ds.md) diff --git a/docs/library/melonds.md b/docs/library/melonds.md index c16d864225..b802b8f865 100644 --- a/docs/library/melonds.md +++ b/docs/library/melonds.md @@ -4,6 +4,12 @@ An up-and-coming Nintendo DS emulator by Arisotura, ported to libretro. +!!! warning "This is the older version!" + This version of the melonDS core is obsolete and unmaintained. + You are encouraged to migrate to [melonDS DS](melonds_ds.md), + which is based on a newer version of the original emulator, + has more features, and is easier to use. + ### Author/License The melonDS core has been authored by @@ -149,3 +155,4 @@ The melonDS core supports the following device type(s) in the controls menu, bol - [Nintendo - DS (DeSmuME 2015)](desmume_2015.md) - [Nintendo - DS (DeSmuME)](desmume.md) +- [Nintendo - DS (melonDS DS)](melonds_ds.md) diff --git a/docs/library/melonds_ds.md b/docs/library/melonds_ds.md new file mode 100644 index 0000000000..809b4b58bf --- /dev/null +++ b/docs/library/melonds_ds.md @@ -0,0 +1,279 @@ +# Nintendo - DS (melonDS DS) + +## Background + +A Nintendo DS emulator (with DSi support) by Arisotura and friends, +ported to libretro by Jesse Talavera. + +!!! info "This is the newer version!" + This version of the melonDS core is based on a newer version of the original emulator, + and has more features than the older [melonDS core](melonds.md). + Use this one unless you're not ready to migrate. + + +### Author/License + +The melonDS DS core has been authored by + +- Jesse Talavera + +The melonDS DS core is licensed under + +- [GPLv3](https://github.com/JesseTG/melonds-ds/blob/main/LICENSE) + +A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). + +## Extensions + +Content that can be loaded by the melonDS core has one of the following file extensions: + +- .nds +- .dsi +- .ids + +## Databases + +RetroArch database(s) that are associated with the melonDS DS core: + +- [Nintendo - Nintendo DS](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DS.rdb) +- [Nintendo - Nintendo DSi](https://github.com/libretro/libretro-database/blob/master/rdb/Nintendo%20-%20Nintendo%20DSi.rdb) + +## BIOS + +Required or optional firmware files go in the frontend's `system` directory. + +| Filename | Description | md5sum | +|:----------------:|:------------------------------------:|:--------------------------------:| +| bios7.bin | NDS ARM7 BIOS - Optional | df692a80a5b1bc90728bc3dfc76cd948 | +| bios9.bin | NDS ARM9 BIOS - Optional | a392174eb3e572fed6447e956bde4b25 | +| firmware.bin | NDS Firmware - Optional | Varies | +| dsi_bios7.bin | DSi ARM7 BIOS - Required in DSi mode | | +| dsi_bios9.bin | DSi ARM9 BIOS - Required in DSi mode | | +| dsi_firmware.bin | DSi Firmware - Required in DSi mode | Varies | +| dsi_nand.bin | DSi NAND - Required in DSi mode | Varies | + +## Features + +Frontend-level settings or features that melonDS DS respects. + +| Feature | Supported | +|-------------------|:---------:| +| Restart | ✔ | +| Screenshots | ✔ | +| Saves | ✔ | +| States | ✔[^1] | +| Rewind | ✔[^1] | +| Netplay | ✔[^2] | +| Core Options | ✔ | +| RetroAchievements | ✔ | +| RetroArch Cheats | ✔ | +| Native Cheats | ✔ | +| Controls | ✔ | +| Remapping | ✔ | +| Multi-Mouse | ✕ | +| Rumble | ✔ | +| Sensors | ✔ | +| Camera | ✕ | +| Location | ✕ | +| Subsystem | ✔ | +| [Softpatching](../guides/softpatching.md) | ✔ | +| Disk Control | ✕ | +| Username | ✔ | +| Language | ✔ | +| Crop Overscan | ✕ | +| LEDs | ✕ | + +### Directories + +The melonDS DS core's library name is 'melonDS DS' + +The melonDS DS core saves/loads to/from these directories. + +#### Frontend's Save directory + +| File | Description | +|:--------------------:|:---------------------------:| +| *.srm | Cartridge battery save | +| dldi_sd_card.bin | Homebrew SD card image | +| dldi_sd_card.bin.idx | Homebrew SD card file index | +| dsi_sd_card.bin | DSi SD card image | +| dsi_sd_card.bin.idx | DSi SD card file index | +| *.public.sav | DSiWare public save data | +| *.private.sav | DSiWare private save data | +| *.banner.sav | DSiWare icon save data | + +#### Frontend's System directory + +| File | Description | +|:--------------------:|:--------------------------------------:| +| melonDS DS/tmd/*.tmd | DSiWare title ID file | +| wfcsettings.bin | DS Wi-Fi settings (built-in BIOS only) | + +#### Frontend's State directory + +| File | Description | +|:--------:|:-----------:| +| *.state# | State | + +### Geometry and timing + +- The melonDS DS core's core provided FPS is 59.898307800293 FPS. +- The melonDS DS core's core provided sample rate is 32768 Hz. +- The melonDS DS core's base width depends on the screen layout and configured renderer. +- The melonDS DS core's base height depends on the screen layout and configured renderer. +- The melonDS DS core's max width depends on the screen layout and configured renderer. +- The melonDS DS core's max height depends on the screen layout and configured renderer. +- The melonDS DS core's core-provided aspect ratio depends on the screen layout and configured renderer. + +## Subsystems + +melonDS DS uses subsystems to enable inserting GBA ROMs into the emulated Slot-2. +GBA save data (if any) must be loaded explicitly. +Subsystems are not used for DSi mode. + +| Subsystem | Description | +|:---------:|--------------------------------------------------------------| +| gba | NDS ROM in Slot-1, GBA ROM in Slot-2 with optional save data | +| gbanosav | NDS ROM in Slot-1, GBA ROM in Slot-2 with no GBA save data | + +!!! info "Not for playing GBA games." + melonDS can load Game Boy Advance ROMs and save data for the purpose of Slot-2 connectivity, + but it cannot actually play GBA games. + Use a GBA core instead. + +Additional BIOS images are not required. + +## Wi-Fi + +melonDS DS fully supports emulating Nintendo WFC services on all platforms. +You can choose from one of several preconfigured servers in the core options menu, +with [Kaeru WFC](https://kaeru.world/projects/wfc) being the default. + +If there's another server you'd like to use, you can set its DNS address from within the emulated console's Wi-Fi settings menu. + +!!! info "Not related to netplay!" + Wi-fi emulation is not related to LAN-based netplay. + +## LAN Netplay + +Coming soon... + +## DSi + +melonDS DS supports DSi mode, which allows you to play DSi-enhanced games and DSiWare. +**There is no need to prepare a NAND image externally;** +when selecting a DSiWare game from RetroArch, +it (and its previously-exported save data) will be +temporarily installed on the configured NAND image. +At the end of the session, +the save data will be exported to the frontend's save directory +and the DSiWare will be uninstalled. + +## Screen Layouts + +melonDS DS supports a variety of screen layouts, including sideways rotation; +you can configure a particular sequence of available layouts in the core options, +and cycle through them with the `Next Screen Layout` button. +Best used with per-game core option overrides. + +## Controllers + +The melonDS DS core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): + +### User 1 device types + +- None - Doesn't disable input. There's no reason to switch to this. +- **Nintendo DS** - Joypad - Stay on this. + +Future device types may be added +to include peripherals that provided additional inputs. + +### Device tables + +#### Joypad + +![](../image/controller/nds.png) + +| User 1 input descriptors | RetroPad Inputs | +|--------------------------|---------------------------------------------| +| B | ![](../image/retropad/retro_b.png) | +| Y | ![](../image/retropad/retro_y.png) | +| Select | ![](../image/retropad/retro_select.png) | +| Start | ![](../image/retropad/retro_start.png) | +| Up | ![](../image/retropad/retro_dpad_up.png) | +| Down | ![](../image/retropad/retro_dpad_down.png) | +| Left | ![](../image/retropad/retro_dpad_left.png) | +| Right | ![](../image/retropad/retro_dpad_right.png) | +| A | ![](../image/retropad/retro_a.png) | +| X | ![](../image/retropad/retro_x.png) | +| L | ![](../image/retropad/retro_l1.png) | +| R | ![](../image/retropad/retro_r1.png) | +| Microphone | ![](../image/retropad/retro_l2.png) | +| Next Screen Layout | ![](../image/retropad/retro_r2.png) | +| Move Virtual Cursor | ![](../image/retropad/retro_right_stick.png) | +| Close Lid | ![](../image/retropad/retro_l3.png) | +| Touch Virtual Cursor | ![](../image/retropad/retro_r3.png) | + +## Migrating from melonDS 2021 + +melonDS DS is intended to replace the [legacy melonDS core](melonds.md). +If you have existing data you'd like to migrate, follow these steps. + +### Save Files + +The save data format is unchanged between the legacy core and melonDS DS. +However, the method used to save game data internally has changed. + +You'll need to do two things: + +1. Go to the RetroArch save directory and rename the "melonDS" folder to "melonDS DS" (if it exists) +2. Rename the save files from `.sav` to `.srm`. + +### Savestates + +**Savestates taken in the legacy core cannot be migrated to melonDS DS.** +In the time since the last release of the legacy core, +the savestate format has changed upstream. +_Save your game normally before migrating your data to melonDS DS._ + +### Config Files + +Rename the following directories to `melonDS DS`: + +- `$RETROARCH_ROOT/config/melonDS` to `melonDS DS`. +- `$RETROARCH_ROOT/config/remaps/melonDS` to `melonDS DS`. +- Rename any files inside these directories named `melonDS.opt` to `melonDS DS.opt`. + +### Cheats + +Rename `$RETROARCH_ROOT/cheats/melonDS` to `melonDS DS`. +Cheat support is unchanged. + +### System Files + +melonDS DS will detect system files (BIOS, firmware, NAND) in the system directory, +so no action is required from you. +However, melonDS DS will prefer system files in the "melonDS DS" subdirectory. + +## Compatibility + +- [Upstream melonDS Forums Compatibility section](http://melonds.kuribo64.net/board/forum.php?id=3) + +## External Links + +- [Official melonDS Website](http://melonds.kuribo64.net/) +- [Official melonDS GitHub Repository](https://github.com/melonDS-emu/melonDS) +- [Libretro melonDS DS Core info file](https://github.com/libretro/libretro-super/blob/master/dist/info/melondsds_libretro.info) +- [Libretro melonDS DS Github Repository](https://github.com/JesseTG/melonds-ds) +- [Report Libretro melonDS DS Core Issues Here](https://github.com/JesseTG/melonds-ds/issues) + +### See also + +#### Nintendo - Nintendo DS + Decrypted + (Download Play) + +- [Nintendo - DS (DeSmuME 2015)](desmume_2015.md) +- [Nintendo - DS (DeSmuME)](desmume.md) +- [Nintendo - DS (melonDS 2021)](melonds.md) + +[^1]: Not available in DSi mode. +[^2]: LAN only. (No, VPNs won't work.) diff --git a/docs/meta/see-also.md b/docs/meta/see-also.md index 0251b026d5..863a74f615 100644 --- a/docs/meta/see-also.md +++ b/docs/meta/see-also.md @@ -109,7 +109,8 @@ This is a list of cores that are related to each other in some way. - [Nintendo - DS (DeSmuME 2015)](../library/desmume_2015.md) - [Nintendo - DS (DeSmuME)](../library/desmume.md) -- [Nintendo - DS (melonDS)](../library/melonds.md) +- [Nintendo - DS (melonDS 2021)](../library/melonds.md) +- [Nintendo - DS (melonDS DS)](../library/melonds_ds.md) ## NES diff --git a/mkdocs.yml b/mkdocs.yml index 084b422827..5947840da1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -191,7 +191,8 @@ nav: - 'Nintendo - Nintendo 64 (Mupen64Plus)': 'library/mupen64plus.md' - 'Nintendo - DS (DeSmuME 2015)': 'library/desmume_2015.md' - 'Nintendo - DS (DeSmuME)': 'library/desmume.md' - - 'Nintendo - DS (melonDS)': 'library/melonds.md' + - 'Nintendo - DS (melonDS DS)': 'library/melonds_ds.md' + - 'Nintendo - DS (melonDS 2021)': 'library/melonds.md' - 'Nintendo - Pokémon Mini (PokeMini)': 'library/pokemini.md' - 'Nintendo - SNES / Famicom (Beetle bsnes)': 'library/beetle_bsnes.md' - 'Nintendo - SNES / Famicom (bsnes-jg)': 'library/bsnes-jg.md'