hello, world

In this section we will figure out how this program works

This program simply displays "hello, world" on your Gamebuino. If everything went properly after the installation of the software and your first upload, you should come up with something like this:

Drawing text on your screen is the initial step towards your very first game.

Let's move on to more serious things! We will now take apart this code, and understand it piece by piece.

Game structure

Here is the basic anatomy of a Gamebuino game:

1: #include <Gamebuino-Meta.h>
2: 
3: void setup() {
4: 
5: }
6: 
7: void loop() {
8: 
9: }

The code is divided into three parts.

The first line of code is #include <Gamebuino-Meta.h>. This line allows us to use the Gamebuino library (i.e. display, buttons, sound, etc). Without it, there would be no game.

Generally speaking #include acts as a bridge between programs. It is useful if you want to use code from another program. #includes are nearly always put at the beginning of the file. Here, we will only need the Gamebuino-Meta.h library.

The two other essential parts of a Gamebuino Game are the two functions setup and loop. Functions are a series of instructions that can be executed whenever they are called. A function's instructions are delimited by two curly brackets { }. So above, the setup function starts at line 3 and ends line 5.

The setup function is called once, when the game starts. The other function, loop, is called after setup until you quit the game; in other words, the instructions inside of loop are executed in a loop. Forever. Well, until you quit ;)

The display

setup()

void setup() {
  gb.begin();
}

As you can see, our setup function only has one instruction: gb.begin(). Anything starting with "gb" is coming from the Gamebuino-Meta library (remember, we can use this library because of #include <Gamebuino-Meta.h>). The function gb.begin() must be called at the beginning of every game, because it initializes you Gamebuino. You may have also noticed that instructions end in a semicolon ;. This is very important, all instructions end in a semicolon.

loop()

void loop() {
  while(!gb.update());
  gb.display.clear();



  // This is where most of the program takes place
  gb.display.print("hello, world");
}

Remainder: instructions located inside the loop() function are executed in a loop forever.

while(!gb.update());

This instruction is also part of the structure of any Gamebuino program. This will do two things for you:

• It will handle everything that happens behind the scenes, such as updating the display, getting button information, or even playing sound.
• This will also throttle the frequency at which loop is called, as to have a constant game speed. By default, this line forces the game to run at 25 frames per second. This means that loop is called every 0.04 seconds. This is fast enough to be fluid to the human eye, but slow enough to let the CPU keep up with calculations.

For now, I am asking you to not think too much about what each character of this instruction means (we will come back to it in a later tutorial). But learn to recognize it, and remember what it does. Again, is a necessary part of every Gamebuino game :)

gb.display.clear();

Because we are calling loop 25 times every second, we need to clear the content of the screen before starting to draw the next frame... Otherwise, this would be quite a mess! Well, this is exactly what gb.display.clear(); does.

gb.display.print("hello, world");

This line is not part of every game you will write, that is because this instruction is responsible for writing the "hello, world" to the screen. If wee take a closer look, gb means that is a Gamebuino function, and gb.display means that we are more specifically using a function that has something to do with the screen. Indeed, the function we use, gb.display.print writes a string of characters, or string for short, to the screen. A string is a series of characters written between quotes " ".

Comments

You may have noticed that we skipped a line in the loop function during the explanation. This is because it is a comment.

// This is where most of the program takes place

Sometimes we need to explain what a certain piece of code does. To do so, we use comments. Comments start with // and are ignored by the compiler. They are very useful to add personal notes and clear explanations of things in your code. We use them throughout tutorials so you do not get lost in the sometimes lengthy code we give :P

Remark about C/C++

C/C++ is the programming language you are currently using. It is a case sensitive language, meaning that print, Print, and pRiNT are all different things. If you make the mistake of calling gb.display.Print("Hey"), you will get an error when compiling. We will look into how to handle errors in the next tutorial.

And don't forget, instructions end in a semicolon! (If you forget this, the compiler may not tell you and compile anyways, which creates very bizarre behavior :P )

It's your turn!

Now that you know how to display text on your Gamebuino, try out other text. How about a poem?

Share your results with #gamebuino #helloworld to celebrate your very first program! :)

• Tip #1 You can use the escape code \n to insert newlines in your text. (e.g. gb.display.print("hello\nWorld");)
• Tip #2 You can change the color of text with gb.display.setColor. Check out Graphics::setColor in the Reference to learn more about this function!
• Tip #3 To change text size, use Graphics::setFontSize.

Now try to recreate the screenshot below with the help of the tips given to you. When in doubt, do not hesitate to read the tutorial a second (or even third) time.

Solution Example

If you ran out of ideas, here is what we did on our side. Hope it helps :)

#include <Gamebuino-Meta.h>
void setup() {
  gb.begin();
}
void loop() {
  while(!gb.update());
  gb.display.clear();
  // Draw text to screen
  gb.display.print("Hello world\nis a tradition\nsince\n\n");
  // Change size of text
  gb.display.setFontSize(2);
  gb.display.print("1978");
  // Change color and revert to original size
  gb.display.setColor(BROWN);
  gb.display.setFontSize(1);
  gb.display.print("\n\n\n     - GAMEBUINO");
}

Next Workshop

By Aurélien Rodot, modified by Julien Giovinazzo

Any questions / comments / suggestions, be sure to drop a comment down below!