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.
Hack Temporal: Forzar Paleta Visible (BGP)
Resumen
Se implementó un hack temporal en la MMU para interceptar escrituras al registro BGP (Background Palette, 0xFF47) y forzar el valor 0xE4 (paleta estándar Game Boy) cuando el juego intenta escribir 0x00 (paleta completamente blanca). Este hack permite visualizar gráficos mientras se investiga por qué algunos juegos (especialmente Dual Mode CGB/DMG como Tetris DX) escriben 0x00 en BGP, haciendo que toda la pantalla sea blanca e invisible. El hack es temporal y se documenta explícitamente como medida de diagnóstico.
Concepto de Hardware
El registro BGP (Background Palette, 0xFF47) controla la paleta de colores de 4 tonos de gris que se usa para renderizar el fondo y la ventana en la Game Boy original (DMG). Cada par de bits del registro BGP mapea un índice de color (0-3) a uno de los 4 tonos de gris disponibles:
- Bits 0-1: Color para índice 0 (normalmente blanco)
- Bits 2-3: Color para índice 1 (normalmente gris claro)
- Bits 4-5: Color para índice 2 (normalmente gris oscuro)
- Bits 6-7: Color para índice 3 (normalmente negro)
El valor 0xE4 (11100100 en binario) es la paleta estándar que deja la Boot ROM:
- Índice 0 → Color 0 (Blanco)
- Índice 1 → Color 1 (Gris claro)
- Índice 2 → Color 2 (Gris oscuro)
- Índice 3 → Color 3 (Negro)
El valor 0x00 (00000000 en binario) mapea todos los índices al color 0 (blanco), haciendo que toda la pantalla sea blanca e invisible. Algunos juegos Dual Mode (CGB/DMG) escriben 0x00 en BGP durante la inicialización, posiblemente porque esperan usar paletas CGB o porque su código de inicialización no está completamente adaptado para modo DMG.
Fuente: Pan Docs - BGP Register (Background Palette)
Implementación
Se añadió una interceptación en el método write_byte() de la MMU que detecta cuando el juego intenta escribir 0x00 en BGP y lo reemplaza automáticamente por 0xE4, forzando una paleta visible.
Componentes creados/modificados
- MMU (`src/memory/mmu.py`): Se añadió una interceptación en
write_byte()que detecta escrituras a 0xFF47 (BGP) y, si el valor es 0x00, lo reemplaza por 0xE4. Se registra un warning en el log para diagnóstico.
Decisiones de diseño
Hack temporal explícito: El código está claramente marcado como "HACK TEMPORAL" con comentarios extensos que explican por qué existe y que debe ser removido cuando se implemente soporte completo para CGB. Esto mantiene la integridad educativa del proyecto.
Logging de diagnóstico: Cada vez que se activa el hack, se registra un warning en el log con el mensaje "🔥 HACK: Forzando BGP 0x00 -> 0xE4 para visibilidad". Esto permite rastrear cuándo y con qué frecuencia el juego intenta escribir 0x00 en BGP.
Interceptación en MMU: El hack se implementa en la MMU porque es el punto central donde todas las escrituras a memoria pasan. Esto garantiza que ninguna escritura a BGP escape al hack, independientemente de dónde se origine en el código del emulador.
No afecta otras escrituras: El hack solo intercepta escrituras de 0x00 a BGP. Cualquier otro valor (incluido 0xE4) se escribe normalmente, permitiendo que el juego configure su propia paleta si escribe un valor válido.
Archivos Afectados
src/memory/mmu.py- Se añadió interceptación de escrituras a BGP (0xFF47) para forzar 0xE4 cuando se intenta escribir 0x00
Tests y Verificación
Este hack se validó ejecutando el emulador con Tetris DX (ROM aportada por el usuario, no distribuida) y verificando que los gráficos sean visibles en pantalla.
- ROM de prueba: Tetris DX (ROM aportada por el usuario, no distribuida)
- Modo de ejecución: UI con logging activado
- Criterio de éxito: Los gráficos deben ser visibles en pantalla (no pantalla blanca o azul)
- Observación esperada: El log debe mostrar mensajes "🔥 HACK: Forzando BGP 0x00 -> 0xE4" cuando el juego intente escribir 0x00 en BGP
- Resultado:
draft- Pendiente de verificación con ejecución real del emulador
Nota legal: La ROM de Tetris DX es aportada por el usuario para pruebas locales. No se distribuye ni se incluye en el repositorio.
Fuentes Consultadas
- Pan Docs: BGP Register (Background Palette)
- Pan Docs: Power-Up Sequence (inicialización de BGP por Boot ROM)
Integridad Educativa
Lo que Entiendo Ahora
- BGP y paletas: El registro BGP controla la paleta de 4 tonos de gris para el fondo y la ventana. El valor 0xE4 es la paleta estándar que deja la Boot ROM, mientras que 0x00 hace que toda la pantalla sea blanca.
- Juegos Dual Mode: Algunos juegos Dual Mode (CGB/DMG) escriben 0x00 en BGP durante la inicialización, posiblemente porque esperan usar paletas CGB o porque su código no está completamente adaptado para modo DMG.
- Hack temporal: Este hack es una medida temporal de diagnóstico que permite visualizar gráficos mientras se investiga por qué el juego escribe 0x00 en BGP. No es una solución permanente.
Lo que Falta Confirmar
- Por qué el juego escribe 0x00: No está completamente claro por qué Tetris DX (y posiblemente otros juegos Dual Mode) escriben 0x00 en BGP. Podría ser un bug en el código del juego, una incompatibilidad con nuestro emulador, o un comportamiento esperado que requiere soporte CGB completo.
- Comportamiento en hardware real: No tengo acceso a una Game Boy real para verificar si el juego realmente escribe 0x00 en BGP o si nuestro emulador está detectando incorrectamente el comportamiento.
- Soporte CGB: Cuando se implemente soporte completo para CGB, este hack deberá ser removido y el juego debería poder escribir su propia paleta sin interferencia.
Hipótesis y Suposiciones
Hipótesis principal: El juego escribe 0x00 en BGP porque espera usar paletas CGB (que son diferentes y se configuran en otros registros). Como nuestro emulador no soporta CGB completamente, el juego intenta configurar una paleta CGB pero falla, dejando BGP en 0x00.
Suposición del hack: Asumimos que forzar BGP a 0xE4 cuando el juego intenta escribir 0x00 no rompe la funcionalidad del juego, solo hace que los gráficos sean visibles. Esta suposición debe ser verificada con pruebas extensivas.
Próximos Pasos
- [ ] Ejecutar el emulador con Tetris DX y verificar que los gráficos sean visibles
- [ ] Revisar los logs para confirmar que el hack se activa cuando el juego intenta escribir 0x00 en BGP
- [ ] Investigar por qué el juego escribe 0x00 en BGP (posible incompatibilidad con modo CGB/DMG)
- [ ] Cuando se implemente soporte CGB completo, remover este hack y permitir que el juego configure su propia paleta
- [ ] Documentar el comportamiento esperado de BGP en juegos Dual Mode