Tutorial 1: The Basics of an Uzebox Game

From Uzebox Wiki
Jump to: navigation, search

What are the key elements of creating a video game?

This guide is a compilation of existing information on Uzebox as well as my own personal additions. The goal of this guide is to help the new Uzebox programmer to learn what is needed to create an Uzebox game. It will cover creating a development environment, learning the tools of the development environment, learning the APIs of the Uzebox, and creating an example game. The examples will assume Video Mode 3.

Key Elements in a Video Game: Tiles

Read the "Hello Tile" article from ladyada.net. It gives a great explanation of why tiles are important. Additionally, the Hello World wiki article covers many of the Uzebox basics. You should read over these articles first!

Link: Hello World: Hello_World

Hello Tile: http://www.ladyada.net/make/fuzebox/hellotile.html

  • Assuming that each pixel on the screen contained 8-bits (which would account for a red, green, and a blue value) a screen would require a large amount of RAM to display. The example from the Fuzebox “Hello tiles!” tutorial explains that if you have 240 by 224 pixels on screen and each pixel requires 1 byte then it would take around 52 kilobytes (53760 bytes!) of data. That may not seem like much but the Uzebox uses a small microcontroller that only has 4 K of RAM available. 52 Kb simply will not fit into a 4 Kb space.
Tile alignment.
  • What if we take the complete screen and break it down into small squares? These squares could be 8 by 8 pixels. If you look at the graphic in the above link you can see that much of the screen data is repeated. The blocks at the bottom are repeated, the clouds are repeated, and the blue background is repeated the most often. Instead of storing the screen data in its entirety, you could simply draw individual squares. If that square is already used then you just point to the original square in Video RAM. You could store a map that would indicate where each of these squares on the screen belong. Maps display arrangements of these squares on the screen.
  • These squares are referred to as ‘Tiles’ and are the main way to put images on the screen. Tiles save VRAM as well as flash because you won’t have to store repeating data. If you still don’t understand then think of tiles as a cheap form of compression. In a way, this is exactly what we are doing. Consider also that the Uzebox uses flash memory to store all of the graphics. Tiles save on flash storage as well as RAM usage.
  • The graphical elements of your game will take up the most RAM and flash space. Therefore, it is a good idea to keep in mind that re-using tiles will allow more room for your game. Try to fit your graphics into as few tiles as possible to save on flash memory. You should also align your tile patterns within 8x8 squares (or whatever the tile size is for your video mode). This will save tiles and be more efficient.

Key Elements in a Video Game: Sprites

  • Like tiles but can be positioned with pixel-level precision.
  • Sprites are your game’s actors and dynamic elements.
  • Can have up to 256 8x8 pixel sprites in a game. (Video Mode 3.)
    • NOTE: The kernel uses the higher indexes for the sprite/background overlaps so stuff will look corrupted before you reach 256.
  • Roughly 20 sprites can be on the screen at a time with Video Mode 3.
    • Depends on RAM.
  • Sprites can have transparent regions.
    • The value for a transparent pixel within a sprite is 0xFE.
  • You can flip sprites along the x-axis at runtime in video mode 3 in order to save space. For example, the image for Mario is exactly the same if he is facing left or right. Instead of storing the image for him standing in both directions you would just store him standing in one direction. You then could flip the image for him to face the other direction.
Super Mario 2x5.
  • The sprite is just a data type to facilitate using the actual ram tiles. If you look inside videoMode3.c you'll see all this and that these are used to calculate the ram tiles needed, the tile under the sprite, the sprite index and finally copy the tile data (from the tile that was there) under the sprite to the ram tile and overlay the sprite tile pixels (these later parts are done in assembly for speed, see videoModeCore3.s). So ram tiles are just like a normal tiles (always aligned on 8pixel boundaries x/y) but are indexes into ram instead of flash memory. Any sprite overlapping even 1 pixel of the tile necessitates a ram tile be placed there, which is the reason sprites that are not bound to either axis are extremely expensive. Anyways maybe you knew all this, but the moral of the story is to design around those situations, implement flickering (simple way: draw sprites first to last, and alternate from last to first), and/or cut the screen height down. You may need to make your own sprite setup routines to have better control of all these factors, since the kernel can't be designed optimally for everything someone might want to do.

Key Elements in a Video Game: Ram-tiles

  • When tiles overlap (like when a sprite tile(s) overlaps tiles while moving) they must be displayed together. Ramtiles allow for this. More ramtiles means more/bigger sprites and mega-sprites. As the name implies, this requires more RAM than already used by just the tiles themselves.
    • To recap, a RAM-tile is used when you overlay a sprite on a background. You will use one RAM-tile for each sprite of a megasprite.
      • Additionally, if your mega-sprite partially (even by 1 pixel) overlaps an adjacent tile then another RAM tile will be used.
  • RAM-tiles can be used in very creative ways. You cannot change flash inside your program but RAM is fair game. You can apply any number of effects to a ram tile and then display it.

Key Elements in a Video Game: What is a Video Mode?

  • How Video Modes Work: http://uzebox.org/wiki/index.php?title=How_Video_Modes_Work
  • Video Generation Basics: http://uzebox.org/wiki/index.php?title=Video_Generation
  • Video Mode 3: http://uzebox.org/wiki/index.php?title=Video_Mode_3
  • Mode 3: 8x8 pixel tiles. 240x224 pixel resolution. Total of 30x28 tiles.
    • If not using the scrolling mode then you have a total of 30x30 tiles.
  • Special section you can enable at the top of the screen to display scores, etc.
  • Full screen scrolling:
  • No scrolling:
  • For VRAM_TILES_V==32
    • LDFLAGS += -Wl,--section-start,.noinit=0x800100 -Wl,--section-start,.data=0x800500
  • For VRAM_TILES_V==24
    • LDFLAGS += -Wl,--section-start,.noinit=0x800100 -Wl,--section-start,.data=0x800300
  • VRAM_TILES must be a multiple of 8.

Key Elements in a Video Game: What is a Collision?

A collision is when two or more tiles meet (touch) each other. For example, in a Space Invaders game a collision would occur if the projectile from the player meets one of the invaders. Your game would need to handle this event. A collision would occur if your player jumps onto a platform. The game would need to know that the player’s fall from a jump or higher platform should stop when they hit the top of a platform.

Key Elements in a Video Game: What is Program Code?

Program code is what glues all of your graphics and game logic together. Some code will display a graphic and other code will change that graphic. Conditions can be checked against in the event that your player touches a wall or a bad guy. Graphics are important but the code is what makes the game a game and not just an arrangement of tiles. There are many guides on the web that explain the concepts of programming. I will provide some links to those as well as some Uzebox examples.

Key Elements in a Video Game: What is a Development Environment?

Your development environment, (sometimes referred to as a ‘kitchen’) will contain all the tools that you use to create your program. There are many tools available. The following is a list of tools that you should consider for your development environment.

Development Environment Tools

  • Getting started on Uzebox:
  • Download the Uzebox files: https://code.google.com/p/uzebox/downloads/list
  • Download the latest dev trunk (Ex. Uzebox Win32 sources and binaries.)
    • Gconvert is in this download. So is Uzem.
  • Download the Uzem emulator (Ex. Uzebox Emulator v1.16 for Windows 32-bit.)
    • Replace the version from the dev trunk with this newer version.
  • Download the rom pack (Pack of all Uzebox ROMS.)
    • The source code for existing games will be helpful to study.
  • Download WinAVR: http://sourceforge.net/projects/winavr/files/WinAVR/
    • This allows the game to be complied for use with the emulator or the Uzebox hardware.
      • Install this right now.
  • Download The GIMP:
    • http://www.gimp.org/downloads/
    • The GIMP is an open-source graphics editor. It has similar functionality to the better-known Adobe Photoshop. With The GIMP, you will be able to edit tile sets.
    • NOTE: If you do not want to learn a new tool, the built-in MS Paint program (from Windows) can do some of the basics. However, the last step will be to convert your image to either RAW or PNG-8 by using The GIMP.


  • UPDATED: 2014-02-10: Added info on RAM tiles
  • Add some graphics to explain tiles, sprites
  • Correct any technical errors.