Getting Started on the Uzebox

From Uzebox Wiki
Jump to navigation Jump to search


To start developing games and programs on the Uzebox you will need the following:

  • Some knowledge of the C language: This language has been around for decades and is still the de-facto high level language for embedded applications.
  • A physical Uzebox or the emulator: You are not obliged to develop on the hardware, the emulator will speed up the process since you won't have to reprogram the micro-controller or copy your game to an SD card every time.
  • An AVR programmer: When using a physical Uzebox, this is also known as an ISP programmer (In System Programmer). This device is used to program your game on the micro-controller, without having to remove it from the board. Many programmers can be found on the market such as the USBTINYISP, Pocket AVR Programmmer, AVRISPMKII and Atmel ICE.
  • An IDE (Integrated Development Environment): This is a program that eases the development process by checking syntax, invoking the compiler and more. Some use Microchip Studio (Windows), Eclipse CDT(Multi platform) or even a plain text editor.
  • The GNU GCC tool chain for AVR. This is made of a series of programs and tools required to compile your programs into a form that can run on the AVR micro-controller.
  • The GNU GCC tool chain for your computer processor. Required to compile the Uzebox tools (ex.: emulators, graphics conversion tool, etc.)

Software Installation

This section explains how to download and install the required tool and also how to get the Uzebox sources and compile them.

Windows specific toolchain installation can be found here.

Mac specific toolchain installation can be found here.

Linux specific toolchain installation can be found here.

After the tools installation, sources checkout and build process has completed, you will end up with the following structure under your work directory:

/bin   : Executables for the compiled tools
/demos : The projects for games and demos
/gfx   : Graphic assets you can copy to your project like fonts
/kernel: Sources and libraries for the Uzebox engine that you embed in your projects
/roms  : All games and demos compiled ROMs in .HEX and .UZE formats. HEX files are used with a chip programmer, UZE files are used with the emulators and bootloader.
/tools : Sources for the Uzebox tools

Flashing the Uzebox

When you compile a Uzebox program, a .HEX file will be generated. This is the uncompressed machine language code for the ATMega644. You need a tool to program (aka flash) the chip with your program.

  • Windows users can do this either using Atmel/Microchip Studio or the command line tools Atprogram or avrdude.
  • Linux users can use avrdude.

While flashing programs is common during development, specially if your program uses features not supported by the emulators, most will want to flash the Uzebox Game Loader (aka bootloader) and use that to load games from a SD card. This avoids having to use a chip programmer each time you wish to play a different game.


What if you want to write video games but you have no programming knowledge whatsoever? I can highly recommend that you read the free online book Program Arcade Games With Python And Pygame. That book will teach you to develop games using Python, which you can't use to code for the Uzebox directly but you will find C much easier to learn after learning Python. Almost all of the concepts you will learn in that book can be applied to writing Uzebox games in C and also other game engines such as Godot, which uses a scripting language called gdscript that is very similar to Python.

If you already know C or a similar programming language, then you should watch Matt Pandina's "Let's code for the Uzebox" series of videos for a good introduction to getting started with developing for the Uzebox under Linux.

There are several demos and simple games in the demos directory of the Uzebox repo. Ghosty Ghost is a simple and very thoroughly commented game that uses scrolling.

If you want to learn AVR assembly, check out this site. You may also refer to the avr-gcc ABI and the Assembler Tips wiki page.

For more in depth and advanced Uzebox development tutorials see Weber's Rants.

Uzebox developers requiring more low-level AVR information should refer to the avr-libc manual pages.