Make Your Own Arduboy Game: Part 6 - Graphics!

Previous parts of this series: Part 1, Part 2, Part 3, Part 4, Part 5

This Tutorial

In this tutorial, I’m going to show you how to make a game demo where you can move a sprite around a screen that has a tiled background. I’ll also teach you some more basic programming fundamentals.

Starting Code

Let’s use this code to start our program. Open the Arduino IDE, start a new project, and make sure the code looks like this:

//Jonathan Holmes (crait)
//November 1st, 2016
//Moving Character Demo
#include <Arduboy2.h>
Arduboy2 arduboy;

void setup() {
  arduboy.begin();
  arduboy.clear();
}

void loop() {
  arduboy.clear();
	
  arduboy.display();
}

Starting Images

Right-click and download these two images to your computer.

This image will be your background image. We’re going to tile it across the entire Arduboy screen.

This image will be your player sprite, which is the image that represents your character. You’ll move this face around your screen on the Arduboy.

Convert Images

Remember how I said that you can store data and variables in several formats? Remember, one format that we used before for numbers was int. Well, to store images, we actually want to convert them into raw data that we can store them in byte arrays. Don’t worry too much about what that means, just know it’s different than an int and can hold a different amount of data.

I’ve seen some people on this forum say that they convert images to raw data by hand, but luckily, there are some nice tools to convert the graphics for you. The one I use is https://teamarg.github.io/arduboy-image-converter/ created by Team ARG.

The site is simple to use - simply drag the images previously saved to your machine onto the page and it will generate the data required to render the image.

Repeat the step for the player graphic:

Here’s the raw data for background image:

const unsigned char PROGMEM background[] = {
// width, height,
8, 8,
0x81, 0x00, 0x12, 0x40, 0x04, 0x11, 0x00, 0x04, 
};

Here’s the raw data for the player sprite:

const unsigned char PROGMEM player[] = {
// width, height,
16, 16,
0xfe, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0x01, 0xc1, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0xfe, 
0x7f, 0x80, 0x9c, 0xbc, 0xb0, 0xb0, 0xb2, 0xb2, 0xb3, 0xb0, 0xb0, 0xb0, 0xbc, 0x9c, 0x80, 0x7f, 
};

Hold onto these for a second and I’ll teach you where to put them.

Talking About Initializing Variables

Alright, I kinda left out some information about initializing variables. So far, I’ve had you initialize variables at the top of the sketch, right under the Arduboy2 arduboy; line. But, it’s important to know that you can actually initialize them pretty much anywhere. We’ll do that later on, so I don’t want it to surprise you.

I want to teach you a shortcut, though. When we’ve been initializing variables, we have been doing them in the following format:

int counter;
counter = 5;

This is valid, but there’s a shortcut that you can take. You can actually set a value to a variable at the same time you initialize it.

int counter = 5;

Cool, huh? You can also do this with constants.

Constants

A constant is like a variable in the sense that you can have it store data that you can also initialize. The only difference is that the data can’t be changed. It saves memory to store data in constants instead of variables if you aren’t going going to change the data that it holds. We’ll do that with our image data since we won’t change the images at all.

To create a constant, you use the const keyword in front of the initialization.

int counter = 5;
const int height = 5;

Since you can’t change the data inside of a constant, height cannot be changed or given a new value. If you were to use the following code, you would get an error and the code will not work.

height = 12;

Storing Images

Whew! That was a lot to tell you real quick, but let’s move on to storing the raw image data into byte arrays. Where you normally initialize variables, put the following code:

const unsigned char PROGMEM background[] = {
// width, height,
8, 8,
0x81, 0x00, 0x12, 0x40, 0x04, 0x11, 0x00, 0x04, 
};

const unsigned char PROGMEM player[] = {
// width, height,
16, 16,
0xfe, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0x01, 0xc1, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0xfe, 
0x7f, 0x80, 0x9c, 0xbc, 0xb0, 0xb0, 0xb2, 0xb2, 0xb3, 0xb0, 0xb0, 0xb0, 0xbc, 0x9c, 0x80, 0x7f, 
};

To summarize this code, we converted 2 images to 2 groups of characters . One is named background and the other is named player . Let’s break this code down a little and go word-by-word.

  • const : We already know that we are creating a variable that cannot be changed.
  • unsigned : This means that we cannot use negative values. Just ignore this for a while.
  • char : The way we store byte data is by putting it into a char , which stands for character . This is the kind of variable that we are creating instead of using an int like the last tutorial. :wink:
  • background : Like all variables, we need to give these two character arrays names. The top one is called background and the bottom one is called player .
  • [] : The brackets that you see here means that we’re creating an array . An array is a group of variables. We’re creating groups of char variables. We can call them character arrays .
  • = : Like in the shortcut that I explained above, when you initialize a variable, you can assign a value to it at the same time. We can do this with arrays. We’ll actually assign the characters directly into the array.
  • { } : Anything inside of the braces is what we’re actually putting inside of the array.
  • 0x84, 0x20,... : This is the data that we got from the TeamARG site. It’s an image stored in multiple bytes/characters. Each character is separated by a comma.

What about PROGMEM ?? No need to worry too much about what that means. Leave that in, though! It’s a special word called a macro that will tell the compiler where to store the array in memory. It makes storing images more efficient for us.

Your game’s code should look like this:

//Jonathan Holmes (crait)
//November 1st, 2016
//Moving Character Demo
#include <Arduboy2.h>
Arduboy2 arduboy;

const unsigned char PROGMEM background[] = {
// width, height,
8, 8,
0x81, 0x00, 0x12, 0x40, 0x04, 0x11, 0x00, 0x04, 
};

const unsigned char PROGMEM player[] = {
// width, height,
16, 16,
0xfe, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0x01, 0xc1, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0xfe, 
0x7f, 0x80, 0x9c, 0xbc, 0xb0, 0xb0, 0xb2, 0xb2, 0xb3, 0xb0, 0xb0, 0xb0, 0xbc, 0x9c, 0x80, 0x7f, 
};

void setup() {
    arduboy.begin();
    arduboy.clear();
}
void loop() {
    arduboy.clear();
    arduboy.display();
}

Parameters

I can’t wait to show you how to draw the above images to the Arduboy screen! But I can’t just yet! :open_mouth: I need to tell you about a function’s parameters! Remember that a function is an instruction for the computer. Sometimes, they look like this:

arduboy.clear();

That clears the Arduboy’s screen. It’s a function that is easy to understand. Here’s another:

arduboy.print(randomnumber);

This is from the last tutorial. The randomnumber is a variable that we put into the function. We told the Arduboy what to print. That’s called a parameter. And in fact, functions can have multiple parameters. We already saw one earlier that did this in the last tutorial, too!

arduboy.setCursor(0, 0);

The arduboy.setCursor() function requires two parameters that are separated by a comma.

The function to draw an image to the Arduboy’s screen has a lot more parameters that you need to use. This is actually pretty common.

Drawing Images

So, we want to draw an image to the Arduboy screen, finally! Let’s start by drawing the player sprite that we called player . Inside of the loop() area, after we clear the screen, let’s add this line of code:

Sprites::drawOverwrite(5, 10, player, 0);

Before we go any further, let’s talk about the Sprites functions. The Arduboy2 library provides a number of functions to render sprites (or graphics) on the screen with both transparent and solid backgrounds. As you
can see from the example we use the prefix Sprites. For the moment you can consider this to be the same as calling functions against the arduboy library.

  • The first two parameters are 5 and 10 . These numbers represent the X and Y location that the image will be drawn to. Changing these numbers will change where the image appears.
  • The next parameter that’s given is the image that we want to draw, which is player .
  • the last parameter is what ‘frame’ to draw. Our examplke sprites have only one frame (with zero being the first) but it is possible to have a graphic with multiple frames in it that might represent a player walking or some other action.
    This is beyond the scope of this tutorial but you can find a detailed discussion in the Arduboy magazine.

Okay! If your code looks like the following, then go ahead and put it on your Arduboy!

//Jonathan Holmes (crait)
//November 1st, 2016
//Moving Character Demo
#include <Arduboy2.h>
Arduboy2 arduboy;

const unsigned char PROGMEM background[] = {
// width, height,
8, 8,
0x81, 0x00, 0x12, 0x40, 0x04, 0x11, 0x00, 0x04, 
};

const unsigned char PROGMEM player[] = {
// width, height,
16, 16,
0xfe, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0x01, 0xc1, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0xfe, 
0x7f, 0x80, 0x9c, 0xbc, 0xb0, 0xb0, 0xb2, 0xb2, 0xb3, 0xb0, 0xb0, 0xb0, 0xbc, 0x9c, 0x80, 0x7f, 
};

void setup() {
    arduboy.begin();
    arduboy.clear();
}
void loop() {
    arduboy.clear();
    Sprites::drawOverwrite(5, 10, player, 0);
    arduboy.display();
}

Your Arduboy should properly display as:

Control The Sprite

Okay, remember how we controlled the value of a variable with the Up and Down buttons? To move the sprite around, we’ll do something very similar.

To start, let’s initialize 2 variables at the top of the sketch:

int playerx = 5;
int playery = 10;

The playerx and playery variables will hold the coordinates for our image as it’s moving around. In the arduboy.drawBitmap() function, let’s replace the X and Y parameter with these variables.

arduboy.drawBitmap(palyerx, playery, player, 16, 16, WHITE);

Let’s increase/decrease those variables’ values when the Up/Down and Left/Right buttons are pressed.

if (arduboy.pressed(LEFT_BUTTON)) {
    playerx = palyerx - 1;
}
if (arduboy.pressed(RIGHT_BUTTON)) {
    playerx = palyerx + 1;
}
if (arduboy.pressed(UP_BUTTON)) {
    playery = palyery - 1;
}
if (arduboy.pressed(DOWN_BUTTON)) {
    playery = palyery + 1;
}

That’s all it takes to move an image around the screen! Test out the code on your Arduboy and have fun with it!

//Jonathan Holmes (crait)
//November 1st, 2016
//Moving Character Demo
#include <Arduboy2.h>
Arduboy2 arduboy;

int playerx = 5;
int playery = 10;

const unsigned char PROGMEM background[] = {
// width, height,
8, 8,
0x81, 0x00, 0x12, 0x40, 0x04, 0x11, 0x00, 0x04, 
};

const unsigned char PROGMEM player[] = {
// width, height,
16, 16,
0xfe, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0x01, 0xc1, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0xfe, 
0x7f, 0x80, 0x9c, 0xbc, 0xb0, 0xb0, 0xb2, 0xb2, 0xb3, 0xb0, 0xb0, 0xb0, 0xbc, 0x9c, 0x80, 0x7f, 
};

void setup() {
    arduboy.begin();
    arduboy.clear();
}

void loop() {
    
  arduboy.clear();
  arduboy.pollButtons();

  if(arduboy.justPressed(LEFT_BUTTON)) {
      playerx = playerx - 1;
  }
  if(arduboy.justPressed(RIGHT_BUTTON)) {
      playerx = playerx + 1;
  }
  if(arduboy.justPressed(UP_BUTTON)) {
      playery = playery - 1;
  }
  if(arduboy.justPressed(DOWN_BUTTON)) {
      playery = playery + 1;
  }

  Sprites::drawOverwrite(playerx, playery, player, 0);
  arduboy.display();

}

For Loop

Okay, remember how I said that loops tell the computer to repeat a set of actions over and over again? I’m going to teach you about one called the for loop. This loop allows you to repeat a set of instructions for a specified amount of times.

Why is this important? We want to make a background for this game, but the background image that we have is too small to fill the entire screen, so we’ll print it many times in different places until it fills up the entire screen.

Let’s say we want to use the arduboy.print(); function to print your name 10 times in a row. We’d have to use a loop keyword and we’ll need a variable to keep track of how many times we’ve printed so far, and a line of code to increase that variable every time we loop through. Luckily, the for loop has a lot of that built-in. Take a look at it, below:

for (int counter = 0; counter < 10; counter = counter + 1) {
  arduboy.print("crait");
}

Alright, again, let’s break this down:

  • for : This is kinda like a function. It lets the Arduboy know you want to use a for loop.
  • int counter = 0; : Whenever you run a for loop, you’ll need to initialize/set a variable. We create a counter variable that is equal to 0. This code gets executed before the loop is entered.
  • counter < 10; : This is the check to see if the loop should run or not. If counter is less than 10 , then it should run.
  • counter = counter + 1 : After all of the instructions inside of the loop are followed, this code is ran. It increases counter by 1 . Eventually, counter will grow big enough so that the loop does not execute anymore.
  • { } : Anything inside of these braces will be considered part of the loop and only be executed when the Arduboy is running this for loop.

Instead of this code printing my name 10 times, we can have it count!

for (int counter = 0; counter < 10; counter = counter + 1) {
  arduboy.print( counter );
}

If we run the above loop, the Arduboy would print out the numbers 0 to 9! You can change the number of times it will loop, you can change what number the counter starts with, and you can even change how many numbers counter is increased by every time the loop is run.

Tile Background

Alrighty! Let’s get the background implemented! We’re almost done!

The Arduboy’s screen resolution is 128 pixels wide by 64 pixels tall, which means if we use a background image of 8 pixels by 8 pixels, we would have 16 columns wide by 8 rows high.

Let’s tile the background image 8 times across the top of the screen.

for (int backgroundx = 0; backgroundx < 128; backgroundx = backgroundx + 8) {
  Sprites::drawOverwrite(backgroundx, 0, background, 0);
}

Do you understand what’s going on, here? :slight_smile: Notice that the backgroundx variable is used to count the loop, but also used when drawing the background image. Since we want to span the background across the width of the screen, we want to count up to 128. Because we want to put a new image every 8 pixels, we’ll increase it by 8 every time a tile is drawn.

Add this code before you draw your sprite and run it on your Arduboy. It should appear like this:

Next, let’s add another for loop. Instead of doing this after the previous loop, we’ll have this loop inside of the other!

for (int backgroundx = 0; backgroundx < 128; backgroundx = backgroundx + 8) {
  for (int backgroundy = 0; backgroundy < 64; backgroundy = backgroundy + 8) {
    Sprites:drawOverwrite(backgroundx, backgroundy, background, 0);
  }
}

To summarize the above code, for each column on the screen, we will draw several rows of background images until the screen is full. This is the result:

Here’s the full code:

//Jonathan Holmes (crait)
//November 1st, 2016
//Moving Character Demo
#include <Arduboy2.h>
Arduboy2 arduboy;

int playerx = 5;
int playery = 10;

const unsigned char PROGMEM background[] = {
// width, height,
8, 8,
0x81, 0x00, 0x12, 0x40, 0x04, 0x11, 0x00, 0x04, 
};

const unsigned char PROGMEM player[] = {
// width, height,
16, 16,
0xfe, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0x01, 0xc1, 0x01, 0x3d, 0x25, 0x25, 0x3d, 0x01, 0xfe, 
0x7f, 0x80, 0x9c, 0xbc, 0xb0, 0xb0, 0xb2, 0xb2, 0xb3, 0xb0, 0xb0, 0xb0, 0xbc, 0x9c, 0x80, 0x7f, 
};

void setup() {
  arduboy.begin();
  arduboy.clear();
}

void loop() {

  arduboy.clear();
  arduboy.pollButtons();

  if (arduboy.justPressed(LEFT_BUTTON)) {
    playerx = playerx - 1;
  }
  if (arduboy.justPressed(RIGHT_BUTTON)) {
    playerx = playerx + 1;
  }
  if (arduboy.justPressed(UP_BUTTON)) {
    playery = playery - 1;
  }
  if (arduboy.justPressed(DOWN_BUTTON)) {
    playery = playery + 1;
  }

  //For each column on the screen
  for (int backgroundx = 0; backgroundx < 128; backgroundx = backgroundx + 8) {
  //For each row in the column
    for ( int backgroundy = 0; backgroundy < 64; backgroundy = backgroundy + 8) {
      //Draw a background tile
      Sprites::drawOverwrite(backgroundx, backgroundy, background, 0);
    }
  }

  //Draw player sprite
  Sprites::drawOverwrite(playerx, playery, player, 0);
  arduboy.display();
}

What’s Next?

What’s next? I’ll teach you how to make your own Pong game from scratch!! Click here to go check it out!

Credits

I wrote this tutorial in order to give back to the programming community that taught me to get into it about 10 years ago. If you’d like to follow me on Twitter, please do so at http://www.twitter.com/crait . I’d greatly appreciate that. :slight_smile:

3 Likes

@crait Is it possible to write the for loop as such?

for ( int counter = 0, 10; counter++) {

}

for ( int counter = 0, 10; counter++ ) {
I haven’t seen that writing style, before. I don’t think that would work, but, I know that C++ is still an evolving language and new features are being added, so if it is valid C++, it must be so knew that I haven’t seen it.

Did you see this anywhere? I’m very interested.


for (int counter = 0; counter < 10; counter = counter + 1) {
  arduboy.print("crait");
}

No, it isn’t.

You always have to have a condition, and you always have to have two semicolons separating the three parts of the for.

The structure of a for loop is basically:

for(/*initialiser*/; /*condition*/; /*step*/)
{
	/*body*/;
}

Which the compiler effectively translates into:

{
	/*initialiser*/;
	while(/*condition*/)
	{
		/*body*/;
		/*step*/;
	}
}

Hopefully that gives you a bit more insight into what’s going on.


However, it would be possible to do something like:

for(int counter : range(0, 10))
{
}

If you had a suitably defined range function.

You can use counter++ instead of counter = counter + 1 though.
Personally I recommend getting used to ++counter though,
particularly if you plan to eventually move to desktop programming.

2 Likes

@crait I have seen this done in other languages and I am just trying to work out some of what will work and what won’t with each language to know the differences between them. Thank you and @pharap for helping me! That makes total sense.

1 Like

What might that ‘range’ function look like? Now, I’m curious! and is there any difference between the way ++counter and counter++ are compiled?

If you’re still new to programming then you might regret asking those questions. :P

I’ve buried all the more detailed explainations in ‘details’ blocks so you’re not overwhelmed by text and can read as much or as little as you’re happy with.

The function itself isn’t where the magic is, it’s in the object that gets returned.

The simplest possible way I can think of doing it...
struct IntIterator
{
	int value;

	IntIterator() = default;

	constexpr IntIterator(int value) :
		value(value)
	{
	}

	constexpr int operator*() const
	{
		return value;
	}

	IntIterator & operator ++()
	{
		++value;
		return *this;
	}

	IntIterator operator ++(int)
	{
		IntIterator result = *this;
		this->operator++();
		return result;
	}
};

bool operator==(const IntIterator & left, const IntIterator & right)
{
	return (*left == *right);
}

bool operator!=(const IntIterator & left, const IntIterator & right)
{
	return (*left != *right);
}

struct IntRange
{
	int low;
	int high;

	constexpr IntRange(int low, int high) :
		low(low), high(high)
	{
	}

	constexpr IntIterator begin() const
	{
		return IntIterator(low);
	}

	constexpr IntIterator end() const
	{
		return IntIterator(high);
	}
};

And then you use:

for(int counter : IntRange(0, 10))
{
}

counter would go from 0 to 9 (the second parameter is exclusive).

It should compile down to roughly the same code after optimisation.

There’s no error checking in this version, so IntRange(10, 0) would give you a very long list of numbers.

As I say, there are much better ways to write this,
but they require knowledge of many more advanced features.

Ultimately it would be a lot of effort for very little gain.

Pretty much all languages that have a range function that does this have a similar complex mechanism buried under the surface.
(Lua, Python, Haskell, C#…)

(I can also think of a cheap way to do it using macros, but macros are evil, so let’s not go there.)

It’s complicated…

The behaviour differs between ‘built-in’ (‘fundamental’) types like int and class types with overloaded ++ operators.

The short version is that for built-in types, the compiled code should be the same if you aren’t using the result of the expression.
That means that in the case of the for loop the final optimised code should be the same regardless of which version you use.

If you do use the result of the expression...

If you take the result of the expression though, e.g. a = ++counter or b = counter++, then the behaviour will be different.

a = ++counter; behaves roughly like:

++counter;
a = counter;

And b = counter++; behaves roughly like:

b = counter;
++counter;

Or perhaps like:

temp = counter;
++counter;
b = temp;

However it’s not quite that simple.

In the second version (post-increment) the compiler has quite a bit of flexibility about how it produces the original value of counter, which can lead to unexpected behaviour.

The former version (pre-increment) doesn’t have as much flexibility because it’s simpler - counter is incremented and a is given the value of counter (after it’s been incremented).

Personally I avoid taking the result of an increment.
Instead I use a preincrement on a separate line, and handle any additional behaviour myself because that way I can guarantee what’s happening.
(The code also becomes more portable because it eliminates compiler-specific behaviour in the process.)

And for non-fundamental types...

As for non-fundamental types, e.g. class types with overloaded ++ operators, the behaviour depends entirely on how the class is implementing the operation.

But in general the ‘canonical’ way of implementing the operators is:

// Pre-incrment version
Type & operator++()
{
	// Do whatever needs to be done
	// to increment this object
	return *this;
}

// Post-incrment version
// (The 'int' is a dummy value used to
// differentiate the two.)
Type operator++(int)
{
	// Create a temporary copy
	Type temporary = *this;
	
	// Call the pre-increment version
	this->operator++();
	
	// Return the temporary copy
	return temporary;
}

(You can in fact see this pattern in the code I posted in my answer to the first question.)

Which means you can expect the post-increment version to be defined in terms of the pre-increment version,
and you can also expect there to be an extra copy used in the post-increment version.

If an object is cheap to copy then this isn’t too much of an issue,
but if an object is expensive to copy then using post-increment instead of pre-increment when the result is going to be discarded can mean an unnecessary performance impact.
Especially if it’s something that’s going to happen a lot (e.g. as the increment used in a for loop).

It’s for this reason that the ‘ranged for’ (the for(object : collection) version of for) internally uses pre-increment,
and why I say that if you’re planning to use C++ for desktop development then it’s a good idea to get used to using pre-increment.

To finish with, here’s a few relevant links backing my assertions:

The starting images aren’t there! Can you reupload them?

Thanks! You should see them, now!