Step 0460: Fix Insufficient Setup Test - Full Tilemap

Summary

Aim:Diagnose and fix the "insufficient test setup" issue that caused palette tests to fail with only 2 unique colors instead of ≥4. Steps 0458 and 0459 confirmed that the PPU reads VRAM correctly and that the conversion pipeline works well when receiving varying indices. The real problem was that the tilemap was almost empty (only 1 entry written), which caused most of the BG to use default tiles that only produced indices {0, 2}.

Confirmed diagnosis:The global index framebuffer showed only {0, 2} on most of the screen because the tilemap only had 1 written entry (tile 0 at position 0,0). The rest of the tilemap was uninitialized, using default tiles that only produced indices 0 and 2.

Applied solution:Completely fill the tilemap (32×32 = 1024 bytes) with tile 0 that has the pattern 0x55/0x33 that guarantees indexes {0, 1, 2, 3}. This ensures that the entire visible screen uses the tile with 4 different indices.

Result:✅ BGP and Not Flat tests pass (2 of 3 objective tests). The OBJ test has a known issue with palette conversion for sprites that is outside the scope of this plan (correct indices {1, 3}, but RGB collapses to (0,0,0)).

Hardware Concept

BG Tilemap on Game Boy

The Background Tilemap is a table of 32x32 tiles (1024 bytes) that defines which tile is rendered at each background position. Each byte of the tilemap contains the index of the tile (0-255) that should be rendered at that position.

Direcciones del Tilemap:

• 0x9800-0x9BFF:Base tilemap (LCDC bit 3 = 0)
• 0x9C00-0x9FFF:Alternate tilemap (LCDC bit 3 = 1)

Insufficient Setup Problem:If only 1 entry is written to the tilemap (e.g. tile 0 at position 0.0), the rest of the tilemap remains uninitialized. When the PPU renders the BG, it reads default tiles (usually 0x00) that only produce indices {0, 2}, causing the framebuffer to have only 2 unique colors on most of the screen.

Solution:Completely fill the tilemap (32×32 = 1024 bytes) with the desired tile to ensure that the entire visible screen uses the same tile with 4 different indexes.

Fountain:Pan Docs - "LCD Control Register" (LCDC bit 3) and "Tile Maps"

Implementation

Phase A: Pre-Change Confirmation

Added diagnostics to the BGP test to verify the framebuffer's global unique index set. This confirmed that the problem was insufficient setup (almost empty tilemap).

# Calculate unique indices on the entire framebuffer (not just first pixels)
unique_idx_set = set()
for i in range(min(23040, len(indices_buffer))): # Entire screen
    unique_idx_set.add(indices_buffer[i] & 0x03)

print(f"[TEST-PRE-CHANGE] Unique idx set global: {unique_idx_set}")

# If we only see {0, 2} or similar, confirm that the problem is almost empty tilemap
if len(unique_idx_set)< 3:
    print(f"⚠️ CONFIRMADO: Tilemap casi vacío. Solo índices {unique_idx_set} en pantalla completa.")

Phase B: BG Setup Fix (BGP Palette)

Modified the BGP test to write complete tile data and fill the entire tilemap (32×32 = 1024 bytes).

# Write complete tile data with pattern 0x55/0x33
tile_index = 0
tile_base_addr = 0x8000 + (tile_index * 16)

for row in range(8):
    addr_low = tile_base_addr + (row * 2)
    addr_high = addr_low + 1
    mmu.write(addr_low, 0x55)
    mmu.write(addr_high, 0x33)

# Fill entire tilemap (32×32 = 1024 bytes)
tilemap_base = 0x9800
for i in range(32 * 32): # 1024 bytes (32×32 tiles)
    mmu.write(tilemap_base + i, tile_index)

Phase C: OBJ Setup Fix (OBP0/OBP1 Palette)

Modified the OBJ test to use the same tile (tile 0) with pattern 0x55/0x33 that guarantees indexes {0, 1, 2, 3}.

Phase D: Adjustment of the "Not Flat" Test

Modified the Not Flat test to reuse the same BG setup (full tile data + full tilemap) and require ≥4 unique colors instead of ≥3.

Sampling Changes

Changed 16x16 grid sampling to first 100 pixels sampling to better capture the 0,1,2,3 repeating pattern.

Affected Files

• tests/test_palette_dmg_bgp_0454.py- BG setup fix: full tile data + full tilemap (32×32)
• tests/test_palette_dmg_obj_0454.py- OBJ setup fix: use the same tile with pattern 0x55/0x33
• tests/test_framebuffer_not_flat_0456.py- Adjustment: reuse entire setup and require ≥4 unique colors

Tests and Verification

Objective tests executed:

• test_palette_dmg_bgp_0454.py::test_dmg_bgp_palette_mapping- ✅ PASSED
• test_framebuffer_not_flat_0456.py::test_framebuffer_not_flat- ✅ PASSED
• test_palette_dmg_obj_0454.py::test_dmg_obj_palette_mapping- ⚠️ FAILED (known issue with palette conversion for sprites, outside the scope of this plan)

Pre-change evidence:

[TEST-PRE-CHANGE] Unique idx set global: {0, 2}
⚠️ CONFIRMED: Tilemap almost empty. Only indices {0, 2} in full screen.
   This explains why unique_rgb_count< 3: la mayoría del BG usa tiles default.

Post-change evidence:

[TEST-BG-SETUP] Tile data written: tile 0 at 0x8000
[TEST-BG-SETUP] Tilemap filled: 32×32 = 1024 bytes with tile 0
[TEST-BG-SETUP] Unique idx set global after filling tilemap: {0, 1, 2, 3}
[TEST-BG-SETUP] Unique RGB colors (first 100 pixels): 4
[TEST-BG-SETUP] Unique colors found: {(170, 170, 170), (85, 85, 85), (255, 255, 255), (0, 0, 0)}

Compiled C++ module validation:✅ Successful build without errors.

Sources consulted

• Pan Docs: "LCD Control Register" (LCDC bit 3) - Tile Map selection
• Pan Docs: "Tile Maps" - Background tilemap addressing
• Pan Docs: "Color Palettes" (DMG) - BGP register mapping

Educational Integrity

Next Steps

• [ ] Investigate and correct the problem of palette conversion for sprites (OBJ test)
• [ ] Verify that the tilemap fills correctly in other tests that use BG
• [ ] Consider creating a helper function to fill the entire tilemap in tests