Key Events

Students learn about events, and add key-event handling to their games.

We’ve already seen one kind of interactivity in our programs: getting the next state from the current state on a tick-event. This is perfect for animations that happen on their own, without any user intervention. In a game, that might be clouds moving across the sky or a ball bouncing on its own. An important kind of behavior in interactive programs is to respond user input, such as keypresses. A keypress, like the tick of a clock, is a kind of event, and we’ll re-use the idea of an event handler like on-tick and a function like next-state-tick. For key-events, the event handler is called on-key, and our function next-state-key will compute the next state from the current one after a key event. We’re going to use this idea to build up a reactor with a character moving in two dimensions, where the movement is triggered by keypresses.

It contains a data block for representing a character’s position (CharState) that has an x and y position.

This is a reminder that it’s often useful, when working on programs that use data to represent positions in an image, to make sure we understand what values in the data structure correspond to which drawing behavior.

There is also a contract for a function next-state-key, which looks like:

It is different from the contract for next-state-tick (which handles tick events) in an important way. When a key event happens, the next state may differ depending on which key was pressed. That means the next-state-key function needs both the current state and which key was pressed as parts of its domain. That’s why next-state-key has an additional String input, which represents the key pressed by the user.

This gives us a good input and output test for the examples block when working on next-state-key. What call to next-state-key should connect these two example instances?

It’s an important point that next-state-key takes in an extra piece of information: the pressed key. This makes it much richer in terms of its purpose statement, which should describe what different keys ought to do to the state of the reactor. Students will create something like this completed file by adding a next-state-key function

As with tick-events, we can manually pass keypress strings into this function, see what the next state would be, and even draw that state to see what it looks like. That’s great, but we still want to hook this function up to a reactor, so that it actually handles keypresses from a user playing the game. To do this, we need to create a reactor use on-key to specify that our next-state-key function should be called when the user presses a key (we don’t need to specify an on-tick handler, since for now the only movement in our program comes from keypresses). Our reactor with a to-draw and on-key handler looks like this:

With this working, you can see the behind-the-scenes work that was going on in Sam the Butterfly from Bootstrap:Algebra. To get to the same point as in Bootstrap:Algebra, we’d next implement is-onscreen to check if Sam has left the board, and use it in next-state-tick.

Act out a reactor with key-events. You will need four students: one who acts as the next-state-key function, one who acts as the keyboard (you could also have the class act as a keyboard by having students shout out keys), one who acts as the reactor, and one who acts as the draw-state function. Give each student a few sheets of paper and something to write with.

When a key is "pressed" by the keyboard, the reactor write the current state and the key that was pressed, then shows their paper to next-state-key. next-state-key produces a new state based on the current state and the key, writes it down, and then hands the new state back to the reactor. The reactor discards their old state, replacing it with the new one, and shows the new one to draw-state. draw-state produces an image for the reactor to post, and draws it on paper. They hand the image to the reactor, who holds it up as the new frame in the animation. We recommend not having a next-state-tick function for this activity, to keep the focus on key events. You can add a on-tick handler in a separate stage when talking through games which have both time- and key-based events.

Optional: implement boundaries to keep character onscreen, using the same ideas as safe-left and safe-right from before. You can also write safe-top and safe-bottom, and use all of them to keep the character fully on the screen.

Optional: use num-to-string and text to display the position at the top of the window.

This activity introduces students to Reactor programs that use key-events and tick events. Students create a "digital pet", which responds to key commands but also changes state on its own.

Now, you’ve seen how to use functions to compute the next state in a game or animation for both tick and key events. We can combine these to make an interactive “digital-pet” from scratch!

Notice that not much is happening! To make this game more interesting, we want to add three behaviors to it:

In this lesson, you will extend the animation three times, once for each of these behaviors, by adding or changing the functions that make up an animation. To do this, you will use the Animation Extension Worksheet three times. Note that none of these should require adding any new fields to the data definition, just adding and editing functions like next-state-tick, next-state-key, and draw-state. We will walk you through the first use of the animation extension worksheet, then let you try the other two on your own.

For this extension, we want to decrease the hunger by 2 and the sleep by 1 each time the animation ticks to a new frame.

In this filled-in worksheet, the description from the problem is written down into the "goal" part of the worksheet. This is like the “purpose statement” for the feature.

Next, we consider the tables that summarize what now changes in the animation.

The worksheet identifies that both hunger and sleep are changing in new ways. Since they aren’t new fields, this feature is completely dependent on existing data, and we don’t need to add any new fields. We therefore leave the second table empty (since we aren’t adding new fields).

Next, we identify the components that we need to write or update. We don’t need to change the data definition at all, because no new fields were added. We may need to update draw-state function, since the size of the bars changes. We definitely need to write the next-state-tick function, which doesn’t yet exist. We do not need to address anything about keypresses with this feature, so next-state-key is untouched. Since next-state-tick has been added for this feature, we need to add a on-tick handler to the reactor.

Now that we’ve planned what work needs to be done (on paper), we can start thinking about the code. As always, we write examples before we write functions, so we are clear on what we are trying to do.

In our samples, we estimate a bit from looking at the pictures, but note that we pick numbers that would work with the desired behavior — MIDPET represents the state after 25 ticks, because hunger is 50 less (decreased by 2 each tick), and sleep is 25 less (decreased by 1 on each tick). The LOSEPET sample instance corresponds to the state when both hunger and sleep values are 0.

Now we need to use this information to edit the current code, checking off the boxes we identified as we go.

The draw-state function already does this, so we can check the draw-state changes off as being done (without doing additional work).

Once we’ve finished using the design recipe to implement next-state-tick, we can check off its box. Finally, we need to add the handler to the reactor so the reactor calls the function we just wrote on tick events.

You should have ended up with something like this:

Make sure you get a working animation with bars that decrease before moving on, like this:

🖼Show image

Next, we’ll add key events to the game so the player can increase them so they don’t reach zero!

As you fill in the worksheet, think about useful sketches that capture this new feature, whether you need new fields, and which functions are effected.

You now know everything you need to build interactive games that react to the keyboard, draw an image, and change over time! These are the fundamentals of building up an interactive program, and there are a lot of games, simulations, or activities you can build already. For example, you could build Pong, or the extended Ninja Cat, a more involved Pet Simulator, a game with levels, and much, much more.

Some of these ideas are more straightforward than others with what you know. The rest of the workbook and units are designed to show you different features that you can add to interactive programs. You can work through them all if you like, or come up with an idea for your own program, and try the ones that will help you build your very own program!