v2026.04.02/emulators/mesen.yml

emulator: Mesen
type: libretro
core_classification: official_port
source: "https://github.com/libretro/Mesen"
upstream: "https://github.com/SourMesen/Mesen"
logo: "https://raw.githubusercontent.com/SourMesen/Mesen2/master/UI/Assets/Mesen.svg"
profiled_date: "2026-03-24"
core_version: "0.9.9"
display_name: "Nintendo - NES / Famicom (Mesen)"
cores: [mesen, mesens]
systems: [nintendo-nes, nintendo-fds]

notes: |
  Mesen is a cycle-accurate NES/Famicom emulator by Sour (the original
  NES-only version, archived in 2020 in favor of Mesen2). NES cartridge
  games need no BIOS. Famicom Disk System games require the FDS BIOS ROM.

  The core tries FdsBios.bin first, then disksys.rom as fallback. Both are
  loaded from the system directory root. If neither is found or the file is
  not exactly 8192 bytes, FDS games fail to load (BiosMissing).

  The Study Box is a Famicom tape-based learning peripheral (mapper 186).
  Its BIOS (StudyBox.bin, 256 KB) is loaded the same way. Only needed for
  Study Box tape dumps (.stbx format).

  MesenDB.txt (game database) is baked into the libretro binary as
  MesenDB.inc and loaded in retro_init(). The external file path in
  InitDatabase() is never reached in the libretro context.

  MesenPalette.pal is an optional custom palette file, loaded only when
  the mesen_palette core option is set to Custom. Accepts 192 bytes
  (64 colors) or 1536 bytes (512 colors with emphasis combos).

  HdPacks go in system/HdPacks/<rom_name>/ -- per-game content, not
  system BIOS.

  File path construction: retro_load_game() sets
  FolderUtilities::SetHomeFolder(systemFolder). All BIOS lookups use
  CombinePath(GetHomeFolder(), filename) -- flat, no subdirectories.

  No functional divergence between upstream and libretro for BIOS loading.

files:
  - name: "disksys.rom"
    aliases: ["FdsBios.bin"]
    system: nintendo-fds
    description: "FDS BIOS ROM"
    required: true
    size: 8192
    validation: [size]
    source_ref: "Core/FdsLoader.cpp:45-59 (LoadBios tries FdsBios.bin then disksys.rom), Core/FdsLoader.cpp:143-146 (LoadRom validates size == 0x2000)"
    notes: "Mapped at 0xE000-0xFFFF as PRG ROM bank 0. Core checks FdsBios.bin first, falls back to disksys.rom. Size must be exactly 8192 bytes or BiosMissing is set."

  - name: "StudyBox.bin"
    system: nintendo-nes
    description: "Famicom Study Box BIOS ROM"
    required: false
    size: 262144
    validation: [size]
    source_ref: "Core/StudyBoxLoader.cpp:125-133 (LoadBios), Core/StudyBoxLoader.cpp:149-152 (LoadRom validates size == 0x40000)"
    notes: "256 KB BIOS for the Study Box tape peripheral (mapper 186). Only needed for .stbx tape dumps. Size must be exactly 262144 bytes."

  - name: "MesenPalette.pal"
    system: nintendo-nes
    description: "External NES color palette"
    required: false
    source_ref: "Libretro/libretro.cpp:301-323 (load_custom_palette), Libretro/libretro.cpp:405-406 (called when mesen_palette == Custom)"
    validation: [size]
    notes: "Loaded when mesen_palette core option is Custom. Accepts exactly 192 bytes (64 RGB triplets) or 1536 bytes (512 entries for emphasis combos). Falls back to built-in default palette if size doesn't match."