{"id":45084696,"url":"https://github.com/eddmann/phpboy","last_synced_at":"2026-02-19T15:36:08.531Z","repository":{"id":323750479,"uuid":"1091708293","full_name":"eddmann/phpboy","owner":"eddmann","description":"Game Boy Color emulator written in PHP 8.4 with full DMG backward compatibility, high accuracy (100% Blargg pass rate), and multiple frontends (CLI terminal, WebAssembly browser, SDL2 desktop)","archived":false,"fork":false,"pushed_at":"2025-11-11T22:21:01.000Z","size":7289,"stargazers_count":2,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-11T23:25:00.043Z","etag":null,"topics":["cli","color-emulation","dmg","emulation","emulator","game-boy","gameboy","gameboy-color","gameboy-emulator","gbc","php","php8","php84","retro-gaming","sdl2","webassembly"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eddmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T12:01:24.000Z","updated_at":"2025-11-11T22:20:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/eddmann/phpboy","commit_stats":null,"previous_names":["eddmann/phpboy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/eddmann/phpboy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpboy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpboy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpboy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpboy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eddmann","download_url":"https://codeload.github.com/eddmann/phpboy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpboy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29620144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T13:04:20.082Z","status":"ssl_error","status_checked_at":"2026-02-19T13:03:33.775Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","color-emulation","dmg","emulation","emulator","game-boy","gameboy","gameboy-color","gameboy-emulator","gbc","php","php8","php84","retro-gaming","sdl2","webassembly"],"created_at":"2026-02-19T15:36:07.786Z","updated_at":"2026-02-19T15:36:08.524Z","avatar_url":"https://github.com/eddmann.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"docs/heading.png\" alt=\"PHPBoy - Game Boy Emulator\" /\u003e\r\n\u003c/p\u003e\r\n\r\nGame Boy Color emulator written in PHP 8.4. Includes CLI terminal frontend, browser WebAssembly frontend (WIP), and native SDL2 desktop (WIP).\r\n\r\n## Current Status\r\n\r\nGame Boy Color emulator with backward compatibility for DMG (original Game Boy) games:\r\n\r\n- ✅ CLI Terminal Frontend: Fully working, 25-30 FPS baseline, 60+ FPS with PHP JIT enabled\r\n- ✅ GBC Emulation: Complete CPU, PPU with color support, memory bus, input, and cartridge support (MBC1/MBC3/MBC5)\r\n- ✅ Color Support: Full GBC color palette system with 15-bit RGB color, background/sprite palettes, and palette RAM\r\n- ✅ DMG Compatibility: Full backward compatibility mode for original Game Boy games\r\n- ✅ Test Accuracy: Passes Blargg's CPU instruction tests (11/11)\r\n- ✅ Commercial ROMs: Tetris (GBC), Pokemon Red, Zelda DX run with color support\r\n- ✅ Browser (WASM): Renderer works but very slow due to WASM overhead\r\n- ✅ Audio: Full audio support in CLI terminal frontend using SoX\r\n- 🔄 Mooneye Test Suite: Working on full support (10/39 currently passing)\r\n- 🔄 Acid Tests: Working on dmg-acid2/cgb-acid2 support\r\n- 🔄 SDL2 Native Desktop: Work in progress\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"docs/cartridges.png\" alt=\"Supported Cartridges\" /\u003e\r\n\u003c/p\u003e\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cstrong\u003eThe Legend of Zelda: Link's Awakening DX\u003c/strong\u003e\u003cbr/\u003e\r\n  \u003cimg src=\"docs/zelda-cgb-1.png\" alt=\"Zelda DX gameplay\" width=\"400\" /\u003e\r\n  \u003cimg src=\"docs/zelda-cgb-2.png\" alt=\"Zelda DX gameplay\" width=\"400\" /\u003e\r\n\u003c/p\u003e\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cstrong\u003ePokemon Red - DMG vs CGB Colorization\u003c/strong\u003e\u003cbr/\u003e\r\n  \u003cimg src=\"docs/pokered-dmg-1.png\" alt=\"Pokemon Red DMG\" width=\"400\" /\u003e\r\n  \u003cimg src=\"docs/pokered-cgb-1.png\" alt=\"Pokemon Red CGB\" width=\"400\" /\u003e\r\n\u003c/p\u003e\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"docs/pokered-dmg-2.png\" alt=\"Pokemon Red DMG\" width=\"400\" /\u003e\r\n  \u003cimg src=\"docs/pokered-cgb-2.png\" alt=\"Pokemon Red CGB\" width=\"400\" /\u003e\r\n\u003c/p\u003e\r\n\r\n## Features\r\n\r\n- PHP 8.4: Uses strict types, readonly properties, enums, typed class constants, and property hooks\r\n- Performance: 60+ FPS with PHP JIT enabled\r\n- Game Boy Color Support:\r\n  - 15-bit RGB color system (32,768 colors)\r\n  - Background and sprite color palettes\r\n  - Color palette RAM with auto-increment\r\n  - VRAM bank switching\r\n  - DMG backward compatibility mode\r\n  - DMG Colorization: Automatic colorization of original Game Boy games using hardware-defined palettes\r\n- Multiple Frontends:\r\n  - CLI Terminal ✅: ANSI color rendering with audio support (SoX), primary frontend\r\n  - Browser (WebAssembly) ✅: Runs via php-wasm (slow performance, audio WIP)\r\n  - SDL2 Native Desktop 🔄: WIP\r\n- Test Coverage: Passes Blargg's CPU instruction tests (11/11)\r\n- Development: Docker-based workflow with PHPUnit 10 and PHPStan level 9\r\n- Architecture: Modular design with separate namespaces for CPU, PPU, APU, Bus, and Frontend\r\n\r\n## Requirements\r\n\r\n- Docker\r\n- Docker Compose\r\n- Make (for convenient task automation)\r\n- SoX (for audio playback in CLI mode) - install via `apt-get install sox` (Linux) or `brew install sox` (macOS)\r\n\r\n## Getting Started\r\n\r\n### Initial Setup\r\n\r\n1. Clone the repository:\r\n\r\n```bash\r\ngit clone https://github.com/eddmann/phpboy.git\r\ncd phpboy\r\n```\r\n\r\n2. Build the Docker image:\r\n\r\n```bash\r\nmake setup\r\n```\r\n\r\n3. Install PHP dependencies:\r\n\r\n```bash\r\nmake install\r\n```\r\n\r\n### Running Game Boy / Game Boy Color ROMs\r\n\r\nThe CLI terminal frontend is the primary way to run PHPBoy. It supports both DMG (original Game Boy) and GBC (Game Boy Color) ROMs with full audio support:\r\n\r\n```bash\r\n# Run with CLI frontend (JIT enabled by default for 60+ FPS)\r\nmake run ROM=path/to/rom.gb    # DMG games\r\nmake run ROM=path/to/rom.gbc   # GBC games\r\n\r\n# Run without JIT for baseline performance testing (25-30 FPS)\r\nmake run-no-jit ROM=path/to/rom.gb\r\n```\r\n\r\n**Note:** Audio playback requires SoX to be installed on your system. See Requirements section above.\r\n\r\nCLI Controls:\r\n\r\n- Arrow Keys: D-pad\r\n- Z: A button\r\n- X: B button\r\n- Enter: Start\r\n- Shift: Select\r\n- Q: Quit\r\n\r\n### Development Workflow\r\n\r\nAll development tasks are managed through the Makefile and run inside Docker containers.\r\n\r\n#### Available Commands\r\n\r\n- `make help` - Show available commands\r\n- `make setup` - Build Docker image with PHP 8.4\r\n- `make rebuild` - Rebuild Docker image from scratch (no cache)\r\n- `make install` - Install Composer dependencies in Docker\r\n- `make test` - Run PHPUnit tests in Docker\r\n- `make lint` - Run PHPStan static analysis in Docker\r\n- `make shell` - Open bash shell in Docker container\r\n- `make run ROM=path/to/rom.gb` - Run emulator with JIT enabled (60+ FPS) - supports .gb and .gbc files\r\n- `make run-no-jit ROM=path/to/rom.gb` - Run emulator without JIT (25-30 FPS baseline)\r\n- `make build-wasm` - Build WebAssembly version for browser\r\n- `make serve-wasm` - Serve WASM build locally on port 8080\r\n- `make clean` - Remove vendor directory and composer.lock\r\n- `make clean-docker` - Remove Docker containers and images\r\n\r\n#### Running Tests\r\n\r\n```bash\r\nmake test\r\n```\r\n\r\n#### Static Analysis\r\n\r\n```bash\r\nmake lint\r\n```\r\n\r\n#### Opening a Shell\r\n\r\nFor debugging or manual operations:\r\n\r\n```bash\r\nmake shell\r\n```\r\n\r\n## Performance\r\n\r\nPerformance with PHP 8.4's JIT compiler:\r\n\r\n- Baseline (no JIT): 25-30 FPS\r\n- With JIT enabled: 60+ FPS\r\n- Commercial ROMs: Tetris (GBC), Pokemon Red, Zelda DX run at target speed\r\n- GBC Mode: Color rendering included\r\n\r\nThe JIT compiler provides approximately 2-3x performance improvement.\r\n\r\n## Additional Frontends\r\n\r\n### Running in the Browser (WebAssembly)\r\n\r\nBrowser version via WebAssembly using [php-wasm](https://github.com/seanmorris/php-wasm).\r\n\r\nNote: WASM frontend has significant performance overhead. Audio is work in progress.\r\n\r\n#### Build for Browser\r\n\r\n1. Build the WASM distribution:\r\n\r\n```bash\r\nmake build-wasm\r\n```\r\n\r\n2. Serve locally:\r\n\r\n```bash\r\nmake serve-wasm\r\n```\r\n\r\n3. Open `http://localhost:8080` in your browser\r\n\r\n4. Load a ROM file and play!\r\n\r\nFeatures:\r\n\r\n- ✅ Runs in browser, no backend required\r\n- ✅ Keyboard controls, speed control, pause/resume\r\n- 🔄 Audio output integration in progress\r\n- ⚠️ Performance: Slow due to WASM overhead\r\n\r\nBrowser Requirements:\r\n\r\n- Chrome 90+, Firefox 88+, Safari 14+, or Edge 90+\r\n- WebAssembly support required\r\n\r\nDocumentation:\r\n\r\n- [WASM Build Guide](docs/wasm-build.md) - How to build and deploy\r\n- [Browser Usage Guide](docs/browser-usage.md) - How to use in browser\r\n- [WASM Options Evaluation](docs/wasm-options.md) - Technical decisions\r\n\r\n### Running with SDL2 Native Frontend (Work in Progress)\r\n\r\nExperimental native desktop rendering using SDL2.\r\n\r\nStatus: 🔄 Work in progress - code implemented but not fully tested/integrated.\r\n\r\nDocumentation:\r\n\r\n- [SDL2 Setup Guide](docs/sdl2-setup.md) - Installation instructions\r\n- [SDL2 Usage Guide](docs/sdl2-usage.md) - Usage and customization\r\n\r\n## Testing \u0026 Accuracy\r\n\r\nTest ROM results:\r\n\r\n### Test Suite Results\r\n\r\n- ✅ Blargg's CPU Instruction Tests: 11/11 passing (100%)\r\n  - `cpu_instrs` - All CPU instructions validated\r\n  - `instr_timing` - Instruction timing accuracy verified\r\n- 🔄 Mooneye Test Suite: 10/39 passing - working on full support\r\n  - Focus on improving timing accuracy for remaining tests\r\n- 🔄 Acid Tests: Working on dmg-acid2/cgb-acid2 support\r\n  - PPU rendering accuracy improvements in progress\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"cgb-acid2-result.png\" alt=\"cgb-acid2 test result\" width=\"320\" /\u003e\r\n\u003c/p\u003e\r\n\r\nSee `docs/test-results.md` for detailed test results.\r\n\r\n## License\r\n\r\n[MIT License](LICENSE)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddmann%2Fphpboy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddmann%2Fphpboy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddmann%2Fphpboy/lists"}