emulator: Gearcoleco
type: libretro
source: "https://github.com/drhelius/Gearcoleco"
cores:
  - gearcoleco
systems:
  - colecovision

notes: |
  Gearcoleco is a ColecoVision emulator by Ignacio Sanchez (drhelius).
  The ColecoVision BIOS ROM is required to run games. Without it, the
  core displays a static "no BIOS" placeholder image (kNoBiosImage from
  no_bios.h) and games will not execute.

  The BIOS is loaded in load_bootroms() (libretro.cpp:293-305) from the
  system directory. The core first tries "colecovision.rom", then falls
  back to "coleco.rom" if the first file is not found.

  Memory.cpp:LoadBios() validates the file size must be exactly 8192
  bytes (0x2000). No hash check is performed by the core itself.

  On reset, the BIOS byte at offset 0x69 is patched to select region:
  0x3C for NTSC, 0x32 for PAL (Memory.cpp:184-187).

  The core also supports Super Game Module (SGM) expanded RAM but that
  requires no additional BIOS files.

files:
  # --- ColecoVision BIOS (required) ---
  - name: "colecovision.rom"
    system: colecovision
    description: "ColecoVision BIOS ROM"
    required: true
    size: 8192
    source_ref: "platforms/libretro/libretro.cpp:297 (load_bootroms)"
    notes: "Primary filename. Loaded via Memory::LoadBios(), must be exactly 8192 bytes."

  - name: "coleco.rom"
    system: colecovision
    description: "ColecoVision BIOS ROM (legacy filename)"
    required: false
    size: 8192
    source_ref: "platforms/libretro/libretro.cpp:303 (load_bootroms fallback)"
    notes: "Fallback filename tried when colecovision.rom is not found."

platform_details:
  colecovision:
    bios_filename: "colecovision.rom"
    bios_fallback: "coleco.rom"
    bios_size: 8192
    source_ref: "src/Memory.cpp:228-258"
    notes: |
      LoadBios() reads the file as raw binary. Size must be exactly 0x2000
      (8192 bytes) or the load is rejected with a log message. The BIOS is
      mapped at address 0x0000-0x1FFF in the ColecoVision memory map. On
      reset, byte 0x69 is patched for NTSC/PAL region selection.