Zork on ESP32 with VGA, PS2 and SD

The 80's are back in text.....

Similar projects worth following
For thus of you who never played Zork, it’s a text based quest, came out in the early 80’s.There is no graphics, and you type in your commands. It used Z-machine instructions as the game data, there for allowing any machine with Z-interpreter to play.
This is the story of me wanting to make a (some what) portable version of it.

How about a game of ZORK on esp32, using PS2 keyboard and a 14 inch VGA screen?

For thus of you who never played Zork, it’s a text based quest, came out in the early 80’s.There is no graphics, and you type in your commands. It used Z-machine instructions as the game data, there for allowing any machine with Z-interpreter to play.

This project actually started 9 years ago, when I came across this post on the Arduino forum

The user Louis Davis did an amazing work of taking an existing Z- interpreter and make it work on an Arduino mega with SD card.

The thing was, that you had to connect it to a computer and play over the serial monitor.

So I made several attempts to make a standalone unit. Adding a PS2 keyboard was easy, but finding a proper output, and get it all to work together was too complicated, and I just stopped trying at some point. Fast forward to few weeks back, I came across another amazing work, which is the fabGL library for ESP32.

Allowing you to basically turn the ESP32 into a small computer, with SD, PS2 mouse and keyboard, sound engine and the cherry on top – VGA output!

Getting the space invaders example working on the VGA screen with sound was surprisingly simple and defiantly it was fun playing. Now all that retro, brought Zork back to my mind and then It clicked – I can finally get that project I was dreaming of to work. I forked the original project and spend 2 days in finding the right combination of libraries and settings to get the code to compile and work. If you want to try it out

The next step, which forced me to make more adjustments, was to make it work on the ESP32. Now since I have made several attempts in the past, some of the code adjustments were ready for me, just had to copy them from old projects I kept (lucky me).I was thrilled when I first got to play it on the new setup.

Now let’s go over the setup.

I took a VGA cable cut off one end and wired it up to a breadboard friendly connector. I used this schematics to figure out the pin out used the 8 color setup, with one pin for each color, connected via a 270Ohm resistor.

I used PS2 with Arduino in the past, so I had a pair of female connectors with pin breakout ready. I use a logic level convertor, since the PS2 is 5V and the esp32 is 3.3V. And added 1K pull-ups on the 3.3V side.

You can use the schematics on the site, to help you with the PS2 connector pin out.

The SD card is connected to the spi bus. And last and not least is the sound, which here I used a cut cable for.

You can use this schematics to set it up

When it comes to the code, I took the original AZIP and added the fabgl on top of it, I do want to point out a few thigs

The SD CONFIG #define SD_CONFIG SdSpiConfig(SS, SHARED_SPI, SD_SCK_MHZ(16))Without this I could not get the code running, but with other SD or breakout this might have to adjust this. I adjusted the VGA pinout to free the 2 SPI pins for the SD, that the original setup was using and this is my pinout displayController.begin(GPIO_NUM_21, GPIO_NUM_22, GPIO_NUM_4, GPIO_NUM_17, GPIO_NUM_15);The PS2 mouse and keyboard are left on their original pinout. The processreadfromsd takes care of the output.

void processreadfromsd(int c) { Serial.write((int) c); //(\n) new line && end of lettersInRowCounter with space if (c == 10 || (c == 32 && lettersInRowCounter >= 71)) { Terminal.write('\r'); Terminal.write('\n'); //Serial.println(lettersInRowCounter); lettersInRowCounter = 0; } // not sure why 13 was used in palces but we ignore it // 91 & 93 are [] which comes aroudn system command else if (c == 13 || c == 91 || c == 93) // DO NOTHING Serial.println("IGNORE...
Read more »


Portable Network Graphics (PNG) - 373.19 kB - 05/25/2021 at 21:18


  • Shooting aliens with PS2 joystick

    talofer9909/10/2021 at 22:02 0 comments

    It’s if this part of the project did not want to come to life, it’s a joystick that act like a PS2 keyboard (this kind of PS2), which was supposed to be an easy build since I done a few PS2 projects in the past.

    I was mid project, when I noticed that there is a glitch in the system once in a while one of the keys will get “stuck” For example, I would release the fire button and yet the firing in the game will continue. and this sent me down the rabbit hole, and this project was on the table for over 2 months now, It got to the point I thought of just letting it go, but let’s start at the beginning.

    At the end of the ZORK episode I mentioned that I want to turn this bundle of wires to a proper board. 2 days later I came across this beauty, TTGO ESP32 VGA,.

    It’s an esp32, SD card, usb for the esp, VGA output, 2 PS2 inputs, sound jack and it even has a connector for battery. They are considerably  cheap,  so I just ordered one. And when it arrived the first thing I done was to run ZORK on it. I immediately noticed a big difference. When the game is loaded on my board the VGA had interference or noise, on this board, it’s just crisp. I did had to change the setting of the VGA pinout in the code, but it was a very simple change. One thing I’m not a big fan of on this board, is the SD connector, I get the cost and size constrain, but this is an accident waiting to happen. So to reduce the chance of destroying the SD I printed out this great case. Makes the SD somewhat more protected. Do note this is meant for the 1.4 version of the board. When I posted this a lot of people commented that I should have used a joystick for playing. Which made me come up with the idea to make a ps2 joystick that will act like a keyboard.

    I done projects with PS2 in the past so I  was prepared. I had a cable ready for it, some code and most important old library of ps2dev.

    I created a simple code that will send a press and release of the key “1” every 1 second, In order for the code to work well I made several adjustments to the old library and to the code itself. But eventually I got it working. At this point I turned to create the joystick part of the project, to start it going I used the 8 button breakout I created for the Port manipulation video ( , since I really do not like using buttons on breadboards. They tend to jump out. I connected the last 4 buttons, while actually using just 3 out of them, 2 for directions and one for the space so we can shoot thus aliens.  And the last wire is ground the buttons are pulled up in the software. The logic for the code was simple. Make sure we debounce the buttons.

    Then if we take this case for example, to send the keyboard right key command to a host, we need to first send 0xe0 that mark the next byte is a special key and in our case its 0x74. Also note that if the button state is HIGH, which means the button was released, we also send the oxf0 in the middle to signal it’s a key release and not a key press. I will explain later why the command is placing the data into a buffer.

    Now all happy and ready to play, I uploaded the space invaders example to the TTGO, uploaded the new code to the nano and was good to go.

    This is when the glitch was found. And it is also the point I stopped documenting the process I spent hours debugging the issue and at some point just gave up. The setup was sitting on the table for few good weeks, then one day I just powered it up, this time powering  the joystick from the esp. It’s only when I got to level 3, I noticed there were no glitches. Happy with that I completed the project – not with ease – as I said it did not want to come to life. The case was designed in fusion 360. This set of analog joysticks were scraped from a joystick long time ago ( This is the nano you...

    Read more »

View project log

Enjoy this project?



Similar Projects

Does this project spark your interest?

Become a member to follow this project and never miss any updates