Temporary Hack: Force Visible Palette (BGP)

Summary

A temporary hack was implemented in the MMU to intercept writes to the BGP register (Background Palette, 0xFF47) and force the value 0xE4 (standard Game Boy palette) when the game tries to write 0x00 (all white palette). This hack allows you to display graphics while investigating why some games (especially Dual Mode CGB/DMG like Tetris DX) write 0x00 to BGP, making the entire screen white and invisible. The hack is temporary and is explicitly documented as a diagnostic measure.

Hardware Concept

The recordBGP (Background Palette, 0xFF47)controls the 4 shades of gray color palette used to render the background and window on the original Game Boy (DMG). Each pair of bits in the BGP register maps a color index (0-3) to one of the 4 available shades of gray:

• Bits 0-1:Color for index 0 (usually white)
• Bits 2-3:Color for index 1 (usually light gray)
• Bits 4-5:Color for index 2 (usually dark gray)
• Bits 6-7:Color for index 3 (usually black)

The value0xE4 (11100100 in binary)It is the standard palette left by the Boot ROM:

• Index 0 → Color 0 (White)
• Index 1 → Color 1 (Light Gray)
• Index 2 → Color 2 (Dark Grey)
• Index 3 → Color 3 (Black)

The value0x00 (00000000 in binary)maps all indices to color 0 (white), making the entire screen white and invisible. Some Dual Mode (CGB/DMG) games write 0x00 to BGP during initialization, possibly because they expect to use CGB palettes or because their initialization code is not fully adapted for DMG mode.

Fountain:Pan Docs - BGP Register (Background Palette)

Implementation

Added an intercept in the methodwrite_byte()of the MMU that detects when the game tries to write 0x00 to BGP and automatically replaces it with 0xE4, forcing a visible palette.

Components created/modified

• MMU (`src/memory/mmu.py`): Added an interception inwrite_byte()which detects writes to 0xFF47 (BGP) and, if the value is 0x00, replaces it with 0xE4. A warning is recorded in the log for diagnosis.

Design decisions

Explicit temporary hack:The code is clearly marked as "TEMPORARY HACK" with extensive comments explaining why it exists and that it should be removed when full support for CGB is implemented. This maintains the educational integrity of the project.

Diagnostic logging:Every time the hack is activated, a warning is recorded in the log with the message "🔥 HACK: Forcing BGP 0x00 -> 0xE4 for visibility". This allows you to track when and how often the game attempts to write 0x00 to BGP.

Interception at MMU:The hack is implemented in the MMU because it is the central point where all memory writes happen. This ensures that no write to BGP escapes the hack, regardless of where it originates in the emulator code.

Does not affect other scripts:The hack only intercepts 0x00 writes to BGP. Any other value (including 0xE4) is written normally, allowing the game to set its own palette if you write a valid value.

Affected Files

• src/memory/mmu.py- Added write interception to BGP (0xFF47) to force 0xE4 when trying to write 0x00

Tests and Verification

This hack was validated by running the emulator with Tetris DX (user-contributed ROM, not distributed) and verifying that the graphics are visible on the screen.

• Test ROM:Tetris DX (user-contributed ROM, not distributed)
• Execution mode:UI with logging enabled
• Success Criterion:Graphics must be visible on screen (not white or blue screen)
• Expected observation:The log should show messages "🔥 HACK: Forcing BGP 0x00 -> 0xE4" when the game tries to write 0x00 to BGP
• Result: draft- Pending verification with actual emulator execution

Legal note:The Tetris DX ROM is provided by the user for local testing. It is not distributed or included in the repository.

Sources consulted

• Bread Docs:BGP Register (Background Palette)
• Bread Docs:Power-Up Sequence(BGP initialization by Boot ROM)

Educational Integrity

Next Steps

• [ ] Run the emulator with Tetris DX and verify that the graphics are visible
• [ ] Check the logs to confirm that the hack is triggered when the game tries to write 0x00 to BGP
• [ ] Investigate why the game writes 0x00 in BGP (possible incompatibility with CGB/DMG mode)
• [ ] When full CGB support is implemented, remove this hack and allow the game to configure its own palette
• [ ] Document the expected behavior of BGP in Dual Mode games