A link to the repository can be found here.

Previously on Apecs

Roughly 4 years ago, I wrote the post An introduction to game development to game development in Haskell using Apecs. I like to think it was one of my most well-received blog posts considering it is featured on the Apecs repository itself, as well as being a common topic across emails and communications I receive.

Apecs is a ‘fast Entity-Component-System library for game programming’ written in Haskell. It is by far one of the best ECS implementations I’ve used and also happens to be my favourite way of structuring games when using Haskell.

However, enough time has passed (4 years!) that some of the tricks and methods used in that blog post are old enough to confuse beginners. Since that was never my intention, I thought I’d make a new blog post about it!

About this post

This post is going to be a little bit different. Whereas normally I’d finish a project and write a post about it, in this post I want to write it as I go along! Each time I finish implement something substantial, I’m going to add to this post so that I can really capture more of the development process.

This may have a few side-effects, however. Firstly, code we write near the beginning may change towards the end. If I make a simple mistake (such as a syntax improvement), I’ll simply swap it out for the superior. But I want the big decisions I make to be written about so that if I later decide against it I can articulate properly why in the post.

My blog has support for both projects and blog posts; this post is a blog post since it is capturing a moment in time, like a photograph. The associated project for this page will be the formal write-up for how the game works, but this will act more as a portfolio piece than as a tutorial. This is a bit of an experiment for me, so please let me know how you think it goes!

Introduction

What is the ECS pattern?

As the name suggests, the ECS pattern is divided into three parts: entities, components and systems. These parts work together to form the foundations of your game’s architecture.

• Entity — Alone, an entity is just a unique identifier, such as a simple integer value. They aren’t very useful by themselves!

• Component — Data, essentially. Anything that has data you need to store between frames, such as position, velocity, health or gold. Each component is attached to an entity in some way — some games have just a big database where an entity is just an integer used as a look-up key, whereas others (who probably would be using object oriented programming) might compose component lists within the entity class itself.

• System — The magic part that a lot of people miss out on! A system is simple: it iterates through entities and updates their components in some way. A player movement system might cherry-pick the player’s entity and update the velocity component with respect to whatever keys are held on the keyboard; a movement system would then iterate through all entities with positions and velocities and update their positions accordingly. If you can break the logic of your game into systems then things become a lot simpler and safer.

It was through ECS that I began to understand how modern game engines work (no thanks to you, university!) since having a greater appreciation for how games can be architected gave me an insight that couldn’t be taught through anything other experience. That isn’t to say that game engines all use ECS, in fact most of them don’t since they want to write their own systems (rendering, physics, scripting etc) that you then use and may or may not customise. Also, they probably don’t implement entities and components in the same way; both Unity and Unreal engines allow for logic to be placed in their components whereas the ECS pattern encourages components to be purely data.

What is Raylib?

One thing we haven’t mentioned yet is that this project will be using Raylib for the rendering side of things. I’ve always wanted to learn more about Raylib, and my chance came when I found the Haskell bindings released recently.

We won’t spend too much time talking about Raylib, in fact I’m using it purely because it’s a really easy way to get things on-screen. The documentation style surprises me a bit, with a preference for documenting the source code rather than an online version of the API. That said, for our purposes the cheatsheet is an excellent resource for just understanding what functions Raylib provides us with and what arguments they take.

What is Notakto?

Notakto is a variant of tic-tac-toe in which both players play using ‘crosses’ as their markers across multiple tic-tac-toe boards. Three crosses in a row on any board will ‘kill’ it, meaning that the board can no longer be played on. When there is only one board remaining, the player who kills it is considered the loser, meaning that to win you have to get yourself in a position where you force the other person to get three-in-a-row on the final board. It is still a solveable game like regular tic-tac-toe, but the stratagies involve enough effort that you will probably not find many people who can figure them out on their own.

Why did I chose to make Notakto? There’s a beauty in making a game where the rules are already well-defined since there is already a definition of ‘done’ — I know what I’m working towards and the project has scope, a perfect scenario for an experimental tutorial!

And with that, it’s 10:00 am, let’s begin our journey!

Getting started

Initial commit

Here we go! I’ve just pushed an initial commit with my standard Haskell bits and bobs. I always like making a library and separating executable-only code from the game itself, meaning that if we wanted multiple executables that handle the game setup in different ways (i.e. terminal or GUI) then we can. I’ve also got a testing folder, maybe we’ll write some tests as we go, who knows?

You may also notice that I am using Nix to build and run this project, so you should just be able to use nix run to run the project at any point in time. If you want to work in this repository, you can use nix develop to get your development environment set up.

At this point in time, running the project should print Hello, Notakto.

Introducing libraries

After setting up the repository, my next step with any project is adding the libraries I know I’ll be using and getting a modified example running to demonstrate that things are working correctly. Lets begin by updating our cabal file to include the h-raylib and apecs.

library
  exposed-modules:  Lib
  hs-source-dirs:   src/lib
  build-depends:
    base,
    apecs,
    h-raylib
  default-language: Haskell2010

Single file example

Imports, options and extensions

Now we can try and use our dependencies by modifying an example! Thankfully, h-raylib supplies us with a first-person-camera example, and I already have some Apecs examples from the project featured in my previous post!

{-# OPTIONS -Wall #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE TemplateHaskell #-}
{-# LANGUAGE TypeFamilies #-}

module Lib (main) where

import Control.Monad (unless)

import Apecs

import qualified Raylib as RL
import qualified Raylib.Colors as RL
import qualified Raylib.Constants as RL
import qualified Raylib.Types as RL
import Raylib.Types (Vector3 (..))

Here is how our Lib module is setup now. We’re still working in one file to keep it simple, so it’s okay for things to be messy.

• I use the -Wall language option just to make sure we’re ironing out warnings we go — personal prefence.
• The language extensions you see are all used by Apecs (or at least, the example made use of them). I know for a fact that TemplateHaskell is used as an easy way of building a World type for use throughout the application.
• Lib only needs to export main for now, but if we ever want to export a configuration data type that our client can provide then this is where we’d put it.
• I try to structure my includes with my ‘Haskell libraries’ at the top (i.e. things that aren’t specific to my project), followed by blocks of imports for my dependencies:
  • Apecs has quite a nice API; it doesn’t get messy if you just import it in its entirety and it almost feels like it’s part of the language.
  • Raylib has a lot of things going on (again, refer to the cheatsheet, so I’ve qualified it. Normally I’d explicitly write every function I use, however for this tutorial I’m going to use qualifications so that you can easily tell when something is a Raylib thing and when it’s something else.
    • I made an exception for Raylib.Types — certain types are quite commonly used throughout the project and so rather than typing RL.Vector3 constantly I instead explicitly imported it so that we can use it without restraint.

Creating and initialising a World

Next up is creating our World. In Apecs, the World is a type built specifically for your components to live in; that’s why TemplateHaskell is used to automatically write the code that glues your components together. The initWorld function is also a result of this template, which is why you might find it hard to find the World type and initWorld in the apecs documentation.

-- Define a component, a Camera
newtype Camera = Camera RL.Camera3D

-- Create a world featuring the lonely Camera component
makeWorldAndComponents "World" [''Camera]

-- Initialise our world in the main function, and give it to our game's systems
main :: IO ()
main = initWorld >>= runSystem (initialise >> run >> terminate)

The big important function here is makeWorldAndComponents. In Apecs, there are multiple template-Haskell functions you can use to create your World and associated components:

• makeWorld takes your components and constructs your World and component associations, but it doesn’t assume anything about your component’s storage mechanisms.
• makeWorldAndComponents calls makeWorld, but then also calls makeMapComponents which takes all of your components and defines Component instances with a Map store. In simple terms, it sets up your components with the most common storage mechanism, Map.

In this tutorial, I’ll be using makeWorldAndComponents to keep things simple, but if you ever want components that have specific constraints you might want to consider makeWorld and defining your mechanisms manually like I did in my previous post.

-- 'Map' storage: standard storage where any entity can have one
-- e.g. Every entity may have a name
newtype Name = Name String deriving Show
instance Component Name where type Storage Name = Map Name

-- 'Unique' storage: only one entity can have this component at maximum
-- e.g. Only zero or one entities can be marked as a player at any given time
data Player = Player
instance Component Player where type Storage Player = Unique Player

-- 'Global' storage: exactly one component exists for the lifetime of the game
-- e.g. There only needs to be one definition of the game's configuration
-- Note that querying for this on ANY entity will yield the global one,
-- effectively sharing the component between all entities
-- Also note that globals need instances for Monoid and Semigroup
data Config = Config String Int
instance Monoid Config where mempty = Config "Foo" 0
instance Semigroup Config where (<>) = mappend
instance Component Config where type Storage Config = Global Config

So, what are the initialise, run and terminate systems? Well, they are just functions with the type System World ()!

• System is an Apecs type defining a system, one of the parts of the ECS pattern. Note that System w a is mapped to SystemT w IO a under the hood; it’s just a convenience type.
• World is our world type created by template haskell in the above snippet.
• () is the absence of type; we aren’t expecting these systems to return anything, so these particular functions are only for executing side effects.

Let’s first look at initialise:

-- Simple system, doesn't return anything
initialise :: System World ()

-- We're in the 'System' monad, use 'do' to compose side effects
initialise = do

  -- Define a Raylib 3D perspective camera and name it 'camera'
  let camera = RL.Camera3D (Vector3 0 1 0) (Vector3 2 1 1) (Vector3 0 1 0) 70
        RL.cameraProjection'perspective

  -- Create a global entity with our camera component
  -- 'set' is an apecs function for setting a component's state on a given entity
  -- 'global' refers to the singular and unique global entity of the game
  -- 'Camera' refers to the constructor for our component which contains a RL.3DCamera
  set global $ Camera camera

  -- The 'System' monad has IO, remember 'System w a = SystemT w IO a'!
  liftIO $ do

    -- Now we can compose side effects for IO, which is what h-raylib uses
    RL.initWindow 1920 1080 "App"
    RL.setTargetFPS 60
    RL.setCameraMode camera RL.cameraMode'firstPerson

The biggest takeaway from the above snippet is to remember that just because we’re in Apecs-land doesn’t mean that we’re constrained to only using Apecs functions. System is a type constructor for SystemT, which apecs documentation explains:

A SystemT is a newtype around ReaderT w m a, where w is the game world variable. Systems serve to:

• Allow type-based lookup of a component’s store through getStore.
• Lift side effects into their host Monad.

We can do IO 🎉 Before we continue though, let’s look into terminate, since it’s good practice to always write in programming to always write delete where there’s new, or a destructor whenever you write a constructor. We have made our window, so let’s handle closing it before we forget:

-- When terminate is called, just close the window
terminate :: System World ()
terminate = liftIO RL.closeWindow

This is a short and sweet one!

Updating and rendering

We aren’t quite done with our single-file example since we have one remaining undefined function: run. Let’s dive in:

run :: System World ()
run = do
  update
  render
  shouldClose <- liftIO RL.windowShouldClose
  unless shouldClose run

Hang on a moment, this is a game loop! So in main, we had initialise >> run >> terminate, you can now see that the reason the program doesn’t terminate immediately is because run is hogging the thread and infinitely looping until told otherwise!

So what are update and render? Well, when you are in a monad be it IO or System, you can easily call functions of the same monadic type to compose side effects. You could pretty much substitute update and render for their contents and everything will work the same; this is a way of breaking things up. I like updating the game and then rendering the result. We can split these two steps into as many more steps as we need, but for our single file example they are singular systems that just handle the entire game.

-- Simple system
update :: System World ()
update = do

  -- Retrieve the camera component from the global entity (c is a RL.Camera3D)
  Camera c <- get global

  -- Update the camera and store the updated version in c'
  -- Also note the use of liftIO to dip into the IO monad to allow the use of raylib
  c' <- liftIO $ RL.updateCamera c

  -- Replace the global entity's Camera with a new one containing the updated camera
  set global $ Camera c'

I was a bit alarmed at first at how small this function is — where is the input handling? Where’s the movement speed definitions and all the other things we expect to see in a first-person game? Well it looks like Raylib is has some very plug-and-play style functions, which is nice to see when playing around. I’m sure anyone looking to make an FPS will be able to roll their own movement system, but for us we’ll be removing this pretty quickly since funnily enough Notakto is not a competitor to Call of Duty.

render :: System World ()
render = do
  Camera camera <- get global
  liftIO $ do
    RL.beginDrawing
    RL.clearBackground RL.black
    RL.drawFPS 10 20
    RL.beginMode3D camera
    RL.drawGrid 10 1
    RL.drawCircle3D (Vector3 2 1 1) 2 (Vector3 0 1 0) 0 RL.white
    RL.drawLine3D (Vector3 3 0 1) (Vector3 1 2 1) RL.white
    RL.drawLine3D (Vector3 3 2 1) (Vector3 1 0 1) RL.white
    RL.drawCubeWiresV (Vector3 (-2) 1 0) (Vector3 1 2 1) RL.white
    RL.endMode3D
    RL.endDrawing

The render system is very straightforward. We grab our camera out of our Apecs World and then use it in the IO monad to help Raylib render the world. I won’t go into much detail here.

After what feels like an eternity (it has taken me 2 hours to write this!), here’s our single file example up and running! Time for a toilet break and a glass of water!

Visualising the state of the game

What should be an entity?

I believe that the next step of this project is to visualise the boards and the marks placed upon them. In terms of priority, I want to get the visuals set up first otherwise testing the game is going to be a pain, but in order to get that done we need to create a basic representation of state!

So, representations of state — data types! Let’s make some new types to represent things we’ll need in our game! But wait.. Do you hear alarm bells?

After heeding that warning, let’s create an action plan. What should consist of an entity in our game? More specifically, should the boards themselves be entities? Should the marks that players place be entities? One could argue that both the board itself and the crosses placed could be entities. I disagree; I believe that the crosses don’t really make sense without the context of a board, and so there’d be little use in having an entity representing each cross in isolation (it might even make things more confusing trying to figure out which board each cross is on).

I believe that’s all we need to think about to get started; let’s do some programming.

The Types module

A single-file example is nice, but is only going to impede us going forward; let’s make a new module containing all of our components and miscellaneous types: Types.hs!

{-# OPTIONS -Wall #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE TemplateHaskell #-}
{-# LANGUAGE TypeFamilies #-}

module Types (
  World,
  initWorld,
  Camera (..),
) where

import Apecs

import qualified Raylib.Types as RL

newtype Camera = Camera RL.Camera3D

makeWorldAndComponents "World" [''Camera]

So I’ve moved all language extensions into this new file, since they’re only relevant for the World initialisation code. We now have a cleaner space to declare new data types, and since components should be simple, we should be fine to place them all in here for the duration of this project.

The BoardComponent

In the previous section, we asked the question “what should be an entity?” Now that we know of some certain entities, we now need to think about what components we might like to attach. The one I’m most interested in right now is a representation of a board, the standard tic-tac-toe battle ground.

-----------
-- Types --
-----------

data Cell = Empty | Filled deriving (Show, Eq)

----------------
-- Components --
----------------

newtype CameraComponent = Camera RL.Camera3D


data BoardComponent = Board {
  _tl :: Cell, _tc :: Cell, _tr :: Cell,
  _ml :: Cell, _mc :: Cell, _mr :: Cell,
  _bl :: Cell, _bc :: Cell, _br :: Cell
} deriving (Show, Eq)

makeWorldAndComponents "World" [''CameraComponent, ''BoardComponent]

This will do for now I think, no need to get too fancy. One thing I’d like to draw your attention to is the separation of standard types and types that are used as components — components are the things you’ll be operating on when using Apecs, so try to organise your code in a way which makes sense to you. I’ve appended Component to my component types, but I’ve omitted it from my data constructors so I don’t have to type it out as much.

Now go back to Lib.hs and fix any errors we have and ensure things still run. Let’s also create an entity with BoardComponents to represent a singular board while we’re at it!

initialise :: System World ()
initialise = do

      -- Update location of camera so we can look at origin
  let camera = RL.Camera3D (Vector3 0 1 6) (Vector3 0 1 0) (Vector3 0 1 0) 90
        RL.cameraProjection'perspective

      -- Define what a blank board looks like
      newBoard = Board Empty Empty Empty Empty Empty Empty Empty Empty Empty

  set global $ Camera camera

  -- Create a new entity with a blank board
  -- Note: if you want the return value, omit '_'
  newEntity_ newBoard

  liftIO $ do
    RL.initWindow 1920 1080 "App"
    RL.setTargetFPS 60
    RL.setCameraMode camera RL.cameraMode'firstPerson

Rendering

Now that we have some data floating around cyberspace it’s time to prove that we do indeed have some state by trying to visualise it. Now for the sake of fun, I’m going to continue to use the first-person camera. If this was any other project I’d throw it out the window, but it gives us an event handling system built as well as a great opportunity to experience Notakto in 3D! Throwing it away right now would just create a detour since we can use it in the short term to explore our world.

Once again, I’m going to make a new module: Rendering.hs. This module is going to import Types and be imported by our main Lib module. This module will house all the dirty Raylib rendering things so that our main file can be more gameplay-focused. I’ve also moved the render function into this module so that we only have to export a single function for the entire module.

module Rendering (
  render
) where

import Apecs

import qualified Raylib as RL
import qualified Raylib.Colors as RL
import qualified Raylib.Constants as RL
import qualified Raylib.Types as RL
import Raylib.Types (Vector3 (..))

import Types


render :: System World ()
render = do
  Camera camera <- get global
  liftIO $ do
    RL.beginDrawing
    RL.clearBackground RL.black
    RL.drawFPS 10 20
    RL.beginMode3D camera
    RL.drawGrid 10 1

  -- Our systems are sandwiched between the 'begin' and 'end' functions
  renderBoards

  liftIO $ do
    RL.endMode3D
    RL.endDrawing


renderBoards :: System World ()
renderBoards = undefined

Time to get creative! We need to draw some array of cubes and shapes to visualise the board! Our use of RL.drawGrid means we can visualise the units of the world — the grid is spaced such that each cell is 1 unit by 1 unit. Now we just need to draw 4 cuboids to mock out a hash symbol.

-- Those experienced with monads can probably guess what cmapM_ does
renderBoards :: System World ()
renderBoards = cmapM_ renderBoard

-- The signature of this function also qualifies as a condition, only the
-- entities that satisfy said condition will have this function mapped onto them
-- In short, only entities with a BoardComponent get rendered via this function
renderBoard :: BoardComponent -> System World ()
renderBoard b = liftIO $ do
  RL.drawCube (Vector3 0.5    1.5 0) t 3 t RL.white
  RL.drawCube (Vector3 (-0.5) 1.5 0) t 3 t RL.white
  RL.drawCube (Vector3 0 1 0) 3 t t RL.white
  RL.drawCube (Vector3 0 2 0) 3 t t RL.white

  -- 't' is the thickness here
  where t = 0.05

The key takeaway here is cmapM_. Let’s quickly recap the other variants so that we can deduce what this does (I’m going to shorten the type signatures a bit here):

cmap :: (cx -> cy) -> System w ()

This function maps a standard, non-monadic function onto all entities with cx. What is cx you might ask? Well I shortened the type signature for the blog (sorry) but it’s a polymorphic parameter representing a bundle of components. Apecs leverages Haskell’s type system to intelligently select all entities that meet the criteria for cx. A singular type is one of the simplest forms of using this function; notice how our renderBoard function requires a parameter of BoardComponent. We can actually specify more than just a single component, and Apecs will use that group as cx. Similarly, cy is a group of components to be output.

cmapM :: (cx -> System w cy) -> System w ()

This function is very similar to cmap with one exception — the function mapped onto entities returns a composable side-effect of the System monad, which also means access to IO as well as other Apecs functions. You will typically use pure <your components> to return things. Appending M to a function to denote the presence of a monad is very common in Haskell.

cmapM_ :: (cx -> System w ()) -> System w ()

Once again, very similar, except this time to cmapM. We still have access to monads, except the function we map onto entities no longer produces a cy. This means that the function you’re mapping onto your entities is there to only produce side-effects. In the case of renderBoards, we want to map a monad function to our entities, but we don’t need to return anything, so cmapM_ is used.

After all of that, we have our first board rendered!

What does this tell us? Well, if we had no entities in the game that contained a BoardComponent, this arrangement of sticks wouldn’t appear in the world at all! We have correctly defined, initialised, stored, read and visualised state, even on a very basic level!

There are some things however that this doesn’t tell us:

• It won’t tell us how many boards there are, they all render on top of each other.
• It won’t show us the state of the board, since we aren’t rendering crosses yet.
• It won’t help us realise why we should love the game of Notakto.

Multiple boards

Let’s address this issue of not being able to see multiple boards. There’s two ways I can think of for going about this:

• We could create a new component representing the origin of the board in 3D space.
• We could count the number of boards and distribute them evenly along the x-axis.

Honestly, we’ll probably end up doing option one eventually, but because I like the idea of boards being automatically arranged I’m going to go with option 2 for now. I think the end game is a mixture of both approaches, where we automatically generate positions for each board, for instance in a circle or something.

renderBoards :: System World ()
renderBoards = do

  -- Now we count how many entities have a BoardComponent using cfold
  numBoards <- cfold (\c (Board{}) -> c + 1) 0

  -- We provide the count to renderBoard
  -- Also, we want to FOLD now, since we're iterating through boards
  cfoldM_ (renderBoard numBoards) 0


-- We now know the total number of boards as well as the current board
renderBoard :: Int -> Int -> BoardComponent -> System World Int
renderBoard total i b = liftIO $ do

  -- Each of our cubes are now offset using a function we define below
  RL.drawCube (addVectors origin $ Vector3 0.5    0 0) t 3 t RL.white
  RL.drawCube (addVectors origin $ Vector3 (-0.5) 0 0) t 3 t RL.white
  RL.drawCube (addVectors origin $ Vector3 0 0.5 0) 3 t t RL.white
  RL.drawCube (addVectors origin $ Vector3 0 (-0.5) 0) 3 t t RL.white

  -- Return the next index (so we can track progress through iteration)
  pure $ i + 1

  -- Determine the origin of the board (4.5 = length of board (3) + padding (1.5))
  where offset = fromIntegral (total - 1) * 0.5
        origin = Vector3 (CFloat (fromIntegral i - offset) * 4.5) 1.5 0

        -- Convenience function for adding a vector to the origin, used above
        offset p = addVectors p $ Vector3 (CFloat origin) 0 0
        t = 0.05


-- Raylib bindings need love; we need to make a function for adding vectors
addVectors :: Vector3 -> Vector3 -> Vector3
addVectors a b = Vector3
    (vector3'x a + vector3'x b)
    (vector3'y a + vector3'y b)
    (vector3'z a + vector3'z b)

The biggest change we’ve made here is the use of cfold and cfoldM_. Our first use of cfold is given a pure function that doesn’t use monads, therefore we use cfold. The second one does use monads, and since we don’t care about a return value we use cfoldM_. Folding is a generic way of doing things like accumulation or filtering; you iterate through the list as well as another parameter, be it a ‘count’, ‘total’ or an entirely different list. In this case, we used folds to firstly count the number of entities satisfying a condition (whether they had a BoardComponent), then we used another fold to iterate through the same set of entities, except this time we used the iteration value (index) as a way of knowing how far through we are, kind of like a for loop in imperative languages.

With that out of the way, let’s instantiate more entities!

-- Let's make 3 boards!
newEntity_ newBoard
newEntity_ newBoard
newEntity_ newBoard

Objective complete! Even though the components of each of these boards have the exact same state, the fact that there are multiple entities now reveals itself visually!

Board state

Time for the final piece of the puzzle: rendering a representation of what marks have been placed on each board! We’re almost there, I promise. This is more of the same kind of stuff.

renderBoard :: Int -> Int -> BoardComponent -> System World Int
renderBoard total i b = do

  -- Render crosses as part of renderBoard
  -- We provide the origin value as well as the component
  renderCrosses origin b

  liftIO $ do
    RL.drawCube (addVectors origin $ Vector3 0.5    0 0) t 3 t RL.white
    -- <...>

-- Given an origin, render a cross for each cell
renderCrosses :: Vector3 -> BoardComponent -> System World ()
renderCrosses origin b = do

  -- This function's job is to geometrically define what 'top left' etc means
  renderCross origin (-1)   1  (_tl b)
  renderCross origin   0    1  (_tc b)
  renderCross origin   1    1  (_tr b)
  renderCross origin (-1)   0  (_ml b)
  renderCross origin   0    0  (_mc b)
  renderCross origin   1    0  (_mr b)
  renderCross origin (-1) (-1) (_bl b)
  renderCross origin   0  (-1) (_bc b)
  renderCross origin   1  (-1) (_br b)


-- Now we have an origin as well as a horizontal + vertical offset and a cell
renderCross :: Vector3 -> Float -> Float -> Cell -> System World ()

-- If the cell is empty, we just do nothing (pure nothingness, pretty metal!)
renderCross _ _ _ Empty = pure ()

-- If the cell is filled, we render a cross
renderCross origin i j Filled = liftIO $ do

  -- We simply draw 2 lines, bottom left to top right...
  RL.drawLine3D (f (-0.4) (-0.4)) (f 0.4 0.4) RL.red

  -- ... and then bottom right to top left
  RL.drawLine3D (f 0.4 (-0.4)) (f (-0.4) 0.4) RL.red

  -- We have some helper values here, center being the center of the cell
  -- calculated using the origin and offsets
  where center = addVectors origin $ Vector3 (CFloat i) (CFloat j) 0

        -- As well as a helper function to create start and end points
        f x y = addVectors center $ Vector3 x y 0

Ready to test it out? Let’s ammend our initialisation for one of the boards:

  newEntity_ $ Board
    Filled Empty Empty
    Empty Empty Empty
    Empty Empty Empty
  newEntity_ newBoard
  newEntity_ newBoard

And now we see that the first board has the top-left cell filled! We can now visualise both the amount of boards and the content of each one! Chapter over!

Making moves

Preparing the raycast

Okay, it’s time to speed up and do some gameplay code. In order to make moves, players will need to shoot a ray out from the camera into the boards so that they can precisely specify where they want to place their cross. Let’s start by adding a new component responsible for storing the player’s current aim. We don’t have to give it a default value as it’ll be written during our update frame anyway.

-- New component to add (Types.hs) and add to World
newtype PlayerAimComponent = Aim RL.Ray


-- New update system to add (Lib.hs) and be called from update system
handlePlayerAim :: System World ()
handlePlayerAim = do

  -- Determine window size so that we can cast from center of screen
  windowWidth <- liftIO RL.getScreenWidth
  windowHeight <- liftIO RL.getScreenHeight

  - Retrieve the camera (will have just been updated)
  Camera camera <- get global

  -- Create a ray to be cast later
  ray <- liftIO $ RL.getMouseRay (RL.Vector2
    (CFloat $ fromIntegral windowWidth / 2)
    (CFloat $ fromIntegral windowHeight / 2)) camera
  set global $ Aim ray


-- New render system to add (Rendering.hs) and be called from render system
renderAimRay :: System World ()
renderAimRay = do

  -- Retrieve player aim component
  Aim ray <- get global

  -- Determine endpoints of a line to draw
  -- Note that we slightly offset the start location since we are drawing
  -- from the camera, and if we didn't offset then the line would appear
  -- as a dot!
  let lineStart = addVectors (RL.ray'position ray) (Vector3 0 (-0.05) 0)
      lineEnd = addVectors (RL.ray'position ray) $
        multiplyVector (RL.ray'direction ray) 10

  -- Render the line
  liftIO $ RL.drawLine3D lineStart lineEnd RL.yellow


-- New utility function
multiplyVector :: Vector3 -> Float -> Vector3
multiplyVector a b = let b' = CFloat b in Vector3
  (vector3'x a * b')
  (vector3'y a * b')
  (vector3'z a * b')

We have momentum now! We haven’t done anything gameplay related really yet, but we’re blasting through the basics and now we’re ready to try and cherry-pick a cell from a board. This yellow line will be really helpful for making sure that the selected cell we’re going to calculate is in the approximate area of the ray.

This is where having each cross as its own entity has a benefit; each cross could easily check if it the raycast strikes it and our picking system would be done in a matter of minutes. However, the drawbacks of this is the task of connecting it back to the board and making changes to the game state. Instead, we’re going to see if the raycast collides with the board, and use the position it strikes the board to determine which cell the player is aiming at.

Identifying the looked-at cell

I knew it was coming; the problem with writing the blog post as I go means that I get stuff wrong. I initially thought it would be a good idea to simply count the entities and render the board in a position dependent on it’s index, however this is just going to be so annoying to calculate each time. That’s okay though, as both Haskell and Apecs are really easy to experiment with and try new things. Here’s a quick correction to our project:

-- New component for tracking positions in 3D space
newtype PositionComponent = Position RL.Vector3 deriving (Show, Eq)


-- Initialisation system for automatically creating n boards across the x axis
-- Note: Thanks to our position component, you could create all sorts of patterns!
createBoards :: Int -> System World ()
createBoards n = do

  -- forM_ is standard library, it's equivalent to flip mapM
  -- Also notice that to create an entity with multiple components we use a tuple
  forM_ positions $ \p -> newEntity_ (newBoard, Position p)
  where newBoard = Board Empty Empty Empty Empty Empty Empty Empty Empty Empty

        -- List comprehension to dynamically generate a list of x coordinates
        positions = [Vector3 x' 1.5 0 | x <- [0..n - 1],
          let x' = (fromIntegral x - (fromIntegral (n - 1) / 2)) * 4.5]


-- Forget cfoldM_, we're back to cmapM_
renderBoards :: System World ()
renderBoards = cmapM_ renderBoard


-- Notice the tuple - this is how you select entities that contain both components
-- Note: You can use the 'Not' type to ensure the entity DOES NOT have that type
renderBoard :: (BoardComponent, PositionComponent) -> System World ()
renderBoard (b, Position p) = do
  renderCrosses p b
  liftIO $ do
    RL.drawCube (addVectors p $ Vector3 0.5    0 0) t 3 t RL.white
    RL.drawCube (addVectors p $ Vector3 (-0.5) 0 0) t 3 t RL.white
    RL.drawCube (addVectors p $ Vector3 0 0.5 0) 3 t t RL.white
    RL.drawCube (addVectors p $ Vector3 0 (-0.5) 0) 3 t t RL.white
  where t = 0.05

This is where things get tricky… I’ve actually had to file a bug report since the raycasting and collision of Raylib don’t seem to be working great. It seems that data that we’re receiving isn’t what we expect and is slightly unreliable unless we do some IO before accessing it. Raylib wasn’t written in Haskell, and so even though our programming can easily be reasoned about, there’s a bit of a grey area where bindings to libraries written in other languages are. For now though, I’m just going to pretend the bug doesn’t exist and try to implement more of the program.

Before we continue, we need to ask ourselves what we actually want to do. Right now, my goal is to make it so that when you aim at a cell, we see a ‘ghost’ of a cross that will appear if you hit the left mouse button. The biggest question is, how do we want to store this bit of state?

1. We could change our Cell type to be either Empty | Filled | Chosen, however that will require us to make sure that only one cell is chosen at most, which is more work.
2. We could specify a new variable on the BoardComponent to keep track on which cell is chosen, but that would mean that we could have multiple chosen cells across multiple boards.
3. We could update the PlayerAimComponent to contain both the ray and the looked-at cell — while this would work, it would be assuming that we’re only interested in players looking at cells, and wouldn’t be very good if your game had multiple things players could interact with.
4. We could try to avoid writing state altogether, but this would mean that every cell will need to crunch the numbers to work out if you’re looking at it every rendering loop. This would also mean that we have to test cells in isolation, meaning that there could be a situation where you’re technically looking at multiple cells at once.

Isn’t gamedev fun? I believe that I’m going to go for option 3. Note that if you were doing a look-at system in a different type of game, you’d most likely just record which Entity you’re looking at. The only reason we are in this scenario is because we avoided making crosses be their own Entity.

Huzzah, after a few days that bug was fixed! Let’s get on with approach number three:

-- New data type representing the player's current looked-at cell
data LookAtTarget = NoTarget | Target Entity Int deriving (Show, Eq)


-- Update the aim component to make use of our new type
data PlayerAimComponent = Aim RL.Ray LookAtTarget deriving (Show, Eq)


-- Update the player aim function to calculate the currently looked-at cell
handlePlayerAim :: System World ()
handlePlayerAim = do
  windowWidth <- liftIO RL.getScreenWidth
  windowHeight <- liftIO RL.getScreenHeight
  Camera camera <- get global
  ray <- liftIO $ RL.getMouseRay (RL.Vector2
    (CFloat $ fromIntegral windowWidth / 2)
    (CFloat $ fromIntegral windowHeight / 2)) camera

  -- Use the ray we generated to find a target
  target <- cfoldM (findLookAtTarget ray) NoTarget
  set global $ Aim ray target


-- Look for closest board that the player is looking at
findLookAtTarget :: RL.Ray -> LookAtTarget ->
                    (BoardComponent, PositionComponent, Entity) ->
                    System World LookAtTarget
findLookAtTarget ray target (_, Position p, e) = do

  -- If our raycast hits the current board
  if RL.rayCollision'hit hitInfo > 0 then

    -- Check if this new target is closer than our current target
    getClosestTarget ray target $ Target e (findCell hitPos)

  -- Otherwise, use the current best target
  else
    pure target

  -- Determine where to place the hitbox for raycast, and check hit location
  where from = addVectors p $ Vector3 (-1.5) (-1.5) (-0.05)
        to = addVectors p $ Vector3 1.5 1.5 0.05
        hitInfo = RL.getRayCollisionBox ray $ RL.BoundingBox from to
        hitPos = subtractVectors (RL.rayCollision'point hitInfo) p


-- Checks two targets and returns the closest one
getClosestTarget :: RL.Ray -> LookAtTarget -> LookAtTarget ->
                    System World LookAtTarget

-- If both variables are valid targets
getClosestTarget ray a@(Target eA _) b@(Target eB _) = do

  -- Note: We could have passed in the position of the prospective target,
  -- but felt a bit rubbish today and just thought I'd keep it simple
  Position posA <- get eA
  Position posB <- get eB

  -- Calculate distances to ray origin
  let p = RL.ray'position ray
      distA = magnitudeVector $ subtractVectors posA p
      distB = magnitudeVector $ subtractVectors posB p

  -- Return closest target
  pure $ if distA <= distB then a else b

-- Handle cases where invalid targets present
getClosestTarget _ a NoTarget = pure a
getClosestTarget _ NoTarget b = pure b


-- Takes a hit position and determines the looked-at cell
findCell :: Vector3 -> Int
findCell (Vector3 x y _)
  | y > 0.5 = findCol 0 1 2
  | y < -0.5 = findCol 6 7 8
  | otherwise = findCol 3 4 5
  where findCol left center right
          | x < -0.5 = left
          | x > 0.5 = right
          | otherwise = center


-- Another utility function to get the length / magnitude of a vector3
magnitudeVector :: Vector3 -> Float
magnitudeVector (Vector3 x y z) =
  let CFloat f = sqrt $ (x * x) + (y * y) + (z * z) in f

Our PlayerAimComponent is now primed! Let’s render it to prove to ourselves that we’ve completed a major hurdle. As an extra spin, I only want to render these markings if the cell isn’t already filled. We’re going to be pretty much updating all of our rendering logic to accept the LookAtTarget as a new parameter:

renderBoards :: System World ()
renderBoards = do
  -- Give the target from our aim component to renderBoard
  Aim _ target <- get global
  cmapM_ (renderBoard target)


-- Accept a new parameter and forward it to renderCrosses
renderBoard :: LookAtTarget -> (BoardComponent, PositionComponent, Entity) ->
               System World ()
renderBoard target (b, Position p, e) = do
  renderCrosses p (b, e) target
  -- ...


-- Each cross now has an index - we need to check if each cross is being
-- aimed at and pass that to renderCross. We have a new function to handle
-- that: isAimingAtCell
renderCrosses :: Vector3 -> (BoardComponent, Entity) -> LookAtTarget ->
                 System World ()
renderCrosses origin (b, e) target = do
  renderCross origin (-1)   1  (_tl b) (isAimingAtCell e 0 target)
  renderCross origin   0    1  (_tc b) (isAimingAtCell e 1 target)
  -- ...


-- Checks if the target is valid, and returns true if entity and cell matches
isAimingAtCell :: Entity -> Int -> LookAtTarget -> Bool
isAimingAtCell (Entity e) i (Target (Entity e') i') = e == e' && i == i'
isAimingAtCell _ _ _ = False


-- This function has another pattern to it depending on whether its aimed at
renderCross :: Vector3 -> Float -> Float -> Cell -> Bool -> System World ()

-- Empty, non-aimed at cells have nothing rendered
renderCross _ _ _ Empty False = pure ()

-- Filled cells are rendered as crosses, regardless of aim
renderCross origin i j Filled _ = liftIO $ do
  RL.drawLine3D (f (-0.4) (-0.4)) (f 0.4 0.4) RL.red
  RL.drawLine3D (f 0.4 (-0.4)) (f (-0.4) 0.4) RL.red
  where center = addVectors origin $ Vector3 (CFloat i) (CFloat j) 0
        f x y = addVectors center $ Vector3 x y 0

-- Otherwise, if we have an empty cell that's aimed at, render a circle
renderCross origin i j Empty True = liftIO $ do
    RL.drawCircle3D center 0.4 (Vector3 0 1 0) 0 RL.yellow
  where center = addVectors origin $ Vector3 (CFloat i) (CFloat j) 0

And with this, it’s game over! From now on it’s mostly gameplay code, and hopefully everything we do can is reflected by our rendering! Well done if you’ve made it this far; like with most games, the rendering can easily eat up a lot of our time. I’m sure the only rendering we’ll do from now on will be trivial.

Placing crosses dynamically

I don’t know about you, but I really hate the fact that this blog post so far has been mostly rendering! Isn’t this meant to be a blog about Apecs?! Well, let’s fix that by finishing our game and coming up with more entities, components and systems! First up are a set of systems to handle playing the game.

So far, our game has been doing all of our systems every single frame — we need to have some logic ran conditionally:

• Obviously, we need to place crosses when we click: We wouldn’t want this running every frame as the game would be unplayable!
• When we get three-in-a-row we need to kill the board: The state of the game only changes when moves are made, so this can also be ran on left click; it would be redundant otherwise!
• We need to check for game-over when a board is killed: When there are no boards remaining, the current player is the loser and the winner is decided. Again, this relies on state being changed, so we’re slowly moving away from frames to turns.
• We need to switch players: We have no concept of players yet, but when we do, we will be switching who’s turn it is as well as incrementing stats of whatever sort after checking for game-over and it being decided that play should be continued.

update :: System World ()
update = do
  updateCamera
  handlePlayerAim

  -- After aiming, we want to handle clicking
  clicked <- liftIO $ RL.isMouseButtonPressed 0
  when clicked $ do
    handleLeftClick


-- Handles everything that may happen following a left-click
handleLeftClick :: System World ()
handleLeftClick = do

  -- Try and place a cross, and print a message when successful
  moveMade <- tryPlaceCross
  when moveMade $ do

    -- Note: This is where we'll check for game-over later
    liftIO $ putStrLn "Move Made!"


-- This system returns true if a new cross is placed on the board
tryPlaceCross :: System World Bool
tryPlaceCross = do

  -- Get the player's target
  Aim _ target <- get global
  case target of

    -- Do nothing if there is no target
    NoTarget -> pure False

    -- If there is a target, try to mutate the state of the board
    Target e i -> do
      board <- get e
      if getCell board i == Empty then do

        -- We set the component on the entity here directly,
        -- if you're doing this on lots of entities you should be using cmap
        set e $ setCell board i Filled
        pure True
      else
        pure False


-- Convenience function for retrieving a cell by-index
getCell :: BoardComponent -> Int -> Cell
getCell b 0 =_tl b
getCell b 1 =_tc b
getCell b 2 =_tr b
-- ...


-- Convenience function for setting a cell by-index
setCell :: BoardComponent -> Int -> Cell -> BoardComponent
setCell b 0 c = b { _tl = c }
setCell b 1 c = b { _tc = c }
setCell b 2 c = b { _tr = c }
-- ...

If you give the game a try now, you’ll be happy to see that, as expected, we can now place crosses when we click the mouse button. We have a lot of momentum now, let’s not stop here and move onto finishing the game loop itself!

Killing boards

The rules of Notakto state that when a three-in-a-row is detected, a board is declared ‘dead’ and can no longer be played on; when there are no boards remaining, the game is over and the current player loses. Killing boards is just as important as making moves on a single board, however fortunately for us this won’t be difficult at all to pull off with the tools we have.

1. We will create a new component that we attach to boards to render them dead: We could calculate if a board is dead every time we need to know, but this will add up especially if we want to render this somehow. If we use a component, we can trivially iterate through alive and dead boards.
2. We will count the dead boards: We will use cfold to count the number of boards that are alive, and if this number is 0 we will declare the game to be over.
3. We will not render dead boards: I’m stick of doing rendering in this tutorial. I’m going to force the players to manually check the state of the board for whether they’re playable — it’s not a missing feature, it’s a skill check.

-- New component with a unary data constructor
-- Note: To test for absense, we will be using the type Not DeathComponent
data DeathComponent = Dead deriving (Show, Eq)


-- New system that will kill any boards with three-in-a-row and
-- then return if there's a game-over
checkForGameOver :: System World Bool
checkForGameOver = do

  -- Map a function onto all entities with boards, killing them if possible
  cmap tryKillBoard

  -- Count the number of boards that are alive (lack of death component)
  let countAlive :: Int -> (BoardComponent, Not DeathComponent) -> Int
      countAlive c (_, _) = c + 1

  -- Perform the counting and return true if all boards dead
  count <- cfold countAlive 0
  pure $ count <= 0


-- Note the type signature; we use 'Not' to exclude dead boards
-- Another thing to note is that we return 'Maybe DeathComponent',
-- this hints that we may or may not be adding a component to the entity
tryKillBoard :: (BoardComponent, Not DeathComponent) -> Maybe DeathComponent

-- Just Dead will add the DeathComponent, Nothing will add nothing
tryKillBoard (bc, _) = if check cellCombos then Just Dead else Nothing

  -- Fold through a list of combos and check if any are threes-in-a-row
  where check = foldl (\dead (a, b, c) -> dead || checkCombo a b c) False

        -- Check if all cells in a combination are filled, meaning a win
        checkCombo a b c = checkCell a && checkCell b && checkCell c
        checkCell c = getCell bc c == Filled


-- A list of all cell combinations in index form (to be used with getCell)
cellCombos :: [(Int, Int, Int)]
cellCombos = [
  -- Horizontal
  (0, 1, 2),
  (3, 4, 5),
  (6, 7, 8),
  -- Vertical
  (0, 3, 6),
  (1, 4, 7),
  (2, 5, 8),
  -- Diagonal
  (0, 4, 8),
  (2, 4, 6)
  ]

You may think that’s it, but now we need to sprinkle mention of the DeathComponent to places where we don’t want interactions with dead boards. After looking through the code, I can only think of one place, but you might have more:

findLookAtTarget :: RL.Ray -> LookAtTarget -> (BoardComponent,
                    PositionComponent, Not DeathComponent, Entity) ->
                    System World LookAtTarget

If you want to special rendering for dead boards, now is the time! You might even want to update the death component to contain data regarding the winning combination for easy access!

Let’s now use our new system in the game and print a message if the game is over:

handleLeftClick :: System World ()
handleLeftClick = do
  moveMade <- tryPlaceCross
  when moveMade $ do
    isGameOver <- checkForGameOver
    if isGameOver then
      liftIO $ putStrLn "Game over!"
    else
      liftIO $ putStrLn "Next turn!"

Restarting the game

Before we finish this chapter, let’s handle restarting the game as it’s very related to the previous section! Firstly, even though we named the function checkForGameOver, this function is also responsible for killing boards. Let’s do this elsewhere so that this function is purely a check, this way we can reuse it without worry!

handleLeftClick :: System World ()
handleLeftClick = do

  -- Check if the game is already over before making a move
  needsRestart <- checkForGameOver

  -- Only make moves if the game isn't over
  if not needsRestart then do
    moveMade <- tryPlaceCross
    when moveMade $ do
      cmap tryKillBoard
      isGameOver <- checkForGameOver
      if isGameOver then
        liftIO $ putStrLn "Game over!"
      else
        liftIO $ putStrLn "Next turn!"

  -- Otherwise, restart the game
  else do
    newGame
    liftIO $ putStrLn "Restarted game!"

-- New initialisation function that deletes all entities
newGame :: System World ()
newGame = do
  cmapM_ deleteBoard
  createBoards 3

  -- You can't really 'delete' entities in Apecs since entities are just ints;
  -- you have to delete their components. We use a convenience function.
  where deleteBoard (Board{}, e) = destroyEntity e


-- We make a type combining all types for miscellaneous use
type AllComponents = (PositionComponent, CameraComponent, BoardComponent,
  DeathComponent, PlayerAimComponent)


-- Trivial deletion function
destroyEntity :: Entity -> System World ()
destroyEntity e = destroy e (Proxy :: Proxy AllComponents)

Deletion in Apecs can be a little tricky, but as the author writes in this comment, as long as we obliterate any components on an entity it will stop having any effect on the application!

Well done, you can now play, complete and restart games! If you were to track turns and play with a friend, you could call this the end and enjoy it! There’s one final thing I want to do before I call quits and leave the rest up to you: creating the notion of players!

Making players take turns

The game is essentially complete, but we don’t really track the current player anywhere! I’m going to leave out the rendering and purely focus on the components and systems as I’m sure anyone reading this can fill in the gaps.

-- New component for tracking the current player
data PlayerComponent = Red | Blue deriving (Show, Eq)


-- Initialise the current player when we initialise the camera
set global $ (Camera camera, Red)


-- Switch players when a non-winning move is made
handleLeftClick :: System World ()
handleLeftClick = do

  -- Grab current player
  player <- get global
  needsRestart <- checkForGameOver
  if not needsRestart then do
    moveMade <- tryPlaceCross
    when moveMade $ do
      cmap tryKillBoard
      isGameOver <- checkForGameOver
      if isGameOver then

        -- Print that the current player lost
        liftIO $ putStrLn $ "Game over! " ++ show player ++ " loses!"
      else do

        -- Swap players and print who's turn it is
        let nextPlayer = if player == Red then Blue else Red
        set global nextPlayer
        liftIO $ putStrLn $ "It's " ++ show nextPlayer ++ "'s turn!"
  else do
    newGame
    liftIO $ putStrLn $ "Restarted game! It's " ++ show player ++ "'s turn!"


-- Change colour of things for different players
playerColour :: PlayerComponent -> RL.Color
playerColour Red = RL.red
playerColour Blue = RL.skyBlue


-- Example of changing colour of ray to suit player
renderAimRay :: System World ()
renderAimRay = do

  -- Notice that we aren't annotating the type for player; we infer it!
  (Aim ray _, player) <- get global
  let lineStart = addVectors (RL.ray'position ray) (Vector3 0 (-0.05) 0)
      lineEnd = addVectors (RL.ray'position ray) $
        multiplyVector (RL.ray'direction ray) 10
  liftIO $ RL.drawLine3D lineStart lineEnd $ playerColour player

Firstly, how cool is it that we can add features to the game this easily when using both Haskell and Apecs? It’s really during the iterations on your project where Haskell shines, and Apecs complements it perfectly. Secondly, notice that we didn’t annotate the type for player — again, thanks to Haskell, we can infer the types of components from their usage, so as long as you use your components for things you typically don’t have to be explicit with what the result of get needs to be. We’ve been mostly explicit up until now as we wanted to pattern match, but the PlayerComponent is very simple.

Here is where I set my first challenge — this blog post is becoming way too long, and so I’m going to make a change and show you how cool the result is, and you’ll have to make the changes yourself! Of course, the repository can be found at the end of the section with a link to the commit, so if you get stuck you can look up how I managed it. These changes are small and numerous; too boring to put write up. Have fun and see you in the next section!

-- We are going to annotate each cell with the player who placed the cross
data Cell = Empty | Filled PlayerComponent deriving (Show, Eq)

-- CHALLENGE:
-- 1. Change colour of crosses to be dependent on player
-- 2. Change circular 'aim' indicator to match player colour
-- 3. Have fun!

Bonus: Manually implementing first-person camera

Okay, so I’ve spied online that this post is actually being read and people are posting it around on Reddit (thankyou!). With that in mind, I thought I’d update the repository so that newer Haskellers can use the code without as many issues. One of the biggest things I found is that the camera was no longer moving on its own.

This was actually something that worried me when using Raylib at first, as it felt too ‘magical’ that their demo just baked in the first person camera movement. Fortunately, this isn’t hard to do, and so here’s the code:

-- Had to update this system to return the window we create
-- Also note that we disable the cursor straight away for free look
initialise :: System World RL.WindowResources
initialise = do
  let camera = RL.Camera3D (Vector3 0 1 6) (Vector3 0 1 0) (Vector3 0 1 0) 90
        RL.CameraPerspective
  set global (Camera camera, Red)
  newGame
  liftIO $ do
    window <- RL.initWindow 1920 1080 "App"
    RL.setTargetFPS 60
    RL.disableCursor
    pure window

-- Also changed terminate to close the specific window we created
terminate :: RL.WindowResources -> System World ()
terminate window = liftIO $ RL.closeWindow window

-- We now manually manipulate the camera's location and rotation
updateCamera :: System World ()
updateCamera = do
  Camera c <- get global
  newCam <- liftIO $ do
    dt <- RL.getFrameTime
    forward <- checkKey RL.KeyW RL.KeyUp
    left <- checkKey RL.KeyA RL.KeyLeft
    backward <- checkKey RL.KeyS RL.KeyDown
    right <- checkKey RL.KeyD RL.KeyRight
    Vector2 i j <- RL.getMouseDelta
    let speed = 5.0
        turnspeed = 1
        Vector3 x _ z =
          (RL.getCameraForward c |* (forward - backward)) |+|
          (RL.getCameraRight c |* (right - left))
        c' = RL.cameraMove c $ safeNormalize (Vector3 x 0 z) |* (speed * dt)
        c'' = RL.cameraYaw c' (-i * turnspeed * dt) False
    pure $ RL.cameraPitch c'' (-j * turnspeed * dt) False False False
  set global $ Camera newCam
  where checkKey a b =
          liftA2 (\x y -> if x || y then 1 else 0) (RL.isKeyDown a) (RL.isKeyDown b)
        safeNormalize v
          | magnitude v == 0 = v
          | otherwise = vectorNormalize v

Some things to note here is that a lot of our vector math functions are built into the h-raylib bindings now, so |+| lets you add two vectors together, |*| lets you multiply two vectors together, |* lets you multiply a vector with a normal scalar value and so on.

So with that in mind, we now retrieve the state of several keyboard inputs one by one and determine which direction we want to move in by combining the player’s net input as well as the camera’s forward and right directions. We then normalize that (I had to make a safeNormalize function for cases when magnituded is zero, this will probably get fixed soon) and multiply it by some speed value and delta time to make it frame independent. Looking around is similar; Raylib already gives us the mouse delta so we can put the right into the look direction logic.

Make sure to check out the diff for all the changes I made in this update. I hope this helps!

Wrapping up

Congratulations! I’m hoping that the content of this post, although long, has been useful as a gateway into the world of Haskell game development. I really enjoyed making this post and I’m hoping my readers enjoyed this new format even if it is a little wordy.

There are no more sections for this blog post, although honestly I wanted to go wild and do things like:

• Projectiles: When you click, you shoot a cube and you have to land it in a cell for it to mark. Would be interesting to make it so that you can only shoot if no projectile currently exists, and making the actions that happen when you click the mouse delayed until the projectile lands. Good luck finding that shot when it goes out of bounds!

• Moving boards: We have a PositionComponent but the data never really changes once created. Wouldn’t it be fun to make the boards fly around?

• Rotated boards: Right now we assume all boards face the same way. Adding a rotation would be fun but a little bit of work since you may need to write your own vector math functions unless you use another library (I wanted the dependency count to be low for this post).

• Forced distance: I wanted to make it so that you could only take a turn if you were stood in an area, so that you had to aim. Would be cool making a little environment with player colouring!

• AI: Here’s an easy peasy one — make it so that when you make your move, you can get an AI to play as the other person! Start off by just randomising the entity and cell index, and once you you’ve got a very basic AI you can move up to implementing the Negamax algorithm!

These things all sound fun, but I believe that the important thing is to teach the basics of Apecs and Raylib so that we get more projects popping up in the Haskell gamedev space. I’ve seen a lot of cool projects like Keid, but admittedly I just love Apecs too much, and now I can love Raylib also (even if I haven’t explored its limits too much).

Big thankyous to:

• Jonas Carpay, author of Apecs,
• Anand Swaroop (Anut-py) for creating the h-raylib bindings,
• the authors of Raylib,
• and finally, the Nix community for helping me with all my problems whenever I go crying to them about something not working. Really, thanks guys!

A scientific certainty

In 1840, Pierre-Simon Laplace[@laplace1840essai] posed the following question:

What is the probability that the sun will rise tomorrow?

This is the Sunrise Problem. It’s a bit of a peculiar one, and at first glance one might think that either the question is trivial, stupid, or both, but let’s dive a little deeper into what it is the question is asking.

Through observation, we can say with confidence that there hasn’t ever been a day where the sun hasn’t risen. It is a scientific certainty that it’ll rise and this very fact is taken as the truth by most if not all of the population — just look up at the sky and one can indeed see the sun rising each morning. After so much time, there is not one doubt that the sun does indeed rise every day.

But… What if it didn’t?

The real question

The reason the sunrise problem is even worth considering can be discovered by simply asking what if it didn’t? — what is it we’re really asking? If the chance of the sun rising is 100%, then what is the purpose of contemplating the scenario where it didn’t?

What we’re actually questioning here is not whether the sun rises, but in fact whether the probability of the sun rising is actually what we expect — this is a question of the probability of another probability!

Laplace’s answer to the sunrise problem

So, what was Laplace’s answer, and why was it interesting? Let’s go back to the sunrise problem: if human life had existed for 99 days exactly and the sun failed to rise on day 100, then one could argue that the probability is 99/100, as in, it happened 99 days in 100. However, on day 99, the observed probability would have been 99/99, or 1, which isn’t too useful in the context of the problem. If only there was a way to think in a similar way that’s as simple, while also giving us an answer of worth.

Laplace’s rule states that, for any event that has occurred multiple times until now, the probability of it happening again is equal one plus to this number divided by the number of times plus two. Obviously, words aren’t the best way of showing this, so here’s some fancy math:

$$ P(X_n+1=1|X_1+...+X_n=s)=\frac{s + 1}{n + 2} $$

Maybe this doesn’t help either.. The part to focus on is the last part on the right side of the equation — take the number of times where the sun has risen and add 1, and divide that number by the number of total days and add 2. What this is essentially doing is ‘simulating’ what the probability would be if there was one more day where the sun had risen, and another where it didn’t. In our example, this would be equivalent to:

$$ P(\text{Sun rises on 100th day})=\frac{99 + 1}{99 + 2}=\frac{100}{101} $$

While simple, and indeed slightly weird, this does provide us a tangible value which we can use, which is a whole lot better than ‘always.. I think’.

I can understand why one would think that this piece of knowledge isn’t very useful, however it’s important to remember what Laplace’s rule is telling us: it’s giving us a probability of a probability in a fairly quick and easy way: all you need to do is add 1 to the numerator and 2 to the denominator!

Finally, remember that in maths there can be multiple ways of doing things; you can get the average of a bunch of values via mean, median or mode, as a quick example. So while this does give us something, you should think of it as an answer rather than the answer.

My experience with the rule of succession

So I learned about this theorem from Grant’s video on Binomial Distributions[@sanderson2020binomial]. While the main topic of this not Laplace’s theorem, it did use it as a quick introduction to the video those 30 seconds truly struck me as something useful. Here’s the video if you’re curious:

Ever since I saw that video, I’ve had the rule of succession flash into my mind whenever I see a situation I might be able to apply it to. In the next section hopefully I can show you how!

Reviews

The question

Admittedly I stole this idea from Grant’s video, but it deserves its own section nonetheless. Unfortunately, fake reviews have recently begun to run rampant and so the effectiveness of applying Laplace’s rule of succession is diminished in these scenarios.

So, let’s imagine that you’re wanting to purchase something and you can see two similarly rated products. The question we’re trying to answer is the following:

Given that numerous people have had positive experiences, what is the probability that my own experience is also going to be positive?

This looks nothing like the rising sun problem! Where in this problem is there an element of ‘probabilities of probabilities’? Let’s start making some assumptions:

1. When we say positive experience, we mean an experience that we could comfortably rate 5/5 stars in the same way that others have done previously.

2. Each review is a binary representation of someone’s experience; they either had a 5 star experience, or they didn’t.

So with that, we can start viewing this problem in the same way as the sunrise problem, except the probability of someone giving a 5 star review is not 100%.

The math

Let’s say that 87% of 957 people gave a product 5 stars, meaning that 832/957 people had a 5 star experience. What is the probability that the next experience (yours) is also going to be positive? Let’s do the math:

$$ P(\text{5 star experience})=\frac{832 + 1}{957 + 2}=\frac{833}{959}=0.86861 $$

We now have a result! 0.86861! You could do the same maths on another product and then compare these values to see which one is more likely to satisfy you. Now like I said before, this is an answer, not the answer. There are many other ways you could compare two products, but if you can’t be bothered going full math-mode, this is a nice trick.

Why is this value useful?

Now the question you might have is, ‘how is this value any better than just taking the raw 87% value?’ The answer lies in the amount of reviews. We’ve always been skeptical of products with 100% 5 star reviews when only 2 people have reviewed it, but why? I believe it’s because deep down we simply don’t trust these two people to have experienced the product enough to represent our own experience, and so we are filled with distrust.

Laplace’s rule of succession handles this gracefully; by adding two extra reviews, one positive and one negative, we can somewhat ‘balance’ the review scores with the amount of reviews. Let’s see an example:

$$ P(\text{5 star experience with } A) = \frac{2 + 1}{2 + 2}=\frac{3}{4}=0.75 $$ $$ P(\text{5 star experience with } B) = \frac{350 + 1}{400 + 2}=\frac{351}{402}=0.87313 $$

In this completely arbitrary example, Laplace’s rule of succession tells us to trust product B more than product A despite B only having an 87.5% review score and A having a 100% review score; the low amount of reviews on product A meant that the adjustments made by the succession rule impact the score more significantly than they did in product B!

Challenge nudger

Another time I’ve used Laplace’s rule of succession was while I was at work! I was working on a piece of UI that ‘nudged’ the player towards content in the game. Players had vast amounts of challenges going on simultaneously, such as ‘kill 50 players’, ‘win 4 matches’ and ‘walk 1000km’. The problem: determining which challenge has the highest probability of being relevant to the player.

After the review chapter, I’m sure you can figure out why I chose to apply the rule here; how do we compare the player’s progress on these challenges when they have completely different requirements in terms of difficulty and time to complete?

Quiz time! Which challenge would you consider to be closest to completion?

1. Win 5 matches — Player has won 4.

2. Kill 50 players — Player has killed 40 players.

3. Destroy 100 barrels — Player has destroyed 80.

4. Walk 1000km — Player has walked 800km.

Regardless of which one you think is more relevant to players, it may be difficult to pick between them especially when their progress percentages are all 80%! However, once again, Laplace’s rule gives us an answer to this question (not the answer). Applying Laplace’s rule here not only allows us to consistently rank challenges by a common metric, but it also allows us to stop caring about details — we know there is not one right answer to this problem, so let’s just lean on statistics and move on!

Wrapping things up

I hope you enjoyed reading this post; this is the first time I’ve written about something other than programming specifically, but I personally have found if very handy for more things than I’ve listed. I hope that after giving it some thought, you too might find the answer’s that Laplace provides useful!

Make it a good one!

A live demo of this project can be found here.

What is this?

I built this as part of my introduction to both Haxe and Heaps. I started off with their sample projects and iterated until I had a good handle about what tools were available. The result is something similar to another project of mine, HexagonalHS.

You can test this project live at https://aas.sh/Voronoi.haxe.

How was it made?

This application features a generated mesh made up of hexagonal tiles of varying heights. This itself isn’t too difficult, especially when you follow the teachings of Red Blob Games. However, these tiles are transformed and deformed to completely alter the overall shape of the landscape.

Generating hexagonal tiles

You can find all the code for actually creating the hexagonal tiles here. I essentially made a class to represent tiles that contain their centers and the world position of each of their 6 corners. The basics of this are described in that Red Blob Games post, but below is the entire snippet of code generating these hexagons:

public function new (
  pos : Axial,
  height : Int,
  size : Float,
  padding : Float,
  heightMultiplier : Float,
  random : Random) {

  // Record variables for convenience
  this.pos = pos;
  this.height = height;
  this.size = size;
  this.padding = padding;
  this.heightMultiplier = heightMultiplier;

  // Calculate perfect center of hexagon
  final width = Math.sqrt(3) * (size + padding);
  center = new Vec3(
      (pos.q * width ) + (pos.r * width * 0.5),
      (pos.r * (size + padding) * (3 / 2)),
      height * heightMultiplier);

  // Generate corners of a regular hexagon
  corners = [for (i in 0...6) {
      final angleDeg = 60 * i - 30;
      final angleRad = Math.PI / 180.0 * angleDeg;
      new Vec3(center.x + size * Math.cos(angleRad),
                center.y + size * Math.sin(angleRad),
                height * heightMultiplier);
  }];
}

Applying voronoi

Next, I started to transform the grid into a voronoi pattern. In nature, voronoi patterns appear in things like bubbles, where a shape is ‘inflated’ until its boundaries collide with other boundaries. The trick is to select a point inside a shape and then ‘inflate’ from there. You can find all the code below here.

To select the location, I separated each hexagon into 3 rhombi around the centre. I then chose a point by randomly traversing the lengths of the rhombus, where each side is equal to the radius of the hexagon to any of its corners.

// The code below is appended to the 'new' function shown above
// Split the hexagon into 3 rhombi and choose one
final selectedCorner = random.randomInt(0, 2) * 2;
final corner = corners[selectedCorner];
final nextCorner = corners[selectedCorner + 1];
var toCenter = center.sub(corner);
toCenter.normalize();
var toNext = nextCorner.sub(corner);
toNext.normalize();

// Randomly select a feature point within the rhombus (and hexagon)
final i = toCenter.multiply(random.random() * size);
final j = toNext.multiply(random.random() * size);
featurePoint = corner.add(i).add(j);

After selecting these points for each hexagon, I then iterated through the list of hexagons to ‘inflate them’. Recall that each corner of a hexagonal tesselation is in contact with three hexagons, meaning that other than the current hexagon, we need to locate these other two hexagons. These hexagons may not exist if the current hexagon is on the border of your grid.

We use these feature points (the name I gave to that randomly selected location we picked earlier) to distort each hexagon in relation to those closest to them. Since we started with pattern of tesselated, regular hexagons, we know that we aren’t going to get more than 3 feature points for any corner since the other corners will act as the contact points in the ‘inflation’ process. It’s hard to explain, but if you visualise the process of picking these points and drawing a line that’s equidistant between them, you’ll see that the way other corners distort results in there only ever being 3 feature points to consider per hexagon.

for (tile in tiles) {

  // Hard code directions for iterating around the tile
  final dirs = [
    new Axial( 1, 0),
    new Axial( 0, 1),
    new Axial(-1, 1),
    new Axial(-1, 0),
    new Axial( 0,-1),
    new Axial( 1,-1)
  ];

  // Iterate for each corner and direction
  for (i in 0 ... 6) {

    // Prepare to reposition corner
    final prevDir = dirs[i > 0 ? i - 1: 5];
    final nextDir = dirs[i];
    final prevTile = getTileAt(Axial.add(tile.pos, prevDir));
    final nextTile = getTileAt(Axial.add(tile.pos, nextDir));

    // ...

Next, we need to find the midpoint of the three hexagons in contact’s feature points. To get the midpoint of three points, simply take the averages of their x, y and z (although I only wanted x and y here, since I manipulated z in other ways to ‘smoothen’ the map).

// Find midpoint between adjacent neighbours
var midpoint = if (prevTile != null) {

  // Both tiles valid - 3 way midpoint
  if (nextTile != null) {
    tile.featurePoint
        .add(prevTile.featurePoint)
        .add(nextTile.featurePoint)
        .multiply(1. / 3.);
  }
  // Just previous tile valid - 2 way midpoint
  else {
    tile.featurePoint
        .add(prevTile.featurePoint)
        .multiply(0.5);
  }
}
else {
  // Just next tile valid - 2 way midpoint
  if (nextTile != null) {
    tile.featurePoint
        .add(nextTile.featurePoint)
        .multiply(0.5);
  }
  // No neighbours - do whatever
  else {
    tile.featurePoint
        .add(tile.corners[i])
        .multiply(0.5);
  }
}

// Apply voronoi if requested
if (voronoi) {

  // If tiles have padding, shift midpoint to tile center
  if (tilePadding > 0) {
    final z = midpoint.z;
    var toCenter = tile.center.sub(midpoint);
    toCenter.normalize();
    toCenter = toCenter.multiply(tilePadding);
    midpoint = midpoint.add(toCenter);
    midpoint.z = z;
  }

  // Set location of corner to resulting midpoint
  tile.corners[i].x = midpoint.x;
  tile.corners[i].y = midpoint.y;
}

And with that, we have our voronoi pattern! We don’t need to worry about the edges, since the corners are where the boundries converge, and so by handling the corners the edges just line into place.

Smoothing

One of the options of this project is the ‘smoothing’ feature. This feature allows the sides of a tile to blend into the tile adjacent, forming ramps where possible. Below is a preview of how this looks:

Smoothing is performed by simply taking the average Z coordinate of all tile vertices that touch. This is essentially the same as the voronoi application with three subtle differences:

1. Smoothing can be enabled independently of voronoi
2. Voronoi application only cares about XY position so that there’s no gaps in the terrain
3. You might not always want to smoothen edges

Point 3 is interesting: take 3 tiles that touch at a single corner. One tile has height of 1, the second a height of 2 and the last a height of 3. If you smoothen the Z coordinate, nothing changes since the average height is 2. Instead, I decided to only smoothen when tiles are within a certain height range of each other (which can be chosen at runtime). This means that in that example, a ‘smoothen height’ of 1 would mean that the first and second tile get smoothed into a ramp, but the final tile remains as a cliff, since the difference between the highest and lowest tiles is greater than the smoothing value. This was done with the following snippets:

// Smoothing logic for 3-way corners
if (smoothen) {

  // Always include current tile
  var count = 1;
  smoothedZ = tile.height;

  // Include previous tile in smoothing if applicable
  if (Math.abs(prevTile.height - tile.height) <= smoothRange) {
    smoothedZ += prevTile.height;
    count += 1;
  }

  // Include next tile in smoothing if applicable
  if (Math.abs(nextTile.height - tile.height) <= smoothRange) {
    smoothedZ += nextTile.height;
    count += 1;
  }

  // Average all applicable tile heights
  smoothedZ /= count;
  smoothedZ *= tileHeightMultiplier;
}

// Smoothing logic for 2-way corners (using nextTile as an example)
if (smoothen && Math.abs(nextTile.height - tile.height) <= smoothRange) {
  smoothedZ = (tile.height + nextTile.height) *
      tileHeightMultiplier * 0.5;
}

How do I use it?

By default, the application will rotate around the map. You can disable this orbiting mode in the top right corner. From there, you can control the camera with your mouse and zoom in with the scroll wheel.

In the top left, you’ll find various settings for changing how the terrain looks. In the top right, you’ll find functions like changing the map’s colour, regenerating the map, and resetting all settings to default.

How do I compile it?

This project was created using Haxe and can be compiled in two ways. Before attempting compilation, you’ll need to install Haxe and Heaps. Additionally, you’ll need to install seedyrng and domkit via haxelib install <package>.

Visual Studio Code:

Haxe works very well with Visual Studio Code when using the Haxe Extension Pack. When everything is installed, you should be able to hit CTRL+SHIFT+B to build the project. It’ll compile to JS and be found in the docs folder, which you can then test by opening index.html in your web browser.

Command line:

After installing dependencies, you can run haxe build.hxml to compile the project. A JS file will appear in the docs folder and you can then test it by opening index.html in your web browser.

The build tool evolution

Typically when working with Haskell, you’d use something like Stack or Cabal to declare dependencies and build the project. This works great most of the time, but sometimes they feel like the thorn that makes me reconsider using Haskell.

I started off with Stack since that’s what most tutorials have you install when you’re a beginner (with good reason too, as it is very nice). However, before Stack there was Cabal which is a lot simpler than Stack and focused on resolving dependencies. Stack introduces things like better project templates, caching of built packages and finally usage of Stackage to pull dependencies.

Enter Nix

There exists yet another build tool: Nix. The easiest way to describe it is that Nix is like Stack except not just for Haskell. Stack is built very intelligently, keeping different versions of dependencies separate from one another while also keeping track of what’s compatible.

Take C++ development for example — typically, you have to download dependencies and manage them yourself. You might put them in a centralised place on your machine so that all of your programs can find them, but then you force other people to have to put them in the same place. You might consider bundling them with your project as a git submodule, but then you’re requiring users to download all your dependencies even if they already have them on their machines (possibly incurring additional compilation times too). Maybe you have a tool that intelligently searches for the locations of these dependencies, but then you’re requiring users to depend on that tool as well. Even if you’re a solo developer, you are a user of your own work.

In this regard, Stack (along with other build tools like Cargo for Rust is a brilliant improvement on this workflow. However, then you need to install each of these build tools for each of the languages your to-be-built programs and libraries use.

This is where Nix comes in. While sometimes these tools cannot be avoided, they can at least be automated. When using Nix, all of these programs can be built, used and depended-on in the exact same way, while keeping the benefits of reproducability (or bringing, if the old build tools didn’t do these things first).

When you use Nix, you don’t need to manually install anything related to your project. I have no traces of Rust or C++ on my machine since the only time I need them is during a project where I can let Nix do the heavy lifting. It really is wonderful when you type nix develop and all of a sudden your shell becomes capable of building, testing and running your work. It’s beautiful.

I’ll probably write some tutorials about Nix at some point, but I’m still learning it myself and have yet to actually submit a package to the ecosystem. I just wanted to participate in some evangelism and mention it on my website.

Why do I use Nix?

Regular readers of this blog (read: nobody) will have noticed that I’ve sneakily edited-in this last section. The reason for this addition is simple: I am not well versed enough in nix to really give an overview of its inner-workings and technicalities. What I can do is give a simple overview of my own experience and usecases.

In the past, my website has caused me hassle as every time I wanted to edit it I’d have to set up haskell on whatever machine I was on, which at the time could have been many. It wasn’t too difficult, but was annoying enough to put me off from working on it. This feeling permeated throughout all my projects; any subtle things I did during setup of one machine lead to me needing to repeat them on the others, increasing the probability of human errors and/or unforeseen circumstances which may result in things going wrong.

Nix fixes these things for me. Admittedly, there is a big up front cost whenever I start a project and more often than not you’ll see me frequent the nix discord server asking for tips for architecting and requesting for packages. There is a big reward associated with this though — once I’ve sucessfully set up a project, it is 100% reproducible so long as my machine has the nix package manager. Previewing my website locally is as easy as nix run ., and all my other projects are just as easy to execute.

Recently I was given the opportunity to work with the windows subsystem for linux which meant that I could open up a terminal that was running a linux distribution from within Windows. Fortunately, my dotfiles were separated into system and user configurations, meaning that I could reproduce my text editor and shell experiences on Windows! A huge win!

Each time I set up a new project, I gain a bit of experience as well as a template for me to reuse in future projects. Just like CMake, I’ll eventually get to the point where new projects aren’t daunting to set up at all! I’m not quite there yet, but I hope to be soon!

GitHub repository for HexagonalHS can be found here.

What is this?

This is just a simple 3D demo of some hexagonal prisms being rendered with code written in Haskell. Each prism is a hexagonal tile with a discrete, randomly generated height, to give the appearance of a simplified heightmap. I wanted to see how far I could push the program and see if a 3D game in Haskell is possible since I was experiencing performance problems rendering lots of entities in SDL.

Initially, this project was going to be the prototype of a game I’ve been wanting to make for a while, but after getting this far, I realised that my workflow for using Haskell was a little bit too bloated and frustrating for my liking. Similarly, the next part of this project was implementing a 3D animation system, and since I program functionally for recreational purposes I really don’t want force myself to continue when I’m not prepared to do so.

In the past, I’ve talked about Haskell as being my favourite language. I’ve learned a lot from it, but ultimately with my new job I’ve had less time to work on hobby projects. I’ve made the decision to move away from Haskell and explore Common Lisp. One of my projects, Space, gave me a very colourful insight into this new world of Lisp and I’m excited to jump into new things. I want to embrace the functional paradigm without reinventing the progress we’ve already made with traditional imperative methods — you’ll see more about this in my future posts!

How do I use it?

The camera uses simple first-person flying controls — WASD to move, Space and C to ascend and descend, and Right Mouse Button to look around. Pressing F1 regenerates the level instantaneously.

The performance measuring widget isn’t bundled with the executable. In the preview, I used MangoHud because it’s a very slick way of measuring FPS and rendering times — I highly recommend its usage on projects like this where garbage collectors are involved for profiling purposes.

How does it work?

This project is largely a port of the tutorials found on learnopengl.com. It was very interesting seeing the problems that came from trying to replicate imperative code in a functional scope. I am especially proud of how I loaded and stored resources:

-- Store a resource along with a way of loading it
data Resource a = Resource 
  { resource        :: Maybe a
  , resourceLoader  :: IO (Maybe a)
  }

-- Store resources by type and name
data Resources = Resources
  { _shaders  :: RMap Shader
  , _meshes   :: RMap Mesh
  }

-- Attempts to retrieve a loaded resource
tryGet :: MVar Resources -> RInfo -> RLens a -> IO (Maybe a)
tryGet mR info@(t, name) lens = do
  rs <- readMVar mR
  let maybeRes = Data.Map.Strict.lookup name $ view lens rs
  case maybeRes of 
    (Just (Resource r _)) -> 
      case r of
        (Just res) -> pure $ Just res
        _ -> tryLoad mR info lens
    _ -> do
      putStrLn $ 
        "[Error] Could not find " ++ t ++ ": '" ++ name ++ "'."
      pure Nothing

-- Try and load an unloaded resource
tryLoad :: MVar Resources -> RInfo -> RLens a -> IO (Maybe a)
tryLoad mR info@(t, name) lens = do

  -- Declare the resource to load
  putStrLn $ "Loading " ++ t ++ ": '" ++ name ++ "'.."

  -- Retrieve resources from mvar
  rs <- takeMVar mR

  -- Get the element to load and the accessor to place it
  let res@(Resource _ l) = view lens rs ! name

  -- Use the loading function to try and load the resource
  maybeRes <- l
  case maybeRes of

    -- If a resource was loaded, update collection
    (Just r) -> do
      let newRs = over lens (insert name res { resource = maybeRes }) rs
      putMVar mR newRs
      pure maybeRes

    -- If nothing was done, do nothing
    _ -> do
      putStrLn $ "[Error] Failed to load " ++ t ++ ": '" ++ name ++ "'."
      putMVar mR rs
      pure Nothing

Resources are stored with a loading function specialised to the specific resource — when loading a texture foo.png, the filepath is curried with the texture loading function and stored so that it can be loaded and retrieved upon request:

-- Display the scene
onRender :: GameScene -> [Uniform] -> App ()
onRender gs uniforms = do

  -- Retrieve map shader
  Env { envResources = rs } <- ask
  mapShader  <- liftIO $ getShader rs "map"

  -- Render the map with global uniforms
  R.render (gameSceneMap gs) mapShader uniforms

That snippet also showcases my Uniform implementation in use. In graphics, a uniform is a parameter that can be passed onto shaders. Data that doesn’t belong to a specific vertex such as the camera’s location and direction can then be passed and used to render the scene.

-- Easy representation of uniform data
data Uniform = Uniform
  { uniformName   :: String
  , uniformData   :: UniformData
  }

-- Easy representation of uniform data
data UniformData where
  UniformData :: GL.Uniform a => a -> UniformData
  UniformDataMulti :: (GL.Uniform a, Storable a) => Vector a -> UniformData

-- Provide a list of uniforms to the supplied shader for rendering
applyUniforms :: Shader -> [Uniform] -> App ()
applyUniforms shader uniforms = do
  GL.currentProgram $= Just shader
  liftIO $ mapM_ f uniforms
  where f (Uniform name d) = do
            location <- GL.uniformLocation shader name
            case d of
              UniformData u -> GL.uniform location $= u
              UniformDataMulti v -> unsafeWith v $
                  GL.uniformv location (fromIntegral $ length v)

Uniforms attach a String to a piece of data that OpenGL can read, such as a floating point value, a vector or a matrix. The location of the uniform in shader code is found and provided with the Uniform’s value.

Inside the Map’s rendering function, you can see these Uniforms are applied to the loaded Shader resources. The map’s shader was bound in the GameScene snippet and given to this rendering function as shader — the map shader uses instanced rendering to render all those hexagonal prisms in one draw call.

-- Allow maps to be rendered
instance Renderable Map where
  render = renderMap

-- Create the relevant uniforms for a given tile
makeUniforms :: Index -> Int -> [Uniform]
makeUniforms pos height = [transform]
  where transform = Uniform "transform" 
          (UniformData $ makeTransform pos height)

-- Render every tile on the map
renderMap :: Map -> Shader -> [Uniform] -> App ()
renderMap map shader globalUniforms = do

  -- Retrieve resources
  Env { envResources = rs } <- ask

  -- Obtain the mesh from resources (or crash)
  mesh <- liftIO $ getMesh rs "hexagonal_prism"

  -- Apply global uniforms to all tiles (this also binds the shader)
  applyUniforms shader globalUniforms

  -- Bind VAO of mesh
  GL.bindVertexArrayObject $= Just (meshVAO mesh)

  -- Prepare to render the map
  let tiles = assembleTile <$> toList (mapTiles map)
      tileInfo = Uniform "tiles" (UniformDataMulti $ fromList tiles)
      offset = bufferOffset $ meshFirstIndex mesh

  -- Provide tile information to the shaders for instanced rendering
  applyUniforms shader [tileInfo]

  -- Render the map via instances of the hexagonal mesh
  liftIO $ GL.drawElementsInstanced 
      GL.Triangles (meshNumIndices mesh) GL.UnsignedInt 
      offset (fromIntegral $ length tiles)

The function GL.drawElementsInstanced is featured in this tutorial and is used to render multiple things in a single draw call. Essentially, when the map shader renders the hexagonal_prism mesh, it will do so multiple times (one time per instance). Each instance is then given an ID number, which is the only detail that differs between each tile. This ID number is used to find the details of the tile in the tiles uniform parameter, as an array of vectors of three. You can see how the details of each tile is used in the shader code below:

// map.vertex.glsl
#version 430 core
layout(location = 0) in vec3 inPosition;
uniform mat4 transform;
uniform mat4 view;
uniform mat4 projection;
uniform vec3 tiles[1000];
void main() {

  // Get the position of the vertex
  vec4 vPosition = vec4(inPosition, 1.0);

  // Calculate translation matrix for current primitive
  vec3 tile = tiles[gl_InstanceID];
  float visible = clamp(tile.z, 0, 1);
  mat4 tileM = mat4(1.0, 0.0, 0.0, 0.0,
                    visible, tile.z, 0.0, 0.0,
                    0.0, 0.0, visible, 0.0,
                    tile.x, 0.0, tile.y, 1.0);

  // Calculate final position
  gl_Position = projection * view * transform * tileM * vPosition;
}

Building

As with any other standard Haskell project, you can install Stack and build it like so:

stack build
stack run

Thanks for reading!

GitHub repository for the viewer can be found here.

What is this?

This project is an interactive simulation for visualising 4D geometry. See report.pdf for a full writeup about what this project is and how it was made. This was really interesting to make as GLSL did not support 5x5 matrices used to manipulate the 4th dimension, and so I had to essentially write matrix mathematics in the shader code in order to get this to work!

How do I use it?

Use WASD to move the camera with space and c to go upwards and downwards. Hold down the right-mouse-button and move the mouse to look around the simulation (much like an FPS game).

Pick a polytope from the menubar in the top left and then use the transformation window to manipulate it. Changing the settings of the 4D camera will also change the appearance of the object — as an exercise to the reader, I highly recommend translating the shape and then moving the 4D camera to correct it!

How does it work?

Perceiving the 4th dimension

In order to see a 4D object, a 4D object needs to be created. The tesseract is a 4D hypercube and is suitable as the main polytope for this project. For this project, I want to perform projections and other transformations using GPU shaders like you would for an ordinary game. A 4D camera can be used to view the fourth dimension from various positions and angles and is just as useful and important as a 3D camera in any 3D game. Next, a projection matrix is used to project vertices into the third dimension, where it is then perceived by a separate, 3D camera and then finally projected to 2D for rendering on screen. Getting all of these steps correct is difficult as they cannot be worked on independently and tested easily — it is the sum of these steps that achieve even the simplest result.

Identifying polytopes

For each polytope there is a set of information that describes the number of vertices, edges, faces and cells of not only the 4D shape but also each variant of the same polytope such as a line, a square and a cube — while this information is trivial, being able to compare the geometry between each shape does help create an understanding of what a higher dimension means. Furthermore, clicking the name of each shape scales the rendered polytope such that a cube would get flattened into a square, for instance. I hope that small details like this inspire interest in the user to learn more about the relationships between dimensions.

Camera movement

While moving the 3D camera acts as you’d expect, moving and turning the 4D camera can appear to twist and deform the object without necessarily moving it. While this project doesn’t include any theories about the meaning of the fourth dimension, one way to think about it is looking at the same object but from a different point in time — it would not move, but simply changing the time of observation can impact an object one is looking at.

4D transformations

In the transformation window, the user can specify different types of transformations to be applied to the object — the product of all these transformations can be seen in the matrix at the top of the window. This is the exact matrix that is sent to the GPU along with the view and projection matrices from the cameras. There are multiple tabs in the transformation window to modify each transformation separately. While they are mainly self-explanatory and just involve dragging values to increase or decrease them, there are some notable features of some transformations.

How do I compile it?

This project was created using CMake to be cross-platform.

Visual Studio:

Using Visual Studio, right click inside the folder and select open cmake project in Visual Studio (or something like that). For more information, check this.

Command line:

You need to create a build directory and then generate some makefiles before you can begin compilation. The full process looks like this:

mkdir build && cd build
cmake ..
make
./App

GitHub repository for Hogs of War: Level Editor can be found here.

What is this?

In my final year of university, we had an assignment to make either a game or a tool, and so I took tried something new and made a cross-platform tool that allows for the visualisation and manipulation of Hogs of War map files. This was around the same time I was working on the 4D Geometry Viewer and so I re-used parts of the code base to speed up the process so I could focus on the meat of both projects.

At the time, the my computer science course was blessed by one of the programmers for Hogs of War. I was lucky enough to get to know him, learn from him, and have him as my supervisor for my thesis and I am very grateful for the time I spent in his sessions. When this assignment was revealed, there was discussion that there could be an opportunity to work with the source code for Hogs of War and maybe make some kind of tool, and so I decided to take on that challenge.

The other students worked on games in groups, but I was on my own for this assignment, and so to keep things fair it was decided that I’d be assessed slightly differently to factor in the need to fully communicate and plan the project to others. One of the just-graduated masters students was considered my ‘client’ for the assignment as he had also done work with the Hogs of War source code and was doing further work with it. My objective was to listen to the kinds of things he’d find useful, translate his requirements into milestones and then use HacknPlan to manage the project so that he could see my progress.

I successfully completed the assignment and felt quite proud at what I had made. It took the form of a level editor; one capable of sculpting and painting the various landscapes found within the old game files of Hogs of War. In the next section you will find a few videos previewing some of the features of what I had produced over the course of the assignment.

Features

Sculpting

The first task of the assignment was simply to load one of the map files of Hogs of War. The source code was, of course, proprietary, so I won’t go into the details of the difficulty I encountered trying to read the decade-old source code. My solution was to load the vertices into my own representation of a map to make it easier to edit, that way the only time I had to touch the old source code was when I needed to load or save a map to a file. In order to see whether I loaded a file correctly, I also needed to render it. Once I had a basic heightmap visualised on screen, everything started falling into place.

The first feature I wanted to implement was simply manipulating vertices with a normal ‘sculpting’ tool — you click and the ground bubbles upwards (or downwards, depending on the settings). Since the tool operates on vertices of the heightmap, I made the decision to draw ‘sticks’ to represent each individual vertex so that it was clear as to why the ‘circle’ shape didn’t raise a perfect circle of terrain. You can see these in the video below:

To make sure that these changes were correctly applied to the map file, I had to demonstrate that I could open a map, edit it, save it and then re-open it to see the changes perfectly recreated.

Editing

The second big feature I implemented was something I noticed from the sculpting feature — the ability to be more specific about which vertices to raise / lower. This was the ‘selection’ tool. This became the best way to edit maps, since you could select vertices without mutating the map and then edit them in bulk. The video below illustrates this better than I can explain it:

The ability to undo and redo was also added around this time, since I was able to be encapsulate an ‘edit’, and so the undo-chain was as simple as applying the same transformation in reverse. This was a little bit trickier with the sculpting tool since that was one long continuous mutation, but all I needed to do was record the net change in height for each vertex.

Data visualisation

One of the later changes I made was the ability to change the appearance of the terrain by literally ‘painting’ textures onto it. To do this, I wanted to experiment with a splatmap system where each colour represented a different texture, these pairings could be configured with a drag-and-drop system. Once I could see and use the splatmap system, texture painting would be a case of adjusting the colours of these splatmaps.

Texture painting

Texture painting was the one feature I wasn’t totally happy with — while it worked, the way it interacted with the undo functionality made it inefficient. This tool didn’t operate on vertices and instead operated on the splatmap textures themselves, meaning that potentially thousands of pixels could be adjusted each second of the paint tool being activated. Trying to record the net change of state for each pixel obviously made this a very intensive process, which is quite funny since the process of actually changing the texture and re-uploading it to the GPU was quite lightweight by comparison.

One of the potential optimisations I wanted to implement was to record the position and details of the brush each frame rather than the affected pixels — while this would be inefficient for vertex manipulation (as there’s a lot less affected vertices than the number of potential frames), it’d be much more efficient for pixel painting. Unfortunately, the deadline of the assignment was coming up and I decided to invest my time into other assignments as at this point I was fairly happy with the progress I had made.

Conclusion

The assignment went really well and I had an absolute blast playing software-dev for the first time! It was an interesting experience applying the skills I had learned from games in a different way. It also opened my eyes to how enjoyable I’d find working on tooling in a job scenario, such as possibly making an in-house plugin for the Unreal Engine or something!

Thanks for reading!

“The path to the right decision: An investigation into using heuristic pathfinding algorithms for decision making in game AI”

This was the title and topic of my well-received final year project for my final year of my masters degree. This investigation involved repurposing a generic implementation of the A* algorithm for decision making as opposed to terrain traversal. In this post, I will summarise what I wrote.

Background

Search algorithms

A search algorithm is a recursive method designed to find a match for a piece of data within a collection such as an array, graph or tree. A piece of data is provided and the search algorithm typically returns whether it is present and it’s location. Dijkstra’s algorithm is a search algorithm that operates on trees and graphs (which are then interpreted as trees). The algorithm calculates the shortest difference from any node on the graph to any other node, and can be terminated early to avoid unnecessary computation if a destination is provided and found.

A* is an improvement of Dijkstra’s algorithm — while it doesn’t stray far from how Dijkstra’s algorithm works it does extend the algorithm using what’s known as a heuristic approach. In a pathfinding situation, a heuristic function could estimate the distance to the goal, by ignoring walls and measuring in a straight line, to direct the algorithm in the right direction and avoid evaluating routes that travel in the wrong direction to make the process more efficient.

This heuristic component of A* transforms it into a family of algorithms where applying a different heuristic selects a different algorithm.

This heuristic component of A* transforms it into a family of algorithms where applying a different heuristic selects a different algorithm, moreover, implementing A* and using a heuristic that returns a constant value for all nodes reverts A* back into Dijkstra’s algorithm. Conversely, implementing a well-designed heuristic method can be used to guarantee optimal solutions, and using a heuristic that is somewhere in-between can output results with varying degrees of accuracy in exchange for faster execution.

The implementation of a good heuristic can be difficult, as making the heuristic take more factors into account for accuracy has the drawback of making the algorithm less efficient overall with the heuristic being frequently used throughout the process.

Traversing decisions

In this project, the AI will be pathfinding through decisions and not locations. While the AI will still be moving through the map, it is doing so because it is deciding to, and not simply calculating a path. Much like a decision tree for game AI, each node in the traversal graph will represent an action for the AI to take and the AI will be generating a plan-of-action by connecting these nodes.

When the game world has been processed, the actions a character can perform have been laid out and the methods of evaluating courses of action have been provided, the only things remaining that A* needs to function are the start and goal node states for the actual decision. The starting state is trivial as it is simply the current state of the character and world; the goal state node requires more consideration than that though. For game AI though, the goal needs to represent how the character or world should be — or rather, the objective outcome of the decision making process.

This objective can be difficult to ascertain as a goal node could represent anything; what seems to be a simple goal such `win the game’ becomes a rigorous series of tests to both calculate the cost reaching the goal than another. On the other hand, objectives that are too small or disconnected may not combine correctly to form this over-arching goal of winning the game. A balance is needed, whether that means the objective is to chase the player or defend an area, the objective needs to be focused on winning without being vague.

Another talking point regarding goals is the amount of designated goal state nodes in the graph. There is typically only a single goal in standard pathfinding, but it is possible, maybe even advantageous, for some games to contain multiple goal nodes in a graph. Having multiple goals and goal types would grant the ability for the AI to re-route to a different goal if it’s easier and therefore accomplish the same task in multiple different ways without creating generic goals; this has its drawbacks though, one being the need for a more intricate and potentially confusing implementation and design of the AI needs, the other being the creation of balancing difficulties to ensure goals are prioritised as expected.

Defining the notion of cost

Cost, sometimes referred to as weight, is a term that will continue to be used when talking about A* as it is the the metric that governs the searching process. Cost doesn’t have to be a numeric value, as long as it can be compared and combined correctly with other cost values. However, one numeric restriction of cost is that it cannot, or rather should not, be negative.

The method A* uses to determine if a route should be expanded before another is if its cost value is lower — when only positive values are added together it is assumed that costs cannot decrease in value. While in mathematics it is entirely possible and valid for these values to be negative, the problems that make this necessary are not applicable to games.

Some decisions are more troublesome to weigh than others; with the constraint of non-negativity, what would the cost be of an ability that regenerates mana instead of expending it? The only way to apply reductions to values in this way would be to have a baseline cost for an action and then add or subtract from it, however, this does mean that this baseline value would dictate the maximum value of the reduction and so forward planning is necessary to ensure that all reductions can be applied in a balanced way.

Another difficult type of decision to way are ones that don’t have inherent characteristics; with a good goal for AI being unpredictable, surprising behaviour, how would the incentive for performing strategies like flanking and ambushing be created, and how would it compare to the cost for attacking an enemy directly head-on?

In this project, penalties were used to represent the cost of performing an action. Shooting an ally or walking into the range of an enemy unit resulted in penalties that could be tweaked per AI. It was hoped that these penalties would give the AI a sense of direction and that it would try to minimise incurring these penalties while making decisions.

Comparisons with GOAP

During this project, I researched a very similar game AI implementation named Goal Oriented Action Planning (GOAP) by Jeff Orkin. The premise is the same; instead of navigating geometry, A* is used to navigate an abstract space where the nodes in the graph represent decisions. The main difference between GOAP and this project is that GOAP summarises an action into a single node — there is a layer of the AI that decides what actions would be relevant and / or how these actions are carried out, so going to cover or a point of interest is more focused. In my implementation, every possible target and tile to move to is a possible node, substantially increasing the size of the graph and relying on A*’s evaluation to choose the best nodes in the process.

The project

Search algorithms such as A* are generic, maintainable and versatile and are therefore theoretically suitable replacements for FSMs and behaviour trees for implementing game AI. While GOAP does use A* for part of it’s decision making process, it isn’t a complete solution and still separates decision making from the pathfinding process. This is acceptable and valid as GOAP is for generating a sequence of actions whereas pathfinding is strictly for navigating the map in order to perform these actions. Unfortunately, some information found during pathfinding that could be considered useful for decision making is lost unless explicitly communicated — a decision might request to navigate to some location, but the path generated might be longer than expected and a different course of action could have been more appropriate. Without replanning, GOAP’s disconnect between these systems could result in the wrong decisions being made.

In this project, the mechanisms of the A* search algorithm were examined and re-engineered, through the substitution of input and output types, to investigate the modularity and adaptability of an AI that uses search algorithms to make decisions while actively involving pathfinding in the process as opposed to keeping these systems separate.

Several approaches to defining goals and heuristic methods were used to visualise the effects they have on a squad-controlling game AI. The aim of using this approach is to bring decision-making and pathfinding closer together and therefore simplifying the overarching process of perceiving, deciding and interacting in the game world.

The strategy game

In order to test and observe this experimental AI, I decided to build a simple, turn-based strategy game for the AI to play. The rules of this game are simple: each player controls a squad of units with the aim being to eliminate all enemy units while maintaining at least one surviving unit. During their turn, a player can select one of their units and then move and attack with it.

A player has a set amount of MP and AP (movement and action points) per turn, and can distribute them between each of their units. Each unit drains a different amount of MP per tile when moving and a different amount of AP when attacking as shown in the table below, meaning that some can move further and some can eliminate more units during a single turn. A unit can only attack another unit when it has enough AP and the target is in sight and range where nothing can be in between the attacker and their target.

Resource management and positioning are the two key elements that make this game strategic. A player will have to distribute MP between their units to keep them out of the enemy’s range and line of sight while also positioning their units to attack the enemy safely. This won’t always be possible; the constraints of the MP and AP mechanics mean that sacrifices have to be made each turn in order to win.

Results summary

The investigation reached its conclusion. While it would be possible to create any number of AIs, it is believed that the research questions posed can be answered from the pool of AIs that have been created. Further AIs would have been created if the results had been more positive, but at this stage the creation of further AIs would simply provide more examples of problems already identified and not yield anything of benefit.

The prototype AIS used in this project are not the only examples of using A* for decision making — GOAP was actually used for the AI in the game F.E.A.R. There are significant differences between the approaches used in this investigation and GOAP; they are only related in the sense that they both use the A* algorithm, but there are clear distinctions between the implementations, usages and behaviours of their resulting AIs.

How plausible is it to use A* in a decision making process for game AI?

The existence of GOAP already demonstrates that A* can be used for AI purposes. However, the case studies suggest that A* is rather unsuitable for AI. One case study illustrated the most common flaw of reimplementing a search algorithm for AI: the AI has a tendency to do nothing unless it is told that doing nothing is wrong. This is problematic, as it should be valid for an AI to do nothing in the correct situation. This problem appeared in the creation of all case studies and the requirement for overcoming it introduces awkward and arbitrary elements to the AI. Telling the AI what not to do, as opposed to what it should do, makes both creating and changing behaviour difficult.

Another flaw in creating AI in this way is that it is hard to be certain about how the AI’s programming will affect behaviour. Every subsequent case study used different weighing functions, each having valid and constructive reasoning. However, in spite of the effort placed into designing these functions it can be concluded that the behaviour of each AI varies drastically and cannot be predicted from the programming alone. This aspect is unlikely to appeal to game developers, as there’s no way of knowing how the AI will behave or whether it is going to break in a given situation. With these things considered, the approaches created in this investigation have not produced any results showing signs of suitability and GOAP continues to be the most successful approach for applying A* to game AI.

How does the inclusion of pathfinding affect decision making?

GOAP’s Actions are used differently when compared to the Actions in this game: GOAP’s Actions are simple and only one instance is created for each type of Action whereas in this investigation an Action instance was created for every opportunity so that they could integrate with the pathfinding process instead of replacing it. Where GOAP’s AI would perform a single Move Action, the AIs observed in this study would have to perform a Move Action for moving to each tile when pathfinding. For GOAP, the choice to attack comes purely from the Attack Action, whereas in this study the AIs evaluated each possible Attack from each possible location. GOAP’s locations and targets are chosen based on the goals provided which reduces the number of Actions and States. In this study, the selections were made within the decision making process which had the opposite affect and inflated these numbers, having consequences in the performance and behaviour of A*.

Case three displayed promise for eliminating enemy teams intelligently. The AI had great gameplay strength and achieved a high aptitude for finding the best outcome of a situation. Feeding all possible situations to A* allows it to find the best sequence of Actions; when a heuristic is provided such as in case four, the algorithm has the ability to terminate early with an acceptable solution that isn’t necessarily the best. Cases three and four demonstrate that A* can make decisions such as where to move and who to attack when given a large number of options, but they also reveal the resulting impact on performance that makes these AIs unsuitable for more realistic applications.

In normal pathfinding on a grid, an agent using A* can move in four directions and the number of routes becomes manageable, but the AIs in this investigation can also attack, select a new unit and end their turn. This means that instead of 4 edges per node A* has to process roughly 10–20, greatly increasing the total number of nodes and the time to process a suitable sequence of Actions. Replacing the game with one that features less interactions would benefit the AI, but the game used in this experiment could already be considered a simplification when compared to commercial games and simplifying things further would not provide any insights applicable to most use cases.

How does changing the components used in A*s fundamental formula affect the output of the algorithm?

Case three relied entirely on the accumulation of Costs and used brute-force to repeatedly expand the cheapest nodes until the algorithm terminated, showing that a heuristic function wasn’t necessary for creating an AI as long as there was enough information reflected by the Cost. The introduction of a heuristic component with case four allowed for greater control over what the AI does but not necessarily how it does it — the heuristic function influenced the AI to eliminate an enemy unit or move closer if that wasn’t possible, making A* expand nodes more likely to satisfy this goal.

As soon as the goal was satisfied, the algorithm terminated meaning that case four would be suitable if there was another system to give it clear, achievable and specific goals to satisfy. Without goals, case four’s behaviour varied from doing nothing like in case one, to playing the game without any particular strengths or weaknesses.

How easy is it to externally influence the AI’s decisions or introduce difficulty?

This question is subjective and context dependent, as the complexity of influencing the AI is dependent on the fidelity of the task required of it and the notion of difficulty is dependent on the mechanics the AI can use to beat the player. For this investigation, the answer to the first part of this question can’t be answered with certainty. While case four managed to satisfy goals with relative ease, the designation of such goals is challenging in its own way. There had to be a guaranteed way of completing the goal in order for the algorithm to terminate successfully, creating the requirement of a valid goal.

Changing the difficulty of the AI was attempted in case study four when playing against case study three. Case study three won in the majority of situations, only losing when playing second in a long-range game against case four. The values for the penalties used in case four were changed, but no combination strengthened behaviour. If there was such a combination that achieved a higher level of strength, the process of finding it would be cumbersome, further reinforcing the lack of plausibility of this approach to game AI.

It could be speculated that the easiest way of introducing difficulty to the AI would be to select more effective goals; changing what the AI considers a goal is a somewhat simple way of changing how the AI plays, and case four already demonstrated how a weak goal resulted in weak behaviour. Alternatively, the implementation of the heuristic and weighing functions could be written with more complexity like the one in case three, although this would mean that each desired difficulty of AI would require alternative functions that then need to be tested independently for bugs.

Conclusions

Considering that the aim of using A* is to make the process of creating game AI flexible and modular, the methods used as a part of this research were unsuccessful in achieving the simplicity necessary to warrant their usage.

It was hypothesised that the combination of decision making and pathfinding would improve the communication of various systems and the output of the perception, decision and interaction processes. This hypothesis was proven false from the difficulties experienced in creating and observing these case studies as evidence, and therefore this project has failed to produce a suitable method of creating game AI using A*.

However, the project as a whole wasn’t a total failure. This research was performed because of the lack of knowledge in this area; GOAP is the only successful approach to have used A* for implementing decision making in game AI, and so this project investigated whether there were potential improvements to be made.

While no improvements were made, but it is hoped that this project leads to a greater understanding of the ways an AI can take advantage of the A* algorithm, or more specifically, how it cannot. Whilte the flaws found during the paper bring attention to some of the reasons not to use A* for AI, GOAP is still applicable to many scenarios and in some cases even preferable.

Thanks for reading!

GitHub repository for Street Fighter Clone can be found here.

What is this?

This project was made as part of a university assignment in November, 2019. Since GMS is proprietary software, I’ve taken the liberty of compiling the project into a .exe file that you can find here. The point of this project was to try and mimic StreetFighter as closely as possible and understand not only what mechanics were programmed but also why.

This assignment was set up as a competition; we all went around the room and played everyone’s games (where everyone had chosen a different character to start with) to see which was the most fun and complete. Additionally, we were given the opportunity to guess whose was the best, and if we got it right, we got an extra mark. The person with the most votes also got extra credit.

I was confident with my project, and because I didn’t really feel like anyone could beat it, I didn’t really want to outright say that someone else’s assignment was better than my own (we were allowed to vote for ourselves and a lot of people did) since I wasn’t really very enthusiastic about students’ marks being dictated by the success of others’. I didn’t put anyone’s name down, and I actually managed to win the competition by a large margin. Lesson learned — if you’re confident in your work, don’t be ashamed!

How do I play?

Simply download and extract the latest release and run the executable (StreetFighter.exe). You will be presented with this screen:

I made this game controller-only because we were all using controllers anyway and there were no extra marks for fully implementing KBM. To get around the issue of ‘who plays who’, I made it so that at the start of the round, both players need to press ‘Start’ on their gamepads. The characters are then assigned on a first-come, first-served basis.

Credits

Obviously, the artwork used in this game isn’t mine. It’s taken from various spritesheets I’ve found on the internet.

GitHub repository for Space can be found here.

What is Space?

Space is an open-source forum that I was making in order to learn Clojure. I’ve never done any sort of web development other than this Blog with Hakyll and some basic assignments for university. I had heard a lot about RESTful APIs but I had no idea what they really were, so I wanted to try making one for myself.

The idea of Space came from my experiences with learning and asking questions. Sometimes, you just need to ask for help — maybe you don’t know enough about the subject to ask the right questions, or maybe the bug you’re experiencing isn’t the code but your approach, something which is harder to learn in tutorials that show solutions rather than workflow.

When newcomers go to Stack Overflow, their first impressions can be hit or miss. If they fail to supply a project that allows for the reproduction of their error, they may get shot down before anyone offers to help. This is very important, as Stack Overflow is more of a resource than a support community, and so must maintain high-quality questions and answers to hopefully answer the further questions on the same topic in the future.

However, not all questions are about correctness — when learning, a lot of questions are merely probes for learning something new. If you’re with a teacher, asking good questions is a great way to learn, but the requirement of preparing code snippets makes this rather difficult.

I intended Space to be a compliment of Stack Overflow. I want it to be a forum that a community could set up and open up to newcomers, and to encourage people to offer their advice and ideas whenever possible through gamification. With Space being open source, a community would host their own Space and have true ownership of their content. While Reddit is a great place, it did kill off most forums by having everything in one place. Because of this, a lot of communities suffer from having to do things the Reddit way, as well as their identities being shared between each community they’re a part of.

Gamification for Space

I have this idea of tags being like skill levels that you can work on while using Space. They are both the ranking system of posts as they act like a bounty value, and the incentive for people to respond to posts made by other users. It’s a cycle.

The goal of a tag is to act as a level. When you make a post, you associate tags with it that will act as categories. The post will have levels associated with its tags that come from your own levels — meaning that in a programming Space, a user’s Clojure level will dictate the Clojure level of their post, assuming they tagged it correctly.

Posts accumilate experience points through a variety of factors, but ultimately the longer the post stays up and the attention it receives increases its levels further. The higher level the post, the more experience points users will receive from participating and responding to said post. Thus, you earn points by solving people’s problems or discussing their topics, and when you decide to post, your post will be considered more worthwhile for other users.

This doesn’t mean that newcomers posts get placed at the back of the queue — instead, it means that their posts become easy targets for experience points as if their posts go unnoticed for too long, the experience rewards will increase and thus it becomes more eye-catching for people to look at. It also would mean that users will have a higher reward for participating in low-difficulty threads.

Tags could eventually evolve elsewhere too. They could be used as currency, used in forum games or give-aways or used as roles to organise site users further.