A Clojure Snake

The Snake game features a player-controlled snake that moves around a game grid hunting for an apple. When your snake eats an apple, it grows longer by a segment, and a new apple appears. If your snake reaches a certain length, you win. But if your snake crosses over its own body, you lose.

Before you start building your own snake, take a minute to try the completed version. Follow the instructions in the README file at the root of the sample code for the book to start a REPL, then enter the following:

Select the Snake window and use the arrow keys to control your snake.

Our design for the snake takes advantage of Clojure’s functional nature and its support for explicit mutable state by dividing the game into three layers:

• The functional model will use pure functions to model as much of the game as possible.

• The mutable model will handle the mutable state of the game. The mutable model will use one or more of the reference models discussed in this chapter. Mutable state is much harder to test, so we’ll keep this part small.

• The GUI will use Swing to draw the game and to accept input from the user.

These layers will make the Snake easy to build, test, and maintain.

As you work through this example, add your code to the file reader/snake.clj in the sample code. When you open the file, you’ll see that it already imports/uses the Swing classes and Clojure libraries that you’ll need:

Now you’re ready to build the functional model.

The Functional Model

First, create a set of constants to describe time, space, and motion:

width and height set the size of the game board, and point-size is used to convert a game point into screen pixels. turn-millis is the heartbeat of the game, controlling how many milliseconds pass before each update of the game board. win-length is how many segments your snake needs before you win the game. (Five is a small number suitable for testing.) The dirs maps symbolic constants for the four directions to their vector equivalents. Since Swing already defines the VK_ constants for different directions, we’ll reuse them here rather than define our own.

Next, create some basic math functions for the game:

The add-points function adds points together. You can use add-points to calculate the new position of a moving game object. For example, you can move an object at [10, 10] left by one:

point-to-screen-rect converts a point in game space to a rectangle on the screen:

Next, let’s write a function to create a new apple:

Apples occupy a single point, the :location, which is guaranteed to be on the game board. Snakes are a bit more complicated:

Because a snake can occupy multiple points on the board, it has a :body, which is a list of points. Also, snakes are always in motion in some direction expressed by :dir.

Next, create a function to move a snake. This should be a pure function, returning a new snake. Also, it should take a grow option, allowing the snake to grow after eating an apple.

move uses a fairly complex binding expression. The {:keys [body dir]} part makes the snake’s body and dir available as their own bindings, and the :as snake part binds snake to the entire snake. The function proceeds as follows:

1. add-points creates a new point, which is the head of the original snake offset by the snake’s direction of motion.

2. cons adds the new point to the front of the snake. If the snake is growing, the entire original snake is kept. Otherwise, it keeps all the original snake except the last segment (butlast).

3. assoc returns a new snake, which is a copy of the old snake but with an updated :body.

Test move by moving and growing a snake:

Write a win? function to test whether a snake has won the game:

Test win? against different body sizes. Note that win? binds only the :body, so you don’t need a “real” snake, just anything with a body:

A snake loses if its head ever comes into contact with the rest of its body. Write a head-overlaps-body? function to test for this, and use it to define lose?:

Test lose? against overlapping and nonoverlapping snake bodies:

A snake eats an apple if its head occupies the apple’s location. Define an eats? function to test this:

Notice how clean the body of the eats? function is. All the work is done in the bindings: {[snake-head] :body} binds snake-head to the first element of the snake’s :body, and {apple :location} binds apple to the apple’s :location. Test eats? from the REPL:

Finally, you need some way to turn the snake, updating its :dir:

turn returns a new snake, with an updated direction:

All of the code you’ve written so far is part of the functional model of the Snake game. It’s easy to understand in part because it has no local variables and no mutable state. As you’ll see in the next section, the amount of mutable state in the game is quite small. (It’s even possible to implement the Snake with no mutable state, but that’s not the purpose of this demo.)

Building a Mutable Model with STM

The mutable state of the Snake game can change in only three ways:

• A game can be reset to its initial state.

• Every turn, the snake updates its position. If it eats an apple, a new apple is placed.

• A snake can turn.

We’ll implement each of these changes as functions that modify Clojure refs inside a transaction. That way, changes to the position of the snake and the apple will be synchronous and coordinated.

reset-game is trivial:

You can test reset-game by passing in some refs and then checking that they dereference to a snake and an apple:

update-direction is even more simpler than that; it’s just a trivial wrapper around the functional turn:

Try turning your test-snake to move in the “up” direction:

The most complicated mutating function is update-positions. If the snake eats the apple, a new apple is created, and the snake grows. Otherwise, the snake simply moves:

To test update-positions, reset the game:

Then, move the apple into harm’s way, under the snake:

Now, after you update-positions, you should have a bigger, two-segment snake:

And that is all the mutable state of the Snake world: three functions, about a dozen lines of code.

The Snake GUI

The Snake GUI consists of functions that paint screen objects, respond to user input, and set up the various Swing components. Since snakes and apples are drawn from simple points, the painting functions are simple. The fill-point function fills in a single point:

The paint multimethod knows how to paint snakes and apples:

paint takes two required arguments: g is a java.awt.Graphics instance, and object is the object to be painted. The defmulti includes an optional rest argument so that future implementations of paint have the option of taking more arguments. (See ​Defining Multimethods​ for an in-depth description of defmulti.) On line 3, the :apple method of paint binds the location and color of the apple and uses them to paint a single point on the screen. On line 6, the :snake method binds the snake’s body and color and then uses doseq to paint each point in the body.

The meat of the UI is the game-panel function, which creates a Swing JPanel with handlers for painting the game, updating on each timer tick, and responding to user input:

game-panel is long but simple. It uses proxy to create a panel with a set of Swing callback methods.

• Swing calls paintComponent (line 3) to draw the panel. paintComponent calls proxy-super to invoke the normal JPanel behavior, and then it paints the snake and the apple.

• Swing will call actionPerformed (line 7) on every timer tick. actionPerformed updates the positions of the snake and the apple. If the game is over, the program displays a dialog and resets the game. Finally, it triggers a repaint with (.repaint this).

• Swing calls keyPressed (line 16) in response to keyboard input. keyPressed calls update-direction to change the snake’s direction. (If the keyboard input is not an arrow key, the dirs function returns nil and update-direction does nothing.)

• The game panel ignores keyReleased and keyTyped.

The game function creates a new game:

On line 2, game creates all the necessary game objects: the mutable model objects snake and apple and the UI components frame, panel, and timer. Lines 7 and 10 perform boilerplate initialization of the panel and frame. Line 14 starts the game by kicking off the timer.

Line 15 returns a vector with the snake, apple, and time. This is for convenience when testing at the REPL; you can use these objects to move the snake and apple or to start and stop the game.

To start the game, use the snake library at the REPL and run game. If you entered the code yourself, you can use the library name you picked (examples.reader in the instructions); otherwise, you can use the completed sample at examples.snake:

The game window may appear behind your REPL window. If this happens, use your local operating system fu to locate the game window.

There are many possible improvements to the Snake game. If the snake reaches the edge of the screen, perhaps it should turn to avoid disappearing from view. Or maybe you just lose the game. Sorry! Make the Snake game your own by improving it to suit your personal style.

Snakes Without Refs

We chose to implement the Snake game’s mutable model using refs so we could coordinate the updates to the snake and the apple. Other approaches are also valid. For example, you could combine the snake and apple state into a single game object. With only one object, coordination is no longer required, and you can use an atom instead.

The file examples/atom-snake.clj demonstrates this approach. Functions like update-positions become part of the functional model and return a new game object with updated state:

Notice how destructuring makes it easy to get at the internals of the game: both snake and apple are bound by the argument list.

The actual mutable updates are now all atom swap!s. We found these to be simple enough to leave them in the UI function game-panel, as this excerpt shows:

There are other possibilities as well. Chris Houser’s fork of the book’s sample code^[33] demonstrates using an agent that Thread/sleeps instead of a Swing timer, as well as using a new agent per game turn to update the game’s state.