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

Run MBC + Headless RAW Classification with Evidence

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

Summary

Execution of complete classification of ROMs by MBC type and headless analysis with RAW evidence. It was executedrom_info_0450.pyabout all the ROMs available to classify MBCs, ran headless RAW with MBC writes for 4 key ROMs (mario.gbc, pkmn.gb, tetris.gb, tetris_dx.gbc), and a final table was generated with complete metrics (cart_type, MBC, supported, mbc_writes, pc_end, vram_raw_nz, nonwhite).Key finding:All MBCs are supported (MBC1, MBC3, MBC5) and MBC writes are detected correctly, but the VRAM remains empty and the framebuffer white, suggesting a ROM mapping problem or another component (PPU/pallets).

Hardware Concept

TheMemory Bank Controllers (MBC)They are chips in Game Boy cartridges that allow access ROMs larger than 32KB throughbank switching. The Game Boy has an address space 16-bit (64KB), but games can be 128KB, 256KB, 512KB or more. MBCs map different ROM "banks" in the range 0x0000-0x7FFF based on commands written by the game.

Common MBC Types:

  • MBC1:Up to 2MB ROM, 32KB RAM optional. Banking via writes to 0x2000-0x7FFF.
  • MBC3:Similar to MBC1, but with support for RTC (Real-Time Clock).
  • MBC5:Up to 8MB ROM, 128KB RAM optional. Simpler banking (9 bits for ROM bank).

Diagnosis of MBC:If a game writes to MBC ranges (0x0000-0x7FFF) but the content read from 0x4000-0x7FFF does not change, there is a mapping problem. If VRAM remains empty after of writes MBC, the code that loads tiles may be in a ROM bank that is not being mapped correctly.

Fountain:Pan Docs - "Memory Bank Controllers (MBC1/MBC3/MBC5)"

Implementation

Three phases of the plan were executed:

Phase A: ROM Classification

It was executedtools/rom_info_0450.pyabout all ROMs available to sort by cartridge type (0x0147), MBC name, and CGB flag. Results:

  • Distribution of MBCs:2 MBC1, 2 MBC3, 3 MBC5, 1 None
  • Medium:All ROMs have MBC supported (8/8 yes)

Phase B: Headless RAW with MBC Writes

Created and executedtools/run_headless_raw_0451.shto run headless on 4 key ROMs (mario.gbc, pkmn.gb, tetris.gb, tetris_dx.gbc) for 240 frames each, capturing:

  • pc_end: Last PC of the final summary
  • vram_nonzero_raw: Non-zero bytes in VRAM usingread_raw()
  • nonwhite_pixels: Non-white pixels in framebuffer
  • mbc_write_count: Total MBC writes detected
  • Last 8 MBC writes (addr, val, pc)

Phase C: Final Table + Automatic Decision

was createdtools/generate_mbc_table_0451.shto generate a comparison table with all the metrics and apply automatic decision rules. The table includes:

  • ROM | cart_type | MBC | supported | mbc_writes | pc_end | vram_raw_nz | nonwhite | conclusion

Key Results

ROM MBC mbc_writes pc_end vram_raw_nz nonwhite Conclusion
mario.gbc MBC5 238 0x12C1 0 0 MBC supported but incorrect mapping
pkmn.gb MBC3 1034 0x6151 0 0 MBC supported but incorrect mapping
tetris.gb None 1 0x036C 0 0 ROM_ONLY: not MBC
tetris_dx.gbc MBC1 17 0x0283 0 0 MBC supported but incorrect mapping

Automatic Decision

The table shows thatall MBCs are supportedand MBC writes are detected correctly, but the VRAM remains empty and the framebuffer white. This suggests that:

  • NO missing MBC support:MBC1, MBC3 and MBC5 are implemented and writes are processed.
  • Mapping or child component problem:The code that loads tiles can be in a ROM bank that it is not mapping correctly, or there is a problem in PPU/palettes that prevents rendering.

Conclusion:No new MBC is implemented in this Step. The next step should investigate the ROM mapping (verify that the banks are mapped correctly after MBC writes) or the PPU/paddles component.

Affected Files

  • tools/run_headless_raw_0451.sh- Script to run headless RAW on 4 key ROMs
  • tools/generate_mbc_table_0451.sh- Script to generate final table with metrics and automatic decision
  • /tmp/viboy_0451/rom_info_all.txt- ROM sorting output
  • /tmp/viboy_0451/headless/*.txt- Headless logs for each ROM
  • /tmp/viboy_0451/mbc_table_final.txt- Final table with metrics and conclusions

Tests and Verification

ROM classification: 

$ python3 tools/rom_info_0450.py roms/*.gb roms/*.gbc
ROM | cart_type(hex) | MBC name | CGB flag | supported
----|----------------|----------|----------|----------
MortalKombat.gb | 0x01 | MBC1 | 0x00(DMG) | yes
pkmn-amarillo.gb | 0x1B | MBC5 | 0x80(CGB) | yes
pkmn.gb | 0x13 | MBC3 | 0x00(DMG) | yes
tetris.gb | 0x00 | None | 0x00(DMG) | yes
mario.gbc | 0x1B | MBC5 | 0xC0(CGB) | yes
Gold.gbc | 0x10 | MBC3 | 0x80(CGB) | yes
tetris_dx.gbc | 0x03 | MBC1 | 0x80(CGB) | yes
zelda-dx.gbc | 0x1B | MBC5 | 0x80(CGB) | Yeah

Headless RAW executed: 

$bash tools/run_headless_raw_0451.sh
[OK] mario.gbc completed
[OK] pkmn.gb completed
[OK] tetris.gb completed
[OK] tetris_dx.gbc completed

Final table generated: 

$bash tools/generate_mbc_table_0451.sh
ROM | cart_type | MBC | supported | mbc_writes | pc_end | vram_raw_nz | nonwhite | conclusion
----|-----------|-----|-----------|------------|--------|-------------|----------|-----------
mario.gbc | 0x1B | MBC5 | yes | 238 | 0x12C1 | 0 | 0 | MBC supported but incorrect mapping
pkmn.gb | 0x13 | MBC3 | yes | 1034 | 0x6151 | 0 | 0 | MBC supported but incorrect mapping
tetris.gb | 0x00 | None | yes | 1 | 0x036C | 0 | 0 | ROM_ONLY: not MBC
tetris_dx.gbc | 0x03 | MBC1 | yes | 17 | 0x0283 | 0 | 0 | MBC supported but incorrect mapping

Validation:All scripts ran correctly and generated numerical evidence for diagnosis. The results show that the problem is NOT a lack of MBC support, but rather a problem mapping or secondary component (PPU/pallets).

Sources consulted

  • Pan Docs: "Memory Bank Controllers (MBC1/MBC3/MBC5)"
  • Pan Docs: "Cartridge Header (0x0100-0x014F)"
  • Step 0450: Real Triage "I Don't See Graphics" - MBC Required + Raw VRAM

Educational Integrity

What I Understand Now

  • MBC Classification:Cartridge types (0x0147) determine which MBC each ROM uses. The distribution in our set is: 2 MBC1, 2 MBC3, 3 MBC5, 1 None.
  • MBC Write Detection:Writes to MBC ranges (0x0000-0x7FFF) are detected correctly through counters in MMU. The games write frequently (238 writes in mario.gbc, 1034 in pkmn.gb).
  • Mapping problem:Although MBC writes are detected, the VRAM remains empty, suggesting that the code that loads tiles is in a ROM bank that is not being mapped correctly, or there is a problem in PPU/pallets.

What remains to be confirmed

  • Mapping ROM after MBC writes:Verify that after an MBC write, the content read from 0x4000-0x7FFF changes correctly depending on the bank selected.
  • ROM bank where the tile loading code is:Identify which ROM bank There is the code that loads tiles into VRAM and verify that that bank is mapped correctly.
  • PPU component/pallets:If the VRAM has data but the framebuffer is blank, there may be a problem in rendering or palettes.

Hypotheses and Assumptions

Main hypothesis:The problem is NOT a lack of MBC support, but a bug in the ROM mapping or in the PPU/pallets component. MBC writes are processed, but the mapped content does not change correctly, or the code that loads tiles is not executed because it is in an unmapped bank.

Assumption:The MBCs are implemented correctly in MMU.cpp (MBC1, MBC3, MBC5), but there may be a bug inupdate_bank_mapping()or how it is read from the mapped banks.

Next Steps

  • [ ] Step 0452:Investigate ROM mapping - Verify that after MBC writes, the content read from 0x4000-0x7FFF changes correctly. Add reading logs from mapped banks.
  • [ ] Step 0453:Identify ROM bank from tile loading code - Track which bank ROM is the code that loads tiles into VRAM and verify that that bank is mapped correctly.
  • [ ] Step 0454:If mapping is correct, investigate PPU component/pallets - Verify that rendering and palettes work correctly when VRAM has data.