⚠️ Clean-Room / Educational

This project is educational and Open Source. No code is copied from other emulators. Implementation based solely on technical documentation and permitted tests.

Tool to Open ROMs in Grid

Date:2026-01-02 StepID:0448 State: VERIFIED

Summary

Created an automation tool to open multiple emulator ROMs in windows organized in a 2 row x 4 column grid. The tool useswmctrlto automatically position and resize emulator windows, making it easy to screenshot multiple ROMs running simultaneously. Includes smart filtering to exclude large windows (such as editors) and only affect emulator windows identified by the title "ViboyColor".

Hardware Concept

This tool does not implement hardware functionality of the Game Boy, but is a development utility to facilitate viewing and documentation of the emulator. Allows you to run multiple instances of the emulator simultaneously, each with a different ROM, visually organized for comparison and screenshot.

The emulator uses Pygame for the viewport, with standard dimensions of 480x480 pixels (3x scaling: original 160x144 pixels + title bar). The tool takes advantage of the capabilities of the Linux window manager (X11) throughwmctrlto manipulate the position and size of windows programmatically.

Implementation

The script was createdtools/abrir_roms_cuadricula.shwhich automates the process of opening and organizing emulator windows. The script implements the following functionalities:

Components created/modified

tools/abrir_roms_cuadricula.sh: Main script that opens and organizes windows
tools/install_wmctrl.sh: Helper script to install the wmctrl dependency
tools/abrir_roms_cuadricula.py: Alternative version in Python (requires python3-xlib)

Main features

Automatic ROM detection: Find all .gb and .gbc files in the directoryroms/
Smart window filtering: Only affects windows with "ViboyColor" in the title and reasonable size (300-2000 pixels wide)
Grid organization: Distributes the windows in 2 rows x 4 columns with 10 pixel spacing
Standard resizing: All windows are resized to 480x480 pixels for visual consistency
Automatic centering: Calculates the starting position to center the grid on the screen
Error protection: Verifies that wmctrl is installed and handles cases where windows do not initialize on time

Design decisions

Filter by size: A filter was implemented that excludes windows with a width greater than 2000 pixels to avoid affecting large windows such as code editors or IDEs. This protects the Cursor window and other important applications.

Title Verification: Before moving each window, the title is verified to contain "ViboyColor" to ensure that only the emulator windows are affected and not other Python applications that may be running.

Standard dimensions: A fixed size of 480x480 pixels is used instead of detecting the size of each window, since all emulator instances should be the same size when they start.

Progressive waiting: The script waits 5 seconds after opening all windows and then an additional 3 seconds before attempting to position them, giving enough time for Pygame to fully initialize each window.

Affected Files

tools/abrir_roms_cuadricula.sh- Main script (215 lines)
tools/install_wmctrl.sh- Auxiliary script for dependency installation
tools/abrir_roms_cuadricula.py- Alternative version in Python (requires python3-xlib)

Tests and Verification

The tool was tested manually with the 8 ROMs available in the directoryroms/:

Tested ROMs: mario.gbc, MortalKombat.gb, Oro.gbc, pkmn-amarillo.gb, pkmn.gb, tetris_dx.gbc, tetris.gb, zelda-dx.gbc
Positioning verification: All windows were correctly organized in a 2 row x 4 column grid
Filtering check: Cursor window (3440x1342) was correctly excluded from positioning
Resizing verification: All emulator windows were resized to 480x480 pixels
Correct coordinates: All calculated coordinates were positive and well distributed on the screen

test command:

bash tools/abrir_roms_cuadricula.sh

Expected result- 8 emulator windows organized in a grid, without affecting other system windows.

Sources consulted

wmctrl documentation:https://linux.die.net/man/1/wmctrl
Pygame Display Modes: Official Pygame documentation on set_mode() and window dimensions

Note: This is a development tool, it does not implement Game Boy hardware functionality.

Educational Integrity

What I Understand Now

X11 Window Manager: wmctrl allows you to manipulate windows programmatically in Linux environments with X11, allowing you to move, resize and obtain window information.
Window filtering: It is important to filter windows by size and title to avoid affecting unwanted applications when automating window manipulation.
Initialization timing: Pygame windows need time to fully initialize before they can be manipulated by external tools like wmctrl.

What remains to be confirmed

Compatibility with other window managers: The script is tested with the current window manager, but might need adjustments for other environments (GNOME, KDE, etc.).
Managing multiple monitors: The script currently calculates positions based on a single monitor, may need improvements for multi-monitor systems.

Hypotheses and Assumptions

All emulator instances are assumed to have the same window size when started (480x480 pixels). If this changes in the future, the script would need adjustments.

Next Steps

[ ] Consider adding command line options to customize the layout (number of rows/columns, window size, spacing)
[ ] Improve handling of multiple monitors if necessary
[ ] Add support to close all windows automatically after an optional timeout