Unit 3.1: Comments and Functions

In this unit, we’ll make a two-player Reaction game!

Players, on your buzzers…

This will introduce and demonstrate some more advanced MakeCode concepts; Comments and Functions.

Tutorial: Reaction Game

Who can react the fastest when the spinning stops?

Here are the rules:

  1. There are two players; Red and Blue.
  2. Each player has a button.
  3. Shaking starts the game spinning for a random amount of time, then it stops.
  4. If a player presses their button while the game is still “spinning”, they lose.
  5. If a player presses their button first when the spinning stops, they win!

The game is a simple state machine with three states: SPINNING, READY, and GAMEOVER.
Here’s what our state diagram looks like:

wpg_div_wp_graphviz_1

Note: Red Wins and Blue Wins are not treated as states by our program, because the program immediately jumps back to the GAMEOVER state.

Let’s write this program.
You’ve had some practice now writing programs.
These tutorials and instructions will become a bit less detailed.
If you get lost, look at the pictures and the block colours – remember the drawers are colour-coded.

Step 1: Variables, States and on start

As in our other state machines, we need some states, and a variable to keep track of them.

  1. Make four variables: SPINNINGREADYGAMEOVER, and current_state.
  2. Drag an on start block into your program.
  3. Use set blocks to set up those variables:
    SPINNING to 0, READY to 1GAMEOVER to 2,
    and current_state to GAMEOVER(Use a variable expression block)

You should have something like this:

NOTE: Make sure the states are all set to different values, or the state machine won’t work!

Step 2: Spin!

When the program first starts, it’s quiet and in the GAMEOVER mode.
As per the state diagram, a shake action should start the game running.

  1. Drag an on shake block into the program.
  2. Inside, set the current_state variable to SPINNING. (Use a variable expression block again)
  3. We’ll need a musical sound to indicate that the game is running, so use a ring tone block.
    (do not use play tone for, the sound needs to run until manually stopped)
  4. We’ll need an animation to indicate that the game is running, too.
    1. Use a show animation for block.
    2. Choose the sparkle animation.
    3. Use a pick random block as the period of time, between 1000 and 2000 milliseconds.
      (So it will wait for 1 to 2 seconds)
  5. Once the animation is finished running, we’ll go to the READY state.
    1. Use a set block to set the current_state variable to READY(Use a variable expression block)
    2. Stop making noise with stop all sounds.
    3. Switch the lights off with clear.

You should be able to test your program in the simulator – just press the SHAKE button.

Did the board do what you expected?

Step 3: Comments

THEORY: COMMENTS
As programs get larger, it can be difficult to remember WHY you put a block in the program, and what it’s supposed to be doing.
(Especially when you try to read someone else’s program, or come back to your own program weeks later)

Any block can have a helpful comment attached;

  • Comments appear as a little question mark in the block.
  • Clicking on the question mark displays the comment.

Caution: If you attach a comment to every block in the program, you’ll probably be even more confused!
Don’t overdo it.
Comments that talk about why are more helpful than just comments that talk about what.

 

  1. Right-click on the show animation block, and select Add Comment.
  2. Type a message describing why the block is there into the yellow square.

Step 4: Red Player

The Red player needs to press button A at the right time.
Our program needs to listen for that button press, and decide what happens next.

  1. Drag an on button A  block into the program, and have it run on down instead of click.
    (on down runs faster – as soon as the button is pressed, on click waits for the button to be released)
  2. Why are we checking the button press?
    Add a comment to the on button A block. (Right-click -> Add Comment -> Type “RED Player”)
  3. The program acts depending on the value of current_state, so;
    1. Drag an if block into the program,
    2. Test if current_state equals SPINNING(With an equals block from the Logic drawer)
    3. Press the + icon until you see an else if section. (You can ignore the else section)
    4. In the else if section, test if current_state equals READY.
  4. Why are we checking the value of current_state?
    Add a comment to the if else-if block. (Right-click -> Add Comment -> Type the message as below)

Step 5: Blue Player

The Blue player needs to press button B at the right time.

  1. Right-click on the on button A block and select “Duplicate”.
    Drag the copied blocks over to a new area.
  2. Change the button to button B.
  3. Fix the “RED Player” comment in the new on button B block;
    1. Click on the ?
    2. Click inside the yellow rectangle.
    3. Change the text to “BLUE Player”.

Now we have the basic player code in place.
How does someone win?

Step 5: Creating Functions – Winner!

If the Red player presses their button too soon, Blue wins.
If the Blue player presses their button at the right time, Blue wins.
How do we do the same thing, without having to write the “wins!” code twice?

THEORY: FUNCTIONS
Sometimes in a program, we need to do the same thing in multiple places.
It’s a good idea not to repeat ourselves.
It’s a good idea not to repeat ourselves.
Seriously though, because repetition leads to all sorts of problems.

Functions are blocks of program that we can reuse:

  • They are defined in one place.
  • They are “called” from anywhere, wherever needed.
  • When a function is called, the blocks inside the function are run.
  • Define once, use multiple times, no repeating ourselves.

And, like variables, we can create functions and give them helpful names.

  1. Open the Advanced drawer, and click on Functions.
  2. Click on Make a Function… and call the function redWins.

    You’ll notice that an empty container block appears in the program:

What do we need to do, now that the Red player has won?

  1. The sparkle animation might still be playing, and the tone might still be sounding.
    The first block in the function should be a stop all animations block. (Light drawer)
    Next in the function, place a stop all sounds block. (Music drawer)
  2. Now let’s go to the GAMEOVER state.
    Use a set block to set the current_state variable to GAMEOVER(Use a variable expression block)
  3. Red won! Let’s light up and celebrate.
    Drag in a show ring block, switch off the LEDs on the right, and set the LEDs on the left to red.
    Drag in a play sound - until done block, and set it to a nice victory noise. (like ‘ba ding’)

So that’s the Red player sorted, what about the Blue player?

  1. Right-click on the function redWins block and select Duplicate.
  2. Click on the new function’s name and change it to blueWins.
  3. Change the show ring to switch off the LEDs on the left, and make the LEDs on the right blue.
  4. Choose a different Victory! sound for the blue player.

Now, when do we call the functions?

Step 6: Calling Functions

Now we’ll link those button presses to the functions;

  1. Open the Functions drawer again. (you may have to click ‘Advanced’ to see it)
  2. Drag a call function redWins block and a call function blueWins block into the Red player’s on button A block:
    (call function blueWins if they press too early, call function redWins if they press at the right time)

  3. Do the same for the Blue player’s on button B block, but in reverse order.
    (call function redWins if they press too early, call function blueWins if they press at the right time)

Phew! Looks pretty good.

Step 7: Download and Testing

Download the code to your Circuit Playground Express, and try playing against another student.

Did it work like you expect?
If not, check it carefully against this example of the full program:

Conclusion:

Functions save us a lot of time, and help us to write elegant code.
Comments may seem like an extra hassle right now, but can be vital to figuring out your program later!

Under the Advanced toggle are several other drawers – what do you think they do?

 


Back to Programming