This was just a hobby project that I started for fun, but was not able to put much effort because of my busy schedule.
But still, the emulator tries to be as accurate as possible but since I don't have the actual hardware for any of the systems that I am trying to emulate, I was completely relying on other's research that I could readily find on discord, blogposts or other emulator specific wiki pages for implementing the corner cases. I personally have done very minimal 'original research' for these platforms.
I have avoided referencing other emulator's source code and tried to only rely on online information as much as possible, but still had to rely on a few cycle accurate emulators (mentioned in credit section below) and tweak them to either extract debug logs or to run my own custom roms and analyse the behaviour.
Note : The source code will be made open-source soon (once the code cleanup is complete)
So, what is Masquerade ?
A multi-system emulator which emulates the following gaming consoles and simulators
- Game Boy Advance (GBA)
- Game Boy Color (GBC)
- Game Boy (GB)
- Nintendo Entertainment System (NES)
- Ms Pacman
- Pacman (supports both Midway and Namco versions)
- Space Invaders
- CHIP8
- S-CHIP
- XO-CHIP
- Game Of Life
Below mentioned gaming consoles MAY PROBABLY be looked at in the future
- Super Nintendo Entertainment System (SNES)
- Nintendo DS
- Nintendo 3DS
Supported features
- GBA
- Supports GBA Bios
- GBA passes jsmolka/alysoha-tas's arm.gba, thumb.gba, memory.gba, flash and PPU tests
- GBA passes FuzzARM.gba
- GBA passes all the tests within the AGS suite except for Prefetch and Wait Cycles based memory tests
- GBA passes the tonc's test suite
- GB / GBC
- Supports GB and GBC Bios
- GB / GBC supports NO MBC, MBC1, MBC2, MBC3, MBC5 and MBC30
- GB / GBC implements Pixel Fetcher/FIFO
- GBC supports GB mode
- GB / GBC passes the complete Tom Harte's CPU test (both official and un-official opcodes)
- GB / GBC passes the all the Blargg test suite except for the following
- oam bug.gb
- GB / GBC passes all of the Moon Eye tests except for the following:
- intr_2_mode0_timing_sprites.gb
- lcdon_timing-GS.gb
- lcdon_write_timing-GS.gb
- halt_ime1_timing2-GS.gb
- di_timing-GS.gb
- hblank_ly_scx_timing-GS.gb
- GB passes all the PeachyHardwareAbuse tests including CTF.gb
- GB / GBC passes DMG Aging Catridge test
- GB / GBC passes the rtc3test suite
- GB / GBC passes all the scribbltests suite except for the following
- Few nops in statcount.gb
- GB / GBC passes the TurtleTests
- GBC passes MagenTests
- GB / GBC passes mbc3-tester
- GB / GBC is able to play severaldemo scenes including notable ones like oh.gb, 20y.gb, pocket.gb and demotronic.gbc
- GB supports multiple palettes
- GBC support color correction to be more in line with the actual HW
- NES
- NES supports NROM, MMC1, UxROM (002), CNROM, MMC3, AxROM and GxROM
- NES supports Zapper in Port 2 (using mouse clicks)
- NES passes Nestest (both official and un-official opcodes)
- NES passes the complete Tom Harte's CPU test (both official and un-official opcodes)
- NES passes the Blargg CPU tests (both official and un-official opcodes)
- NES passes the Blargg's CPU timing tests (both official and un-official opcodes)
- NES passes the Blargg's CPU dummy read/write tests (both official and un-official opcodes)
- NES passes all CPU tests mentioned in Nes Dev Wiki (both official and un-official opcodes)
- NES passes the blargg_ppu_tests_2005.09.15b tests
- NES passes the blargg_apu_2005.07.30 tests
- NES passes the Blargg's sprite_overflow_test suite
- NES passes the Blargg's sprite_hit_tests_2005.10.05 test suite
- NES passes all APU tests except for DMC tests
- NES passes Blargg's vbl_nmi_timing and ppu_vbl_nmi tests
- NES passes Blargg's cpu_interrupt_v2 tests
- NES passes the OAM stress tests
- NES passes both Blargg's / Bisqwit's ppu_open_bus tests
- NES passes Bisqwit's cpu_exec_space tests
- NES passes the Blargg's mmc3_irq_tests suite
- NES passes all of Blargg's mmc3_test/mmc3_test_2 expect for 4-scanline_timing.nes
- Pacman and MsPacman
- Supports both Midway and Namco variants
- Also tested again the following boot-legs
- Hangly Man
StreakingTitanCaterpillarAbscamJoymanPiranhaGalaxian Hardware Variant- Uniprom Variant
- Baracuda
- NewPuc
- After Dark
- Snatcher Set 1 and 2
- Supports MsPacman
- Also tested again the following boot-legs
MsPacPlusAfter DarkMsPacAttackNewMsPacAtackOld
- Space Invader
- Supports color overlays
- Supports many Z80 test roms (Undocumented Opcode Tests are still not handled)
- Supports many c6502 test roms (both official and un-official opcodes)
- Supports many 8080 test roms (Undocumented Opcode Tests are still not handled)
- Chip8
- Chip8 supports CHIP8, S-CHIP and XO-CHIP modes
- Chip8 passes all Timendus's chip8-test-suite v4.0 (Most of v4.2 tests pass as well except for scrolling tests which is not implemented yet)
- Game Of Life supports Normal Mode and Torroidal Mode
- Supports Save States and Load States
- Supports OTA updates
- Supports dynamic drag and drop of roms. This includes multiple rom files for Space Invaders and Pacman/MsPacman
Known Major Issues/Features under Debug/Implementation
- GBA still doesn't support audio output (only GB/GBC based APU is implemented)
- NES still doesn't support audio output (APU is implemented except for DMC)
Other Issues/Features under Debug/Implementation
- Support Link Cable for Gameboy and Gameboy Color
- Support for scrolling test needed by Timendus's chip8-test-suite v4.2
- Deviation of CGB's STAT timings w.r.t DMG is yet to be emulated
Other Known Issues
- GBA still fails a lot of 'Wait Cycles' and 'Catridge Prefetch' (this is not even implemented yet) based tests present in AGS and mgba test-suite
- GBA not so often / rarely exibits few minor graphical glitches. Suspected to be related to some startup/initialization which is not happening as expected
- GB/GBC still fails few of the Wilbertpol's 'Non Moon Eye Tests'
- GB/GBC still fails many roms in the AGE test suite
As of today, there are 2 variants of masquerade available, P52 and P10. The major differences between the two variants is w.r.t the supporting libraries used.
- P52 : Is based on ImGui (+ SDL3 + OpenGL3)
- P10 : Is based on OLC
- Gameboy Advance
- Under Development
- Gameboy / Gameboy Color
- Under Development
- Nintendo Entertainment System
- Under Development
- Any other consoles/simulators
- No Support
- Not Supported
Gameboy Color (Pokemon Crystal), Gameboy Advance (Pokemon Emerald) and Gameboy (Pokemon Blue)
- Below 'in-game snapshots' were taken on a windows PC using a P10 build i.e. an OLC build (v0.6036 or lower) which is now deprecated
- Masquerade users are always recomended to use ImGui build (P52) as OLC build (P10) will not be supported for further updates
Gameboy Advance (Pokemon Ruby, Emerald and Sapphire)
Gameboy Advance (Pokemon Fire Red and Leaf Green)
Gameboy Color (Donkey Kong Country and Pokemon Crystal)
Gameboy (Prehistorik Man in 'BGB' palette, Pinball Deluxe in 'Gearboy' palette and Altered Space in 'Sameboy' palette)
Nintendo Entertainment System (Super Mario Bros 3 and Zelda II: The Adventure of Link)
Nintendo Entertainment System (Super Mario Bros and Kong Classic)
Pacman
Ms Pacman
Space Invader
Chip8 (Pong)
Game Of Life (Toroidal Mode)
As of now, masquerade is only tested for windows platform. There are plans to port this to other platforms in near future.
- Imgui and nativefiledialog-extended are used for user interface
- Note that OLC is deprecated
- In windows platform, the standard "winAPI" based user interface can be used for accessing various options of the emulator.
- In non-windows (and windows) platforms, an "inbuilt OLC specific" user interface is also provided. Windows user can hence use both interfaces and can toggle b/w "winAPI" or "inbuilt OLC specific" interfaces by pressing 'esc' or 'R' keys respectively.
- ImGui
- SDL3
- OpenGL3
- nativefiledialog-extended
- Boost libraries to parse .ini files
- Forked version of One Lone Coder's Pixel Game Engine
- One Lone Coder's Sound Wave Engine
- Boost libraries to parse .ini files
- GB Pandocs (https://gbdev.io/pandocs/)
- GB Dev Wiki (https://gbdev.gg8.se/wiki/articles/Memory_Bank_Controllers)
- Codeslinger's blog (http://www.codeslinger.co.uk/pages/projects/gameboy.html)
- Night Shade's blog for audio implementation (https://nightshade256.github.io/2021/03/27/gb-sound-emulation.html)
- Blargg Roms used for testing
- The Ultimate Gameboy Talk (https://github.com/drhelius/Gearboy)
- Antonio's blog (https://github.com/AntonioND/giibiiadvance/blob/master/docs/TCAGBD.pdf)
- Gearboy used for testing as I don't have the actual Gameboy or Gameboy Color (https://github.com/drhelius/Gearboy)
- gbmulator used for testing as I don't have the actual Gameboy or Gameboy Color (https://github.com/mpostaire/gbmulator)
- Emulator Development Discord Channel (https://discord.com/invite/emudev)
- gbatek (http://problemkaputt.de/gbatek-gba-reference.htm)
- TONC (https://gbadev.net/tonc/)
- NBA HW Docs (https://nba-emu.github.io/hw-docs/)
- GBA Docs (https://gbadev.net/gbadoc/)
- Dillonb blog for catridges (https://dillonbeliveau.com/2020/06/05/GBA-FLASH.html)
- Dillonb used for testing and also for providing the inspiration for the CLI based logger/debugger (https://github.com/Dillonb/gba/tree/master)
- NBA used for testing as I don't have the actual Gameboy Advance (https://github.com/nba-emu/NanoBoyAdvance)
- SkyEmu used for testing as I don't have the actual Gameboy Advance (https://github.com/skylersaleh/SkyEmu)
- jsmolka and alyosha-tas test roms
- AGS test roms and their source files from DenSinH (https://github.com/DenSinH/AGSTests/tree/main)
- NES Dev Wiki (https://www.nesdev.org/wiki/Nesdev_Wiki)
- GBA PPU access pattern (https://nba-emu.github.io/hw-docs/ppu/ppu.html)
- Tom Harte tests for 6502 and SM82 cpu testing