Free · runs in your browser · no sign-up · Arduino Uno, Nano, Mega, ESP32, ESP8266, Pico
Quick start
- Pick a template from the bar at the top, or keep the starting program. Each template runs on the preview straight away.
- Change the blocks. Drag new blocks from the menu on the left into Setup (runs once) or Loop (repeats). Click a number to edit it.
- Test it. The preview restarts after every change. Each pin used by a button block gets a test button under the screen. Hold it, or press keys 1 to 9.
- Copy the sketch under Arduino sketch, install the U8g2 library in the Arduino IDE, choose your board and upload.
Arduino OLED game templates
Every template is built only from blocks, so you can open it, see how it works and change it. All of them compile for an Arduino Uno with the U8g2 library and work on SSD1306 and SH1106 displays.
Wiring the OLED and the buttons
Connect the OLED's GND to GND, VCC to 3.3 V or 5 V, and SDA and SCL to the board's I2C pins: A4 and A5 on an Uno or Nano, GPIO21 and GPIO22 on an ESP32, D2 and D1 on a NodeMCU, GP4 and GP5 on a Pico. Each button goes between its pin and GND with no resistor, because the sketch turns on INPUT_PULLUP.
How each game works inside
Open a template and you will see that every game is the same loop: read the buttons, move things, check for a hit, draw the screen, show it and wait a moment. Knowing which variable does what makes the blocks easy to change.
Snake
The head position is x and y, always a multiple of 4, so the snake moves on a grid of 4-pixel squares. The direction d is a number: 0 right, 1 down, 2 left, 3 up. Pressing the button adds 1 to d and wraps 4 back to 0, which turns the snake clockwise. Before the head moves, each tail square copies the one in front of it (x4 takes x3, x3 takes x2 and so on), and that copying is what makes the tail follow. When the head lands on the food square, the score goes up and the food jumps to a new random square. Leaving the playing area shows GAME OVER and resets every variable.
Dino runner
The dino's top edge is y and its vertical speed is vy. A press while standing on the ground sets vy to −8, so the dino moves up 8 pixels, then 7, then 6, because one is added to vy every frame. That is a simple form of gravity, and the jump lasts about 16 frames. The cactus x position cx goes down by 4 each frame. When it leaves the screen it comes back at a random distance and you score a point. The game is over when the cactus overlaps the dino on the x axis while the dino is still low (y greater than 32).
Pong and 2-player Pong
The ball has a position (bx, by) and a speed (vx, vy). Bouncing is just flipping a speed: vy becomes 0 − vy at the top and bottom walls. In the one-player game, holding the button moves the paddle up and letting go moves it down. If the ball reaches the left edge outside the paddle, the game ends. In the 2-player version each player has two buttons. A missed ball gives the other player a point, and the ball is served again from the middle at a random angle.
Tap to fly
Holding the button sets the speed to −2, so the bird rises. Letting go adds 1 to the speed each frame, up to a limit of 3, so it falls but never too fast. The pipe has an x position px and a gap that starts at gy and is 24 pixels tall. Each time a pipe leaves the screen, a new gap height is picked at random. Hitting the top or the bottom of the screen, or a pipe outside its gap, ends the game.
Menu
The chosen line is sel (0, 1 or 2). Up and down change it and wrap around at the ends. The frame around the chosen line is drawn at y = 16 + sel × 14, so one rectangle block follows the cursor. Each button has its own was variable, so holding a button moves the cursor only once. Select shows the chosen item for 1.5 seconds. Replace the three texts and the picked blocks with your own actions to make a settings menu for a project.
Make the games your own
- Faster or slower: change the last wait block in the Loop. 150 ms for Snake is relaxed, 80 ms is hard.
- Higher jump: in Dino runner, set vy to −9 or −10 instead of −8.
- Getting harder over time: add a variable speed, use it in the change cx by block, and add 1 to it every 5 points.
- Lives instead of instant game over: make a lives variable set to 3, take one away on a hit and only show GAME OVER when it reaches 0.
- A best score: keep a best variable. In the game over blocks, if score is greater than best, set best to score, then write both.
- Bigger pixels for the snake: change the squares to 6 or 8 pixels and move by the same step. Keep the food positions on the same grid.
- A start screen: in Setup, write the game name, show it and wait until the button is pressed using a repeat while not button pressed loop with a short wait inside.
- A different player shape: draw the dino as two rectangles and a dot, or the bird as a circle with a line for a wing.
Parts for a handheld OLED game
| Part | Why |
|---|---|
| Arduino Nano or ESP32 | Small enough to fit in a case. A Nano runs every template. |
| 0.96 or 1.3 inch I2C OLED | Bright and readable in a dark room. The 1.3 inch SH1106 is easier to see. |
| 1 to 4 tactile push buttons | 12 mm buttons with caps feel best for games. |
| Breadboard and jumper wires | Build and test before you solder anything. |
| USB power bank or a 3.7 V battery with a charger board | Makes it portable. Use the board's USB port or its 5 V pin from the charger's boost output. |
| Perfboard or a 3D-printed case (optional) | For a finished gadget you can carry around. |
From blocks to a working gadget
- Wire the OLED and one button on a breadboard and upload the Button counter template. If the number goes up when you press, the wiring is right.
- Load the game you want, check it in the preview, and upload it the same way.
- If the game feels slower than in the preview, lower the last wait block a little. The board needs about 25 ms to send each frame to the display.
- Move the parts to perfboard or into a case once everything works, keeping the I2C wires short.
Problems people hit with button games
- The game ends straight away: a button pin is wired to 5 V instead of GND, so the board reads it as always pressed. With
INPUT_PULLUP, the other leg goes to GND. - One press turns the snake twice: the press is being read on two frames. The templates use a was variable to stop that. Keep it if you rebuild the turning blocks.
- Nothing happens on an ESP board: pins 2 and 3 are not safe on every ESP. On an ESP32 move the buttons to GPIO 4, 5, 18 and 19. On a NodeMCU use D5, D6 and D7.
- The screen flickers or shows half a frame: there is a show on screen block in the middle of the drawing. Keep one show block at the end of each frame.
- Text is cut off at the top: text y is the bottom line of the letters. Use 8 or more for small text.
Frequently asked questions
Is the OLED Block Coder free?
Yes. It is free with no sign-up and no limit on projects. It runs in your browser, and your blocks are saved in that browser automatically. Use Save as file to keep a copy on your computer.
Which Arduino boards can run the games?
Any board with an Arduino core and I2C: Arduino Uno, Nano, Mega, Leonardo, Uno R4, ESP32, ESP8266 and Raspberry Pi Pico. Every template was compiled for an Arduino Uno, which is the smallest of these, so the bigger boards have room to spare.
Which OLED displays work?
0.96 inch SSD1306 128x64, 1.3 inch SH1106 128x64 and 0.91 inch SSD1306 128x32 modules with four pins (GND, VCC, SCL, SDA). Choose your display under Board and display and the sketch uses the matching U8g2 constructor.
Do I need resistors for the buttons?
No. The sketch sets every button pin to INPUT_PULLUP, which turns on a resistor inside the chip. Wire one leg of the button to the pin and the other leg to GND.
Why does my game run slower on the Arduino than in the preview?
The preview draws instantly, but a real board also needs time to send the screen. A full 128x64 frame is 1,024 bytes over I2C, which takes roughly 25 ms on an Uno, on top of your wait block. Lower the last wait in the Loop by about 20 ms to get the same speed as the preview.
Can I use a joystick instead of buttons?
Not directly yet, because there is no analog input block. A joystick module also has a push switch that works with the button block. The Move the dot template shows the same idea with four buttons.
Can I add sound to the games?
There is no sound block yet. You can add a tone() call to the generated sketch by hand, or make the melody with the Arduino Buzzer Song Generator and paste its function into the sketch.
Can I test my program without hardware?
Yes. The live preview runs your blocks, and the Pin test buttons stand in for real buttons. To test the exact sketch, paste it into an online simulator that supports U8g2 and an SSD1306.
Will my blocks be lost if I close the page?
No. They are saved in your browser on this device. Clearing the browser data removes them, so use Save as file for anything you want to keep, and Open file to load it again.
Can I edit the Arduino code after copying it?
Yes. It is a normal Arduino sketch that uses the U8g2 library, with readable variable names. You can paste it into the Arduino IDE and keep working on it, but changes made there do not go back into the blocks.
Every block, the screen coordinates, the generated code, memory on the Uno and a troubleshooting table are in the full OLED Block Coder guide. To draw frame-by-frame pixel art instead, use the OLED Animation Maker.