emulator: "emux (Game Boy)"
type: libretro
source: "https://github.com/libretro/emux"
profiled_date: "2026-03-19"
core_version: "0.1"
display_name: "Nintendo - Game Boy / Color (Emux GB)"
cores:
  - emux_gb
systems:
  - nintendo-gb

notes: |
  emux is a multi-system emulator by Sebastien Ronsse, supporting CHIP-8,
  Game Boy, NES, and Sega Master System as separate libretro cores.

  NOT an alias of Gambatte. Completely different codebase and BIOS requirements.
  Gambatte uses gb_bios.bin/gbc_bios.bin (optional, HLE fallback).
  emux_gb uses dmg_boot.bin (required, no HLE, core fails without it).

  Boot ROM loading in controllers/mapper/gb_mapper.c:
    static char *bootrom_path = "dmg_boot.bin";  (line 32)
    gb_mapper->bootrom = file_map(PATH_SYSTEM, bootrom_path, 0, BOOTROM_SIZE);
  If file_map returns NULL, gb_mapper_init returns false — core cannot start.
  No HLE fallback, no skip logic.

  Boot ROM is 256 bytes (BOOTROM_SIZE in gb_mapper.h:10), mapped at 0x0000-0x00FF.
  When register 0xFF50 (BOOT_LOCK) is written with non-zero, the bootrom region
  is removed from the memory map (lock_writeb, gb_mapper.c:130-138).

  Memory map from mach/gb.c:
    0x0000-0x00FF  Boot ROM (overlays ROM0 until BOOT_LOCK)
    0x0000-0x3FFF  ROM bank 0 (16 KB)
    0x4000-0x7FFF  ROM bank 1 (switchable, 16 KB)
    0x8000-0x9FFF  VRAM (8 KB)
    0xA000-0xBFFF  External RAM (8 KB)
    0xC000-0xDFFF  WRAM (8 KB)
    0xFE00-0xFE9F  OAM (160 bytes)
    0xFF80-0xFFFE  HRAM (127 bytes)

  The .info declares firmware_count=1, firmware0_opt=false.
  is_experimental=true. Core does not support save states, rewind, or netplay.

  system_directory obtained via RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY
  (libretro/libretro.c:23-25), passed as "system-dir" config param.

files:
  - name: "dmg_boot.bin"
    system: nintendo-gb
    description: "Game Boy (DMG) boot ROM"
    required: true
    size: 256
    md5: "32fbbd84168d3482956eb3c5051637f5"
    source_ref: "controllers/mapper/gb_mapper.c:32 (bootrom_path), gb_mapper.h:10 (BOOTROM_SIZE=256)"
    note: "Mapped at 0x0000-0x00FF, overlays ROM0 until BOOT_LOCK (0xFF50) written. No HLE — core fails to init without this file."