Galaga, Pac-Man and Donkey Kong Arcade Emulator for the ESP32

https://github.com/harbaum/galagino

Galagino - ESP32 Arcade Emulator

Play Galaga, Pac-Man, Donkey Kong, Frogger, Digdug and 1942 on the ESP32

Cabinet

Pac-Man screenshot Galaga screencast Donkey Kong screenshot Frogger screenshot Digdug screenshot 1942 screenshot

Pac-Man, Galaga and Donkey Kong are three of the most iconic arcade machines of all times and are listed on places #1 to #3 on the Killer List of Video Games.

Especially Pac-Man and Galaga have been remade and emulated many times. So far the cheapest and smallest system able to do a faithful emulation of the original arcade machines was the raspberry pi. But even the much cheaper ESP32 should be able to easily emulate a machine from the early ’80s, shouldn't it?

Well, things are not that easy. The Galaga arcade was driven by three Z80 CPUs, each running at 3Mhz. Additionally the arcade machine included two more CPUs, one for button and coin handling and one for audio support. And finally the hardware itself had dedicated support for simple wavetable audio, tilemap graphics and up to 64 sprites. The video resultion was 224 by 288 pixels.

The ESP32 on the other hand comes with two cores running at 240MHz. But it lacks dedicated video hardware. Emulating the various CPUs as well as the handling of audio and graphics turned out to be challenging for the ESP32.

Cheap TFT screens with a resolution of 320 by 240 pixels are avaialable in various sizes from 2.0 inch to 3.2 inch allowing for a very small and cheap galagino setup.

These small displays usually allow for SPI clock rates of up to 40MHz allowing for a max screen refresh rate of ~30Hz. This is exactly half the refresh rate of the original arcade machine. 30Hz is sufficient for a very fluid gameplay. However, with displays coping with 80MHz SPI clock, Galagino will run at full 60Hz refresh.

Youtube videos

Hardware

Original Hardware

The hardware is built around one of those cheap ESP32 development boards like the ESP32 Devkit V4 depicted in the images below. The components needed for the breadboard setup are listed below. If you plan to build the cabinet instead you might want to make sure you order the exact parts that aren't only electrically compatible but also mechanically.

  • ESP32 development board (e.g. Devkit V4)
  • A 320x240 SPI TFT screen (no touch needed)
    • Either a ILI9341 based screen as depicted, or
    • a ST7789 based screen with 320x240 pixels
  • An audio amplifier and speaker
  • five push buttons, or
  • one push button and a five way joystick breakout (for Pac-Man and Donkey Kong)
  • breadboard and wires

The entire setup should be connected as depicted below. The Devkit is too wide for the breadboard leaving no space above it to connect wires. Thus the wires going to the top pin row of the Devkit are placed underneath the DevKit with the connections done as shown in the image below. See galagino/config.h for the button mappings.

Breadboard scheme

PDF

Breadboard photo

This setup with five buttons works fine for Galaga since there is no vertical movement in the game that requires a joystick. A joystick is needed for Pac-Man and Donkey Kong. The joystick based setup would then be wired in the following way:

Breadboard scheme with 5 way joystick

PDF

"Cheap Yellow Display"

The ESP32-2432S028R A.K.A. the Cheap Yellow Display is an ESP32 Board that comes with the majority of hardware required to build a Galagino device.

Cheap Yellow Display

Hardware Needed:

  • Cheap Yellow Display
  • A Nintendo Wii nunchuck and adaptor - This can be connected to the JST connector labled "CN1" with the cable included with the display
  • A speaker - This can be attached to the display with a 1.25mm JST connector to the connector labled "SPEAK" (or soldered)

Note: The Start button is connected to the "boot" button on the board.

To get the project working on the Cheap Yellow Display, just uncomment the #define CHEAP_YELLOW_DISPLAY_CONF line in galagino/config.h

Software

Important notice 1: You really need to use the Arduino IDE as it provides the optimization settings required for sufficient perfgormance of Galaga and Digdug by default. E.g. PlatformIO doesn't seem to enable enough optimization.

Important notice 2: I2S/DAC support seems to be broken in the ESP32 board package version 2.0.10 and up. Please use ESP32 board package 2.0.9 or older for a clean sound.

The software consists of three parts:

Galagino uses code that is not freely available and thus not included in this repository. Preparing the firmware thus consists of a few additional steps:

  • The ROM files have to be placed in the roms directory, together with the ZIP file containing the Z80 emulator.
  • A set of python scripts is then being used to convert and patch the ROM data and emulator code and to include the resulting code into the galagino sketch directory.
  • The same scripts are afterwards being used to convert audio sample files into the desired format.

The ROM conversion as well as the audio sample conversion create a whole bunch of additional files in the galagino directory. Please check the README's in the romconv and samples directories for further instructions.

With all these files in place, the galagino.ino sketch can be loaded into the Arduino IDE. The Arduino IDE must have the ESP32 board support installed and the appropriate board like e.g. the ESP32 Dev Module should be selected. Finally the default core used by Arduino should be 1 (this is the default) as Galagino will use core 0 for audio and video emulation. Furthermore the FastLED library should be installed to support the LEDs in the cabinets marquee. LED support can be disabled in the configuration if no LEDs are going to be installed.

Configuration

The Galagino code can be configured through the galagino/config.h file. This is also the place where it's possible to choose between the ILI9341 controller (default) and the ST7789.

Also the pin assignment can be adjusted as well as the TFT SPI clock or the use of LEDs for the marquee.

{
"by": "rcarmo",
"descendants": 0,
"id": 40221246,
"score": 5,
"time": 1714556819,
"title": "Galaga, Pac-Man and Donkey Kong Arcade Emulator for the ESP32",
"type": "story",
"url": "https://github.com/harbaum/galagino"
}
{
"author": "harbaum",
"date": null,
"description": "A Galaga, Pac-Man and Donkey Kong arcade emulator for the ESP32 - harbaum/galagino",
"image": "https://opengraph.githubassets.com/2755b45059f8f8010aab06714b5f24879619352821ab48aa3d366799519b353f/harbaum/galagino",
"logo": "https://logo.clearbit.com/github.com",
"publisher": "GitHub",
"title": "GitHub - harbaum/galagino: A Galaga, Pac-Man and Donkey Kong arcade emulator for the ESP32",
"url": "https://github.com/harbaum/galagino"
}
{
"url": "https://github.com/harbaum/galagino",
"title": "GitHub - harbaum/galagino: A Galaga, Pac-Man and Donkey Kong arcade emulator for the ESP32",
"description": "Galagino - ESP32 Arcade Emulator Play Galaga, Pac-Man, Donkey Kong, Frogger, Digdug and 1942 on the ESP32 Pac-Man, Galaga and Donkey Kong are three of the most iconic arcade machines of all times and...",
"links": [
"https://github.com/harbaum/galagino"
],
"image": "https://opengraph.githubassets.com/2755b45059f8f8010aab06714b5f24879619352821ab48aa3d366799519b353f/harbaum/galagino",
"content": "<div><article><p></p><h2>Galagino - ESP32 Arcade Emulator</h2><a target=\"_blank\" href=\"https://github.com/harbaum/galagino#galagino---esp32-arcade-emulator\"></a><p></p>\n<p>Play Galaga, Pac-Man, Donkey Kong, Frogger, Digdug and 1942 on the ESP32</p>\n<p><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/galagino_cabinet.jpg\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/galagino_cabinet.jpg\" alt=\"Cabinet\" /></a></p>\n<p><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/pacman.gif\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/pacman.gif\" alt=\"Pac-Man screenshot\" /></a>\n<a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/galagino.gif\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/galagino.gif\" alt=\"Galaga screencast\" /></a>\n<a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/dkong.gif\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/dkong.gif\" alt=\"Donkey Kong screenshot\" /></a>\n<a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/frogger.png\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/frogger.png\" alt=\"Frogger screenshot\" /></a>\n<a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/digdug.png\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/digdug.png\" alt=\"Digdug screenshot\" /></a>\n<a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/1942.png\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/1942.png\" alt=\"1942 screenshot\" /></a></p>\n<p><a target=\"_blank\" href=\"https://en.wikipedia.org/wiki/Pac-Man\">Pac-Man</a>,\n<a target=\"_blank\" href=\"https://en.wikipedia.org/wiki/Galaga\">Galaga</a> and\n<a target=\"_blank\" href=\"https://en.wikipedia.org/wiki/Donkey_Kong_(video_game)\">Donkey Kong</a> are three of the most\niconic arcade machines of all times and are listed on places #1 to #3\non the <a target=\"_blank\" href=\"http://www.klov.net/\">Killer List of Video Games</a>.</p>\n<p>Especially Pac-Man and Galaga have been remade and emulated many\ntimes. So far the cheapest and smallest system able to do a faithful\nemulation of the original arcade machines was the raspberry pi. But\neven the much cheaper ESP32 should be able to easily emulate a machine\nfrom the early ’80s, shouldn't it?</p>\n<p>Well, things are not that easy. The Galaga arcade was driven by three\nZ80 CPUs, each running at 3Mhz. Additionally the arcade machine\nincluded two more CPUs, one for button and coin handling and one for audio\nsupport. And finally the hardware itself had dedicated support\nfor simple wavetable audio, tilemap graphics and up to 64 sprites.\nThe video resultion was 224 by 288 pixels.</p>\n<p>The ESP32 on the other hand\ncomes with two cores running at 240MHz. But it lacks dedicated video\nhardware. Emulating the various CPUs as well as the handling of\naudio and graphics turned out to be challenging for the ESP32.</p>\n<p>Cheap TFT screens with a resolution of 320 by 240 pixels are avaialable\nin various sizes from 2.0 inch to 3.2 inch allowing for a very small\nand cheap <em>galagino</em> setup.</p>\n<p>These small displays usually allow for SPI clock rates of up to 40MHz\nallowing for a max screen refresh rate of ~30Hz. This is exactly half\nthe refresh rate of the original arcade machine. 30Hz is sufficient\nfor a very fluid gameplay. However, with displays coping with 80MHz\nSPI clock, Galagino will run at full 60Hz refresh.</p>\n<p></p><h2>Youtube videos</h2><a target=\"_blank\" href=\"https://github.com/harbaum/galagino#youtube-videos\"></a><p></p>\n<ul>\n<li><a target=\"_blank\" href=\"https://www.youtube.com/shorts/LZRI6izM8XM\">First Galaga Emulation test </a></li>\n<li><a target=\"_blank\" href=\"https://www.youtube.com/shorts/8uNSv0aRtgY\">Sound and Starfield working</a></li>\n<li><a target=\"_blank\" href=\"https://www.youtube.com/shorts/wqnJzOAAths\">Galaga is finally playable</a></li>\n<li><a target=\"_blank\" href=\"https://www.youtube.com/shorts/F4-XiiPwG1c\">Pac-Man on Galagino</a></li>\n<li><a target=\"_blank\" href=\"https://www.youtube.com/shorts/KROFJ0Rtj0w\">Donkey Kong on Galagino</a></li>\n<li><a target=\"_blank\" href=\"https://www.youtube.com/shorts/_PJyn06yrtg\">Boot menu</a></li>\n<li><a target=\"_blank\" href=\"https://youtube.com/shorts/vverV4NphlQ\">Cardboard cabinet prototype</a></li>\n<li><a target=\"_blank\" href=\"https://youtube.com/shorts/a3-wctRAIds\">Finished plywood cabinet</a></li>\n<li><a target=\"_blank\" href=\"https://www.youtube.com/watch?v=p29Yvht4jSI\">John Bradnam's 3D printed case</a></li>\n<li><a target=\"_blank\" href=\"https://youtube.com/shorts/LrBkN1pu7yE\">Frogger on Galagino</a></li>\n<li><a target=\"_blank\" href=\"https://youtube.com/shorts/fmQmfKEhVy4\">Digdug on Galagino</a></li>\n</ul>\n<p></p><h2>Hardware</h2><a target=\"_blank\" href=\"https://github.com/harbaum/galagino#hardware\"></a><p></p>\n<p></p><h3>Original Hardware</h3><a target=\"_blank\" href=\"https://github.com/harbaum/galagino#original-hardware\"></a><p></p>\n<p>The hardware is built around one of those cheap ESP32 development\nboards like the ESP32 Devkit V4 depicted in the images below. The\ncomponents needed for the breadboard setup are listed below. If you\nplan to build the <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/hardware/cabinet\">cabinet</a> instead you might want\nto make sure you <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/hardware\">order the exact parts</a> that\naren't only electrically compatible but also mechanically.</p>\n<ul>\n<li>ESP32 development board (e.g. <a target=\"_blank\" href=\"https://www.espressif.com/en/products/devkits/esp32-devkitc\">Devkit V4</a>)</li>\n<li>A 320x240 SPI TFT screen (no touch needed)\n<ul>\n<li>Either a ILI9341 based screen as depicted, or</li>\n<li>a ST7789 based screen with 320x240 pixels</li>\n</ul>\n</li>\n<li>An audio amplifier and speaker\n<ul>\n<li>e.g. a <a target=\"_blank\" href=\"https://www.adafruit.com/product/2130\">PAM8302A</a> and a 3W speaker (as seen in the photos), or</li>\n<li>a <a target=\"_blank\" href=\"https://www.keyestudio.com/products/keyestudio-sc8002b-audio-power-amplifier-speaker-module-for-arduino-player\">Keyestudio SC8002B</a>, or similar</li>\n</ul>\n</li>\n<li>five push buttons, or</li>\n<li>one push button and a five way joystick breakout (for Pac-Man and Donkey Kong)</li>\n<li>breadboard and wires</li>\n</ul>\n<p>The entire setup should be connected as depicted below. The Devkit is\ntoo wide for the breadboard leaving no space above it to connect\nwires. Thus the wires going to the top pin row of the Devkit are\nplaced underneath the DevKit with the connections done as shown in the\nimage below. See <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/galagino/config.h\">galagino/config.h</a> for the button\nmappings.</p>\n<p><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/galagino_bb.png\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/galagino_bb.png\" alt=\"Breadboard scheme\" /></a></p>\n<p><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/galagino_bb.pdf\">PDF</a></p>\n<p><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/galagino_breadboard.jpeg\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/galagino_breadboard.jpeg\" alt=\"Breadboard photo\" /></a></p>\n<p>This setup with five buttons works fine for Galaga since there is no\nvertical movement in the game that requires a joystick. A joystick is\nneeded for Pac-Man and Donkey Kong. The joystick based setup would\nthen be wired in the following way:</p>\n<p><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/galagino_5way_bb.png\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/galagino_5way_bb.png\" alt=\"Breadboard scheme with 5 way joystick\" /></a></p>\n<p><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/galagino_5way_bb.pdf\">PDF</a></p>\n<p></p><h3>\"Cheap Yellow Display\"</h3><a target=\"_blank\" href=\"https://github.com/harbaum/galagino#cheap-yellow-display\"></a><p></p>\n<p>The ESP32-2432S028R A.K.A. the <a target=\"_blank\" href=\"https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display\">Cheap Yellow Display</a> is an ESP32 Board that comes with the majority of hardware required to build a Galagino device.</p>\n<p><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/images/CheapYellowDisplay.png\"><img src=\"https://github.com/harbaum/galagino/raw/main/images/CheapYellowDisplay.png\" alt=\"Cheap Yellow Display\" /></a></p>\n<p>Hardware Needed:</p>\n<ul>\n<li>Cheap Yellow Display</li>\n<li><a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/hardware/NUNCHUCK.MD\">A Nintendo Wii nunchuck and adaptor</a> - This can be connected to the JST connector labled \"CN1\" with the cable included with the display</li>\n<li>A speaker - This can be attached to the display with a 1.25mm JST connector to the connector labled \"SPEAK\" (or soldered)</li>\n</ul>\n<p>Note: The <code>Start</code> button is connected to the \"boot\" button on the board.</p>\n<p>To get the project working on the Cheap Yellow Display, just uncomment the <code>#define CHEAP_YELLOW_DISPLAY_CONF</code> line in <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/galagino/config.h\">galagino/config.h</a></p>\n<p></p><h2>Software</h2><a target=\"_blank\" href=\"https://github.com/harbaum/galagino#software\"></a><p></p>\n<p><strong>Important notice 1:</strong> You really need to use the Arduino IDE as it\nprovides the optimization settings required for sufficient\nperfgormance of Galaga and Digdug by default. E.g. PlatformIO doesn't\nseem to enable enough optimization.</p>\n<p><strong>Important notice 2:</strong> I2S/DAC support seems to be <a target=\"_blank\" href=\"https://github.com/espressif/arduino-esp32/issues/8467\">broken in the\nESP32 board package version 2.0.10 and\nup</a>. Please\nuse ESP32 board package 2.0.9 or older for a clean sound.</p>\n<p>The software consists of three parts:</p>\n<ul>\n<li>The <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/galagino\">Galagino specific code</a> contained in this repository</li>\n<li>The orignal ROM files\n<ul>\n<li><a target=\"_blank\" href=\"https://www.bing.com/search?q=galaga+namco+b+rom\">Galaga (Namco Rev. B ROM)</a></li>\n<li><a target=\"_blank\" href=\"https://www.bing.com/search?q=pacman+midway+arcade+rom\">Pac-Man (Midway)</a></li>\n<li><a target=\"_blank\" href=\"https://www.bing.com/search?q=donkey+kong+arcade+rom\">Donkey Kong (US set 1)</a></li>\n<li><a target=\"_blank\" href=\"https://www.bing.com/search?q=frogger+arcade+rom\">Frogger</a></li>\n<li><a target=\"_blank\" href=\"https://www.bing.com/search?q=digdug+arcade+rom\">Digdug</a></li>\n<li><a target=\"_blank\" href=\"https://www.bing.com/search?q=1942+arcade+rom\">1942</a></li>\n</ul>\n</li>\n<li>A <a target=\"_blank\" href=\"https://fms.komkon.org/EMUL8/Z80-081707.zip\">Z80 software emulation</a> by <a target=\"_blank\" href=\"https://fms.komkon.org/\">Marat Fayzullin</a></li>\n</ul>\n<p>Galagino uses code that is not freely available and thus not included in this\nrepository. Preparing the firmware thus consists of a few additional steps:</p>\n<ul>\n<li>The ROM files have to be placed in the <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/roms\">roms directory</a>, together with the ZIP file containing the Z80 emulator.</li>\n<li>A set of <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/romconv\">python scripts</a> is then being used to convert and\npatch the ROM data and emulator code and to include the resulting code into the\ngalagino sketch directory.</li>\n<li>The same scripts are afterwards being used to convert <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/samples\">audio sample files</a> into the desired format.</li>\n</ul>\n<p>The <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/romconv\">ROM conversion</a> as well as the <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/samples\">audio sample\nconversion</a> create a whole bunch of additional files in the\n<a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/galagino\">galagino directory</a>. Please check the README's in the\n<a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/romconv\">romconv</a> and <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/samples\">samples</a> directories for further\ninstructions.</p>\n<p>With all these files in place, the galagino.ino sketch can be loaded\ninto the <a target=\"_blank\" href=\"https://docs.arduino.cc/software/ide-v2\">Arduino IDE</a>. The\nArduino IDE must have the <a target=\"_blank\" href=\"https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html\">ESP32 board support</a>\ninstalled and the appropriate board like e.g. the\n<em>ESP32 Dev Module</em> should be selected. Finally the default core used\nby Arduino should be 1 (this is the default) as Galagino will use core 0\nfor audio and video emulation. Furthermore the FastLED library should\nbe installed to support the LEDs in the <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/hardware/cabinet\">cabinets marquee</a>.\nLED support can be disabled in the configuration if no LEDs are going to be installed.</p>\n<p></p><h2>Configuration</h2><a target=\"_blank\" href=\"https://github.com/harbaum/galagino#configuration\"></a><p></p>\n<p>The Galagino code can be configured through the <a target=\"_blank\" href=\"https://github.com/harbaum/galagino/blob/main/galagino/config.h\">galagino/config.h</a>\nfile. This is also the place where it's possible to choose between the ILI9341\ncontroller (default) and the ST7789.</p>\n<p>Also the pin assignment can be adjusted as well as the TFT SPI clock or the\nuse of LEDs for the marquee.</p>\n</article></div>",
"author": "",
"favicon": "https://github.githubassets.com/favicons/favicon.svg",
"source": "github.com",
"published": "",
"ttr": 212,
"type": "object"
}