Our game of pong is going to have a few dependencies. First and foremost, we’ll use a library called gloss for drawing all of our graphics. We could use cabal to install gloss globally, so that all Haskell code on the computer could use it. However, with this approach we may eventually run into problems: if I have two packages, A (which depends on gloss-1.0) and B (which requires gloss-1.2), having a single global version of gloss won’t work, because we cannot have both A’s and B’s requirements satisfied simultaneously.

Instead of installing gloss globally, we’re going to create a sandbox. A sandbox is a directory in which cabal will (for the most part) ignore the global packages, and will instead install packages directly to that directory. First, let’s create a directory and switch to it with the following commands:

Now, let’s turn this directory into a sandbox. Make sure you cd to your new directory before running this, since your working directory is what will be turned into a sandbox.

Cabal should tell you that it’s created a directory, with an output like this:

If you look in that directory with ls -a, you should see the file cabal.sandbox.config and the directory .cabal-sandbox. You do not need to worry about or edit either of these, but they are important for cabal. All libraries and supporting files will be installed to .cabal-sandbox, as long as you run the cabal command from the pong directory.

Now that we have a sandbox to play in, let’s create our first package. Once again, make sure you are running this from within the pong directory. This command will turn the pong directory into a Haskell package directory (as well as a sandbox):

Cabal can create either an executable or a library package. Since we want a runnable game, we must create an executable. When you run cabal init, one of the questions will be:

Make sure to enter "2" in order to create an executable package.

When cabal asks Include documentation on what each field means (y/n)?, you will want to answer y (instead of n, which is the default), so that the generated package file will have useful comments.

Once cabal init is done, it will have created two files for you: Setup.hs and pong.cabal. Setup.hs allows packages to write advanced build scripts — you do not need to worry about it for the time being. pong.cabal is a configuration file which tells cabal everything it needs to know about your package. Take a look at pong.cabal. You will see a bunch of top-level fields, like these:

In addition to the to-level fields, you will also see a section describing the output executable:

We now have a sandbox and a package, which means we can start writing code! Begin by entering the following simple program into Main.hs. Recall that the main-is field in pong.cabal requires the file to be named Main.hs (unless you changed it from the default, in which case, edit the file specified by your main-is field).

You can now run your executable:

The output from the first time I run cabal run looks like this:

cabal keeps around old compiled data, so it does not have to re-compile all your files every time you make a change. If you’d like to clean out its cache, you can run

Instead of using cabal run to run your executable, you can also build and run it yourself.

cabal build will compile your program and create the dist directory. Your executable will be located in dist/bin, and will be named pong (or whatever follows the executable keyword in your pong.cabal).

Congratulations! You’ve created your first working cabal package.

Let’s start off with some very basic code. First, find the documentation for the latest version of Gloss on Hackage. This guide is written for Gloss 1.8, so some code may be out of date if you are using a newer version of Gloss. (If you don’t know where to find that, searching for "Haskell gloss hackage" is likely to get you where you need to be.) Open the documentation for Graphics.Gloss, the top-level module exported by the gloss library. We’ll start off with the demo code very similar to that which is included in the Gloss documentation:

If you enter this into Main.hs and then try to cabal run, you’ll get an error message like this:

We’ve forgotten to do two things. First of all, we have to install the gloss library into the sandbox:

Make sure you run all cabal commands (including the previous one) from the sandbox directory (pong). Next, once gloss is installed, we have to tell cabal that our package is allowed to use it. Find the line in pong.cabal that mentions build-depends and change it to the following:

If we forget to modify built-depends, we’ll get an error that looks like this:

Once we get out program compiling, we will see a window containing our simple drawing (a circle on a white background):

Before moving on, let’s break down the code that produced this circle.

As always, our Main module must have a main function. When using gloss, this main function will always be one line. That line will depend on how much control we want over our application. Right now, we want to do the bare minimum, and let gloss to the rest, and for that we use display:

The display function takes three arguments. To learn more about it, open the Hackage documentation for gloss and find the display function. (If you are not experienced with reading documentation on Hackage, you should do that right now. Practice reading documentation is useful!) The documentation tells us that the three arguments to display are a display mode, a background color, and the picture we’d like to draw. It also says that we can move the resulting viewport around and quit using the Escape key.

The display mode (type Display) tells gloss how we want to display our picture. We can use the FullScreen constructor to create a fullscreen application, or use the InWindow constructor to create a window.

The InWindow constructor accepts a string as a title, a size (width and height in pixels), and a position for the top-left corner of the window.

The color (type Color) we pass to display sets the background color.

Unlike Display, we don’t have access to the constructors for Color. Instead, we have access to functions such as makeColor, dim, bright and predefined colors such as black, white, azure, and chartreuse which we can use to create Color values.

Finally, our Picture tells gloss what to draw in the window:

We have access to many constructors and functions to create Picture values. For example, the Circle constructor creates a circle. Each constructor has aliases; for example, circle is a function alias for Circle. We also have more complex functions, such as circleSolid or lineLoop. circle 80 creates a picture with a circle of radius 80 centered in the window. (We could use the translate function to move it around if we didn’t want it to be centered.)

Let’s start off by drawing something which looks like a game of Pong. As before, start off with a general skeleton of the application, which looks almost identical to the previous one:

Once we define drawing, we can get something that looks like this:

To build this image, we’ll start off with a few basic drawing primitives:

Everything in the image above is drawn using only those two shapes. Let’s try placing one of each in an image. To combine two or more Picture values, we can use the pictures function and pass it a list of the pictures we want to overlay:

If you run this, you will see a completely blank black window. Although it may seem like there’s nothing on the screen, we actually are drawing the circle and rectangle; however, the default color for all shapes is black, so we draw a black shape on a black background, and see nothing. To fix this, we can use the color :: Color -> Picture -> Picture combinator function, which changes the color of a shape and returns the new colored shape.

This code will let us see the shapes we’ve drawn in color:

We still have a problem — all our shapes are awkwardly jumbled together in the middle. By default, all shapes in Gloss are drawn centered at the middle of the screen. In order to change this, you can use the translate :: Float -> Float -> Picture -> Picture function, which translates a picture by a given x and y distance and returns a new, translated picture. For example, let’s shift over those shapes a little bit in each direction:

As expected, the shapes are no longer in the center:

Armed with these tools, you can create the Pong game you saw earlier. The code that generated is a little bit longer than it really needs to be for such a simple drawing for the sake of clarity, but should be fairly straightforward to comprehend:

Before moving on, we’d like to refactor this a little bit. In particular, when we’re drawing frames of our game, we don’t want to pass around a half dozen Float values. We might easily get confused as to which is which, and functions with too many parameters are annoying to work with. Instead, we’ll refactor our system into three pieces:

This way, we can easily update the game state (the PongGame) without worrying about how its drawn, and we can write a render function without worrying about how the game state is updated. The game state can be summarized by the following fields:

We can put all of these into a single record:

For the time being, our initial state is just an arbitrary initialiation of this data structure:

The most complex bit of this refactoring is the render function. It is almost identical to the code we wrote before, but uses the PongGame it’s provided with instead of hard-coding all the values:

In this section, we’ll upgrade our application from a static display to an animation. This animation will do very little; it’ll move the ball, but it won’t implement collision logic or anything else.

In Gloss, animations are created using the animate function of type animate :: Display -> Color -> (Float -> Picture) -> IO (). This is almost identical to display; however, where display takes a Picture, animate takes a function of type Float -> Picture. In other words, to create an animation, you have to write a function which can generate a picture when given the number of seconds that have passed since the start of the animation.

In our case, we’ll use this to compute a new position for the ball, based on its initial location and velocity. First, let’s define a moveBall function which can create a new game state by updating the ball position from an old one:

To implement this, we use the ballLoc and ballVel fields of the PongGame:

Then, we can use this in our main instead of the picture we pass to display:

We can’t do much using animate, since we have no information about the previous state of the game, cannot update the state of the game, and cannot handle any interesting logic or user input. For a little bit more power, we can use the simulate function, which has the following type signature and documentation:

We can start off by just re-implementing our animation using simulate.

Next, let’s implement collisions, so that our game becomes playable. We have two types of collisions we need to implement: collisions with the side walls and collisions with the paddles. We’ll implement these by writing the following functions:

Bouncing off the walls is easier, because it doesn’t require accessing the game state to find out where the paddles are. We can start by detecting the collisions, given just the location of the ball and its radius:

Using wallCollision, we can easily implement wallBounce. The only tricky aspect is accessing the game state and updating the y velocity of the ball:

Finally, we have to change our update function to use wallBounce. Our new update will consist of two steps: first, move the ball according to the number of seconds that have passed; then, check for wall collisions, and update based on collisions.

In the function above, we use (.), the function composition operator. The function composition operator has type (.) :: (b -> c) -> (a -> b) -> (a -> c); given an input, it runs the right function on it, gets the output of the right function, then runs the left function on that output, and returns the output of the left function. This is just like the hollow dot symbol you may be acquainted from in mathematics.

In Haskell, function composition via the (.) operator (as above) is used very commonly to express a pipeline of operations. When combined with currying, it can be very clean and concise, though some beginners may find it tough to understand at first. In the example above, we curry moveBall with seconds, yielding a function of type moveBall seconds :: PongGame -> PongGame. If we compose that with wallBounce, we get another function PongGame -> PongGame, which is exactly what we need, sine update only handled the first two of three arguments it has (and left the last argument, a PongGame, to be handled by its output).

So far, we have an app that starts a pong game and then plays it forever. However, the players can’t move their paddles! In this section, we’ll fix this issue and learn how to deal with user input.

For games and other applications which require user interaction, Gloss provides the play function:

This function has a ton of arguments, but we have already dealt with most of them when we used simulate. We have one new function of type Event -> PongGame -> PongGame, which handles input events.

Find the documentation for Event in the Gloss documentation. You will find that it has three constructors: EventKey, EventMotion, and EventResize, represnting keyboard and mouse button presses, mouse movement, and window resizing (respectively). When our function receives an Event, it can pattern-match on the Event data structure and respond appropriately (by modifying the PongGame). The documentation will be very helpful when figuring out how to construct patterns to detect the events that you care about.

In our game, we’d like to detect keypresses. Specifically, when the user presses 'w' or 'a', the left paddle should move up and down, respectively. In the following example, we reset the ball to the center whenever the user presses 's':

In order to use the Event, EventKey, and Char symbols (and anything else related to events), you must import Graphics.Gloss.Interface.Pure.Game.

In the handleKeys example, we ignore many aspects of the Event, such as the KeyState (Up or Down), any Modifier keys that are held, and the position of the mouse at the time. For more complex interactions, we may care about these.

In order to use handleKeys, we simply pass it to play:

In addition, update must no longer take the ViewPort; since we didn’t use it anyways, you can remove the _ pattern we used to ignore it, and all will be good.