Make sure you have the latest CircuitPython firmware loaded for your board to use displayio. You can download it from the link below.

This example is simple, but shows a basic usage of what makes TileGrid so cool. While you can create a TileGrid with multiple tiles, you can also create a TileGrid with just a single tile. This special case is often referred to as a "sprite". You still need a source Bitmap for the TileGrid. So we use one that contains several sprites all arranged nicely. This is called a "sprite sheet".

Here's a nice little sprite sheet bitmap we will use for this example:

It's super tiny! If you zoom in, it looks like this:

Let's add a grid overlay to better show each individual pixel:

You can see how there are 6 total sprites. Each sprite is 16 pixels wide by 16 pixels high. We want to slice it up like this:

Remember, this is not the TileGrid. This is just how the source bitmap is sliced up to provide source tiles for the TileGrid.

We will create a TileGrid with only one tile (sprite). We can then change the index of this TileGrid to be whichever of these 6 characters from the source bitmap (sprite sheet) we want to show. And we can change it again to show a different one, etc.

We have everything we need:

  • A source Bitmap - the sprite sheet
  • We know each sprite is 16 pixels by 16 pixels
    • tile_width = 16
    • tile_height = 16
  • We know we want a TileGrid that is only 1 wide by 1 high
    • width = 1
    • height = 1

Here is what creating the TileGrid would look like to set this up:

sprite = displayio.TileGrid(sprite_sheet, pixel_shader=palette,
                            width = 1,
                            height = 1,
                            tile_width = 16,
                            tile_height = 16)

By default, the source index will be 0 to start with. So the sprite is set to show Blinka (the purple snake). You can change it to any of the other 6 sprites using the syntax:

sprite[0] = 1

Now the sprite is set to show Adabot - index 1. Note that the sprite index is [0], which is the only index that applies in this case, since there's only 1 tile in the TileGrid.

Want Sparky? Do this:

sprite[0] = 4

And so on.

Sprite Sheet Example

Here's the full code. It loads the source Bitmap, sets up the TileGrid, adds it to a Group, which is then added to the Display so it's finally shown. It then cycles through each of the sprites.

import time
import board
import displayio
import adafruit_imageload

display = board.DISPLAY

# Load the sprite sheet (bitmap)
sprite_sheet, palette = adafruit_imageload.load("/cp_sprite_sheet.bmp",

# Create a sprite (tilegrid)
sprite = displayio.TileGrid(sprite_sheet, pixel_shader=palette,
                            width = 1,
                            height = 1,
                            tile_width = 16,
                            tile_height = 16)

# Create a Group to hold the sprite
group = displayio.Group(scale=1)

# Add the sprite to the Group

# Add the Group to the Display

# Set sprite location
group.x = 120
group.y = 80

# Loop through each sprite in the sprite sheet
source_index = 0
while True:
    sprite[0] = source_index % 6
    source_index += 1

Change The Scale!

The sprites are pretty small. The default scale is 1, so each pixel of the sprite is a pixel on the display. You can change this using the scale parameter which is passed in when creating the Group.

Try changing that to something like 2 or 4 and running the code again. It's this line of code:

group = displayio.Group(scale=1)

Now the sprites should show up much larger!

Change The Location!

Want the sprites to show up in a different location? You can do so by changing these lines and setting new values for x and y.

group.x = 120
group.y = 80

This guide was first published on Apr 30, 2019. It was last updated on 2021-02-27 10:36:25 -0500.

This page (Sprite Sheet) was last updated on Jun 16, 2021.

Text editor powered by tinymce.