⚠️ 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.

Herramienta para Abrir ROMs en Cuadrícula

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

Resumen

Creación de una herramienta de automatización para abrir múltiples ROMs del emulador en ventanas organizadas en una cuadrícula de 2 filas x 4 columnas. La herramienta utiliza wmctrl para posicionar y redimensionar automáticamente las ventanas del emulador, facilitando la captura de pantalla de múltiples ROMs ejecutándose simultáneamente. Incluye filtrado inteligente para excluir ventanas grandes (como editores) y solo afectar las ventanas del emulador identificadas por el título "ViboyColor".

Concepto de Hardware

Esta herramienta no implementa funcionalidad de hardware del Game Boy, sino que es una utilidad de desarrollo para facilitar la visualización y documentación del emulador. Permite ejecutar múltiples instancias del emulador simultáneamente, cada una con una ROM diferente, organizadas visualmente para comparación y captura de pantalla.

El emulador utiliza Pygame para la ventana gráfica, con dimensiones estándar de 480x480 píxeles (escala 3x: 160x144 píxeles originales + barra de título). La herramienta aprovecha las capacidades del gestor de ventanas de Linux (X11) a través de wmctrl para manipular la posición y tamaño de las ventanas de forma programática.

Implementación

Se creó el script tools/abrir_roms_cuadricula.sh que automatiza el proceso de apertura y organización de ventanas del emulador. El script implementa las siguientes funcionalidades:

Componentes creados/modificados

tools/abrir_roms_cuadricula.sh: Script principal que abre y organiza las ventanas
tools/instalar_wmctrl.sh: Script auxiliar para instalar la dependencia wmctrl
tools/abrir_roms_cuadricula.py: Versión alternativa en Python (requiere python3-xlib)

Características principales

Detección automática de ROMs: Busca todos los archivos .gb y .gbc en el directorio roms/
Filtrado inteligente de ventanas: Solo afecta ventanas con "ViboyColor" en el título y tamaño razonable (300-2000 píxeles de ancho)
Organización en cuadrícula: Distribuye las ventanas en 2 filas x 4 columnas con espaciado de 10 píxeles
Redimensionamiento estándar: Todas las ventanas se redimensionan a 480x480 píxeles para consistencia visual
Centrado automático: Calcula la posición inicial para centrar la cuadrícula en la pantalla
Protección contra errores: Verifica que wmctrl esté instalado y maneja casos donde las ventanas no se inicializan a tiempo

Decisiones de diseño

Filtrado por tamaño: Se implementó un filtro que excluye ventanas con ancho mayor a 2000 píxeles para evitar afectar ventanas grandes como editores de código o IDEs. Esto protege la ventana de Cursor y otras aplicaciones importantes.

Verificación de título: Antes de mover cada ventana, se verifica que el título contenga "ViboyColor" para asegurar que solo se afecten las ventanas del emulador y no otras aplicaciones Python que puedan estar ejecutándose.

Dimensiones estándar: Se usa un tamaño fijo de 480x480 píxeles en lugar de detectar el tamaño de cada ventana, ya que todas las instancias del emulador deberían tener el mismo tamaño cuando se inician.

Espera progresiva: El script espera 5 segundos después de abrir todas las ventanas y luego 3 segundos adicionales antes de intentar posicionarlas, dando tiempo suficiente para que Pygame inicialice completamente cada ventana.

Archivos Afectados

tools/abrir_roms_cuadricula.sh - Script principal (215 líneas)
tools/instalar_wmctrl.sh - Script auxiliar para instalación de dependencia
tools/abrir_roms_cuadricula.py - Versión alternativa en Python (requiere python3-xlib)

Tests y Verificación

La herramienta fue probada manualmente con las 8 ROMs disponibles en el directorio roms/:

ROMs probadas: mario.gbc, MortalKombat.gb, Oro.gbc, pkmn-amarillo.gb, pkmn.gb, tetris_dx.gbc, tetris.gb, zelda-dx.gbc
Verificación de posicionamiento: Todas las ventanas se organizaron correctamente en cuadrícula de 2 filas x 4 columnas
Verificación de filtrado: La ventana de Cursor (3440x1342) fue correctamente excluida del posicionamiento
Verificación de redimensionamiento: Todas las ventanas del emulador se redimensionaron a 480x480 píxeles
Coordenadas correctas: Todas las coordenadas calculadas fueron positivas y bien distribuidas en la pantalla

Comando de prueba:

bash tools/abrir_roms_cuadricula.sh

Resultado esperado: 8 ventanas del emulador organizadas en cuadrícula, sin afectar otras ventanas del sistema.

Fuentes Consultadas

Documentación de wmctrl: https://linux.die.net/man/1/wmctrl
Pygame Display Modes: Documentación oficial de Pygame sobre set_mode() y dimensiones de ventana

Nota: Esta es una herramienta de desarrollo, no implementa funcionalidad de hardware del Game Boy.

Integridad Educativa

Lo que Entiendo Ahora

Gestor de ventanas X11: wmctrl permite manipular ventanas de forma programática en entornos Linux con X11, permitiendo mover, redimensionar y obtener información de ventanas.
Filtrado de ventanas: Es importante filtrar ventanas por tamaño y título para evitar afectar aplicaciones no deseadas cuando se automatiza la manipulación de ventanas.
Timing de inicialización: Las ventanas de Pygame necesitan tiempo para inicializarse completamente antes de poder ser manipuladas por herramientas externas como wmctrl.

Lo que Falta Confirmar

Compatibilidad con otros gestores de ventanas: El script está probado con el gestor de ventanas actual, pero podría necesitar ajustes para otros entornos (GNOME, KDE, etc.).
Manejo de múltiples monitores: El script actualmente calcula posiciones basándose en un solo monitor, podría necesitar mejoras para sistemas multi-monitor.

Hipótesis y Suposiciones

Se asume que todas las instancias del emulador tienen el mismo tamaño de ventana cuando se inician (480x480 píxeles). Si esto cambia en el futuro, el script necesitaría ajustes.

Próximos Pasos

[ ] Considerar agregar opciones de línea de comandos para personalizar el layout (número de filas/columnas, tamaño de ventana, espaciado)
[ ] Mejorar el manejo de múltiples monitores si es necesario
[ ] Agregar soporte para cerrar todas las ventanas automáticamente después de un timeout opcional