Catching Raindrops
In this tutorial, you will build a game with your BBC micro:bit, where you move a cardboard
coffee cup to catch virtual rain drops.
The BBC micro:bit is a great device for
developing interactive games with, because it
can sense movement and orientation using its
built in accelerometer sensor.
By attaching the BBC micro:bit to a physical
object, you give that object a personality. This
personality is communicated by the gestures and
screen animations that you design, but also by the
story that you tell when you are showing the
game to your friends.
You can pick almost any inanimate object you like,
and breathe life into it with your micro:bit!
In this tutorial, you will attach your micro:bit to
a spare cardboard coffee cup, and play a game
called “Catching Raindrops”.
To play this game, you tilt your coffee cup from
side to side to move an image of the cup on the
screen. Random rain drops fall down the screen,
and the objective of the game is to catch as
many drops as you can, to get the highest score
possible.
What makes this game fun, is the combination
of movements and screen animations that you
design for it.
Figure 1: The Raindrops game, assembled
To develop this game on the micro:bit, first you will learn some basics about how to sense the real
world surrounding the micro:bit, and how to display images on the screen. You will do this by
performing some simple experiments.
What you will learn
In this tutorial, you will learn how to do the following:
- write simple code using the Block editor
- modify and write new code in the TouchDevelop editor
- test your programs both on the emulator, and on the real micro:bit
- display images on the screen
- detect button presses
- respond to movement by using the accelerometer
- attach an external buzzer and make game sounds
In this tutorial, you are encouraged to experiment as much as possible, learning by exploring –
please click/press on different things to find out what they do, read through the program listing to
understand how it works, and use the online help at the top right of the screen (you can open the
help in another browser window)
Steps
1. Experiment with the buttons and screen
2. Experiment with the accelerometer
3. Play the game
4. Understanding how the game works
5. Reconfigure the game
6. Add a beeper to your game
7. Make the game your own
1. Experiment with the buttons and screen
In this tutorial step, you will write a small program
that makes a dot move around on the screen as you
press the A and B buttons.
This will show you how to plot pixels on the
screen, and how to check when buttons are
pressed, which you will need to understand in
order to develop and understand the raindrops
game.
Figure 2: Pressing a button to move a dot
You will also learn how to test code in the
emulator, convert Block code into TouchDevelop
code, and run your code on your real micro:bit.
Create a new script by clicking on CREATE
CODE, then under the Microsoft Block Editor,
click NEW PROJECT and choose a name.
Using the palette on the left, drag blocks onto
the programming space to make your script look
like the script on the right.
Now press the RUN button at the top of the
page. You should see the micro:bit emulator
appear, and pressing on the A button will move
the screen dot to the right, and pressing the B
button will move the screen dot down.
When the dot reaches the edge of the screen, the
code makes sure that it wraps back to the start of
the screen again.
Figure 3: Sensing button presses
Once you have tested this on the emulator, the next step is to compile and run it on your
real micro:bit.
Press the COMPILE button and wait for the program to build and download onto your computer.
Then in your downloads folder, find the new .hex file that has appeared, plug in your micro:bit into
the USB port of your computer, and drag the new .hex file onto the drive that has appeared called
“MICROBIT”.
When the programming has finished, the drive will automatically eject. Then press the system
button on the back of the micro:bit to run the program – test it still works by pressing the A and B
buttons, and the dot should move on the screen.
The Block language is quite simple to start learning to code, but after a while it gets quite crowded
with everything on one screen. Your last step in testing this program is to press the CONVERT
button. This will convert your Block program into a TouchDevelop program (the original Block
program is still there).
TouchDevelop is a textual programming language, but is designed so that it works very intuitively
on a touch surface like a tablet or a phone. You should recognise the program that you originally
wrote in the new TouchDevelop editor. RUN it again in the emulator to make it works, then try the
COMPILE button to download a .hex file and drag that to the MICROBIT drive, and make sure
the program still works on your real micro:bit before moving to the next step of this tutorial.
2. Experiment with the accelerometer
In this tutorial step, you will write a small program
that makes a dot move around on the screen as
you tilt the micro:bit from side to side.
This code will be used later in the game to detect
that your coffee cup has moved, and will be the
main gesture used to catch rain drops with your
micro:bit.
Figure 4: Tilting the micro:bit
Create a new script by clicking on CREATE
CODE, then under the Microsoft Block Editor,
click NEW PROJECT and choose a name.
Using the palette on the left, drag blocks onto
the programming space to make your script look
like the program on the right.
Figure 5: Sensing tilt
RUN this program on the emulator, and make sure that the dot moves as you lean the emulated
micro:bit from side to side. Then COMPILE and load the newly downloaded .hex file onto your
real micro:bit, and test that when you lean the micro:bit, the dot moves.
Finally, use CONVERT to convert your program to a TouchDevelop program, test it in
the emulator, and test it on the real micro:bit.
As a challenge, can you work out how to modify the code so that changes in the Y acceleration will
also move the dot up and down the screen?
3. Play the game
In the previous tutorial steps, you learnt how to use
the buttons, how to use the screen, and how to use
the accelerometer.
In this tutorial step, you are going to make your
coffee cup game and play it for real.
Figure 6: An assembled cup and micro:bit
The game is just a slightly more detailed version of
the code you have already developed, but to save
you some work, we have provided a complete
runnable .hex file, and also a nearly finished
version of the game. First though, build your cup!
To build your cup game, get a (hopefully empty
and dry!) cardboard coffee cup. Hold the
micro:bit against the front of the cup, and with
a pen, poke the pen through holes 1 and 3V and
mark places on the coffee cup. Now with the
pen, push two holes through the cup at these
marked positions.
Using a cable-tie included in your kit, thread the
cable tie point through the front of the 3V hole,
and through the right hand hole in the cup. Link
up a second cable tie to the back of this first
one, and wrap it round the battery pack inside Figure 7: Marking the holes
the cup.
Now thread the pointed end of the second cable tie through the left hand hole of the cup, through
from the back of the '1' hole, and loop it through the eye of the first cable tie. Pull both cable
ties tight to hold the micro:bit and battery pack secure.
Finally connect the battery pack to your micro:bit.
Using the sample CatchingRaindrops.hex file we have provided, plug in the USB and drag this onto
the MICROBIT drive. When it has loaded, unplug the USB and press the system button on the
back. The game should now show the start screen, which looks like a little smiley face with
blinking eyes.
Explanation of the game
The purpose of this game is to catch as many raindrops as possible with your coffee cup and get the
highest score possible. Hold the A button to start the game, and when the screen goes blank, let go
of the button and the game will start.
You move the virtual on screen cup from side by side by tilting the real coffee cup, just like with
your accelerometer test program. Raindrops will fall down at random positions on the screen, and
you must tilt your coffee cup to catch the raindrop directly in the centre of the little virtual cup on
the screen.
If you catch a raindrop, the cup will temporarily 'bulge' on the screen to show that you have caught
it. If you miss a raindrop, the cup will jump up in the air in disgust at you missing the drop! If you
miss 5 drops, the game is over, so try not to miss the drops!
If you are able to catch 5 drops, then the cup will look like a filled in block, and this represents a
“full” cup (the cup can only hold 5 raindrops at a time, it is a very small cup!) Now you will realise
why you used a cable tie to fix everything together – quickly turn the cup upside down, and the
screen will animate the raindrops falling out of the cup so you can empty it – quick though, turn the
cup back up the right way and catch the next drop in time!
If you fail to empty the cup in time for the next drop, the cup will show an animation of it
overflowing, and the game will be over.
You will know when the game is over, because the cup will float up to heaven like a little angel, and
finally it will blink its two eyes at you, and then show you your score.
Play the game for a while to learn how the movements work and what each of the animations mean.
Then demonstrate the game to a colleague – as you are demonstrating it, tell a little story about
what the animations and gestures mean. It is the story that you tell that really allows the micro:bit to
give a true personality to your coffee cup! Then get your friends to play the game and see if they
can beat your score.
4. Understanding how the game works
Now that you have played the game for a while, it is time to learn how the code that you loaded into
the micro:bit actually works, and this will then allow you to start to modify it and alter its
personality and make it your own personal version of the game. In doing this, you will learn a lot
about how the TouchDevelop programming language works, and you should begin to see the
amazing opportunity that the micro:bit offers to help children to learn to code and to create their
own amazing inventions with it!
Open the Touch Develop program “Catching Raindrops – near complete”. You can find this as a
published script by searching for the script id nmnbiw in the search box.
You should see the main() function – this is where the program always starts when the micro:bit is
powered up. Because the micro:bit is an embedded device, it will always need a while true (or a
forever) loop, otherwise you will have to turn it off and on again to start the game.
The program is split into 3 levels of detail – main() is the first level of detail, and sets up the
parameters of the game, shows the splash screen animation, waits for a button press, and either
plays the game, or enters a test mode where you can check the sensitivity of the accelerometer.
When the game is finished, the score is displayed, and it then loops round again to do the same.
This might be the first part of the program you would like to tinker with, such as changing some of
the parameters, or changing the splash screen animation.
The second level of detail is in a function called play game() - you can get to this by clicking on
SCRIPT and choosing “play game” from the list.
The “play game” function is where it all happens – it uses a game loop that loops around all the
while the game is being played. There are some variables at the top that are used while the game is
running, followed by a while true loop with a set of if/else if statements. Each of these program
statements makes a part of the game actually work.
To understand the game loop properly, here is a diagram that shows the different states that the
game can be in, and what makes the game change between those states – look back at the
description of what the game does (earlier) and follow round this diagram with your finger and
make sure you understand how the game hangs together as a program.
Figure 8: The 'state diagram' of Catching Raindrops
For each of the states, read the code within the if statement for that state, and familiarise yourself
with what the program does in that state, and how it might change to another state. Instead of us
describing each of these states in detail here, read through them one by one yourself, and look in the
TouchDevelop help pages (link at the top right of the screen) to understand what each of the lines of
code does for you. You will find you will learn more about the programming language by exploring
someone else's program in this way.
The final level of detail of the program is in some lower level code functions, called “start game”,
“get cup position” and “test movement” - you should recognise the code in “test movement”
because it is mostly the same as the code you wrote for your accelerometer experiment. “get cup
position” works out using the accelerometer (or buttons) what position the cup needs to be
displayed at. “start game” just sets the various game variables to sensible defaults, and makes sure
that the logo up/down detection code is running.
5. Reconfigure the game
The best way to learn about a new programming language, is to read and then change other people's
programs. The BBC micro:bit editors and website are a great way to do this, because you can
publish your code for others to read, and then you can search for code written by others.
In this tutorial step, you will experiment by changing some of the default parameters of the game,
and this will give you some feel for aspects of games that make them easy or hard, interesting or
really exciting to play!
In main(), try different values of cup capacity, speed, max misses and sensitivity. See if this makes
your game easier or harder to play. Look through the program listing of the “play game” function to
see where these variables are used and to predict how changes to their initial values will affect the
gameplay.
6. Add a beeper to your game
In this step of the tutorial, you will wire up a small
electronic device to the pins on the edge
connector of the micro:bit.
This demonstrates that the micro:bit is not only
limited to the devices built on board, but can be
extended beyond this to control other devices –
only limited by your imagination and
determination to succeed.
Figure 9: An added beeper
Take the beeper from your kit, and attach a crocodile clip wire from the RED wire and clip it onto
pad 0 on the micro:bit. Take another crocodile clip wire and join it from the BLACK wire onto the
GND pin on the micro:bit. Try to put all the excess wire inside the cup, and perhaps use another
cable tie to keep all the wires tight and tidy together so they don't fall out when you turn the cup
upside down. You can probably tie-clip it all to the battery pack by looping the second tie clip
through the first one.
If you use the CatchingRaindrops.hex file that we provided in the kit, you should be able to hear the
sounds playing already when you play the game – try it now and see if you can work out where all
the sounds are.
Changes to make to your TouchDevelop program
To make a beep, use pins→digital write pin (“P0”, 0) to turn the beeper off, and change the '0' to a
'1' to turn it on. You can then use basic→pause(100) to insert a delay of 100 milliseconds.
- beep for half a second when game starts
- beep for 100ms on a catch
- beep for 400ms on a miss
- beep for 1 sec for game over
7. Make the game your own!
In the final step of this tutorial, you should spend some time altering the game to make it your own.
Below are some suggestions of things you could try, but the best approach is to play the game and
work out what features make the game fun and exciting to play, and then try to add those new
features. Remember to use the TouchDevelop help system which is linked in the top right of the
screen. Also keep in mind that TouchDevelop “comes alive” when you use it on a tablet or a touch
surface computer of some kind.
- change the splash screen animation
- add a high score feature
- speed the game up on every level achieved
- change all the animations to personalise the game
- use a random sensitivity after each catch
- decrease the capacity of the cup after each level achieved
- display 1 of 4 messages when the game is over based on score
0..4
5..9
10..15
16+
beginner
average
good
master
- display one of 4 icons based on the above score, perhaps use variations on a smiley face.
Credits
Software Design: David Whale, Illustration: Pamela Dowie. Photos: Sukkin Pang.