What is MakeCode Arcade?

Microsoft MakeCode Arcade is a web-based beginner-friendly code editor to create retro arcade games for the web and for microcontrollers. In this guide, you will learn how to assemble your own Arcade hardware from different parts. MakeCode Arcade is open source on GitHub.

Beta Zone: MakeCode Arcade is still in its beta. It might still have a few rough edges...

Arcade is for retro 2D sprite-based games.

Arcade supports a 160x120 screen with 16 colors, and has a 2D game engine with sprites, platformer-style collisions, tile maps, particle systems and more!

Arcade is a web-based code editor. 

Just like the MakeCode Circuit Playground Express editor, you can use blocks or JavaScript to build your program in your browser. Nothing to install - it just works!

Arcade is friendly to beginners! 

Get started with building your own retro games, using the block editor and the many guides. You don't need to be a programmer to get started!

Arcade is friendly to seasoned programmers too!

Switch to JavaScript and type away. MakeCode supports Static TypeScript, a special flavor of JavaScript optimized for compilation on micro-controllers.

Arcade runs on hardware (in particular SAMD51)! 

While all games can be shared and played via the web, the fun starts when you compile them for SAMD51-based boards, like the Adafruit Itsy Bitsy M4 Express.

Bootloader

The bootloader is piece of software on the board that is responsible for flashing the rest of the board with the program from the user. Many of the Adafruit M0 and M4 boards, as well as others, now come with a UF2 bootloader. The UF2 bootloader emulates a USB (or pen / thumb / flash) drive and lets you flash the board by simply copying a UF2 file onto the drive presented by the board.

Are you trying to build a MakeCode Arcade for Raspberry Pi 0? Try this guide instead.

With MakeCode Arcade, we go a step further and let you use the same UF2 file on many different boards, which differ only in the pinout (how things are mapped). To do that, the bootloader contains a small amount of configuration data that specifies which pin is connected to which button, and which pins are connected to the screen. The Arcade program then probes this data at runtime and configures itself accordingly. This way, the same Arcade binary game (UF2 file) could run on a device made of an ItsyBitsy M4, a Feather M4, or another completely custom board that uses the ATSAMD51 microcontroller (MCU).

Bootloader screen

 

This is the screen image displayed by the bootloader for an ATSAMD51-based MCU. "D51" is the code name with a green background, and this image helps you configure the MakeCode Arcade editor.

 

The screen also displays the drive name, ARCD-D51 in this case.

ItsyBitsy M4 Express Bootloader

If you have an ItsyBitsy M4, that's great! However, the bootloader that comes with it by default doesn't have the configuration data needed for MakeCode Arcade, mostly because we don't know where you want to connect things beforehand!

This means you'll need to update the bootloader on your ItsyBitsy M4; it's very fast and painless to do so. Just follow the steps below:

  1. Connect your ItsyBitsy M4 to a computer with a USB cable. Then make sure the ITSYBOOT drive is visible. If it is not appearing, you might need to double-click the reset button for it to show up on your list of drives.
  2. Download the UF2 file (below) and copy (or drag) it onto the ITSYBOOT drive.
  3. After a few seconds, the LEDs should start blinking on the ItsyBitsy M4, and you can reset it then.
  4. Once completed, the ARCD-D51 drive should show up on your computer, which means you have successfully turned your ItsyBitsy M4 into an Arcade MCU!

Feather M4 Express bootloader

If you want to use a Feather M4 to build your arcade, instead of the ItsyBitsy M4, use the bootloader below. Drop it on the Patcher site to see the pinout!

 

Custom configuration data

Earlier, we mentioned that configuration data is necessary for the bootloader. You can view the configuration data by dragging and dropping the UF2 file onto our page here: https://microsoft.github.io/uf2/patcher/

When you do this with any of the bootloaders we've provided above, you will see how buttons and the screen are to be connected, such as this example below:

PIN_BTN_A = PIN_SCL
PIN_BTN_B = PIN_D7
PIN_BTN_DOWN = PIN_D12
PIN_BTN_LEFT = PIN_D11
PIN_BTN_MENU = PIN_SDA
PIN_BTN_RIGHT = PIN_D9
PIN_BTN_UP = PIN_D10
PIN_DISPLAY_BL = PIN_A5
PIN_DISPLAY_CS = PIN_A2
PIN_DISPLAY_DC = PIN_A3
PIN_DISPLAY_MISO = PIN_MISO
PIN_DISPLAY_MOSI = PIN_MOSI
PIN_DISPLAY_RST = PIN_A4
PIN_DISPLAY_SCK = PIN_SCK

If you decide to use other pins, just copy the configuration lines you want to change to the text area on top of the page, change the setting, and hit the **Apply my patch** button. This will generate a new bootloader updater, that you can apply just like those we've provided above.

ItsyBitsy M4 Express

In this guide, you will learn how to breadboard an Arcade from scratch using an Adafruit ItsyBitsy M4 Express, a 1.8" TFT screen breakout and a few buttons.

 

Before we get started, make sure you have the parts we've listed below!

1 x Adafruit ItsyBitsy M4 Express
The board that will be running the Arcade game engine and driving the screen.
1 x 1.8" Color TFT LCD display with MicroSD Card Breakout
This will be the screen for your MakeCode Arcade
1 x Full size breadboard
We need a lot for space for a board, a screen and 6 buttons!
1 x Premium Male/Male Jumper Wires - 40 x 6" (150mm)
You are going to need a few cables to wire this all up.
1 x Tactile Button switch (6mm) x 20 pack
Enough buttons for a D-Pad, A, B, Menu. You can use the tiny breadboard buttons or full size Arcade buttons. You will be needing 7 total.

Part 1: Let's connect the screen

Let's begin by getting the screen up and running. First, solder male headers onto both the TFT screen breakout and the ItsyBitsy M4 Express. This makes it so that they can both be mounted easily onto the breadboard.

Above is a diagram that shows you how to connect everything. Be sure to check this out before starting to get a sense of what you'll be connecting. We've also attached the Fritzing file below for just the screen hookup.

Step 1

Mount the screen on the breadboard, next to the ItsyBitsy M4 Express.

Step 2

Connect the screen to the Itsy using male-male jumper cables. Starting from the left pin on the screen, follow the pin mapping specified in the bootloader. We've provided a chart below to show you how to map the pins to the ItsyBitsy.

Step 3

Power up your board and test that you're seeing the bootloader screen. If you have skipped the bootloader steps, now is the time to download it!

 

If you see a white screen or it isn't turning on, please check that every cable is secured and plugged into the breadboard properly.

 

When it all works, unplug the usb cable to continue the guide and get buttons connected.

Part 2 - Connecting the buttons for your Arcade

Next, we're going to hook up all the buttons for your Arcade. We're going to hook up an 'A', "B', "Left", "Right", "Up", "Down" and "Menu" button, which are all used in different ways in some of the games you can code or play on your Makecode Arcade.

Step 1: Hook up a single button

To start, below is a Fritzing diagram that shows how to hook up the ONE button to the ItsyBitsy M4 Express. The button hooked up in our example fritzing diagram below is the 'B' button. The B button is mapped to D7 on the ItsyBitsy M4.

You will be following a similar pattern for the remaining buttons by mapping them to their corresponding pins.

 

Step 2: Hook up the remaining buttons

As you can tell from above, connecting a single button is fairly simple. Below are the final mapping of pins on the breadboard to the ItsyBitsy M4.

Required Pin Mappings:

For the Arcade, you'll need to use the pin mappings below to hook up the remaining 6 buttons (A, Left, Up, Right, Down and Menu). We support 7 buttons in total.

  1. A ---> SCL
  2. Up ---> D9
  3. Right ---> D10
  4. Left ---> D11
  5. Down ---> D12
  6. Menu ---> SDA

With the mappings above, add 6 more switch pins to the bread board and get them all connected! Use the Fritzing diagram below if you need some visuals of how to connect the buttons for your Arcade.

 

We've also attached the Fritzing file in case you wanted an even closer look. Just make sure to download and install the additional Adafruit parts needed to open the file correctly in Fritzing (download here).

And here is what a fully assembled Arcade looks like! It's beautiful isn't it! :-)

Step 3: Load a game!

You've got a fully assembled MakeCode Arcade, so now it's time to load a game onto your Arcade. Here is what you need to do:

  1. First go to the MakeCode Arcade page: https://arcade.makecode.com
  2. Download the Level Up! game onto your ItsyBitsy M4 Express Arcade (see the Downloading games page for instructions)
  3. Play the game! You now should be able to move around and collect the cherries before time runs out!

Congratulations! You've just build your very own MakeCode Arcade board from parts. You can checkout the MakeCode Arcade site for additional games and start making your own as well!

Feather M4 Express

Here you will learn how to breadboard an Arcade from scratch using an Adafruit Feather M4 Express, a 1.8" TFT screen breakout and a few buttons. If you've already checked out the ItsyBitsy M4 Express page, we'll be following similar steps.

 

As always, before we get started, make sure you have the parts we've listed below!

1 x Adafruit Feather M4 Express
The board that will be running the Arcade game engine and driving the screen.
1 x 1.8" Color TFT LCD display with MicroSD Card Breakout
This will be the screen for your MakeCode Arcade
1 x Full size breadboard
We need a lot for space for a board, a screen and 6 buttons!
1 x Premium Male/Male Jumper Wires - 40 x 6" (150mm)
You are going to need a few cables to wire this all up.
1 x Tactile Button switch (6mm) x 20 pack
Enough buttons for a D-Pad, A, B, Menu. You can use the tiny breadboard buttons or full size Arcade buttons.

Part 1: Let's connect the screen

Let's begin by getting the screen up and running. First, solder male headers onto both the TFT screen breakout and the Feather M4 Express. This makes it so that they can both be mounted easily onto the breadboard.

Above is a diagram that shows you how to connect everything. Be sure to check this out before starting to get a sense of what you'll be connecting. We've also attached the Fritzing file below for just the screen hookup.

Step 1

 

Mount the screen and the Feather M4 Express onto the breadboard.

Step 2

Connect the screen to the Feather M4 Express using male-male jumper cables. Starting from the left pin on the screen, follow the pin mapping specified in the bootloader. We've provided a chart below with how to map the pin to the Feather M4 Express

Step 3

Power up your board and test that you're seeing the bootloader screen. If you have skipped the bootloader steps, now is the time to download it!

 

If you see a white screen or it isn't turning on, please check that every cable is secured and plugged into the breadboard properly.

 

When it all works, unplug the usb cable to continue the guide and get buttons connected.

Part 2 - Connecting the buttons for your Arcade

Next, we're going to hook up all the buttons for your Arcade. We're going to hook up an 'A', "B', "Left", "Right", "Up", "Down" and "Menu" button, which are all used in different ways in some of the games you can code or play on your Makecode Arcade.

Step 1: Hook up a single button

To start, below is a Fritzing diagram that shows how to hook up the ONE button to the Feather M4 Express. The button hooked up in our example Fritzing diagram below is the 'B' button. The B button is mapped to D6 on the Feather M4 Express.

 

You will be following a similar pattern for the remaining buttons by mapping them to their corresponding pins.

Step 2: Hook up the remaining buttons

As you can tell from above, connecting a single button is fairly simple. Below are the final mapping of pins on the breadboard to the Feather M4 Express.

Required Pin Mappings:

For the Arcade, you'll need to use the pin mappings below to hook up the remaining 6 buttons ( A, Left, Up, Right, Down and Menu). We support 7 buttons in total.

  1. A ---> SCL
  2. Up --->D10
  3. Right ---> D9
  4. Left ---> D11
  5. Down ---> D12
  6. Menu ---> SDA

With the mappings above, add 6 more switch pins to the bread board and get them all connected! Use the Fritzing diagram below if you need some visuals of how to connect the buttons for your Arcade.

We've also attached the Fritzing file in case you wanted an even closer look. Just make sure to download and install the additional Adafruit parts needed to open the file correctly in Fritzing (download here).

And here is what a fully assembled Arcade looks like using the Feather M4 Express. It's even more crazy than the ItsyBitsy isn't it?!

Step 3: Load a game!

You've got a fully assembled MakeCode Arcade , so now it's time to load a game onto your Arcade. Here is what you need to do:

  1. First go to the MakeCode Arcade page: https://arcade.makecode.com
  2. Download the Eater Princess game onto your Feather M4 Express Arcade (see the Downloading games page for instructions)
  3. Play the game! You now should be able to move around and collect the cherries before time runs out!

Congratulations! You've just build your very own MakeCode Arcade board from parts. You can checkout the MakeCode Arcade site for additional games and start making your own as well!

Downloading Games

components_29-_1060119.jpg
A single-button Arcade game using Adafruit Itsy Bitsy M4 Express

Once you have a game working on the MakeCode Arcade web editor, it's time to download it and flash it onto your Adafruit board. There are essentially two ways to do it:

  1. Using WebUSB in the browser. More details can be found here: WebUSB
  2. You can also drag and drop a .uf2 file.

You can find additional games by:

  1. Opening https://arcade.makecode.com in your favorite browser
  2. Either open a game that we've provided or start creating your own!

Downloading a game through WebUSB

If you are in a WebUSB-enabled browser (most likely Chrome), you will be prompted to pair your device with your browser. In fact, you will be prompted twice to pair the device in application mode and in bootloader mode (they are essentially two different devices). Once the pairing is completed, flashing will happen automatically in future. Here is how you do it:

  1. Connect your board to your computer with a micro-USB cable.
  2. Press the Download button on the Arcade interface in the browser you are using. If it is unpaired, you will be taken through a wizard to pair the application device and bootloader device.
  3. Wait a few seconds, and your board will be flashed!

Downloading a game with a drag and drop .uf2 file

When WebUSB is not available, you can always use the drag and drop flow. Here is how you do it:

  1. Connect your board to your computer with a micro-USB cable.
  2. Press the reset button to put your device in bootloader mode. You should see the bootloader picture with the big D51 sign.
  3. Press on the Download button in the Arcade editor and select the D51 hardware platform.
  4. Drag and drop the generated arcade-YOURGAME.uf2 file into the ARCD-D51 drive.
  5. Wait a few seconds and the board will restart in the game!

Sharing Games

There are plenty of ways to share games with your friends, family and anyone else who you think might enjoy something you've created!

Let's quickly go over a few of your options.

Online page

Click on the Share button and follow the steps to upload a version of your game online. It will generate a URL for you.

 

Anyone with the generated URL will be able to play in a full screen mode, or edit your game! They'll also be able to download it onto their own Arcade if they have one.

 

This page supports oEmbed and other various embedding options.

Save into an image

Click the disk icon will save your code into a PNG image. You can import the image back or simply drag and drop it into the editor to reload the code.

 

The image below contains the falling duck game.

You will literally want to download the image itself - its a polyglot file that contains data within its pixels!

Downloaded .UF2 files

Downloaded .uf2 files also contain the game code. You can import them or drag and drop them into the editor to reload the code.

GitHub repo

You can also use GitHub repositories to store and share your code. This is particularily useful if you end up building a lot of code or if you want to share an extension with other users. Read all about getting started with GitHub at https://makecode.com/extensions/github-authoring .

Resources

Bootloaders

Attached below are the current boards we support for building your own MakeCode Arcade. More will be coming soon!

Fritzing files

Attached below are the Fritzing files for the supported boards from the guide!

This guide was first published on Jan 18, 2019. It was last updated on Jan 18, 2019.