⚠️ Clean-Room / Educativo

Este proyecto es educativo y Open Source. No se copia código de otros emuladores. Implementación basada únicamente en documentación técnica y tests permitidas.

Ejecutar Clasificación MBC + Headless RAW con Evidencia

Fecha: 2026-01-02 Step ID: 0451 Estado: VERIFIED

Resumen

Ejecución de clasificación completa de ROMs por tipo MBC y análisis headless con evidencia RAW. Se ejecutó rom_info_0450.py sobre todas las ROMs disponibles para clasificar MBCs, se ejecutó headless RAW con MBC writes para 4 ROMs clave (mario.gbc, pkmn.gb, tetris.gb, tetris_dx.gbc), y se generó una tabla final con métricas completas (cart_type, MBC, supported, mbc_writes, pc_end, vram_raw_nz, nonwhite). Hallazgo clave: Todos los MBCs están soportados (MBC1, MBC3, MBC5) y los writes MBC se detectan correctamente, pero el VRAM permanece vacío y el framebuffer blanco, sugiriendo un problema de mapping ROM o de otro componente (PPU/paletas).

Concepto de Hardware

Los Memory Bank Controllers (MBC) son chips en los cartuchos de Game Boy que permiten acceder a ROMs mayores de 32KB mediante bank switching. El Game Boy tiene un espacio de direcciones de 16 bits (64KB), pero los juegos pueden ser de 128KB, 256KB, 512KB o más. Los MBCs mapean diferentes "bancos" de ROM en el rango 0x0000-0x7FFF según comandos escritos por el juego.

Tipos de MBC comunes:

  • MBC1: Hasta 2MB ROM, 32KB RAM opcional. Banking mediante escrituras en 0x2000-0x7FFF.
  • MBC3: Similar a MBC1, pero con soporte para RTC (Real-Time Clock).
  • MBC5: Hasta 8MB ROM, 128KB RAM opcional. Banking más simple (9 bits para ROM bank).

Diagnóstico de MBC: Si un juego escribe a rangos MBC (0x0000-0x7FFF) pero el contenido leído desde 0x4000-0x7FFF no cambia, hay un problema de mapping. Si el VRAM permanece vacío después de writes MBC, el código que carga tiles puede estar en un banco ROM que no se está mapeando correctamente.

Fuente: Pan Docs - "Memory Bank Controllers (MBC1/MBC3/MBC5)"

Implementación

Se ejecutaron tres fases del plan:

Fase A: Clasificación de ROMs

Se ejecutó tools/rom_info_0450.py sobre todas las ROMs disponibles para clasificar por tipo de cartucho (0x0147), nombre MBC, y flag CGB. Resultados:

  • Distribución de MBCs: 2 MBC1, 2 MBC3, 3 MBC5, 1 None
  • Soporte: Todas las ROMs tienen MBC soportado (8/8 sí)

Fase B: Headless RAW con MBC Writes

Se creó y ejecutó tools/run_headless_raw_0451.sh para ejecutar headless sobre 4 ROMs clave (mario.gbc, pkmn.gb, tetris.gb, tetris_dx.gbc) durante 240 frames cada una, capturando:

  • pc_end: Último PC del resumen final
  • vram_nonzero_raw: Bytes non-zero en VRAM usando read_raw()
  • nonwhite_pixels: Píxeles non-white en framebuffer
  • mbc_write_count: Total de writes MBC detectados
  • Últimos 8 writes MBC (addr, val, pc)

Fase C: Tabla Final + Decisión Automática

Se creó tools/generate_mbc_table_0451.sh para generar una tabla comparativa con todas las métricas y aplicar reglas de decisión automática. La tabla incluye:

  • ROM | cart_type | MBC | supported | mbc_writes | pc_end | vram_raw_nz | nonwhite | conclusión

Resultados Clave

ROM MBC mbc_writes pc_end vram_raw_nz nonwhite Conclusión
mario.gbc MBC5 238 0x12C1 0 0 MBC soportado pero mapping incorrecto
pkmn.gb MBC3 1034 0x6151 0 0 MBC soportado pero mapping incorrecto
tetris.gb None 1 0x036C 0 0 ROM_ONLY: no es MBC
tetris_dx.gbc MBC1 17 0x0283 0 0 MBC soportado pero mapping incorrecto

Decisión Automática

La tabla muestra que todos los MBCs están soportados y los writes MBC se detectan correctamente, pero el VRAM permanece vacío y el framebuffer blanco. Esto sugiere que:

  • NO falta soporte MBC: MBC1, MBC3 y MBC5 están implementados y los writes se procesan.
  • Problema de mapping o componente secundario: El código que carga tiles puede estar en un banco ROM que no se está mapeando correctamente, o hay un problema en PPU/paletas que impide el renderizado.

Conclusión: No se implementa nuevo MBC en este Step. El siguiente Step debe investigar el mapping ROM (verificar que los bancos se mapean correctamente después de writes MBC) o el componente PPU/paletas.

Archivos Afectados

  • tools/run_headless_raw_0451.sh - Script para ejecutar headless RAW sobre 4 ROMs clave
  • tools/generate_mbc_table_0451.sh - Script para generar tabla final con métricas y decisión automática
  • /tmp/viboy_0451/rom_info_all.txt - Salida de clasificación de ROMs
  • /tmp/viboy_0451/headless/*.txt - Logs de headless para cada ROM
  • /tmp/viboy_0451/mbc_table_final.txt - Tabla final con métricas y conclusiones

Tests y Verificación

Clasificación de ROMs: 

$ python3 tools/rom_info_0450.py roms/*.gb roms/*.gbc
ROM | cart_type(hex) | MBC name | CGB flag | soportado
----|----------------|----------|----------|----------
MortalKombat.gb | 0x01 | MBC1 | 0x00(DMG) | sí
pkmn-amarillo.gb | 0x1B | MBC5 | 0x80(CGB) | sí
pkmn.gb | 0x13 | MBC3 | 0x00(DMG) | sí
tetris.gb | 0x00 | None | 0x00(DMG) | sí
mario.gbc | 0x1B | MBC5 | 0xC0(CGB) | sí
Oro.gbc | 0x10 | MBC3 | 0x80(CGB) | sí
tetris_dx.gbc | 0x03 | MBC1 | 0x80(CGB) | sí
zelda-dx.gbc | 0x1B | MBC5 | 0x80(CGB) | sí

Headless RAW ejecutado: 

$ bash tools/run_headless_raw_0451.sh
[OK] mario.gbc completado
[OK] pkmn.gb completado
[OK] tetris.gb completado
[OK] tetris_dx.gbc completado

Tabla final generada: 

$ bash tools/generate_mbc_table_0451.sh
ROM | cart_type | MBC | supported | mbc_writes | pc_end | vram_raw_nz | nonwhite | conclusión
----|-----------|-----|-----------|------------|--------|-------------|----------|-----------
mario.gbc | 0x1B | MBC5 | sí | 238 | 0x12C1 | 0 | 0 | MBC soportado pero mapping incorrecto
pkmn.gb | 0x13 | MBC3 | sí | 1034 | 0x6151 | 0 | 0 | MBC soportado pero mapping incorrecto
tetris.gb | 0x00 | None | sí | 1 | 0x036C | 0 | 0 | ROM_ONLY: no es MBC
tetris_dx.gbc | 0x03 | MBC1 | sí | 17 | 0x0283 | 0 | 0 | MBC soportado pero mapping incorrecto

Validación: Todos los scripts se ejecutaron correctamente y generaron evidencia numérica para diagnóstico. Los resultados muestran que el problema NO es falta de soporte MBC, sino un problema de mapping o componente secundario (PPU/paletas).

Fuentes Consultadas

  • Pan Docs: "Memory Bank Controllers (MBC1/MBC3/MBC5)"
  • Pan Docs: "Cartridge Header (0x0100-0x014F)"
  • Step 0450: Triage Real "No Veo Gráficos" - MBC Requerido + VRAM Raw

Integridad Educativa

Lo que Entiendo Ahora

  • Clasificación MBC: Los tipos de cartucho (0x0147) determinan qué MBC usa cada ROM. La distribución en nuestro set es: 2 MBC1, 2 MBC3, 3 MBC5, 1 None.
  • Detección de Writes MBC: Los writes a rangos MBC (0x0000-0x7FFF) se detectan correctamente mediante contadores en MMU. Los juegos escriben frecuentemente (238 writes en mario.gbc, 1034 en pkmn.gb).
  • Problema de Mapping: Aunque los writes MBC se detectan, el VRAM permanece vacío, sugiriendo que el código que carga tiles está en un banco ROM que no se está mapeando correctamente, o hay un problema en PPU/paletas.

Lo que Falta Confirmar

  • Mapping ROM después de writes MBC: Verificar que después de un write MBC, el contenido leído desde 0x4000-0x7FFF cambia correctamente según el banco seleccionado.
  • Banco ROM donde está el código de carga de tiles: Identificar en qué banco ROM está el código que carga tiles en VRAM y verificar que ese banco se mapea correctamente.
  • Componente PPU/paletas: Si el VRAM tiene datos pero el framebuffer está blanco, puede haber un problema en el renderizado o en las paletas.

Hipótesis y Suposiciones

Hipótesis principal: El problema NO es falta de soporte MBC, sino un bug en el mapping ROM o en el componente PPU/paletas. Los writes MBC se procesan, pero el contenido mapeado no cambia correctamente, o el código que carga tiles no se ejecuta porque está en un banco no mapeado.

Suposición: Los MBCs están implementados correctamente en MMU.cpp (MBC1, MBC3, MBC5), pero puede haber un bug en update_bank_mapping() o en cómo se lee desde los bancos mapeados.

Próximos Pasos

  • [ ] Step 0452: Investigar mapping ROM - Verificar que después de writes MBC, el contenido leído desde 0x4000-0x7FFF cambia correctamente. Añadir logs de lectura desde bancos mapeados.
  • [ ] Step 0453: Identificar banco ROM del código de carga de tiles - Rastrear en qué banco ROM está el código que carga tiles en VRAM y verificar que ese banco se mapea correctamente.
  • [ ] Step 0454: Si mapping está correcto, investigar componente PPU/paletas - Verificar que el renderizado y las paletas funcionan correctamente cuando VRAM tiene datos.