Gameduino: getting started


This page collects all the software tools for the Gameduino 3X.

With the Arduino IDE

The Gameduino library supports Gameduino 2, 3 and 3X -- it auto-detects the attached board at startup. The library is tested with Arduino, ESP8266 and Teensy controllers.

The current version of the GD2 library is 1.3.4. It supports GD2, GD3 and GD3X, including the Dazzler.

To install it:

  1. download the library
  2. install it in the Arduino IDE. Instructions for doing this are at
  3. restart the Arduino IDE, and load one of the sketches, for example File Sketchbook libraries Gameduino2 1.Basics helloworld

Some examples don't need a microSD card, some do (see the FAQ for a list). To prepare a card, format it and copy the files in to it.

With CircuitPython

We've worked with Adafruit to add support for the Gameduino into CirCuitPython. This page has all the details.


The new Gameduino 3X Dazzler has its own User Guide and Datasheet.

The Gameduino 2/3 printed book is available from Amazon USA, UK, France and Germany.

The Gameduino 2/3 online book is available as a PDF download. A Chinese translation by YunFei Robotics Laboratory is also available for download.

The asset converter

The asset converter is a program that prepares media on your PC for use with the Gameduino 2/3. You can use the asset converter to:

  • convert sprite graphics for the Gameduino2
  • convert audio samples
  • convert TrueType (TTF) fonts

After installation, you can run the asset converter by typing:

gd2asset --help


gd3asset --help

into a command shell. You should see something like:

usage: gd2asset <options> <assets>

  -o   output header file
  -f   output asset file (default is header file)

If no output header file is given, then "default_assets.h" is used

Each asset is a filename, optionally followed by some var=val
assignments. For example:
  pic1.png                 image, format ARGB4
  pic2.jpg,format=L8       image, format L8
  serif.ttf,size=16        font, 16 pixels high

The assets are compiled into flash, or if the "-f" option is given
into a file. In this case the file should be copied to the
microSD card.
In either case, calling LOAD_ASSETS() from the program loads all

There are two ways of storing assets. The first is to use an array in Arduino flash memory. This works well for small sized assets, up to around 20K. The second way is to load the assets from SDcard memory.

If you run it like this:

gd2asset -o myassets.h pic1.png pic2.png pic3.png

then it creates a file myassets.h. Add it to your Arduino sketch, and in your sketch do:

#include "myassets.h"

and after GD.begin(), do:


and you can use the assets pic1, pic2, pic3, for example:

GD.Vertex2ii(10, 100, 0); // pic1
GD.Vertex2ii(10, 200, 1); // pic2
GD.Vertex2ii(10, 300, 2); // pic3

If you run gd2asset like this:

gd2asset -f myassets.gd2 -o myassets.h pic1.png pic2.png pic3.png

then it creates two files:

  • myassets.gd2 - copy this onto your microSD
  • myassets.h - include this from your program

Copy myassets.gd2 to the SDcard, and the sketch can use the assets as above. The only difference is that the data is stored on the SDcard instead of taking up flash memory.

Installation on Mac and Debian/Ubuntu

The Gameduino 2/3 asset converter is available at It is a pure Python package. Its only dependency is on Pillow. You can install the latest version with:

pip install -U gameduino2

and run it by typing:


Installation on Windows

If you are a Windows Python user, you can use the above pip command. Alternatively you can use pre-built executables. For GD2 use:

And for GD3 use:

Note that these are command-line utilities, so you run them from a Command prompt. For example: