emulator: melonDS
type: standalone + libretro
core_classification: community_fork
cores: [melonds, "melonds-sa"]
source: "https://github.com/libretro/melonDS"
upstream: "https://github.com/melonDS-emu/melonDS"
profiled_date: "2026-03-24"
source_commit: "66b5d2634cd0a79030562811e6e05f5532f800ba"
upstream_commit: "7d8dea42e221b13521270c423b61add41a741b97"
core_version: "0.9.3"
version_basis:
  kind: file
  path: "Makefile.common"
  pattern: '^MELONDS_VERSION\s*=\s*"([^"]+)"'
display_name: "Nintendo - DS (melonDS)"
systems: [nintendo-ds, nintendo-dsi]
data_root:
  windows:
    path: "<folder of melonDS.exe>"
    source_ref: "upstream src/frontend/qt_sdl/main.cpp:182-184, 196-205, upstream src/frontend/qt_sdl/CMakeLists.txt:197-202"
    note: "portable beside melonDS.exe when that folder exists. A build with the PORTABLE option off uses the Qt config location"
  macos:
    path: "~/Library/Preferences/melonDS"
    source_ref: "upstream src/frontend/qt_sdl/main.cpp:182-200, 206-211"
    note: "portable beside melonDS.app when that folder exists"
  linux:
    path: "$XDG_CONFIG_HOME/melonDS, else ~/.config/melonDS"
    source_ref: "upstream src/frontend/qt_sdl/main.cpp:182-184, 196-200, 206-211"
    note: "portable beside the executable when that folder exists"

pin_build:
  - platform: rocknix
    repo: "https://github.com/ROCKNIX/distribution"
    revision: "20261101"
    path: "projects/ROCKNIX/packages/emulators/standalone/melonds-sa/package.mk"
    variable: PKG_VERSION
    value: "906e9ebb27da8c6a715cd7abab4abfe8a8d29427"
config_reads:
  - file: "melonDS.ini"
    platforms: [rocknix]
    source_ref: "upstream src/frontend/qt_sdl/main.cpp:366, upstream src/frontend/qt_sdl/Config.cpp:682-774, 777-783, 785-795, upstream src/frontend/qt_sdl/Platform.cpp:144-166, ROCKNIX projects/ROCKNIX/packages/emulators/standalone/melonds-sa/patches/001-default-config.patch:8-13, ROCKNIX projects/ROCKNIX/packages/emulators/standalone/melonds-sa/patches/003-hotkeys.patch:41-76"
    keys:
      - key: "BIOS9Path"
        source_ref: "upstream src/frontend/qt_sdl/Config.cpp:238, 240, upstream src/frontend/qt_sdl/EmuInstance.cpp:855-876, 1261-1263"
        condition: "ExternalBIOSEnable=1"
      - key: "BIOS7Path"
        source_ref: "upstream src/frontend/qt_sdl/Config.cpp:238, 241, upstream src/frontend/qt_sdl/EmuInstance.cpp:878-898, 1265-1267"
        condition: "ExternalBIOSEnable=1"
      - key: "FirmwarePath"
        source_ref: "upstream src/frontend/qt_sdl/Config.cpp:238, 242, upstream src/frontend/qt_sdl/EmuInstance.cpp:992-1016, 1269"
        condition: "ExternalBIOSEnable=1 and ConsoleType=0"
      - key: "DSiNANDPath"
        source_ref: "upstream src/frontend/qt_sdl/Config.cpp:227, 249, upstream src/frontend/qt_sdl/EmuInstance.cpp:1039-1043, 1227, 1312-1322"
        condition: "ConsoleType=1"
  - file: "melonDS.toml"
    platforms: [emudeck, retrobat]
    revision: "b86390e4428bf38ce4c1ce0e9ca446d6d25955e8"
    revision_from: "melonDS 1.1: the Flathub manifest net.kuribo64.melonDS at e5ce4504 builds it, and RetroBat's melonDS.exe names it"
    source_ref: "upstream src/frontend/qt_sdl/main.cpp:196-213, 328, upstream src/frontend/qt_sdl/Config.cpp:42, 785-799"
    keys:
      - key: "[DS] BIOS9Path"
        source_ref: "upstream src/frontend/qt_sdl/EmuInstance.cpp:868-889, 1277"
        condition: "[Emu] ExternalBIOSEnable = true"
      - key: "[DS] BIOS7Path"
        source_ref: "upstream src/frontend/qt_sdl/EmuInstance.cpp:891-911"
        condition: "[Emu] ExternalBIOSEnable = true"
      - key: "[DS] FirmwarePath"
        source_ref: "upstream src/frontend/qt_sdl/EmuInstance.cpp:1013-1031, 1285"
        condition: "[Emu] ExternalBIOSEnable = true and ConsoleType = 0"
      - key: "[DSi] BIOS9Path"
        source_ref: "upstream src/frontend/qt_sdl/EmuInstance.cpp:913-938, 1328-1336"
        condition: "[Emu] ConsoleType = 1"
      - key: "[DSi] BIOS7Path"
        source_ref: "upstream src/frontend/qt_sdl/EmuInstance.cpp:940-965, 1328-1332"
        condition: "[Emu] ConsoleType = 1"
      - key: "[DSi] FirmwarePath"
        source_ref: "upstream src/frontend/qt_sdl/EmuInstance.cpp:1013-1029, 1285"
        condition: "[Emu] ConsoleType = 1"
      - key: "[DSi] NANDPath"
        source_ref: "upstream src/frontend/qt_sdl/EmuInstance.cpp:1064-1068, 1338-1340"
        condition: "[Emu] ConsoleType = 1"

notes: |
  FreeBIOS fallback for DS mode (NTR), while DSi mode requires all native files.
  Libretro fork based on melonDS ~0.9.x era, validates size only.
  Upstream adds CRC32 validation on BIOS files (MemConstants.h).
  DSi SD card emulation controlled by melonds_dsi_sdcard core option.

files:
  # --- Nintendo DS (NTR) ---
  - name: bios9.bin
    system: nintendo-ds
    description: "ARM9 BIOS"
    required: false
    hle_fallback: true
    size: 4096
    validation: {core: [size], upstream: [size, crc32]}
    crc32: 2ab23573
    source_ref: "source src/NDS.h:196, source src/NDS.cpp:467-477, source src/frontend/Util_ROM.cpp:99-111"
    note: "FreeBIOS fallback (src/FreeBIOS.h), native needed for Key1 cartridge crypto"

  - name: bios7.bin
    system: nintendo-ds
    description: "ARM7 BIOS"
    required: false
    hle_fallback: true
    size: 16384
    validation: {core: [size], upstream: [size, crc32]}
    crc32: 1280f0d5
    source_ref: "source src/NDS.h:197, source src/NDS.cpp:482-492, source src/frontend/Util_ROM.cpp:117-131"
    note: "FreeBIOS fallback (src/FreeBIOS.h), native needed for Key1 init at offset 0x0030"

  - name: firmware.bin
    system: nintendo-ds
    description: "NDS firmware image"
    required: false
    hle_fallback: true
    min_size: 262144
    max_size: 524288
    validation: [size]
    source_ref: "source src/SPI.cpp:192-211, source src/frontend/Util_ROM.cpp:174-195"
    note: "Generated 128KB firmware as fallback, native must be 256KB or 512KB for boot"

  # --- Nintendo DSi (TWL) ---
  - name: dsi_bios9.bin
    system: nintendo-dsi
    description: "DSi ARM9 BIOS"
    required: true
    size: 65536
    validation: {core: [size], upstream: [size, crc32]}
    crc32: bae84f6c
    source_ref: "source src/DSi.h:33, source src/DSi.cpp:587-599, source src/frontend/Util_ROM.cpp:145-156"

  - name: dsi_bios7.bin
    system: nintendo-dsi
    description: "DSi ARM7 BIOS"
    required: true
    size: 65536
    validation: {core: [size], upstream: [size, crc32]}
    crc32: 4316cc42
    source_ref: "source src/DSi.h:34, source src/DSi.cpp:604-620, source src/frontend/Util_ROM.cpp:158-170"
    note: "Contains eMMC key-Y at offset 0x8308 for NAND init"

  - name: dsi_firmware.bin
    system: nintendo-dsi
    description: "DSi firmware image"
    required: true
    size: 131072
    validation: [size]
    source_ref: "source src/SPI.cpp:197-211, source src/frontend/Util_ROM.cpp:201-217"

  - name: dsi_nand.bin
    agnostic: true
    system: nintendo-dsi
    description: "DSi NAND dump"
    required: true
    size: 251658304
    storage: large_file
    source_ref: "source src/frontend/Util_ROM.cpp:224-235, source src/DSi_NAND.cpp:58-97"
    note: "Any regional dump works. Nocash footer required (DSi eMMC CID/CPU at EOF-0x40 or 0xFF800). AES keys derived from ARM7i BIOS offset 0x8308."

  - name: dsi_sd_card.bin
    standalone_path: "dsisd.bin"
    system: nintendo-dsi
    description: "DSi SD card image"
    required: false
    source_ref: "source src/frontend/Util_ROM.cpp:237-243, source src/libretro/libretro.cpp:837, 553, upstream src/frontend/qt_sdl/Config.cpp:120, upstream src/FATStorage.cpp:1024-1025"
    note: "Created if missing, requires melonds_dsi_sdcard core option enabled"