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

Correction of Debug Palette Indexes 1 and 2

Date:2025-12-25 StepID:0303 State: VERIFIED

Summary

Correction of all debug palettes in the renderer that use green colors for indexes 1 and 2, changing them to true grays to eliminate the green streaks that appear when the framebuffer contains values 1 or 2. Identified and corrected 4 locations where palettes with green values are defined.

Result: Corrected the values of indexes 1 and 2 in all debug palettes, changing from green to true gray. This will remove visual green streaks when the framebuffer has values 1 or 2, displaying them as light gray and dark gray respectively.

Hardware Concept

Color Palette on Game Boy

The PPU framebuffer containscolor indices(0-3), not RGB colors directly. The renderer must convert these indices to RGB colors using a palette. The standard Game Boy palette (greyscale) uses:

  • Color 0: White(255, 255, 255)- the clearest
  • Color 1: Light gray(170, 170, 170)
  • Color 2: Dark gray(85, 85, 85)
  • Color 3: Black(0, 0, 0)- the darkest

These values are standard in emulation and provide the correct contrast for display in gray scale.

Debug Palette vs Real Palette

The debug palette is a diagnostic tool that maps indexes to fixed colors to display the contents of the framebuffer without going through the hardware palettes (BGP/OBP). You must use the same values than the standard palette for correct representation. If the debug palette uses incorrect colors (such as green instead of gray), any value in the framebuffer with that index will be displayed incorrectly.

Fountain: Pan Docs - "Background Palette (BGP)", "Object Palette (OBP)", "Palette"

Implementation

4 locations were identified where debug palettes are defined with green values for indexes 1 and 2, and were corrected by changing them to true grays according to the constantPALETTE_GREYSCALE.

Fixed Locations

  1. self.COLORSin__init__()(lines 192-193):
    • Index 1:(136, 192, 112) → (170, 170, 170)
    • Index 2:(52, 104, 86) → (85, 85, 85)
  2. render_frame()with PPU C++(lines 494-499):
    • Index 1:(136, 192, 112) → (170, 170, 170)
    • Index 2:(52, 104, 86) → (85, 85, 85)
  3. render_frame()Python method(lines 579-584):
    • Index 1:(136, 192, 112) → (170, 170, 170)
    • Index 2:(52, 104, 86) → (85, 85, 85)
  4. render_sprites()(lines 955-960):
    • Index 1:(136, 192, 112) → (170, 170, 170)
    • Index 2:(52, 104, 86) → (85, 85, 85)

Correct Values

All corrected values ​​coincide with the constantPALETTE_GREYSCALEdefined in the module (lines 53-58):

PALETTE_GREYSCALE = [
    (255, 255, 255), # Color 0: White
    (170, 170, 170), # Color 1: Light Gray
    (85, 85, 85), # Color 2: Dark Gray
    (0, 0, 0), # Color 3: Black
]

Consistency

All debug palettes now use the same values ​​for visual consistency. The comments They have also been updated to reflect that they are now true grey, not green.

Affected Files

  • src/gpu/renderer.py- Corrected 4 pallet locations (lines 192-193, 494-499, 579-584, 955-960)
  • docs/bitacora/entries/2025-12-25__0303__correccion-paleta-debug-indices-1-2.html- This entry (new)
  • docs/bitacora/index.html- Updated with entry 0303
  • REPORT_PHASE_2.md- Updated with Step 0303

Tests and Verification

The correction is purely visual and does not require unit tests. However, it is recommended:

  • Visual verification: Run the emulator for 5-10 minutes to verify that the green stripes do not appear
  • Code inspection: Verify that all palettes use consistent values

Suggested check command: 

python main.py roms/pkmn.gb

Validation: Visual confirmation that:

  • Pixels with index 0 are displayed in white
  • Pixels with index 1 are displayed in light gray (not green)
  • Pixels with index 2 are displayed in dark gray (not green)
  • No green streaks after several minutes

Sources consulted

  • Pan Docs: "Background Palette (BGP)", "Object Palette (OBP)", "Palette"
  • Step 0302: Identify the green palette problem for indexes 1 and 2

Educational Integrity

What I Understand Now

  • debug palette: You must use values ​​consistent with the standard palette (greyscale) for correct representation. Green colors are incorrect and cause visual confusion.
  • Index Mapping: The framebuffer contains indices (0-3), not RGB colors. The renderer maps these indices to RGB colors using a palette. If the palette is incorrect, the display will be incorrect.
  • Consistency: All debug palettes should use the same values ​​for visual consistency between background, sprites and different rendering methods.
  • Visual bug fixes: Visual bugs can be caused by problems in the mapping palette, not necessarily in the framebuffer or rendering logic.

What remains to be confirmed

  • Correction effectiveness: Whether this fix completely removes the green streaks after 5-10 minutes of running (visual check pending).
  • framebuffer root cause: Why the framebuffer starts having values ​​of 1 or 2 after ~5 minutes (this was not fixed, just the display).

Hypotheses and Assumptions

Main hypothesis: The green stripes will disappear after this correction because now framebuffer values 1 and 2 will be displayed as true gray, not green. This hypothesis is based on:

  • Step 0302 monitors showed that the palette never changes during the run
  • The visual problem (green stripes) appeared when the framebuffer had values ​​1 or 2
  • The debug palette used green colors for indexes 1 and 2

Assumptions:

  • The framebuffer will still have values ​​of 1 or 2 after ~5 minutes (this was not fixed)
  • Values ​​1 and 2 are correct and only needed to be displayed as gray, not green

Next Steps

  • [ ] Extended visual verification: Run the emulator for 10+ minutes to verify that the green stripes do not appear
  • [ ] If the stripes disappear: Continue with other emulator functionalities
  • [ ] If problems persist: Investigate why the framebuffer changes values ​​(Step 0304/0305)