Introduction

Motivation

Welcome! This is the first part of what I hope will be a complete series on how to make a roguelike game in Haskell. The original roguelike tutorial has been endlessly used (I remember going through it all with Python in…god knows when. Probably early 2010) and loved and adapted to many other languages and frameworks for Rust with rltk, Javascript with rot.js, C# with RogueSharp; for Godot, for Unity, and a ton more I’m missing. “r/roguelikedev does the roguelike tutorial” has become a yearly event. There’s a great roguelike fan Discord server with an active dev chat. Making roguelikes is great fun, and it’s easier than people think.

There’s a kind of mental jump going between “I can solve all these problems in a given language” and “I can write an application (possibly a game)”. Maybe the reason these tutorial series are so popular, despite being very clear that nothing they are introducing to the reader is new to them, is because they provide a welcoming helping hand. They take you from being able to write a bunch of classes or functions to an actual game with a randomly generated dungeon with monsters and combat and items and all that cool stuff.

This is a bit of a challenge to bring to Haskell. There’s a reputation about how purity and functional programming isn’t suited to gamedev. This is completely mostly false, of course - it’s far more doable than you think! A lot of the flak Haskell gets is that it’s complicated (not unless you make it so), you need to know all about monads and algebraic effects and functional lenses (you don’t), or that it’s not suited to most sorts of application (again, not true). I want to dispel these fictions.

This tutorial won’t be an introduction to Haskell for completely new people to the language, but the intended level is at the advanced beginner. Perhaps having taken most of a functional programming course, or having read Learn You A Haskell or Real World Haskell. If you are coming from another functional language (F#, Scala, OCaml) then most of the concepts should be familiar to you and it is mostly syntax that isn’t.

If the following list doesn’t make you run away screaming, then fingers are crossed that this should be understandable:

  • The Haskell language
    • Datatypes, records, ADTs, polymorphism, typeclasses, constraints, functions;
    • Polymorphism (type parameters, polymorphic functions);
    • Data structures - lists/vectors/arrays, maps, sets;
    • map/fmap/mapM, filter, fold;
  • Monads
    • do-notation;
    • State, Reader, Writer, IO;
    • Simple monad stacks, in whatever form (StateT s IO a or MonadState s m => m a or State s :> es => Eff es a) - or at least the concept of putting two monads together;
  • Modules;
  • cabal - adding build-depends, modules, building and running projects

It’d be very useful to know about:

  • Language extensions (e.g. OverloadedLabels, OverloadedStrings, NoImplicitPrelude, TypeApplications, etc)
  • Basic roguelike concepts like generating tile-based dungeons and an obsession of rendering things in ASCII characters, but that’s why you’re here - right?

And finally these things won’t explicitly be part of the tutorial (at least to start with) but are really useful to know about for when you want to go further; I use them extensively in my own projects and the libraries do have full support for them:

  • Lenses/Optics
    • Just acknowledging their existence as nicer ways to get, set, and modify nested record fields (especially in combination with state monads or stateful effects);
    • ^./view, .~/set, %~/over
    • the state monad equivalent optics - use, ~=, and %=
    • Using overloaded labels to avoid the pain of duplicate record field names or having typenameFoo everywhere;
  • Effect Systems - specifically effectful.

Planned tutorial structure

  • Part 0 (this one) Introduction, setting up the project, opening a window
  • Part 1: Drawing a @ and moving it around
  • Part 2: Generating a couple of maps
  • Part 3: Field of view
  • Part 4: Monsters, AI
  • Part 5: Combat
  • Part 6: UI
  • Part 7: Items and inventory
  • ???

Example screenshots

I’ll update this as I go.

Project structure setup

The rest of this part is setting up an empty cabal project, installing the relevant libraries, and verifying that indeed the hell of library paths has been solved.

Installing bearlibterminal

First, we need to download bearlibterminal, which is the graphics library that roguefunctor is built on. There are prebuilt binaries available at the bottom of the readme on GitHub. If you are on a platform that doesn’t have a prebuilt binary (for example, an M1 Macbook with Apple Silicon) then you can build it yourself:


git clone https://github.com/cfyzium/bearlibterminal.git
cd bearlibterminal/Build
cmake ../
make all

With the library file (.so,.dll, .dylib) you have two options:

  • you can either install this yourself into /usr/lib or equivalent.
  • you can copy the library file into some directory of your project and pass the library option to cabal with --extra-lib-dirs=/path/to/the/library. The downside of this method is that you do also need to set LD_LIBRARY_PATH(Linux) or DYLD_LIBRARY_PATH (Mac) or something else (Windows) to actually do cabal run, because it doesn’t copy the library into the cabal build directory. If anyone knows cabal better than I, please let me know how to set this up! PRs also incredibly welcome.

Making a new cabal project

Let’s begin by making a new project directory and initialising a blank cabal project. We’ll go for the unexciting name hs-rogue.

mkdir hs-rogue
cd hs-rogue
cabal init

This will start the interactive wizard for setting up a new cabal project. The options of importance:

  • we want just an executable project. In the future we might want to extract some things into a library if we wanted to build off our framework, but for now we just want to make an app.
  • we want cabal version 3.4 minimum, because default-language: GHC2021 saves a lot of time with writing out language extensions!
  • we want to use GHC2021 as the language for our executable, as this enables a bunch of language extensions for us.

The reason I suggest GHC2021 is because of the following language extensions - there’s probably more that are enabled and used, but these are the major ones:

  • DeriveFunctor, DeriveGeneric - Being able to derive functor instances for things that look like wrappers around an a with a bunch of additional data is super handy to have. Deriving Generic where possible is great primarily for the ‘free’ LabelOptic instances it gives you when using optics (which we are not in this tutorial) but also for making it simple to derive FromJSON/ToJSON when it comes to saving and loading our game.
  • LambdaCase - Saves an awful lot of time to just write \case rather than \x -> case x of!
  • TupleSections - Another quick timesaver - ( , a) rather than \x -> (x, a).
  • DisambiguateRecordFields - I’m not a fan of prefacing record field names with typename, so this saves the headache of the compiler complaining that it cannot identify which width is meant in the record update f { width = (width f) + 1 }.

This gives us hs-rogue.cabal pre-populated. Currently (as of April 2024), one of the libraries we need - roguefunctor - is not on Hackage, so cabal cannot automatically download it. We need a cabal.project file that specifies where the repositories for this library can be found as well as the packages in our project. We only have one package, but otherwise cabal run will complain that the project file lists no packages to run. Create cabal.project in the root directory of the project and add the following:

source-repository-package
  type: git
  location: https://github.com/PPKFS/roguefunctor.git
  tag: main
packages:
  hs-rogue.cabal

We specify that for the roguefunctor library, it’s available as a git repo at the above URL and the version of the repository we want is the main branch.

Whilst we’re at it, it’s safe to assume we would like haskell-language-server to work with this project. Whilst the language server shouldn’t have a problem working without it, it can sometimes be a bit…temperamental. We’ll add a hie.yaml to be safe, which is a config file that tells HLS where to find the hs-rogue executable component of our project:

cradle:
  cabal:
    - path: "hs-rogue/app"
      component: "executable:hs-rogue"

So now we will have tooltips and code actions and hints. Nice.

Initial dependencies

We’ve got one final setup step, and that’s adding some dependencies and extensions to the cabal file. These are the ones we’ll need for the first few parts of the tutorial. I’ll make sure in future parts to put all the modifications to the .cabal file at the start of the post. Under build-depends, add:

build-depends:
  base
  , bearlibterminal
  , roguefunctor
  , containers
  , random
  , text

From the top:

  • bearlibterminal and roguefunctor are the two libraries we are using for this tutorial. You could very easily do this tutorial without roguefunctor and just use bearlibterminal. However, it introduces some useful abstractions (like viewports, event handling, colours, field of view algorithm[s], and so on) so it means we can spend more time making a game and less time writing engine infrastructure.

  • containers - as we’re basically doing everything as a stateful Map of IDs to various things, this is kind of key to the whole thing.

  • optics - making updating the stateful Maps a lot easier.

Now if you run cabal build, it should download and build the two libraries. You’ll know your setup for installing bearlibterminal was correct if it successfully builds, as otherwise it will give errors about missing C libraries.

Default extensions

Finally we can add a couple of default extensions. GHC2021 automatically contains most of the “key” extensions for writing comfy modern Haskell, but there’s at least two more I suggest:

    default-extensions:
      NoImplicitPrelude
      OverloadedStrings
    default-language: GHC2021 -- if it's not already added
  • NoImplicitPrelude removes the implicit import Prelude from every module, thus allowing you to use your own Prelude. This works better than cabal mixins, which aren’t great when it comes to integrating with HLS. In this tutorial, we’ll write our own HsRogue.Prelude - a very thin wrapper around Prelude but with some extra re-exports that are still quite strangely not exported by the regular one - Text, forM_, (&), void, and so on - as well as some imports we want to use everywhere in our project, like Rogue.Geometry.V2. In roguefunctor there is also a custom prelude - Rogue.Prelude - that is a thin wrapper around relude. Whilst I do like to use relude myself - Text over String by default, no partial functions, polymorphic show, and many other nice-to-haves - Rogue.Prelude is geared towards using effectful and optics rather than mtl.
  • OverloadedStrings allows string literals to be interpreted as any instance of IsString rather than just as String. This is because we want to use Text over String for efficiency, as you should do in Haskell.

I also typically use TemplateHaskell and RecordWildCards on a per-module basis.

Opening a window

To verify that everything has been set up correctly, you can open a window by copying this into Main.hs - a full explanation will be in Part 1, along with drawing some things to the screen. In short, we use withWindow to open a window (with some provided options) and run our main event loop. The main loop refreshes the window, blocks until some input event is received (either a window event or a keypress) and loops if this is anything other than a window close event or an Escape key press.

module Main where

import Prelude -- we'll make our own prelude in part 1

import BearLibTerminal
import Control.Monad (when)
import Rogue.Config
import Rogue.Events
import Rogue.Geometry.V2
import Rogue.Window

screenSize :: V2
screenSize = V2 100 50

main :: IO ()
main =
  withWindow
  defaultWindowOptions { size = Just screenSize }
  (return ()) -- no init logic
  (const runLoop)
  (return ()) -- no shutdown logic

runLoop :: IO ()
runLoop = do
  terminalRefresh
  -- event handling
  shouldContinue <- handleEvents Blocking $ \case
    TkClose -> return False
    TkEscape -> return False
    _ -> return True
  when (and shouldContinue) runLoop

You can run your program with cabal run hs-rogue. If everything goes to plan, you should now have a black window open!

Troubleshooting

If you cannot build the project because of missing libraries, make sure you are supplying --extra-lib-dirs. If you can build but not run the project because of missing libraries, make sure you’ve copied libbearterminal.so/dylib/dll to a location on your PATH or export LD_LIBRARY_PATH/DYLIB_LIBRARY_PATH.

Maybe there will be more things, which can be added later.

Wrapping up

Well, that’s it for part 0. Not exactly much coding, but we can now hit the ground running for Part 1!

The code - well, a blank project structure - is available at the accompaying github repo here.

Hopefully this was understandable - any feedback is greatly appreciated. You can find me on the various functional programming/roguelike Discords as ppkfs and on Bluesky as @ppkfs.bsky.social.

Hope to see you for Part 1 soon!