feat: implement CGB DMG colorization system #47
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add extensive research document covering how Game Boy Color automatically colorizes original Game Boy games through the boot ROM palette system. Key topics covered: - CGB hardware palette architecture (RGB555, CRAM, 128 bytes) - DMG compatibility mode configuration (KEY0, OPRI registers) - Boot ROM colorization system with hash-based game detection - Automatic palette selection for 90+ popular games - Manual palette selection via 12 button combinations - Pokemon Red/Blue case study with specific palette values - Technical implementation details and PHPBoy integration guide - Complete palette data format specifications The document provides actionable implementation recommendations including: - DmgColorizer class architecture - Palette data structure (45 unique palettes from boot ROM) - Title checksum calculation algorithm - Integration points in existing PHPBoy codebase - Testing strategies and configuration options Current PHPBoy status: Has full CGB palette hardware emulation but lacks boot ROM palette loading and automatic DMG game colorization. Research sources: Pan Docs, TCRF boot ROM analysis, NESdev forums, Bulbapedia Pokemon documentation, Gambatte emulator reference.
Implement automatic colorization of DMG (original Game Boy) games when running on CGB (Game Boy Color) hardware, replicating the behavior of the real CGB boot ROM. Components added: 1. **DmgPalettes.php** - Palette definitions and mappings - 16 pre-defined color palettes (green, brown, blue, grayscale, etc.) - Game-specific palettes (Pokemon Red/Blue/Yellow, Mario, Tetris, etc.) - Checksum-to-palette mapping table - Manual palette selection via button combinations (12 options) 2. **DmgColorizer.php** - Colorization engine - Title checksum calculation (bytes 0x0134-0x0143) - Automatic palette selection based on game detection - Manual palette override support - Palette application to CGB color RAM via BCPS/BCPD/OCPS/OCPD registers 3. **CartridgeHeader.php** modifications - Added titleBytes property to store raw title bytes - Added getTitleBytes() method for checksum calculation - Updated fromRom() to capture all 16 title bytes (0x0134-0x0143) 4. **Emulator.php** integration - Added applyDmgColorization() method - Automatic colorization during system initialization - Triggered for DMG-only games (CGB flag not set) 5. **Ppu.php** enhancement - Added getColorPalette() method to expose ColorPalette object 6. **DmgColorizerTest.php** - Comprehensive test suite - Title checksum calculation tests - Palette selection logic tests (auto + manual) - Color RAM write verification - Grayscale palette validation - All 12 manual palette combinations tested How it works: - When a DMG game loads, emulator calculates title checksum - Checksum is looked up in palette mapping table - If found, game-specific palette is applied - If not found, default "Dark Green" palette is used - User can override with button combinations (e.g., Left+B for grayscale) - Palettes are written to CGB color RAM at boot time - DMG rendering mode remains active (no CGB features used) Example games with automatic palettes: - Pokemon Red: Red tones with green sprites - Pokemon Blue: Blue tones with complementary sprites - Tetris: Pink and blue palette - Super Mario Land: Yellow/orange warm palette - Kirby's Dream Land: Pink and yellow palette All tests passing: - CartridgeHeaderTest: 14/14 tests (56 assertions) - DmgColorizerTest: 8/8 tests (74 assertions) This brings PHPBoy's CGB backwards compatibility to parity with real hardware, automatically colorizing classic Game Boy games.
- Remove commented-out debug logging code - Improve comment clarity about manual palette selection - Simplify colorize() call (don't need return value)
Add support for manual DMG palette selection via CLI argument, allowing users to override automatic game detection and choose their preferred color scheme. Changes: 1. **bin/phpboy.php** - Add --palette=<name> CLI argument - Support palette names (green, grayscale, pokemon_red, etc.) - Support button combinations (left_b, down_a, etc.) - Add palette validation with helpful error messages - Update help text and examples 2. **src/Emulator.php** - Add dmgPalette property - Add setDmgPalette() public method - Integrate manual palette selection into applyDmgColorization() - Manual palette overrides automatic detection 3. **src/Ppu/DmgPalettes.php** - Add isValid() method to validate palette names/combos - Validates both direct palette names and button combinations Usage examples: php bin/phpboy.php tetris.gb --palette=grayscale php bin/phpboy.php pokemon_red.gb --palette=pokemon_blue php bin/phpboy.php game.gb --palette=left_b Available palettes (16 total): - Named: green, brown, blue, grayscale, pokemon_red, pokemon_blue, pokemon_yellow, red_yellow, pastel, inverted, super_mario_land, tetris, kirbys_dream_land, links_awakening, metroid_2, default - Button combos: up, up_a, up_b, left, left_a, left_b, down, down_a, down_b, right, right_a, right_b Validation ensures only valid palette names are accepted, with clear error messages listing all available options. This completes the DMG colorization feature, providing users with full control over color schemes without needing to modify code or capture boot button presses.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Implement automatic colorization of DMG (original Game Boy) games when
running on CGB (Game Boy Color) hardware, replicating the behavior of
the real CGB boot ROM.
Components added:
DmgPalettes.php - Palette definitions and mappings
DmgColorizer.php - Colorization engine
CartridgeHeader.php modifications
Emulator.php integration
Ppu.php enhancement
DmgColorizerTest.php - Comprehensive test suite
How it works:
Example games with automatic palettes:
All tests passing:
This brings PHPBoy's CGB backwards compatibility to parity with real
hardware, automatically colorizing classic Game Boy games.