Andrey Listopadov

Slopes in AABB collision systems

Fri, 09 Jan 2026 04:11:00 +0300

Recently (again, bored on a vacation), I started working on a game I’ve planned for a long time. I wasn’t satisfied with my existing implementations of a player controller¹, so I started working on a new one. After a bit of fiddling around, I came to something I’m satisfied with, for now, at least, but while working on it, I wanted to add something I haven’t done in any of my projects yet - I decided to add slopes to my game.

I’m no game developer, to be honest, it’s not even my hobby, although I enjoy the process to some extent. Game development offers immediate visual and interactive feedback, unlike many other areas in programming, and I like that. So, while working on this player controller and figuring out how to implement slopes, I’ve searched the web to see if someone already did something similar in a system I’m working with, but I didn’t manage to find anything. Maybe I simply wasn’t specific enough in my search requests, or didn’t search deep enough, and there’s actually a guide on how to do that somewhere on the web, I decided to write this post anyway.

AABB collisions

First, let’s discuss what AABB actually means.

For those unfamiliar with collision detection, there are many ways of checking if two objects collide. A lot of them, actually, each with its pros and cons. Some give very accurate collisions for objects of any shape, but are not real-time viable, others are real-time, but far less accurate. It’s an ongoing research, and new ways of detecting complex collisions as fast as possible appear every now and then.

I’m mainly developing games in either TIC-80 or LÖVE2D. LÖVE2D actually comes with a collision detection library, called Box2D. My games are sprite-based, and since I often use TIC-80, I can’t really commit to Box2D, so instead I opt for a simpler collision detection logic.

That’s where AABB comes - it’s an Axis-Sligned Bounding Box collision detection system:

Figure 1: Axis-aligned rectangles are quite easy to check for intersections, since all we need to know is their origin and dimensions.

The general idea is that if the bounding box of object A is completely to the left or to the right of object B, the objects don’t collide. Similarly, if the object A is above or below object B, there’s no collision either. And when all four of these situations are not true, then there’s a collision.

It’s a rather simple solution, but it can yield satisfying results. Implementing this by hand is trivial, but there’s a lot more to checking collisions - we need to make it quite optimized, and handle object interactions.

Thankfully, there’s an amazing pure Lua library called bump.lua, that implements these AABB checks and more. And it’s near perfect for sprite-based games, since everything is aligned to the grid, so that’s what I’m using in TIC-80 and Love2D. Perfect, until we want something other than a rectangle. For example, slopes.

Implementing slopes with `bump.lua`

To be honest, there’s not that much to it for implementing slopes in an AABB collision system. Actually, I could just give you the formula and be done with it. Even more, actually - I’m sure you can figure it out if you think about it for just a bit. But that’s not fun! So instead, I’ll walk you through from the beginning - creating a TIC project, adding bump.lua, loading entities to the world, adding collisions, simple physics, and finally, slopes.

But, if you want, you can skip directly to the slope implementation section, no worries!

TIC-80

TIC-80 is a small game engine that supports Lua as one of its main languages to develop games, along with other ones, like Fennel. I primarily do my projects in Fennel, as I like it a little bit more than Lua², but for this post, I chose Lua, as I want this to be a more general tutorial, applicable to a wider audience.

Even though TIC-80 is a fantasy computer, I believe it is capable of being an engine that you can use to make full-fledged games with. Two years ago, Balatro again proved that Love2D is fully suited for making massively successful games, without the need for something more, like Godot or Unity. I think TIC-80 can shine similarly, but it seems that far fewer people consider it as a viable alternative, even fewer than with Love2D.

The other thing I often think about is that games don’t have to be implemented with the best technology to be good games. I’ve played a few games on Game Boy Color and especially Game Boy Advance, and they were amazing even today. And these consoles were quite limited even for the time. Yet, people are still making games for them.

And that’s another reason why I want to write this post more as a tutorial on TIC-80, as it can maybe make you want to try it!

So let’s start by firing up TIC-80:

By default, TIC-80 starts you in a console-like environment. It’s a fantasy computer, after all.

By pressing Esc, you can go into the code editor:

You can also switch to a built-in sprite editor by pressing F2 or clicking on a ghost icon in the top bar:

There’s also a map editor, which we’ll look into a bit later, you can create sound effects with a built-in synthesizer and write music in the tracker! It’s a fully self-contained system that you can develop your games in, and not just games - people write music in it, create beautiful entries for Demo Scene contests, and more.

I won’t be using the inbuilt code editor, though, as I’m much more comfortable writing in Emacs, and you can use any external editor with TIC, but we’ll be using the sprite and map editors. So, let’s start!

Creating a project and adding `bump.lua`

Actually, if you did start the TIC-80 with me, you don’t have to create anything - by default, TIC creates a sample cart that you can edit right away. That’s what we’ll do. First, let’s edit the metadata at the top of the cart:

-- title:   AABB Slopes
-- author:  Andrey Listopadov
-- desc:    Making slopes wiht AABB collisions
-- site:    https://andreyor.st
-- license: MIT License
-- version: 0.1
-- script:  lua

We could also delete default sprites right now, but we’ll do it later. Right now, we need to add bump.lua to the cart.

TIC-80 doesn’t really provide access to your filesystem - it is expected for the cart to contain everything, much like game cartridges did in the early days of home consoles. Because of that, it’s not possible to install bump.lua via LuaRocks, or download it and place the file near your cart. We’ll have to embed it directly.

Luckily for us, it’s really easy to do so in Lua! All we need is to set package.preload.bump to a function that contains all of the library code. And even greater, that bump.lua is a simple, single-file, self-contained Lua library.

So we can do it like so:

package.preload.bump = function()
    -- Copy the bump.lua file contens here.
    -- Yes, as is.
end

Now, we can use require to bring this library to our game, and create the world:

local bump = require "bump"

local world = bump.newWorld(24)

Great! Now let’s draw some sprites we’ll use!

Creating sprites and using the map editor

There’s nothing much to talk about here, as TIC features a rather simplistic sprite editor:

However, we’ll be using some of its advanced features, which can be revealed by pressing this switch in the top left corner of the editor:

Figure 2: Advanced mode switch (red arrow), flags (green arrow)

One of such features is the flags we can set on a sprite. These flags act as a bit mask, so you can set up to 256 combinations of flags, which is enough, since TIC has space for exactly 256 sprites. Did I mention how cool the design of TIC is yet?

I’ve set bit 1 here to indicate that this sprite is a ball, and I set bit 0 for all of the solid objects drawn near it. This way, when we load these sprites to the game world, we’ve created with bump.lua, we will be able determine what this object should be.

Now, let’s use these sprites in the map editor:

In the map editor, you can choose from either 256 tiles or 256 sprites to draw your map with. TIC actually has two sprite-sets: tiles and sprites. The only distinction between them is that you’re limited to either of those sets when you design your map. Other than that, they’re the same.

I’ve created a small test scene, with our ball and some walls:

Now we can start implementing our game logic, as right now if we run this cart, nothing would happen yet.

Loading entities to the world

We’ll start by editing the TIC function in our standard cart:

function TIC()
    cls(0)
    map(0, 0, 31, 18, 0, 0, 0, 1)
end

Now, if we run our cart, we’ll see the same thing we’ve seen in the map editor:

However, nothing moves yet, as we haven’t implemented any of the game’s logic. Before we can do that, we’ll need to populate our world with rectangles, so let’s do that.

local function load_map()
    for x=0, 240 * 8, 8 do
        for y=0, 136 * 8, 8 do
            local obj = is_obj(x, y)
            if obj then
                world:add(obj, obj.x, obj.y, obj.w, obj.h)
end end end end

Here, I’m loading the entire map to the world. It’s not necessary to do that, since we’re only going to use one map screen, but it doesn’t hurt. The key function here is the is_obj predicate, which we’re going to write next:

local balls = {}

local function is_obj(x, y)
    local id = id_at(x, y)
    if is_solid(id) then
        return {x = x, y = y, h = 8, w = 8}
    elseif is_ball(id) then
        local ball = {
            x = x,
            y = y,
            h = 8,
            w = 8,
            xvel = 0,
            yvel = 0,
            is_ball = true
        }
        balls[ball] = true
        return ball
end end

First things first, we need to get the ID of the tile at coordinates x and y. We do so by using TIC’s built-in function mget:

local function id_at(x, y)
    return mget(x // 8, y // 8)
end

Next, we’ll define a set of predicates that, given an id will tell if the object we’re inspecting is a wall, or a ball:

local function is_solid(id)
    return fget(id, 0)
end

local function is_ball(id)
    return fget(id, 1)
end

So the is_obj function we’ve defined above gets the tile id, and checks if it is a ball, or a wall tile. If so, it creates an object that we can add to the bump.lua world. Each object has a set amount of required properties, but you can also have additional ones, like the is_ball field, in the case of the ball object. We also add a ball to the list of balls, in case we might want to add more than one ball later.

Now, we can load the map. We do so in the BOOT function, which executes when the cart is being loaded. You can also write the call at the top level if you want, and it may make the code a little bit more portable, as older versions of TIC didn’t have BOOT, but I’m not targeting those, so:

function BOOT()
    load_map()
end

With that in place, we can implement some simple physics for the ball.

Working with `bump.lua`

Since we’ve loaded everything into the world we’ve created with bump.lua, we can now manipulate things in it. We’ll be mainly manipulating balls, so let’s add some methods to the balls table:

setmetatable(
    balls,
    {
        __index = {
            update = function(self)
                for ball in pairs(self) do
                    ball.yvel = lerp(ball.yvel, 5, 0.1)
                    ball.xvel = lerp(ball.xvel, 0, 0.1)
                    ball.x, ball.y, cols, len = world:move(ball, ball.x + ball.xvel, ball.y + ball.yvel)
                    for i = 1, len do
                        local col = cols[i]
                        if col.normal.y == -1 then
                            ball.yvel = -(ball.yvel * 0.9)
                        end
                        if col.normal.x ~= 0 then
                            ball.xvel = -(ball.xvel * 0.9)
            end end end end,
            draw = function(self)
                for ball in pairs(self) do
                    spr(1, ball.x, ball.y, 0)
            end end
        }
    }
)

I’ve added two methods: draw and update. It’s not necessary to separate these, you could do everything in one call, but it’s a bit easier to reason about them this way. Yeah, I know, looping over all of the balls two times just to update each, and then draw each is bad design, since we could do it in one loop, but that’s not the main focus here. But it’s great that you’ve pointed this out! Ten points to the TIC house!

Anyway, we’re looping over all of the balls in the table, which we don’t have that many yet, only one, and updating each one. The important part here is that we compute the ball’s X and Y velocity, and then use them to move the ball in the world, by calling world:move(). I’m using linear interpolation, defined as follows:

local function lerp(a, b, t)
    return ((1 - t) * a) + (t * b)
end

We don’t care that much about delta-time here, as TIC runs at a consistent 60 frames per second even when you push it to the limits. You can, of course, slow it down with bad code, and we already have two loops instead of one, which is concerning, but we’ll be fine, don’t worry. Lua is quite fast.

ball.x, ball.y, cols, len = world:move(ball, ball.x + ball.xvel, ball.y + ball.yvel)

So by calling world:move() with the ball object, we receive new X and Y positions of that ball after it was moved with respect to collisions. We’re not going to build a sophisticated physics engine here, but we will need to handle some collisions. bump.lua actually has different collision types, like bounce, that we could use here, but for our purposes the default slide is better.

In addition to the new X and Y positions, this function returns a list of collisions that happened during the move. We can loop over those and update our ball’s properties, such as its velocity. We do so in the following loop³:

for i = 1, len do
    local col = cols[i]
    if col.normal.y == -1 then
        ball.yvel = -(ball.yvel * 0.9)
    end
    if col.normal.x ~= 0 then
        ball.xvel = -(ball.xvel * 0.9)
end end

We’re slowly decreasing the ball’s velocity, also switching directions on contact. That’s pretty much what the bounce collision would do for us.

For the draw method, we simply draw the ball sprite using another TIC’s builtin function spr.

Having these implemented, we can add them to the TIC function, like so:

function TIC()
    cls(0)
    map(0, 0, 31, 18, 0, 0, 0, 1)
    balls:update()
    balls:draw()
end

Now, if we run our game, we’ll see our ball bouncing:

Your browser does not support the tag

Uh oh, why are there two balls, and one floating over the ground? Did we forget to add it to the balls table, so it gets updated? If we did, why is it even drawn - we loop over balls in both functions.

If you look closer, you’ll see the problem. We’ve loaded the map to the world, and we’re drawing the ball using the spr function. But we’re still drawing the original map in the TIC function by calling map! And our map still has the ball.

We can go two ways here. One would be to use the mset function and replace the ball tile with nothing in our map when we’re loading it. Or, we can hide the ball at runtime using map function’s special remapping feature. Let’s do that instead, as it is a bit cleaner:

local function remap(id)
    if is_ball(id) then
        return 0
    end
    return id
end

Now, we update our TIC function to use this remap function in our map call:

function TIC()
    cls(0)
    map(0, 0, 31, 18, 0, 0, 0, 1, remap)
    balls:update()
    balls:draw()
end

And, presto!

Your browser does not support the tag

Handling mouse events

Our introduction to TIC isn’t over yet, because I always wanted to try using the mouse integration. Our ball is currently pretty stiff, so we’ll tweak its physics along the way. Having mouse support will make it easier to test things out, as doing so by updating the code is a bit cumbersome. And I don’t know how to make sensible controls for a ball with arrow keys - it’s just a bouncing ball, what do you expect it to do, roll by itself when you press a magic key?? Let’s drag the balls instead.

We’ll start by creating a small storage variable that we’ll assign to the currently grabbed ball:

local grabbed = nil

It’s uninitialized by default, we’ll set it later in the update method:

local mx, my, is_pressed = mouse()
if is_pressed and not grabbed then
    local items = world:queryPoint(mx, my, function(obj) return obj.is_ball end)
    if next(items) then
        grabbed = items[1]
    end
elseif not is_pressed then
    if grabbed then
        grabbed.xvel = (grabbed.x - grabbed.prev_x)
        grabbed.yvel = (grabbed.y - grabbed.prev_y)
        grabbed.prev_x, grabbed.prev_y = nil, nil
    end
    grabbed = nil
end

We add this before the main loop over all balls in the update function.

The mouse function in TIC returns a set of values, X and Y coordinates, and states of each mouse button. We’re only interested in the left mouse button, so that’s what we store.

Then, if the button is pressed, we use a method from the Intermediate API section of bump.lua. It returns a list of items, and since we don’t have anything that overlaps, we can safely take the first item in the list. We’re also using a similar feature to the map function’s remap here - we’re providing a filtering function that will make sure that we can only grab ball objects, not other tiles.

When the button is released, its state will change, and we need to release the ball. If there was a ball grabbed, we set its velocity to conserve the momentum from moving it by the mouse, which we’ll handle later. Then we unset the grabbed storage variable.

Next, in the for loop responsible for updating the balls, we check if the current ball is the one we’ve grabbed, and we override its movement:

for ball in pairs(self) do
    if ball == grabbed then
        local x, y = lerp(grabbed.x, mx-4, 0.3), lerp(grabbed.y, my-4, 0.3)
        grabbed.prev_x, grabbed.prev_y = grabbed.x, grabbed.y
        ball.x, ball.y = world:move(ball, x, y)
    else
        -- no changes to the old logic
end end

So, as you can see, we’re moving the ball to the mouse pointer coordinates, still with respect to collisions. We also store additional information in the grabbed object, mainly the previous X and Y positions that we use in that momentum conservation code a bit earlier. And with that, we can drag the ball around:

Your browser does not support the tag

This is as basic as it gets - you’ll notice that if we add more balls, we can’t move other balls with the one we’re dragging. You can, of course, make a more sophisticated physics simulation - handle collisions better, so it would move other balls as well, transfer the momentum to other objects, make balls roll off each other, as right now they’re basically squares, and so on.

So you can do something like that if you try experimenting with collision resolution a bit more:

Your browser does not support the tag

Now, we’re pretty much set for working towards the main topic of this post - slopes.

Implementing slopes with AABB collisions

Phew, FINALLY, all that just to tell you that to handle slopes you just need to do…

Figure 3: …is this.

OK, this is anticlimactic, so let’s implement this. But first, what is a slope in our case?

Because we can only have axis-aligned rectangles, we need to create a special kind of object in our world that will still be a rectangle, but handle collisions differently. Since our game is tile-based, we don’t have a lot of meaningful angles to support. The most common slope in games is a segment with dimensions of 16x8. It spans exactly two tiles and takes you one tile height up. Let’s draw it:

You can see that I’ve set bit 2 to the slope tile here, so we can correctly handle it while loading our map to the world. If we add these to the world right now, they won’t work, obviously, since these are regular rectangles:

Your browser does not support the tag

So let’s change that:

local function is_up_slope(id)
    return fget(id, 2)
end

local function is_down_slope(id)
    return fget(id, 3)
end

We’ll start by defining two more predicates, and then use them in our is_obj function:

local function is_obj(x, y)
    local id = id_at(x, y)
    if is_solid(id) then
        return {x = x, y = y, h = 8, w = 8}
    elseif is_up_slope(id) then
        return {x = x, y = y, h = 8, w = 16, slope = slope, dir = 1}
    elseif is_down_slope(id) then
        return {x = x, y = y, h = 8, w = 16, slope = slope, dir = -1}
    elseif is_ball(id) then
        local ball = {
            x = x,
            y = y,
            h = 8,
            w = 8,
            xvel = 0,
            yvel = 0,
            is_ball = true
        }
        balls[ball] = true
        return ball
end end

As you can see, these are regular rectangles, except in our world, the 8x8 tile creates a 16x8 rectangle. The other half of the slope is just decoration.

We also have the slope and dir fields here. The slope is a function responsible for handling collisions that we’ll implement shortly. The dir field determines if this is an up-slope, raising from left to right, or a down-slope, lowering from left to right (or raising from right to left). We need to know the direction, otherwise, we won’t be able to calculate normals and properly map coordinates to new values.

Calculating slope collision coordinates

Here’s the slope function:

local function slope(obj)
    if obj.yvel >= 0 then
        local _, _, cols, len = world:check(obj, obj.x, obj.y + obj.yvel, slope_filter)
        for i=1, len do
            local col = cols[i]
            if col.normal.y ~= 1 then -- -1 or 0 will do
                local slope_floor = col.other.y - col.other.h
                local delta = clamp(0, (obj.x + obj.w / 2) - col.other.x, col.other.w) / col.other.w
                local y_off = nil
                if col.other.dir > 0 then
                    y_off = lerp(col.other.h, 0, delta)
                else
                    y_off = lerp(0, col.other.h, delta)
                end
                local newy = slope_floor + y_off
                return math.floor(newy), slope_normal(col.other)
end end end end

Now, that’s a lot to take in. Let’s go through step by step.

First, we check if the object’s velocity is going at least downwards. We don’t want to trigger slope collisions when objects move away from the slope, so that’s pretty simple.

Next, as usual, we need to handle collisions. However, there’s a catch - since our slopes are rectangles in disguise, we can’t just use the normal world:move() and be done. Instead, we need to kinda implement the world:move() in terms of world:check() and world:update().

The check method does the same stuff as move except it doesn’t move anything. It pretends that the object has moved, and returns a list of collisions and coordinates where it would end up if it actually moved. That’s perfect for our needs. The update method can move the object around without checking for any collisions, and that’s the other piece of the puzzle.

But right now, the ball collides with the slope rectangle, and it can’t go further, what can we do? We use filtering, of course.

The world:check() also accepts the collision filter, as world:move() does. We’ll need to add two new filter functions, one for checking slopes specifically, and the other to allow balls to move through slope rectangles freely:

local function slope_filter(_, other)
    if other.slope then
        return "cross"
end end

local function ball_filter(_, other)
    if other.slope then
        return "cross"
    else
        return "slide"
end end

With that out of the way, we can go into collision checking.

As usual, we iterate over a list of collisions. We then check if the collision’s Y component of the normal vector points at least up. If so, we have our collision, but we are just getting started.

Next, we calculate the slope floor Y position. This is the lowest coordinate our collision could possibly have:

local slope_floor = col.other.y - col.other.h

Next, we calculate the delta:

local delta = clamp(0, (obj.x + obj.w / 2) - col.other.x, col.other.w) / col.other.w

This is how far from the left edge of the slope rectangle the collision is going to happen. We try to measure in the center of the colliding tile, and normalize it to be a value from 0 to 1.

Next, we need to determine the Y coordinate on that slope:

local y_off = nil
if col.other.dir > 0 then
    y_off = lerp(col.other.h, 0, delta)
else
    y_off = lerp(0, col.other.h, delta)
end

We do so by checking the slope direction, and do a linear interpolation between 0 and slope height, using our delta value. Linear interpolation will move us in a straight diagonal line from the bottom corner of the slope to the top corner of the slope. Direction is simply used to flip the interpolation.

Finally, we’re calculating a ney Y position, and normals to return:

local newy = slope_floor + y_off
return math.floor(newy), slope_normal(col.other)

Our Y position from lerp is relative to the slope, so we add back the slope_floor position to translate it back to world coordinates.

And that’s pretty much just a small part of it! Wait…

Handling slope collisions

We still need to adjust the object’s position to that coordinate - why didn’t we do so in the slope function itself? Well, because reasons…

I mean, I tried to do that, but it didn’t work well, there are many outside factors that we may need to consider, and it’s not the best way to move it to this function. So let’s change our update method of the balls table.

First, let’s handle normal ball collisions. Mouse collisions will come later:

for ball in pairs(self) do
    if ball == grabbed then
        --- 8< ---
    else
        ball.yvel = lerp(ball.yvel, 5, 0.075)
        ball.xvel = lerp(ball.xvel, 0, 0.03)
        ball.x, ball.y, cols, len = world:move(ball, ball.x + ball.xvel, ball.y + ball.yvel, ball_filter)
        for i = 1, len do
            local col = cols[i]
            if col.other.slope then
                local newy, xnorm, ynorm = col.other.slope(ball)
                if newy and ball.y >= newy then
                    world:update(ball, ball.x, newy, ball.w, ball.h)
                    ball.y = newy
                    ball.xvel = ball.xvel + xnorm
                    ball.yvel = (- ball.yvel - ynorm) * 0.5
                    break
                end
            else
                if col.normal.y ~= 0 then
                    ball.yvel = -(ball.yvel * 0.9)
                    ball.xvel = ball.xvel * 0.75
                end
                if col.normal.x ~= 0 then
                    ball.xvel = -(ball.xvel * 0.9)
end end end end end

Code Snippet 1: Imagine if I didn't stack the end keywords on the same line? This post would be even longer! It's already a bit too long…

Main differences from before: we added ball_filter to the world:move() call, and split collision handling logic into two separate branches. The first branch checks if the collision happens with a slope and handles it. The second branch is the same as before.

The collision handling is pretty simple, really - we check if slope actually returned a new coordinate, and if the ball’s current Y position is lower than that, we need to handle the collision. The ball_filter sets slope collisions to cross, and it allows balls to move through slope blocks as if they’re not there, except we still get collision information. So if the ball’s Y coordinate is less than the slope collision coordinate, it means that we need to push the ball out of the slope. We do it straight up, without concerns about the normal vector to the slope, but it is possible to do so (I’m just lazy).

Calling world:update() sets the ball to a new position, and we also update its fields to set the new coordinate, and update velocities. We also break from this loop, as we don’t really want to handle any other collision, since it could get messy.

Now, let’s do the same for mouse movement:

for ball in pairs(self) do
    if ball == grabbed then
        local x, y = lerp(ball.x, mx-4, 0.3), lerp(ball.y, my-4, 0.3)
        ball.prev_x, ball.prev_y = ball.x, ball.y
        ball.x, ball.y, cols, len = world:move(ball, x, y, ball_filter)
        for i = 1, len do
            local col = cols[i]
            if col.other.slope then
                local yvel = ball.yvel
                ball.yvel = 1 -- needed for the slope check to happen
                local newy = col.other.slope(ball)
                ball.yvel = yvel -- restore the original velocity
                if newy and ball.y >= newy then
                    world:update(ball, ball.x, newy, ball.w, ball.h)
                    ball.y = newy
        end end end
    else
        --- 8< ---
end end

It’s pretty similar to the one above, except we need to do a small trick.

Notice how we set the ball’s velocity to 1 right before the check? Since the ball is moved by the mouse, its velocity is not really updated. Don’t ask me how long I was debugging why the collision doesn’t happen…

And that’s pretty much it!

Your browser does not support the tag

We can also add a different kind of slope to show that this approach is generic enough:

Your browser does not support the tag

Conclusion

This is still, by no means, a proper physics simulation of slopes. Balls bounce off slopes in the wrong direction at certain angles, normals are ignored when handling collisions, but hey, this might not be a problem in your game at all!

For instance, in my original case, the player is the main object I need to be able to interact with slopes, and I have a pretty simplistic game-oriented physics. So I don’t need the player to jump in a weird way when it’s on a slope - jumps should remain predictable. There are no projectiles that bounce off walls either, and thus, this implementation works fine.

You can, of course, use these principles to implement a more sophisticated engine. And there’s still a lot of room for improvement, too.

For instance, the way we define slopes is quite limited. Sure, we can adjust the slope angle, but because we’re building large slopes from small building blocks, there’s a wonky collision at these blocks’ corners. Instead, we could define two points and programmatically generate map tiles along the slope angle up to its end, using predefined sprites. And for non-sprite-based games, it doesn’t make sense to limit slopes to certain angles - you can define arbitrary-sized rectangles, making slopes as steep as needed.

Alternatively, you can refactor this code and define slopes as mathematical functions. Thus, you’ll be able to create splines and have curved slopes. Normal vector calculation will be a bit tougher, though.

And actually, if you happen to know some blog posts on the matter, please send them! I’m quite interested.

If you want to experiment with the code, here’s a cart that you can load with TIC-80, or you can experiment online on TIC’s website:

Figure 4: That’s an actual game cartridge you can load into TIC-80!

That’s all from me. Hope you’ve enjoyed this write-up as much as I did, and see you next time!

Code responsible for controlling the player object - movement, abilities, general game logic ↩︎
Fennel is Lua, but it adds a few features on top, like macros that allow additional metaprogramming capabilities, and fixes a bunch of Lua’s shortcomings. ↩︎

This looks so much tighter in Fennel, gosh:

       (each [_ col ipairs(cols)]
         (when (= col.normal.y -1)
           (set ball.yvel = (- (* ball.yvel 0.9))))
         (when (not= col.normal.x 0)
           (set ball.xvel = (- (* ball.xvel 0.9)))))

↩︎

Comment via email

Interactive game development with LÖVE

Sun, 08 Sep 2024 21:00:00 +0300

This is a continuation of the previous post on game development with the LÖVE game engine. I’m slowly appreciating the freedom it gives, compared to the TIC-80 experience. One of such freedoms is the fact, that LÖVE is a well-behaving console application.

When you launch TIC, it boots up into a console:

If you do so from a terminal emulator, you can see that the same console is there too:


 TIC-80 tiny computer
 version 1.1.2837 Pro (be42d6f)
 https://tic80.com (C) 2017-2024

 hello! type help for help

>ls

[tic80.com]
mtd.lua

>

However, writing in this prompt doesn’t do anything - it’s not sent back into TIC. And unfortunately, there’s no way of reading from standard IN, because there’s no io namespace provided. One could, theoretically, fiddle with sockets, if it is even possible to load them into TIC, which I’m not so sure about.

In LÖVE, however, you get full Lua experience and more! As you may know, Lua’s io.read() is blocking, and there’s no real way of making it non-blocking or checking the input buffer. However, that’s not a problem for LÖVE, as it has threads! So we can set up a separate thread that reads from the stdin.

Why would we want that? Well, you see, when it comes to Lua, I usually do my programming in Fennel, and Fennel has a decent REPL for doing interactive development. I love the idea of programming with a REPL, I do it a lot for my hobby projects, and at work with Clojure. Interactive development makes iterations much faster, and, in my experience, minimizes the amount of bugs in the resulting program. And we can leverage that during game development too.

Adding the REPL

The way we’re going to set this up is as follows:

We create a new, asynchronous handler for the REPL, and spawn it on the main thread. Then, we’re going to spawn another thread, that will listen on stdin, and send everything it reads to the main thread. Finally, once the main thread finishes the evaluation, it sends the data back to the IO thread for printing. After that, I’m going to spice things up by using the Fennel Proto REPL package I made for Emacs for a better REPL experience.

Let’s look at the REPL code:

(require :love.event)

(local fennel
  (require :lib.fennel))

(fn read [cont?]
  (io.write (if cont? ".." ">> "))
  (io.flush)
  (.. (tostring (io.read)) "\n"))

(case ...
  (event-type channel)
  (while true
    (match (channel:demand)
      :write (-> (channel:demand)
                 (table.concat "\t")
                 (io.stdout:write "\n"))
      :error (-> (channel:demand)
                 (io.stderr:write "\n"))
      :read (->> (channel:demand)
                 read
                 (love.event.push event-type)))))

(let [chan (love.thread.newChannel)
      repl (coroutine.wrap #(fennel.repl $...))]
  (repl
   {:readChunk (fn [{: stack-size}]
                 (chan:push :read)
                 (chan:push (< 0 stack-size))
                 (coroutine.yield))
    :onValues (fn [vals]
                (chan:push :write)
                (chan:push vals))
    :onError (fn [errtype err]
               (chan:push :err)
               (chan:push err))
    :moduleName "lib.fennel"})
  (-> (love.filesystem.read "lib/repl.fnl")
      (#(fennel.compile-string $))
      (love.filesystem.newFileData "repl")
      love.thread.newThread
      (: :start :eval chan))
  (set love.handlers.eval repl))

Simply requiring this file would start a REPL. You may be confused, about how’s it going to work, the while true may look especially concerning.

When we require this file, the ... is bound to the module name, so the case doesn’t match, as it expects two values an event-type and the channel. Then we fall into the let block, which defines the channel chan, the REPL handler repl, starts the REPL coroutine, which pushes the :read message to the channel. Finally, we load this file again, using love.filesystem.read, compile it to Lua, and start a new thread with :eval for the event-type, and chan for the channel. This makes case match and starts the while loop, whose sole purpose is to take values off the channel and act accordingly.

Finally, we set the love.handlers.eval handler, matching our :eval event type to call the repl as a callback when the event occurs. The event occurs only when we get the :read message from the channel, then we use read to get data from the stdio, and we push it back to the eval handler so the repl callback can be called.

That’s pretty much it! Now, let’s put it to the test!

Changing code at runtime

Here, I have a simple player controller and a bunch of values that correspond to how the player behaves:

(local fall-vel 300)
(local jump-vel -300)
(local run-vel 200)

(local player
  {:name "player"
   :color [0.3 0.7 0.3 1]
   :xvel 0
   :yvel 0
   :x 50
   :y 50
   :flip? false
   :width 16
   :height 24
   :state :idle
   :extra-jump 10
   :draw
   (fn [p]
     ;; omitted
     )
   :update
   (fn [{: xvel : yvel : extra-jump : flip? : x : y &as p} dt]
     ;; omitted
     )})

We can try and change the run-vel and see if it is picked up by the game:

Your browser does not support the tag

Seems it’s not. Perhaps, we need to recompile the game module?

Your browser does not support the tag

Aw, snap!

By recompiling the entire module, we undefined some variables, and the game crashed! By the way, the reason changing the run speed value didn’t apply is that we were actually defining a completely new speed value, that is not part of the module we’re editing. That’s a quirk of how Lua modules work and how Fennel REPL works. So let’s fix this!

Modules and state

While Lua has some lisp characteristics, it is understandably not an actual lisp. So, unfortunately, we can’t expect the same level of interactivity from it.

In Lua, a module is an ordinary table. When you write Lua, you return the value at the bottom of the file, usually a table, or sometimes a function. Any local variables, defined in that module are locals, stored as closures for the functions that reference them in the exported value.

Because of that, there’s no such thing as entering a module like in many other lisps. The REPL has its own kind of module space, where all locals, defined in the REPL are stored. The same goes for any code that we send to the REPL. So, while we do have a REPL, we can’t enter a specific module and change it partially - the only way to do that is to recompile the module and put the updated version in the package.loaded table. Which we can do.

However, there’s another problem lurking around - state. The video above shows that the error message was:

./game.fnl:68: attempt to index upvalue 'world' (a nil value)

When we’ve recompiled the module, world became nil, why? Well, because world is defined as a nil, and later set in the love.load function:

(var world nil)

;; ---- 8< ----

(fn love.load []
  (set world (bump.newWorld 64))
  (each [_ wall (pairs level)]
    (world:add wall wall.x wall.y wall.width wall.height))
  (world:add player player.x player.y player.width player.height))

However, the love.load runs only when the game starts, and hence after recompiling the module, world becomes nil again, and our game doesn’t really expect that. The same would happen to any other state we’re setting up when the game loads.

Unfortunately, Fennel doesn’t have a defonce or anything like it. The defonce macro is available in many lisps, and its purpose is to ensure that when we’re redefining something in the REPL or re-evaluating the whole module/namespace/package (whatever you guys call it) the value doesn’t get redefined. Fennel lacks this because there’s no way of doing this in Lua, because of how locals are stored (as closed variables).

But there’s a way around this, we can move the definitions to another module, and use require to load them. In Lua require caches everything it loads, so when we run require again, it doesn’t really do anything except get the value from the package.loaded table.

Here’s how we can define the world module:

(local bump (require :lib.bump))

(bump.newWorld 64)

Code Snippet 1: state/world.fnl

That’s it. Now, we can bring it to the main game module using require:

(local world (require :state.world))

This way, when we recompile the module, we get the same world as before, unless we were to recompile the world module.

I moved most of the game state in such modules, and now we can use our REPL.

Using the REPL

Here’s an example of tweaking the player’s motion speed again:

Your browser does not support the tag

I’m sending the code to the REPL, instead of reloading the module, just because it’s a bit more convenient. This way tweaking the game is much nicer and frictionless, although it doesn’t reach the same heights as that one video from Bret Victor.

Here’s me using a REPL to make an ad-hoc level editor:

Your browser does not support the tag

Unfortunately, there’s no way of using the REPL on Android, since there’s no way of running LÖVE from the same environment as Emacs, without installing X11 and running everything through Termux. Probably doable, but I don’t want to go this route. Android development is more backup route anyway, since I have access to my PC again.

Comment via email

Boredom and gamedev

Sun, 08 Sep 2024 00:34:00 +0300

I spent the previous ten days on vacation. Usually, I try to go off once or twice a year to somewhere where I can just passively relax - usually, it is some sea resort. This year I decided to go to the Republic of Türkiye and spend my time at the beach without any major attractions. The problem is - I get bored pretty quickly and my brain wants to do something.

I took with me my trusty Nintendo 2DS in case I have an urge to spend some time looking at the screen and to get myself occupied on the plane, and a phone with some books to read while I’m lying on the beach. However, my phone is also my computer, and I do a lot of coding on it in my spare time, usually when I don’t have access to a proper PC.

The last time I went on such a vacation I got so bored, that I decided that I wanted to do some game dev, and started a personal game dev marathon. Originally, I planned to start once I got back from vacation, but I was so eager that I started early, while I was still at the beach. The marathon was a crunch, and I had mixed feelings about it in the end, which ultimately led to burnout, and I put the idea of making games on the shelf for a while. And while the last time I started doing this I only drew some sprites, the only reason for that was that I couldn’t get any game engine on my phone. This time around, I got so bored that I started programming a game while gradually getting sunburns and taking breaks to go and actually swim in the sea.

Making games on Android

Basically, if the only thing you have is a phone you have two main options - TIC-80 and löve2d. tic has everything you need - an integrated code editor, a sprite editor, a map editor, and even a sound editor if you’re that versatile. however, the experience of using TIC for doing everything is not great, especially on the phone. I mean, that’s what you have to deal with:

Not a lot of screen space to view the code, the keyboard is abysmal, and the editor experience itself has a lot to be desired. Yes, it is authentic, I get it, it’s just not what I’m personally after.

On PC you can actually get a PRO version of TIC-80, which allows you to write a game in an external editor, and load it into the engine. Technically, you could do the same on Android, but there’s a problem - I use Android 14, which has storage restrictions for apps. And TIC-80 can’t access anything except files in its directory stored at /sdcard/Android/data/com.nesbox.tic80/. Which can’t be accessed directly on the phone either - you need a PC to access it. So even if you have a separate text editor, you can’t do your game development with TIC on Android. Moreover, you can’t even get your game out of the engine unless you have a PC at hand.

The other option, as I said, is LÖVE2D. It has the same problem as TIC, as you can’t launch the game from anywhere but /sdcard/Android/data/org.love2d.android/, however, newer versions have a separate dedicated launcher, that can load .love files from anywhere on the filesystem, which is good enough. Alternatively, an older version, like 11.3 can be installed that bypasses the sandboxing restrictions. So that was the route I took.

Making games on Android with LÖVE

I have little experience with LÖVE2D. Previously, I did a bunch of tests with it and made a few demos like the one described in my raymarching post, or the F.A.B.R.I.K. algorithm I implemented back in the day. So nothing major. The raymarching demo barely runs on a PC, and there’s no way to control it on the phone without connecting a gamepad. Unfortunately, I had no gamepad with me this time, so if I wanted to make a game on the phone I had to implement one myself. Fortunately, I have a lot of experience playing games with the on-screen gamepad, so I’m at least well accustomed to the idea.

I had no idea how to interact with the touch screen though, so I found a drop-in gamepad implementation for LÖVE2D in the game-tools repository:

Figure 1: lovepad.lua

Still, I wanted this gamepad to be a bit more advanced, with analog stick imitation, and more buttons, so I ported it to Fennel first and then extended it with more features:

tag"/>

It has all of the buttons of a modern controller, so I could share the control scheme between the on-screen gamepad and a real gamepad. I do understand that the on-screen gamepad should, ideally, be tailored around a game, but this will suffice for now. It was fun to implement this too, and I found a small bug in the lovepad.lua file, while I was porting it.

Next, I added the bump.lua library for basic physics (because I don’t want to deal with box2d yet), and made a simple player controller:

As you can see, I’m using Emacs on the phone, with the Google Keyboard set to PC QWERTY layout - a neat feature. This is my phone setup for programming, and I’m actually using the same configuration as on my regular PC.

After adding a camera library from the author of bump.lua, here’s what the player controller looks like at the moment:

Your browser does not support the tag

I want to tweak this player-controller a bit further, making it more fleshed out, but as you can see it already handles a few things:

Direction facing is tracked based on horizontal velocity
Jumping
- Holding the jump button longer increases the jump height
- Bumping against a ceiling resets the vertical velocity
Crouching and crawling
- When crouched, the player’s height is reduced, and when crawling the width is increased
- When crawling into a narrow space, the player changes to the crouched state if no direction input is given.
The camera follows the player
- Camera pans in the direction of movement, showing more of the upcoming level
- Vertical position only changes when the player is grounded, or when the vertical position is lower than the original camera position

I still need to tweak various speed values and add more movement options like dashing, sliding, etc., but it already feels gameish.

Writing a player controller was the most challenging thing before when I made the first demo game in the marathon. I made this one similar to the previous one, as can be seen in further GAME1 demos, but it’s a complete rewrite, as I wanted to make it differently this time. We’ll see how it evolves over time.

Drawing

While I didn’t draw anything for this game, I have a few updates on how I approach drawing on the phone. In short, I ditched the PixelStudio I’ve talked about in the first post about GAME1 mainly because its UX doesn’t work for me personally. It’s still a good app for pixel art, I just don’t like how it works, and it lacks some features I’d like to have.

Fortunately, there exists a better option - Krita which has a port for Android that doesn’t compromise any features, so you get a full Krita experience. It’s probably better suited for Android tablets, but works well enough for me on the phone. I’m slowly learning pixel art, and here’s a timelapse of me drawing a tree on my phone:

Your browser does not support the tag

I made a few mistakes when using various tools, as I was not well accustomed to Krita’s toolset back then.

Here’s the final result after a bit of refinement:

This isn’t a drawing for the game I’m making, just a sketch, following the principles outlined in this amazing video by Brandon James Greer. But one thing that makes a difference when making games for LÖVE2D and not for TIC-80 is the unrestricted palette. It’s still better to restrict the palette when making pixel art, but using only 16 colors for the entirety of game graphics is too restrictive for me. Especially right now.

One thing I haven’t tried yet is animating. PixelStudio had a decent animation pipeline, and it was possible to export the animation as a sprite-sheet. Still need to experience this in Krita - I know it has animation capabilities, but I’m not sure if they’ll be comfortable to use on the phone or not.

I’ll be making more pixel art for this game I’m making in the future, so I’ll post actual images once I have anything more to share!

Comment via email

Game4 and Autumn Lisp Game Jam

Thu, 19 Oct 2023 18:42:00 +0300

You might be wondering why there were no posts on the game development marathon I’ve been doing. Maybe you’d thought that I gave up after the admittedly underwhelming game3 having no actual game just some basic movement. And yeah, I felt burned up a lot, and considered skipping a month maybe - but then this happened.

So I thought - well, I just make the game during the game jam instead, and rest up until the jam begins. Yes, it means I will technically have less time to do this, but I did spend even less time on game dev last month, so it’s fine. I also got an unplanned vacation, so I guess I’ll actually have free time too.

Though, I lied a bit. The other reason I didn’t do anything is also because the next genre I wanted to work in is a puzzle platformer. And honestly, I don’t know what kind of puzzles to make. None seem appealing.

So after a bit of consideration, I’ve decided that can try to make something like a Lode Runner type of game. I already have the platformer engine from the very first game in this series, and originally I’ve planned that I would make a really simple 2D platformer, then in the subsequent game I will refine and improve it. Similarly, with the top-down games - first make a simple dungeon crawler, then take the blueprint and make an adventure with it. Unfortunately, the second game was a flop, and thus if I am to make the fifth game I’ll have to do everything from scratch.

So I’ve been thinking how I should handle the game. I guess I’m going to ditch the camera here, so the level fits the screen. It will make it a bit easier to reason about, and I guess I can always add camera back later if I really need to.

AI would be an issue though - I’ll need to implement some kind of path-finding for the 2D grid with gravity in mind. In other words, enemies should understand that they can jump down from cliffs if it will bring them on the same elevation with the player. Additionally, enemies shouldn’t just follow the shortest path to the player, as it will make them very predictable.

And if I have time, I can try putting on a twist to the formula. Not sure what kind of twist yet, but we’ll see I guess.

The jam starts in ~12 hours, which unfortunately means that it will begin while my work week isn’t yet ended. So I will have one day less already. Additionally, right now I’m in another city, and will lose another day on train to get back home. So this leaves me with 8 days instead of 10.

Hopefully it will not be an issue. Wish me luck!

Comment via email

Game3 - Results

Sun, 01 Oct 2023 17:12:00 +0300

I gave myself 1 extra day on this game because in total I was only able to work on this game for 5 days, two of which were on the train. So this game is now done, although I couldn’t make any sounds for it. Designing explosion and blaster sounds that sound good is hard. The game isn’t really complete, and you get practically invincible once you get 3 power-ups. As wasn’t able to do much this time, so a lot of sprites are left unused. Anyhow, here’s the game:

Play Game3 - Shoot 'Em Up on itch.io

Since the last post, I changed a lot. First, bump is back and all collisions are handled through it again.

I made some more weapons, the default one has a rapid-fire rate, but low damage:

Your browser does not support the video tag.

There are three more weapons - laser gun, magic gun, and rocket gun. Each of these has different damage values. Originally I planned to implement the overheat mechanic, but ran out of time and passion to do that.

It was fun implementing the flame that appears when the ship is taken down. It is done as a particle effect, as the ship simply constantly emits flame particles when burning, and they get removed once their animation ends. Similar to how the bullets interact with enemies.

If you want to download this game, here’s the cartridge:

The next game on my list is a puzzle platformer. For now, I’m not sure if I will have time or passion to do it, and I honestly don’t know what types of puzzles should it have. We’ll see. I already have a pretty decent engine for a platforming game, so it’s a good time to refine it.

Comment via email

Game3 w2/3

Sun, 24 Sep 2023 20:55:00 +0300

Another week passed, but I didn’t manage to squeeze out much spare time to make any significant progress with the game. Not like I didn’t do anything, but the game is far from being playable. This week I, unfortunately, could spend only a single day working on a game, because every day after work I had some personal stuff to take care of, which took all of my after-work hours. But it doesn’t matter, the challenge is a challenge! Hopefully, the next week will be a bit less busy. Although the stuff happening right now is very exciting and very important, so if the next week is busy again - so be it.

Anyway, here’s the progress so far:

Your browser does not support the video tag.

It’s a prototype. I’m experimenting with enemy patterns, like a simple sine wave, or tracking enemies. No collision has been implemented yet. This is my plan for the next and final week. As well as doing more animation, as the ship is just a cardboard right now, making weapons work, and not just fly with you, and implementing a scoring system. Probably that’s the most I’ll be able to do.

Another thing I want to look into is rotating sprites, as I want to spawn meteorites semi-randomly after some time passes in the game, so the game becomes harder. These meteorites will shatter, and smaller parts will also damage the player, making it harder to maneuver. But that’s probably the least prioritized thing as of this moment.

Comment via email

Game3 W?/4

Sat, 16 Sep 2023 01:59:00 +0300

I’m working on the next game, although I gave myself an extended period of rest. After failing to complete the last one I needed to distract myself a bit from this activity, so I worked a bit on Fennel stuff, played some games, and I think I’m back in business by now. I have an interesting thing going on with my productivity - it comes in waves. What I mean is that I can go onto programming frenzy for several months, and then once I feel burned out, I can just play games for another full month straight. Though I get tired of games too, and if by that time I feel that I’m not ready for programming yet, I can read some technical books, or even just some manga if I still feel too tired to be productive.

So this five month marathon is a bit hard for me, as I basically have to give up on long periods of rest, and juggle my free time to actually have some time to work on these projects. While these games are nothing special, I feel like I’m still learning new stuff, and thus this is beneficial for me still. Though, at some I actually thought of dropping the whole idea, and starting a more complex project that I was thinking about for a lot of time already. But I decided to leave it for the next year, as I still need a lot to learn. But, back on the topic.

This post actually marks the end of only the second week of the current game. How come, you might ask? To put it simply, I miscalculated a bit, and in reality I had another week on the previous game by the time I dropped it. So, technically, I could probably finish that game, but the burnout got me, so that’s that.

As for this game, I have a little to show. As it is a side-scrolling shooter, I designed a basic ship with some shooting modules, and some powerup icons. I considered to not making any graphics for this one, and doing everything with just primitives, like triangles, circles and so on, but after trying to draw a ship like this I dropped the idea and returned to Pixel Studio. Here are the results so far:

The ship turned out to be a bit too big, but I decided that I can make a game with larger assets for a change. So the enemy also uses 4 sprites, instead of just one, as in my previous games.

And here are the enemies animated:

Movement animations

Explosion animations

Obviously, I need to add more enemy variety, with different patterns, but designing enemies is hard. BTW, if you’re curious how I draw things on the phone, here’s a time-lapse:

Your browser does not support the video tag.

Though, I usually don’t do it in the landscape mode, portrait mode works better for me, especially with a stylus. This process was recorded in landscape just for viewing convenience.

On the technical side of things, I already implemented a basic movement with linear interpolation for the flying modules, and implemented some enemy patterns, but there’s no actual interactions yet. I’m kinda torn on the idea of including bump.lua again, as I feel like that this game can be done without any collision library. At the same time, having a collision library may make things much simpler, so I’m still thinking how to approach this game.

For the record, I basically dropped the idea of making any kind of music for these games because I just can’t get myself to work on it. I do plan to take some courses on music composition for future projects, though. Sound effects are challenging enough already by themselves.

That’s all for this week! Hopefully, I’ll manage to finish the game this time, though I already lost one week. Let’s say, this is week 1/3 instead of 2/4 shall we? Feels less demotivating this way.

Comment via email

Game2 W4/4

Fri, 25 Aug 2023 18:35:00 +0300

Well, It’s unfortunate, but I couldn’t make the game in these 4 weeks. August is just too much of a pain in terms of the amount of different events - maybe even the busiest month in the whole year, for me personally. Judging by the commit history, I was able to work only for 11 days out of the 28 days given to me by the challenge - and I tried to do at least some work every day and commit everything I did. I’m saying 11 days, but maybe 5 of these were in this last week.

This last week was all about level generation and, unfortunately, I failed at it. I was trying to implement the Wave Function Collapse algorithm in Lua and for some weird reason, it didn’t work. After three failed attempts, I decided to cheat. My idea was to go and port my ClojureScript version to Fennel form by form and compile it to Lua after it works. However, it didn’t work as well, no idea why. For some reason, some branches in my code are just never visited at all, although I did everything the same way, and implemented missing pieces from Clojure’s standard library for this code to work. At least it terminated, but instead generated a complete gibberish:

>> (wfc (gen_world 9 9) coast)
[["🟩" "🟩" "🟦" "🟦" "🟩" "🟩" "🟩" "🟦" "🟩"]
 ["🟩" "🟩" "🟫" "🟦" "🟫" "🟦" "🟦" "🟩" "🟦"]
 ["🟦" "🟩" "🟫" "🟫" "🟦" "🟫" "🟩" "🟫" "🟫"]
 ["🟫" "🟫" "🟩" "🟩" "🟩" "🟦" "🟫" "🟦" "🟦"]
 ["🟫" "🟫" "🟩" "🟫" "🟩" "🟦" "🟩" "🟩" "🟩"]
 ["🟦" "🟦" "🟩" "🟫" "🟦" "🟩" "🟦" "🟩" "🟫"]
 ["🟦" "🟫" "🟩" "🟦" "🟦" "🟩" "🟩" "🟩" "🟫"]
 ["🟦" "🟩" "🟦" "🟦" "🟩" "🟩" "🟩" "🟫" "🟩"]
 ["🟦" "🟩" "🟫" "🟦" "🟦" "🟩" "🟩" "🟦" "🟫"]]

It is supposed to look like this:

user> (wfc (gen-world 9 9) coast)
[["🟫" "🟫" "🟫" "🟫" "🟫" "🟫" "🟫" "🟫" "🟫"]
 ["🟩" "🟫" "🟫" "🟫" "🟫" "🟫" "🟫" "🟫" "🟫"]
 ["🟦" "🟩" "🟫" "🟫" "🟫" "🟫" "🟫" "🟫" "🟫"]
 ["🟦" "🟦" "🟩" "🟫" "🟫" "🟫" "🟫" "🟫" "🟩"]
 ["🟦" "🟦" "🟦" "🟩" "🟫" "🟫" "🟫" "🟩" "🟦"]
 ["🟦" "🟦" "🟦" "🟦" "🟩" "🟫" "🟩" "🟦" "🟦"]
 ["🟦" "🟦" "🟦" "🟦" "🟦" "🟩" "🟦" "🟦" "🟦"]
 ["🟦" "🟦" "🟦" "🟦" "🟦" "🟦" "🟦" "🟦" "🟦"]
 ["🟦" "🟦" "🟦" "🟦" "🟦" "🟦" "🟦" "🟦" "🟦"]]

This reminded me of the importance of data structures and their properties I keep forgetting when programming in Clojure. Because in Clojure it’s just the thing you have, so you don’t think much about it.

You see, Clojure has 4 main data structures, baked up with literals: list (a, b), map {k1 a, k2 b}, vector [a, b], and set #{a, b}. Each of these has its own set of properties, for example, lists are only fast to add elements at the front, and vectors are fast to add elements to the tail. Maps are mostly like Lua’s tables, and sets are like maps in the way that they can only store unique elements, and are indexed like a map but iterated like a list.

In my ClojureScript implementation of the WFC algorithm, I used all these data structures and relied on their behavior. For example, the superposition for a cell after the world’s initialization is a set of all possible values for the cell:

#{"🟦", "🟩", "🟫"}

I used maps to store the recipe:

{"🟫" {:up #{"🟫"}
       :down #{"🟫" "🟩"}
       :left #{"🟩" "🟫"}
       :right #{"🟫" "🟩"}}
 "🟩" {:up #{"🟫"}
       :down #{"🟦"}
       :left #{"🟫" "🟦" "🟩"}
       :right #{"🟫" "🟦" "🟩"}}
 "🟦" {:up #{"🟩" "🟦"}
       :down #{"🟦"}
       :left #{"🟩" "🟦"}
       :right #{"🟦" "🟩"}}}

The map itself stores maps with sets that are later used in the algorithm. Other data structures are at play for other parts of the whole process, but I’m not going to touch them here.

Lua on the other hand has only one collection type - the table. It can serve as a vector, to which you can add elements at the tail, and you can use them as hash tables, where there can only be a single instance of a given key. Sets can also be represented if we just use a table where keys are elements and values are the same elements or something like true.

local superposition = {["🟦"]=true, ["🟩"]=true, ["🟫"]=true}

This is actually what the “Programming in Lua” book suggests. The recipe then looks like this:

-- Sorry, not sorry for formatting - all these brackets on separate
-- lines take a stupidly big amount of vertical space
{["🟫"]={up={["🟫"]=true},
         down={["🟫"]=true, ["🟩"]=true},
         left={["🟩"]=true, ["🟫"]=true},
         right={["🟫"]=true, ["🟩"]=true}},
 ["🟩"]={up={["🟫"]=true},
         down={["🟦"]=true},
         left={["🟫"]=true, ["🟦"]=true, ["🟩"]=true},
         right={["🟫"]=true, ["🟦"]=true, ["🟩"]=true}},
 ["🟦"]={up={["🟩"]=true, ["🟦"]=true},
         down={["🟦"]=true},
         left={["🟩"]=true, ["🟦"]=true},
         right={["🟦"]=true, ["🟩"]=true}}}
-- also, the table syntax is just horrible - why square brackets are
-- needed around strings for keys? Why can't we write {"foo bar"="baz"}?
-- And why can we write {foo="bar"}? Why variable foo is not the same
-- foo when used in the table? Why foo is now a string?  The syntax is
-- too smart for its own good.

Now, here’s the problem - how do we tell apart sets from key-value tables? We can write some predicates, like is_set that either check that all values are true, or create a constructor function that will add a hidden __index metatable with a is_set key set to true, but it’s all pretty janky, in my opinion at least. A proper data structure should have its own syntax literal and a set of functions to check the type. Lua doesn’t even give you the ability to distinguish sequential tables from associative ones¹. I don’t think that Clojure’s choice of #{} for sets is great, but it’s a lot better than nothing.

But there’s also another issue with our implementation of sets - iteration support. In Clojure, you can iterate over any type of data structure, and it will actually do it in a meaningful way.

If you try to iterate over a list, vector, or set - it will just iterate over the elements:

user> (map identity '(:a :b :c))
(:a :b :c)
user> (map identity [:a :b :c])
(:a :b :c)
user> (map identity #{:a :b :c})
(:b :c :a)

In the case of a set the order is not determined, so the order of results is arbitrary. If you try to iterate over a map though, it’s a bit different:

user> (map identity {:a "b", :c "d", :e "f"})
([:c "d"] [:a "b"] [:e "f"])

Same as for the set, the order is arbitrary, but you can see that the elements in the list are vectors. That’s right, when we iterate over the map we get back vectors, containing the key and its value, which we can then use in the function that we iterate with.

You may be thinking: “Well, that’s the same as what pairs does in Lua” but it’s not. Unlike what I have shown to you, pairs will always return the key and value, even for vectors. Yes, in the case of a vector, the key will be an index, and we can pretty much ignore it most of the time, but what about our sets? In the case of our set implementation, the key is actually the value we’re looking for, because the value is just true. So no, implementing sets as tables that store true as a value is a no-go for most use cases, we have to store the value both as a key and a value in a set:

local superposition = {["🟦"]="🟦", ["🟩"]="🟩", ["🟫"]="🟫"}

But I digress.

Another, very important property of Clojure’s data structures is that they’re both immutable and persistent. This means that whatever we do with the vector doesn’t actually change the vector - it returns a new vector that shares the unchanged part of the structure with the old one plus new stuff. Clojure author went to great lengths to make this process fast and reliable.

I used this heavily in the CLJS version of the algorithm. Perhaps too heavily, but it’s a different topic. What it gave me though is the ability to change the world without mutating the original world, so every step of the algorithm actually produced a new world, and I could trace it back to the very beginning if I wanted to. It is not as fast as the mutation-based approach but is much more sane to work with and debug.

My first implementation of the algorithm in Lua, however, was mutating the world. Not only it is hard to debug, Lua makes it harder because you can’t view the data structure you’re working with. You probably don’t remember it, but I made a complete rewrite of the pretty printer for the Fennel language, and I did it mostly because the original one produced the representation that was hard to read due to indentation going all over the place. Well, guess what, Lua doesn’t have its own pretty printer whatsoever. You have to write your own or import some library that does it for you, which is not feasible with TIC-80, as its screen resolution is too small to comfortably read anything, especially huge tables that contain lots of elements, like the world I was trying to generate. Can you feel my frustration?

Then I made a hacky deepcopy function (another part that lacks from Lua because tables²) to at least get a copy-on-write type of immutability in Lua. This slowed down things to the point that it was useless for the sizes of worlds I wanted to construct. And it didn’t fix the problem, so it was somewhere else. I wasn’t ready to re-implement the whole thing again, so I stopped here.

Another thing I keep forgetting is how great Clojure’s standard library for manipulating collections is. There are all sorts of operations on sets, you can transform maps, iterate on anything, rename keys, etc., etc. Lua has a very rudimentary library for tables, that can’t do almost anything. Sure, there are libraries like Penlight³, and lua-stdlib that could help with that, and I made a port of Clojure’s core namespace to Fennel (and therefore Lua) but again - TIC-80 makes it hard to use these libraries. So, no, Lua isn’t great at manipulating data structures, and porting Clojure code to it is a pain. What did I expect? Well, I’ve ported all the functions I used in my CLJS WFC implementation, things like map, keep, map-indexed, get-in, assoc-in, etc., but there were still problems with how to iterate over tables, as there is no sequence abstraction in Lua, and it’s hard to make it properly. I tried multiple times before, and the best I got was my lazy sequence library for Fennel, but even there I took some shortcuts regarding the situation with tables that have both associative and array parts. Sorry Lua fans, but combined data structures like that are stupid.

I’m writing this a bit early, as there are clearly some more days until the end of this week, but then again, I won’t have time to do any work neither this evening, nor tomorrow, or the day after that. It’s a shame though, I don’t want to abandon this roguelike idea, and maybe I’ll get back to it after the challenge ends. Or maybe not, I don’t know. I will have another chance to make a top-down game, but probably without an isometric projection.

Looking back on the development process for this game I can see that choosing the isometric projection was probably the wrong decision. First, I struggled with the projection itself, then with the projection of screen coordinates back to the world coordinates. Halfway through I ditched the isometric projection and started drawing stuff without it, in hopes that I will just enable it back when the world generation is ready. But then the world generation was a problem. I didn’t even get to work on enemies, items, menus, and so on. Well, a roguelike is a lot more involved than a simple platformer, so it is expected that it takes more time to do stuff, but I didn’t have that time unfortunately.

Lua isn’t the one to blame for all these problems though. While I did get some frustrations with its syntax, overall the experience wasn’t that bad. However, I will not probably use it for upcoming projects. The lua-mode package for Emacs is in a rough shape - there is no pairing support for do end keywords, like in sh-mode or ruby-mode. Indentation is extremely slow and often unpredictable.

The next game on the list is a Card game but I’m not in the mood for that at all, so I’m going to change this and make a side-scrolling shoot-em-up kind of game. It should be much easier, and with all of the frustration built up over the last month, this is probably just what I need.

I know that the distinction isn’t possible because the data structure combines both sequential and associative parts in one package, but at least Lua could give us some predicates that would check if the associative part has any values and if the sequential part is not empty. This way we would be able to detect if the table we’re looking at only has the array part, or only has the associative part which is much better than nothing. It can be done in Lua but it is slow and often unreliable. ↩︎
It is hard to properly implement deep copying because of metatables. ↩︎
I keep forgetting its name and every single time I have to search for it as “lua batteries included” to only find a reddit post with a link to the repo that just lists lots of libraries for Lua. ↩︎

Comment via email

Game2 W3/4

Sun, 20 Aug 2023 21:02:00 +0300

Why is it the third week that I finally gain any interest in actually working on the game? Now, when I think of it, this may be the whole reason I couldn’t get into game dev during earlier attempts in the past years. I consider myself an OK programmer and I know a bit of math that is required for making basic games, so I doubt it was due to a lack of knowledge. Maybe it is that by the third week, there are some actual results that produce enough stimulation to my brain making it act as a feedback loop that amplifies the feeling until it burns out, and I just never stuck enough for that to trigger before. Well, I experienced something like that during my first game jam, but not so much after when I made further attempts at this. I guess forcing myself was the right decision.

Anyways. I mostly figured out the map problem I talked about in the previous post and the whole thing started moving, like, literally. I ported the camera into this project and made a really basic way of moving in the world and it already feels like a game:

Your browser does not support the video tag.

This, however, didn’t go as smoothly, as the previous time. I’m still figuring out the quirks, as my rendering pipeline is kinda weird. You see, in the previous post, I made it so the tiles, used to build up a level, are baked into the cart’s map memory block. This way I don’t have to recalculate projections of every floor tile on every tic and can do culling, drawing only what’s really is on screen, plus some extra boundary for smooth camera movement. However, it means that when projecting to the level I need to account for the map offset, somehow. This turned out to be a bit more challenging than I thought.

For now, I put that problem aside, as I can always get back to it when I have more complex levels, and I needed to figure out the opposite of what I was doing in the previous post - project screen coordinates back to the world’s coordinates. Because this game is meant to be a roguelike I’m going to use the mouse in this game for movement with some automatic path-finding. Path-finding will have to wait though.

After a bit of trial and error, I got it working:

But again, this only works either for the static camera position, or a specific level geometry because of all the magic numbers spread through my code. I didn’t have much time this week, only the first half, so I basically did nothing starting from Wednesday. While it’s a shame, Starting next week I’m on vacation and hopefully will be able to spend much more time on the game and finish it in time. Or at least get all of the mechanics working, and publish it as another demo.

So, next up - world generation. I looked at some interesting algorithms for dungeon generation in 2D roguelike games and while many of them are interesting in their own way, I don’t want to complicate things that much. So instead, I turned to my older project - wave function collapse.

I’m going a bit ahead of myself here as I haven’t started working on this yet, but I thought that it will be a nice and organic way to generate small, fixed-size levels. But a plain WFC won’t work for me, so I made some adjustments. The basic idea is to choose some points on the finite grid and assign them to specific elements.

Here’s a janky drawing with all of this in place:

These objects in the drawing are:

Four rotations of room exits, connected to a floor tile, corridor tile, and two wall tiles;
level entry and level exit, connected to 4 floor tiles at each side;
spawn tile, also connected to 4 floor tiles.

To evenly distribute things in the level, I decided to divide the world into four sectors shown above as a gray grid. Each sector can have only so many objects to hold, with the exception of entries and exits - these are shared across all segments and there can be only one of each.

Once objects are in place, the actual WFC takes over and fills the world. The blue walls on the image and black corridor paths will be generated by WFC, and because it will not pick empty tiles by itself, I suppose isolated rooms won’t appear. The nice part is that the rules can be extremely simple, as there are basically 4 types of tiles used, unlike my previous project. Of course, I can add variety later. But that’s the topic for the next week.

Comment via email

Game2 W2/4

Sun, 13 Aug 2023 10:23:00 +0300

Didn’t have much progress on the Game2 this week. Mostly worked on some additional assets, and rendering the world into an isometric grid.

In the last post, I mentioned that it is very hard to come up with floor tiles that leave enough colors for things to be seen. I didn’t mention it in the previous post, but here are the original tiles I drew for the game to represent the floor and walls:

That’s right, I didn’t plan on using isometry originally. However, this looked blunt and there wasn’t enough space to add any decoration. I could, of course, bump the floor tile size to 4 tiles, but it started to look way too big. Isometry, however, looks decent in my opinion:

The only problem though is how do I draw this?

I created a sample level as a two-dimensional array and a simple projection function to project the world’s coordinates to screen coordinates:

local level = {
  {LW,RW,RW,RW,RW,RW,RW,RW,RW,RW},
  {LW,F, F, F, F, F, F, F, F, F},
  {LW,F, F, F, F, F, F, F, F, F},
  {LW,F, F, F, F, F, F, F, F, F},
  {LW,F, F, F, F, F, F, F, F, F},
  {LW,F, F, F, LW,F, F, F, F, F},
  {LW,F, F, F, RW,F, F, F, F, F},
  {LW,F, F, F, F, F, F, F, F, F},
  {LW,F, F, F, F, F, F, F, F, F},
  {LW,F, F, F, F, F, F, F, F, F},
  {LW,F, F, F, F, F, F, F, F, F},
}

local function isometric_project (x, y, w, h)
  return (x*8)+(y*-8), (x*4)+(y*4)
end

LW is Left Wall, RW is a right wall, and F is floor. All are objects with a single draw method, that knows how to draw the tiles.

I then drew this to the screen with a simple nested loop:

local function load_level (level)
  local ox,oy=x,y
  local offx,offy=120,8
  for y=1,#level do
    for x=1,#level[y] do
      local t=level[y][x]
      if "table" == type(t) then
        local mx,my=isometric_project(x-1,y-1)
        t.draw(mx+ox+offx,my+offy+oy)
      end
    end
  end
end

This gives me the correct result, albeit there’s no special code to draw this with composite tiles, so walls correctly intersect with ordinary tiles:

While this works, there’s a problem. As can be seen in the level array, there are only two kinds of walls - left and right ones. Ultimately, I want to bake this layout into the map, so I can just call map to render the whole level, and get camera culling as I did in the previous game. And it isn’t easy to see the problem with the isometric grid from the app where I drew these tiles, so let me bring a non-isometric grid in the engine:

There are some tiles that right now only take up half of a tile vertically, and some walls are drawn with two tiles and some with three tiles. This means, that I can’t just bake this on a tile-by-tile basis into the map with mset.

Here’s a closer look at the problem in case you didn’t see it:

I, however, only used the two-tiled walls in this picture (marked with a red grid), so because of that I can’t bake this into a map, as the tiles I used don’t match the map grid. Still thinking about how to approach this, as there’s also a second problem - entities should be able to stay behind the walls, so in reality I can’t bake this all to the map, probably only the floor tiles, and I will have to draw the walls separately. Or via a second map call. I mean, I can draw it just like I do now, but this nested for loop bothers me way too much. When I will add entities and have bigger levels I fear this will become really slow.

There are probably ways of doing this easied than what I try to do, but this is just how I roll.

Additionally, I drew even more items, and I decided that for every single-tile item I will draw a bigger one for the equipment menu:

Hopefully, I will figure out the isometry and have time to implement this.

Comment via email

Game2 W1/4

Sun, 06 Aug 2023 23:04:00 +0300

First week, second game!

This time I opted to go with plain Lua. Don’t get me wrong, I like Fennel, but I wanted to get a bit more authentic experience. Apart from having a nicer standard library, Fennel doesn’t add anything to the table in the case of the TIC-80 environment. E.g. there’s no REPL that I can attach to from the editor and change code around, and there’s no real need for macros.

Plus, I’d like to remind myself why I appreciate Fennel so much, as things like pattern matching, table comprehensions, and other Fennel-specific features are not available in Lua. On the other hand, Lua is simpler, and the code being run is what you’d expect, not something that a compiler produced. If you dared to look into the Lua version of the cart that I published at the end of the last post on the Game1 topic, you know that it looks horrific at times.

So Lua it is. TIC-80 actually provides even more languages, namely Ruby, JavaScript, MoonScript, Scheme, Squirrel, Wren, Janet, Python, and even plain WASM, I may try to use some of these. I haven’t decided on future games yet though.

Speaking of languages - why so many? This is probably the single thing I dislike about TIC-80 and like more in PICO-8 - the latter is only programmable in a subset of Lua. If I’m being honest, I would rather only leave Lua in TIC and ditched everything else - it’s much more authentic this way. Even if that would mean losing direct Fennel support which, while a shame, is OK - we can always AOT.

I’ve quickly gone through the development log, and it seems that the author is pretty generous with adding new languages to the project. MoonScript was added first (probably), as far as I can see. There’s a still open request for Nimscript, whatever it is. Don’t get me wrong, the project is nothing less than amazing, I just think less is more when it comes to things like this. But I digress.

I’ve spent most of my first week thinking about the game and what would it evolve around. After a bit of consideration, I decided to make a cyber-based roguelike, because there are already way too many traditional magic-based roguelikes. So instead of a mighty artifact in my game, the character will search for the mighty neural chip that can do any kind of calculations instantly. I can also try focusing on range battles, which should give a fresh spin on classic roguelikes too.

I started working on graphics, but then life told me that I should not do anything this week and I had a power outage for quite some time. Anyhow, this is what I got so far:

I also tried making some floor tiles, and once again I feel the limitations of the palette - it’s so hard to come up with floor tiles that will make other sprites properly visible. Maybe I’ll add outlines if I will not find a clever solution.

One such solution might be to divide the palette into two smaller palettes. In other words, the first 8 colors can be used for interactable objects, and the last 8 for the scenery. Maybe I’ll try that too. It’s even more restrictive, though.

Unfortunately, I don’t think I followed my own word, and the first week went pretty unproductive regarding Game2. And yes, I will name all of these games like that, sorry! I did some work on my async library for Fennel, as I found some bugs in it though. But I’ll bring the pace up the next week for sure!

Comment via email

Game1 - Results

Sun, 30 Jul 2023 15:29:00 +0300

Well, this was fun! A bit exhausting, actually. The first of five months of the challenge has ended and here are the results:

Play Game1 on itch.io

The game isn’t really complete, but I did my best to make it feel as complete as possible in the time constraints I had. Technically, I have 1 day left, but given that I need to start working on the next game immediately I decided to give myself a day off. It only features one level, and cuts out to the “you won” screen, but I still consider it a success.

Here’s the last bit of devlog for this particular game outlining some things I did since the last post in no particular order.

Graphic overhaul

I’ve added parallax scrolling to the background, making the game happen inside a cave. Well, at least, now the background is not that boring to look at, but it’s still plain.

Then, I added a second layer and started experimenting with different colors:

The problem with limited colors is that I can’t find a way of having foreground and background properly separated without using outlines on sprites, which I wanted to avoid for this game at least. Thus, slimes are now blue instead of green. But I like it more this way because it pops from the green ground a bit better. And now that the background is also green it’s a lot more sensible.

I’ve spent some time drawing foliage, like mushrooms, trees, grass, water, and so on. None of this is animated though - time is once again against me.

Also, added the menus, title screen, cover art, and some fade-in/out animations for smoother transitions:

Enemy AI

While I wanted to add more enemy types to the game I simply ran out of time, so the game only features basic slimes. Their AI is extremely simple too - just roam forward until there’s no more ground, a wall, or another entity, then turns around.

Still, I had some trouble implementing this at first, as I tried to use the world:check method to try and move the slime forward and below to check if there’s ground to traverse on. But this didn’t work for some reason, so I opted for advanced bump API world:queryRect and queried the rectangle below the slime instead. It worked nicely, and perhaps I’ll use this to make a more robust AI in future games.

I was toying for a little bit with flying enemies, but it’s hard to make them work right with the environment. I didn’t want something like Medusa heads from Castlevania games, but that’s exactly what I got during testing.

I also finally added the death mechanic, as previously the game lacked it completely. Death doesn’t take away your score, as the game turned out to be hard, and there are not enough coins in the only level to get 100 of them and earn an extra life.

Level design

Probably shouldn’t have left this to the last possible moment, but designing interesting levels turned out to be a lot harder than I thought initially. I think I’ve managed to at least do a somewhat challenging one, but you’re the judge here. Probably most enemies and traps are cheap.

As I mentioned previously, I’ve used the map editor to construct the level:

It’s a shame though that Tiled, a tilemap editor, doesn’t support TIC’s maps. Well, there’s a converter but it didn’t work for me. Map editor in TIC isn’t bad, but it isn’t as good as something like Tiled. For example, Tiled has randomization from a selected set of tiles when you paint with them, which makes things like ground feel less repetitive. In TIC I had to do it by hand, and I may have forgotten to do it somewhere in the game, so excuse me if you’ll see something like that.

I used the bottom of the map to draw menus, backgrounds, transitions, and so on, as can be seen here:

My initial idea was to implement the first few levels like this, one below another, and then switch the memory bank, draw a new set of tiles, and make more levels. But not only I ran out of time, I also ran out of ideas. Maybe next time.

Overall, I’d say making levels isn’t my least favorite thing so far but it’s close. I’ve played in a fair bit of games with level editors and even published some online, but it never grew on me. I guess I’m not a level designer at heart.

Music and SFX

This was probably the hardest part. I can’t compose music and TIC’s tracker is alien to me. Sound design is a bit easier, but I don’t know a lot of tricks, so sounds in this game are far and few between. Still was worth a shot.

Up next

The next game in the challenge is a roguelike. This kind of game poses different problems, like pathfinding, more complex enemy AI in general, randomization of levels, items, etc. I kinda feel exhausted right now but I’ll still try not to repeat the mistake I made and not procrastinate too much in the first weeks. Though the next month is packed with various life-related events, much more than this one, so we’ll see.

As for this game, here’s the cartridge if you want to play it yourself:

Though, because the original code requires a more recent version of Fennel than the one TIC provides, the code in the cart above was AOT compiled to Lua and isn’t very readable. Also note that the last stable release of TIC still contains the #1904 bug, which means that my game will run ~10 times slower than it should. So you either need to play the game on the itch.io page, as it features a more recent version, build a standalone version yourself, or use an older release with the Lua version above. You can read the original source code at the itch.io page linked above, or in the game repository.

Comment via email

Game1 W4/4 progress

Wed, 26 Jul 2023 20:09:00 +0300

This post is midway through the last week I have to work on the game in a platforming genre. And it’s a bit of a shame because currently, I’m having a blast - now that the physics and camera are in place the game already feels like a playable thing. So I decided to boost this feel and make some graphics so the world won’t look too boring to traverse.

I haven’t decided on what the world be like yet, but I’m running out of time, and also, I’m not that experienced in pixel art. A few posts ago I wrote how I tried to do pixel art on the phone by using a stylus, and it worked pretty well for me. So I took out the app again and started thinking about how would I use the colors that are still available to me.

I’ve briefly considered changing the palette too. The default TIC-80 palette is a bit weird for my taste, and it doesn’t include some colors that I’d like to have, e.g. brown. I don’t know how, but every time I see some pixel art that uses this particular palette I swear it has brown, but upon closer inspection it’s an illusion caused by interplay with the other colors. Unable to find a new palette that works, and also that doesn’t make every other sprite I drew up to this point use some weird colors, I gave up for now. Maybe I’ll just look at what colors I don’t use at all or use too infrequently and replace them with the colors I need for my purposes.

For now, I drew some grass on stone type of terrain (again, no brown for dirt!), and some construction site-type red bars:

Note, these are tiles, e.g. what goes on the map, but there are some things that are not part of the map, for example, the coin, or the slime enemy. I’ll explain why they’re here shortly.

And here are the sprites:

As you can see, I’m storing these sprites mostly in rows, and tall sprites, like the player character look naturally in the editor. Except for the ones in the third and fourth rows first half - these are horizontal sprites, but I still store them this way, because of how I do animations. This reminds me that I haven’t explained anything regarding how my game works! I guess I was too busy implementing it and didn’t have any spare time to write a proper post.

So the animations are implemented in terms of sprites, obviously, but the way I set up them is a bit weird. And I know, I definitively could save some space and re-use some sprites, because clearly there are doubles or even triples of the same sprite. But it was easier this way, so I did it anyway. I have this function, called sprites that takes an id of the first sprite, the last sprite, and an optional loop? parameter:

(fn sprites [from to loop?]
  (let [sprites (fcollect [id from (or to from)] id)]
    (doto sprites
      (tset :n (length sprites))
      (tset :loop? loop?))))

The result of this function is a table, that simply holds a range of IDs for all the sprites in the animation. Does the n key hold the total count of sprites, and loop?, well, we’ll get to it in a moment.

The other component of animation is how I choose when to change the frame. I’m sure there’s a different, and probably more robust way of doing this, but what I’ve settled on is this function:

(fn next-frame [obj dt]
  (let [dt (+ dt (or obj.last-draw-time 0))]
    (if (>= dt 60)
        (let [sprites (obj:sprites)
              n (m/floor (/ dt 60))]
          (set obj.last-draw-time 0)
          (if (= obj.frame sprites.n)
              (case sprites.loop?
                n (if (= :number (type n))
                      (set obj.frame n)
                      (set obj.frame 1)))
              (set obj.frame
                (clamp 1 (+ n obj.frame) (length sprites)))))
        (set obj.last-draw-time dt))))

As you can see, this function receives an object obj and a delta time dt. The object stores its own draw time, and when the sum of dt and this time is greater than 60 I change the frame. The loop? field is used in a special way - when the next frame exceeds the total sprite count, we check if the animation should loop. If the field is true the animation loops from the first frame. However, if the field is a number, we restart the animation from that number. This way the animation can have a set of frames that act as preparation or transition, and then loop only the necessary part.

Here’s how I draw coins:

(local coin-sprites (sprites 330 335 :loop))
(local coin-collect-sprites (sprites 346 351))

(fn draw-coin [{: x : y : frame &as self} {:x cam-x :y cam-y}]
  (match (self:sprites)
    coin-sprites
    (let [s (or (. coin-sprites frame) 511)]
      (spr s (+ cam-x -120 x) (+ cam-y -64 y) 0 1)
      (next-frame self (/ dt 2)))
    coin-collect-sprites
    (let [s (or (. coin-collect-sprites frame) 511)]
      (spr s (+ cam-x -120 x) (+ cam-y -64 y) 0 1)
      (next-frame self dt)
      (when (= frame collect-sprites.n)
        (tset coins self nil)))))

There are some wonky numbers in here to adjust to the center of the screen and camera position in the world, but the code should be straightforward. The (self:sprites) call simply returns the object’s current set of sprites, which I change in other functions depending on the situation. E.g. if the coin was collected, the object’s sprite is changed to the coin-collect-sprites which doesn’t loop, and the last sprite of that animation is invisible. The coin itself is deleted from the world once the last frame of the animation was played out.

Your browser does not support the video tag.

This is the basis for all animation in the game. Each object has it’s :draw method, and each such method calls to next-frame to understand what to display next time.

Interaction with entities is done similarly - each entity has an :interact method that decides what to do when a collision is detected. For example, for the slime enemy, the method accepts the y normal of the collision, and if it is not negative 1, which means that the collision happened from the side or from below, the player is damaged. Otherwise, the slime sprite set is replaced with the stomp animation, and the object is deleted from the world:

Your browser does not support the video tag.

By the way, I haven’t talked about how I structure the world yet. You may know, that TIC has an inbuilt map editor:

This is basically a level designer for me because I’ve implemented a small function that upon loading the cart walks through each tile on the map and populates the world based on it. I still use map for drawing the level, but before that, all entity tiles are removed from the map, like in the image above coins and slimes, and the player’s head, which acts as a spawn point. This way I can simply put objects in the map editor, and re-run the game, getting an updated world, complete with collectibles, power-ups, enemies, etc.:

Your browser does not support the video tag.

Here I’m obviously testing things out, but the game feels complete enough to actually start designing some actual levels. I’m running out of time though, so perhaps I’ll just make a single course to complete, and that’s it. But it’s already more than I’ve anticipated at the beginning!

I’ve also started working on the menu, but there’s nothing to show yet.

From now, I’ll probably stop doing any in-game stuff, and concentrate on the level itself and I also need some audio to play when the player collects coins, takes damage, jumps, and so on. Maybe I’ll even include some music if I’ll manage to compose something not too annoying to listen to.

Comment via email

Game1 W3/4 (again)

Sat, 22 Jul 2023 21:03:00 +0300

Who knew that writing a post about how I’ve procrastinated for two whole weeks instead of following my own challenge would be so motivating? Immediately after I posted the previous post on Monday, I regained interest and started working on physics integration. Well, making a platformer without experience turned out to be harder than I thought, though I got stuck on things that are not platformer specific.

For the first half of the week, I’ve been trying to implement collision resolution myself. This… didn’t go well, as can be seen here:

Figure 1: The green rectangles depict the area in which I check for possible collisions, and red rectangles mark tiles that collided with the player

I’ve read some tutorials on TIC’s wiki, mainly this one. It mentions how to track collisions by checking nearby squarest cells on the map grid. That was exactly my idea, but it didn’t work well, as was shown in the GIF above.

I suspect the main reason for that is that the player object moves at irregular intervals because the distance is determined by velocity, and not constant as in the tutorial. Thus, the object often overshoots or undershoots the wall and the floor, which led to the player stuck in walls, or going completely through them. It reminded me of problems I had with my previous game, where the ball often got through the platform and bricks, so after failing to do physics again I decided to use a library.

Using a library in a TIC game means that the library has to be included in the game cart because there’s no other way of shipping games for this platform - a cart is a self-contained program without external dependencies. TIC’s carts also have limited capacity so the amount of code I can include is also limited. Fortunately, there’s a small enough library called bump.lua that does AABB collision detection, which is exactly what I need for this type of game. TIC games are tile-based, so axis-aligned rectangles are exactly what I need to handle. With some trickery, it is even possible to implement slopes by using special kinds of boxes that define a slope offset based on the X coordinate.

There was a problem though. bump.lua is a Lua library, and while TIC supports Lua, I’m doing this game in Fennel. Usually, it’s not a problem, because projects written in Fennel can use Lua libraries without any issues, and technically I could have used bump.lua as a library from TIC-80 too. But, as I mentioned, TIC carts must be self-contained, and thus can’t load an external library. So I had to decide - either I port bump.lua to Fennel, or compile my Fennel code to Lua and continue the development this way. I also considered re-implementing a smaller subset of bump.lua specifically for using it in TIC with map tiles, which would probably make the library smaller and easier to handle, but I decided that I want to actually see some results of my work at the end of this month.

There was another compelling way of handling this situation though. I could have used Fennel’s -require-as-include compile flag to, well, include bump.lua as an embedded dependency, and after the development is finished compile the cart to Lua right before shipping. This would be the easiest way of doing things, as it would mean that I can do a completely normal development and use any libraries I want, but the downside is that the cart will be a hot mess of obfuscated Lua code, and I wanted the cart to actually contain something readable. Maybe I’ll try this in the future, who knows?

So, after some consideration of continuing in Lua and just copying bump.fnl code into the cart, I decided to translate bump.lua to Fennel. As much as I like Lua, Fennel is more pleasant to work with. It wasn’t that hard to do, given that there’s an excellent Lua-to-Fennel decompiler, that did most of the job. It does generate weird code here and there, calling set-forcibly! every now and then, and inserting (lua "return ") in places where Lua code had a sole return, or doing things like this:

-- original Lua code
local function sortByTiAndDistance(a,b)
  if a.ti == b.ti then
    local ir, ar, br = a.itemRect, a.otherRect, b.otherRect
    local ad = rect_getSquareDistance(ir.x,ir.y,ir.w,ir.h, ar.x,ar.y,ar.w,ar.h)
    local bd = rect_getSquareDistance(ir.x,ir.y,ir.w,ir.h, br.x,br.y,br.w,br.h)
    return ad < bd
  end
  return a.ti < b.ti
end

;; Lua decompiler result
(fn sort-by-ti-and-distance [a b]
  (when (= a.ti b.ti)
    (local (ir ar br) (values a.itemRect a.otherRect b.otherRect))
    (local ad
           (rect-get-square-distance ir.x ir.y ir.w ir.h ar.x ar.y ar.w ar.h))
    (local bd
           (rect-get-square-distance ir.x ir.y ir.w ir.h br.x br.y br.w br.h))
    (let [___antifnl_rtn_1___ (< ad bd)] (lua "return ___antifnl_rtn_1___")))
  (< a.ti b.ti))


;; cleaned version
(fn sort-by-ti-and-distance [a b]
  (if (= a.ti b.ti)
      (let [ir a.itemRect
            ar a.otherRect
            br b.otherRect
            ad (rect-get-square-distance
                ir.x ir.y ir.w ir.h ar.x ar.y ar.w ar.h)
            bd (rect-get-square-distance
                ir.x ir.y ir.w ir.h br.x br.y br.w br.h)]
        (< ad bd))
      (< a.ti b.ti)))

Code Snippet 1: e.g. here, the decompiler transformed a single-branch if into when and generated an explicit return, but a smarter decompiler could transform this into two branched if without any early returns. Conceptually these two variants are the same, except one is more like the guard-return style and another is more like actual lisp-style.

So I took some extra time to clean all set-forcibly! calls, restored the original comments which were lost during translation, and removed all instances of explicit early returns, by converting the code to use branches instead. After compiling the library back to Lua, I tested it with some demos listed in the library’s readme and it worked fine, so I hope I didn’t introduce any new bugs during the cleanup state. The next thing was to integrate it into the game.

It wasn’t that hard to do, as I just copied the whole library code into the cart, but I was worried if it will be able to handle lots of squares. My idea was to iterate over every map cell, check if it is solid or not, and if so add it to the world. Thus, each non-empty tile on the map exists in the world and acts as a collideable object. As a result, I can use the map editor basically as a level editor, as adding a tile basically is like adding a world object.

The resulting performance seems to be fine on my PC, though I’m unsure about the browser which I’ll target to make the game playable on my itch.io web page. I’m still exploring the idea of using special tile flags to make rooms longer than they seem on the map, as described in the platformer tutorial that I’ve mentioned. But this probably requires special handling when it comes to integrating it with the bump library. For now, the result (with some debug info) looks like this:

Figure 2: bump.lua in TIC-80 with some debug visualisations of collisions

The next thing to do was the camera. Now, since each object in the world has the same coordinate as the map, the only thing I need to do is implement the translation of world coordinates to screen coordinates based on player position with some slight interpolation. Fortunately enough, there’s a handy tutorial on camera movement, and while I’d like to try and implement this myself, I decided to rely on external source of wisdom.

Unfortunately, for some weird reason, the camera described in this tutorial worked differently for me. For some reason, the player sprite was drawn in the top left corner of the screen, and the camera was also positioned there. I mean, it moves correctly but is unplayable in this state. After I’ve experimented with some random numbers I’ve managed to get it to work:

Figure 3: The camera moves with a slight delay to add a bit more dynamic feel, but I didn’t go for a more proper camera implementation that tries to show more in the direction of movement yet. Also, what’s up with these GIFs generated by TIC, their size is around 10MB each, so I had to heavily compress them myself, yet they look entirely the same afterwards.

With that in place, now I need to design some levels and add more graphics, and sounds. As well, as implement actual environment interactions, such as roaming and collideable enemies, stationary hazards like spikes, health, score, and respawn systems, and maybe some other intractable objects, like coins to collect. Not sure what I’ll do first, probably the latter, as it will teach me how to add collideable items to the world that should not be treated as platforms.

Comment via email

Game1 W3/4

Mon, 17 Jul 2023 23:07:00 +0300

Long story short, no progress so far. I’m starting to think that the way I’ve set this challenge up actually mostly demotivates me to continue rather than encourages me to press forward. To say that I’ve been working on Game1 will be both a lie to myself and to you. Well, I did, but in a tinkerer’s fashion - rewriting one piece of code til I’m satisfied (except I never am).

So far I’ve managed to put sprites into the TIC-80 engine and created a simple controller, that actually doesn’t work how I expected it to, and that’s it:

Mostly because for the past two weeks I was either distracted by work or by working on a new Emacs window manager described in the last post (that, probably, no one needs, even me).

I have two weeks left (including this one), and I don’t think I’ll be able to finish this one in time, at least in its full shape. Maybe I’ll settle on a simpler thing, like a demo in which I just explore how to write a platformer, it’ll still be a good start.

Comment via email

Game1

Fri, 30 Jun 2023 22:46:00 +0300

As I stated a month ago, I’m going to force myself into game development with a personal game dev marathon¹ that will span over the next five months. Technically, nothing prevents me from jumping off at any point, so I do want this to go as smoothly as possible, so I won’t burn out until I get out at least two games. Well, we’ll see, of course - life often has its own plans for me, so… yeah.

The first game on my list is a platformer, which I wanted to be as simple as possible, e.g. basically run and jump. I have no prior experience in making platformers, so this will be an exciting thing to try! I’ve decided to go with TIC-80 for this one, to further reduce friction, as this game engine/fantasy console has everything I need to design a game.

In the previous post, I also mentioned that I was traveling, and while I wasn’t able to get to my laptop at all, I’ve decided that I will allow myself to draw some sprites for the upcoming game in advance. The only problem was that I had to do it on my phone, which is a challenge on its own, and I don’t know what software to use.

I’ve tried a bunch of options, and settled with PixelStudio by hippogamesunity. Sadly, it’s not open source, but it is common for a lot of software for pixel art, and art in general. The only open-source free software pixel art app I know is LibreSprtie, which itself is a fork of Aseprite which changed its license some years ago and is no longer FOSS. Since I was considering paying for either of those, I decided to go with PixelStudio because my phone has a stylus (S-Pen) that is supported by the app, and drawing on the screen seemed nicer. I can always bring LibreSprite on my laptop in case I need more, and TIC also has a sprite editor. TIC is also available on the phone, but unlike TIC, PixelStudio gives me the ability to do animations, which is what I was mainly looking for. If not for animations, I would probably stick with the phone version of TIC until I’ve returned.

So I went on and started working on characters for my Game1 project. Game1 is, of course, a work-in-progress title, but it’s not far from the truth, as this will probably be the first thing that I will consider something like a real game made by me. Anyway, this is how the app in which I drew my character looks:

The interface is a bit cluttered, but I find it useful enough if the screen is big enough, which is my case. But, back on character animations, here’s what I’ve got so far:

This is just a mockup, testing around how animations would look in-game. The blue fireball was added to show the damage animation, I’m not even sure if the projectiles will be in the game. And starting from tomorrow I will actually start putting things together in the TIC. I’m now realizing that by using too much color in the character sprite, I kinda limited myself on the number of colors that I can use for the background, and terrain because the default palette in TIC is quite limited on colors:

So I may need to do a bit of redesign on the character part. Actually, I’ve always liked pixel art for its limiting nature - the ability to express a lot of ideas and small details in such a low amount of pixels and colors always fascinated me. I don’t know much about pixel art, and it probably shows, but hey, this marathon is to learn new stuff, so give me some time! But, right now I’m not even sure how do I program such animations, so I’ll probably start with just drawing a rectangle for the player, enemies, and platforms.

I will be posting updates as soon as I get more progress, so expect this as a kind of dev-log, but honestly, it is mostly for me, as I find this kind of activity encouraging to keep on.

You’re welcome to join, of course, but I’m not going to organize an actual event ↩︎

Comment via email

Fennel Game Jam 2022

Sun, 12 Jun 2022 12:37:00 +0300

Quite recently a Fennel game jam happened on itch.io and I’ve decided to participate. I’ve been part of the Fennel community for some years, and every once in a while a lot of people from this community participated in a lisp game jam, but I’ve never made a game before, so I’ve skipped these events. However, when the Fennel-specific game jam was announced I decided that I must finally put myself together and participate.

The rules of the jam were quite relaxed - you basically had to use fennel for game programming, and release the game under an OSI approved license. No theme, no engine restrictions, no size requirement - an ideal situation for a programmer like me, who doesn’t know how to make a game, at all. When I was young, and I mean, like almost 20 years ago, I only toyed with Macromedia Flash and ActionScript 2.0 at my school computer class, making interactive cartoons, which can hardly be considered games. It’s not like I’m a complete stranger to game programming though, we had a very brief introduction to game programming at the university, except we never actually programmed games during these courses. So, for example, I know what delta time is, how it should be used, or how to do vector math needed for basic movement, but this doesn’t count as experience. If you read my blog, you may remember my small projects like raycasting and raymarching, which feature movement, camera programming, basic collision detection, and a basic game-loop. So actually I felt prepared when I decided to enter the jam.

I’ve already tried LÖVE2D in the mentioned raymarching example, so I’ve decided to change things up a bit since I’ve wanted to explore another project - TIC-80. The change from LÖVE2D to TIC-80 actually made it easier for me, since I could do the sprite-work and sound effects inside tic’s inbuilt editors. So I’ve begun to work on it.

I’ll try to structure this post as a series of days based on the notes I made during the event. There probably will not be any code though, as I have no early versions, since I’ve opted out of using version control systems for this project, to keep the retro vibe of the fantasy computer.

Day 1

The hardest day in my opinion because it is the day when I have to start working on a project I haven’t had any thoughts about beforehand. I’ve sat down and thought about what kind of game I can make in the limited time of the event which was going from May 25 to Jun 1st. Given 5 days and almost no game development experience, I’ve decided to play it safe and make a Breakout-like game. Though a plain breakout clone would be a bit boring, so I’ve decided that I’ll put a small twist once you destroy the final block which would shake things a bit and hopefully be a welcome surprise.

Now, since the theme was chosen I at least knew what I needed to start - a ball, a platform, and a box to bounce the ball to prevent it from flying away to infinity. But I didn’t know how to do anything in tic, so I’ve opened up a manual. The manual is minimalist, to say the least, and doesn’t provide a lot of info beyond essential things. So I’ve picked up the circ rect and rectb functions and started working. This was my first result:

Your browser does not support the video tag.

This has very basic hard-coded physics, meaning that I’ve literally defined a vector of all ball velocities and just cycled through it when the ball collided with any world object. But it already has some interesting stuff done, which I haven’t changed much afterward.

The first thing is that It has a proper world to screen coordinate transformation, which I’ve kinda never done before. It’s a simple thing, I just have a world X and Y offsets that made the game world, e.g. the box rest, not in the top left corner but 10 pixels to the right and down. All game physics was calculated with the top left corner in 0,0 and then translated before drawing.

The platform tracks its position and makes sure not to go outside the world boundaries. And the ball is checked for collisions with everything but the lower boundary. There, instead of a collision a basic game-over? flag is set to interrupt the game loop.

I was pretty satisfied for day one, especially since it wasn’t really a full day of me programming this, but only 3 hours after work. The jam started at 10:00 AM in my time zone, and my work day also starts at the same time, so I had to begin working on a game 9 hours after the start of the jam. I’m sure this is a common situation for most other participants, though perhaps they have had time before work too.

Day 2

I knew that I’ll not be able to move forward with the current physics system I’ve added to the game, so I spent most of the second day fighting with the collision system. This was the result I got:

Your browser does not support the video tag.

This had really wonky surface normal calculations, and you can see that the ball isn’t particularly happy with the results, as it just decides to leave the game. I wasn’t happy with it either, but it was a move in the right direction.

In addition to improved physics, I’ve added destructible bricks with a random amount of health represented by a color. The color was an accident, as I used brick health in place of the brick color when bricks were drawn on the screen, but I actually liked it. The health was distributed randomly, but I’ve been focused on physics, so I’ve left it as is.

There were two main problems. First, I’ve re-used some linear algebra code from my raymarching project, mainly the calculation of the distance to the box and the calculation of the normal. However, the calculation of a normal was done for a 3D world and wasn’t as meaningful for 2D space. I’m not sure whether I’ll be able to explain the general method, but the idea is that I’ve found an intersection point, and picked two more points one below the surface and to the left and another above the surface and to the right. Then I used some vector math to find a normal based on distance estimation from these points to the intersection point. This works quite well for 3D, given that all reflections in the raymarching demo were correct, but in 2D it resulted in weird unexpected reflections (not in the video).

Unfortunately, I have this kind of problem that once I’ve fixated on some solution I can’t see another one until I step away from the problem for a bit. So I’ve kept the current physics and ended the day 2 session.

Day 3

This day was mostly spent polishing and rewriting the collision system. I’ve almost fully fixed bugs with unexpected angles, but the ball still managed to find its way inside the platform. I couldn’t spend too much time on it, so I’ve decided to leave it as is, and maybe fix it after everything else is done.

In addition to that, I’ve made it such that the block health depends on the row it was spawned at. So the lower blocks had 1 health, the next row above it had 2 health, and so on. This can be seen with this nice color transition from purple to orange.

Your browser does not support the video tag.

I’ve also done some basic point systems that added 100 points when you destroy a brick, and 10 points upon collision. There are now lives, so you can lose the ball several times before the “game over”. Satisfied with that I’ve ended the third day, realizing that theirs not that much time left, but also not too far til the game will be complete.

For the next two days, I was planning to add graphics and a small twist that will hopefully make the game a bit more interesting.

Day 4

Up until this day I’ve drawn everything with basic rectangles and this wasn’t going to cut for the jam in my opinion. So for the fourth day, I’ve decided to focus on some graphics and sounds.

The inbuilt sprite editor is quite good, actually. I’ve only tried the LibreSprite, an open-source fork of aseprite sprite editor, and it was a bit sluggish, perhaps because it was using a software cursor, which felt unresponsive. But with TIC’s sprite editor it wasn’t a problem and I quickly drew basic sprites for bricks, the platform, and the ball:

Figure 1: Sprites

Then I decided to add power-ups.

There are three classic power-ups that affect the size of the ball or the platform - the big ball, the long platform, and the short platform. All these powers are timer-based, with a small exception for the big ball - if you lose the ball while it’s big, the power-up is also lost. In addition to that, there are two speed-related power-ups, one that increases the ball’s speed, and one that decreases it.

Speaking of speed, I’ve also made it so that the speed of the ball gradually grows during the game up to twice the initial speed. And there’s a mentioned power-up to increase and decrease the value by a quarter.

Here’s a demonstration of various power-ups:

Your browser does not support the video tag.

As can be seen, the ball still can act weirdly, almost spinning around the platform, but I’ve already spent most of my time on graphics and sounds, so I’ve decided to left it for the last day.

Day 5

The last day of the jam! I’ve added more graphics, as I wasn’t able to figure out how to measure things in seconds, as the values of the time function were kinda weird. So I’ve opted out of colored bars that gradually decrease in length. I’ve also decided to add some effects, like screen shake when the ball is big. Here’s how it looks:

Your browser does not support the video tag.

At this point, I’ve started working on the twist and polishing things out. For the twist I’ve decided to do a boss battle at the end of the game, essentially turning the Breakout game into Pong when the last brick is destroyed:

Your browser does not support the video tag.

The boss has a fixed amount of health, and each hit with the ball removes some amount of it. If the big ball power-up is active the ball deals twice the damage. I’ve actually made it that this damage multiplier also affects bricks, so bricks are destroyed a bit faster now too. And if you score the boss, it’ll lose 5 times hp of a single hit, although it’s almost impossible, unless you picked a lot of speed power-ups.

Boss’ health is represented with another bar that changes color depending on the health range, going from green at full to red near the end. To win the game you must defeat the boss, which is actually a bit tricky and I can’t do it consistently myself either. Speaking of power-ups, there’s a random chance to spawn a power-up in a random location during the boss battle. The chance of spawning is very low though.

I’ve uploaded the game to itch as a web build, and noticed a weird problem. All power-ups were wearing off too fast! I couldn’t understand what the problem is, because to my knowledge I did a proper way of handling power-up times - I obtained the current game-time with the call to the time function, added a fixed amount to it, and checked on each frame if the value returned by time surpassed it. To simplify, upon activation of a timer based power-up, I did this end = time() + powerup_duration, and checked for end < time() to disable the power-up. Given that it is based on time and not on some ticking mechanism, I’ve thought that it should work equally well regardless of frames per second. Even more weird was that the ball speed was the same as on the desktop. So in short - power-ups ended a lot faster, yet the rest of the speed was the same.

I’ve decided to do it “properly” and calculated the delta time. Then I multiplied ball movement by newly calculated dt and reworked power-ups to work based on ticks, meaning they weren’t tied to time directly. Checked that all works well on my desktop I’ve made a fresh web build, uploaded it to itch, and it was way too fast! The ball speed now was superfast, power-ups ended almost immediately. After a ton of debugging, and trying to make any sense out of the phrase that the main TIC function is called 60 times per second, when it clearly wasn’t, as the game speed was different between the web and Linux builds. Then I made a Windows build, and it worked with the same speed as the web build, and I thought that maybe it was a bug in the Linux build. I’ve checked what value of dt was calculated on each platform, and the Linux build had a 10-fold difference from other platforms:

Figure 2: Delta time differences between platforms

The Linux build had a delta time value of approximately 0.001 while the web and Windows build had 0.02. I’ve tried an older version of TIC, and it had no such issue but didn’t support the Fennel version I was using for the game. So I had to distribute the game only as a web build until the issue is fixed. I’ve tweaked the speed by adding a game_speed parameter that I could tweak around inside the web build to make the speed feel right. After that, I pushed a final web build with these tweaks and submitted the game.

Jam results

Because of my time zone, I was the first who submitted a game, but I couldn’t do any more work because the last hours of the jam were at nighttime here. Out of 21 participants, only seven games were submitted, which actually a pretty great result, in my opinion, it’s a solid third! Funnily enough, we have about 60 people in our #fennel IRC channel on Libera.Chat, so 21 people is a third too. The results can be viewed here, and I suggest you try all games, as there are pretty cool entries!

I managed to score third place, which actually surprised me a bit, given how simple the concept of my game was. But I’m glad, and I think it’s a solid result for the first game.

In retrospect, I think I could do some things better, especially in the user interface department. Adding a proper menu, maybe an intro, making the interface look more like an arcade cabinet, which I’ve originally attempted, but my pixel-art skills are not that great yet. But I still like the result, I feel that for a first game it turned out pretty great. And the process was quite fun, which is the most important thing for me.

I hope I’ll participate in more lisp-themed jams, maybe in a lisp game jam or the next Fennel jam. I’ve always wanted to make games, and I had some ideas about the game I want to make in the Metroidvania genre. Game jams are perfect for experiments, and you can learn a lot by doing things you never did before. I’m not going to make a whole game during the jam as I want it to be a more complete thing, but the jam can help me to flesh out some main mechanics, be it the movement, or world-building practice. So I’m looking forward to the upcoming events!

This was a lot of fun, and I hope more people will join next time! Thanks to everyone who participated, Matt Roelle for organizing the Jam, and everyone involved in Fennel and TIC-80 development.

Comment via email

Wave Function Collapse Algorithm in ClojureScript

Tue, 10 May 2022 08:20:00 +0300

The last time I touched ClojureScript was almost two years ago. It was a really fun experience, and actually, it was a bit special to me personally. Prior to that post, I only learned lisp¹ via books and mostly used it only for configuring Emacs, and while I’ve liked the idea of code as data and other lisp aspects, I never did anything more with the language. So this was the first thing that I’ve done in lisp from start to finish, the first thing done in Clojure, the first interactive thing with some sort of visualizations. And this is pretty much the reason I fell in love with Clojure and not with another dialect - I’ve used it for something real, not just an exercise for the book, and I liked the syntax, the data structures, immutability, laziness, and other features. Since that post I’ve got a job in Clojure, so now it’s my primary programming language and I love it still. However, I have a lot less experience with ClojureScript, mainly because I mostly do backend development, and we have a separate team working on the frontend part.

I like games, but I’ve never actually done anything more than simple demos of various game algorithms and techniques². And I mostly did it in Fennel, because it’s also a very nice lisp-like language with a very similar syntax to Clojure. I wanted to do more, but I wanted these experiments to be a bit more reachable, and possibly viewed directly in my blog, as it was with the raycasting example. So I knew that I wanted to do something with ClojureScript instead of Fennel, which became my main language for this type of thing. Another reason is that I’m thinking about doing some frontend programming in ClojureScript in the upcoming years.

Luckily for me, not so long ago I found a really neat algorithm for generating worlds. The algorithm is called Wave Function Collapse, and it actually has nothing to do with quantum physics. In this post, I’ll try to walk you thru the algorithm, and explain how I’ve approached this problem.

The algorithm

What makes this algorithm different from most procedural generation algorithms I’ve read about is that it is extremely simple. It can generate images based on a small sample of data, as shown below:

Figure 1: Example Input

Figure 2: Generation result

However, just implementing the algorithm from some description isn’t fun. What I like to do, and this is a general approach I use for all my projects, is to get some assumptions about the thing I want to implement, and then do everything based on these assumptions only³. So instead of learning how the algorithm is implemented, I’ve just observed its behavior with simple input.

For example, let’s look again at the input sample, but let’s split it into tiles with a grid:

Figure 3: Sample

This sample specifies that for each tile on this image there are only so many possible neighbors. For example, this tile in the middle can only have one unique neighbor on each of its sides:

Other tiles may have two or more unique neighbors, and the job of the algorithm is to analyze each tile on the image, and track what neighboring cells it has, storing it into a ruleset. And an image is then generated based on these adjacency rules only.

This is basically what I knew about the algorithm when I started implementing it. Of course, it’s not that simple, but it’s still easy to grasp, and some nuances become apparent when you actually start working on it. I’ll give the algorithm a more comprehensive explanation a bit later, as we’ll encounter problems.

Text version of the algorithm

For this project, I once again picked shadow-cljs, so the project can be created with npx create-cljs-project wave-function-collapse. But before actually working with images we can begin with a bit simpler to debug version of it which deals with an ordinary text. This can be done in plain Clojure, but since we’ll later plug it into our page, let’s use .cljs file. We start by implementing our algorithm in the file wfc.cljs, wfc being short for wave function collapse.

As I’ve explained in the previous section, we start by transforming an input into a set of rules for the algorithm. Our input will be a two-dimensional matrix, in this case, an array of arrays of strings. Let’s start with a similar sample to that I’ve shown in the previous example:

(def coast
  [["🟫" "🟫" "🟫" "🟫"]
   ["🟩" "🟫" "🟫" "🟩"]
   ["🟦" "🟩" "🟩" "🟦"]
   ["🟦" "🟦" "🟦" "🟦"]])

It’s even simpler, as it doesn’t have tiles that represent corners. The first thing we need to do is to define a function, that gets all neighboring cells in all cardinal directions:

(defn get-neighbors [m x y]
  (->> {:up [(dec x) y]
        :down [(inc x) y]
        :left [x (dec y)]
        :right [x (inc y)]}
       (into {}
             (keep (fn [[dir pos]]
                     (when-some [cell (get-in m pos)]
                       [dir {:pos pos :cell cell}]))))))

This function gets only those cells inside our matrix and discards those that are outside of its boundaries. With this function we can write a function that builds a recipe from the input sample:

;; add [clojure.set :as set] to :require
(defn build-recipe [sample]
  (->> sample
       (map-indexed
        (fn [x r]
          (map-indexed
           (fn [y c]
             (let [neigbors (into {}
                                  (map (fn [[dir {:keys [cell]}]] [dir #{cell}]))
                                  (get-neighbors sample x y))]
               {c neigbors})) r)))
       flatten
       (apply merge-with #(merge-with set/union %1 %2))))

I’m using map-indexed because we need to get neighbors for each cell, and this is what our get-neighbors function accepts. Calling this function on the coast recipe yields the following map:

{"🟫" {:up #{"🟫"}
       :down #{"🟫" "🟩"}
       :left #{"🟩" "🟫"}
       :right #{"🟫" "🟩"}}
 "🟩" {:up #{"🟫"}
       :down #{"🟦"}
       :left #{"🟫" "🟦" "🟩"}
       :right #{"🟫" "🟦" "🟩"}}
 "🟦" {:up #{"🟩" "🟦"}
       :down #{"🟦"}
       :left #{"🟩" "🟦"}
       :right #{"🟦" "🟩"}}}

Now we have a proper illustration of the adjacency rules we’ve talked about before. With that, we can start implementing the algorithm itself.

Collapsing cells

In order to collapse anything, we need a world in which we’ll do our work. The beauty of this algorithm lies in the fact that it can work with a partially filled world, but generally, the world starts in a so-called superposition. To get this superposition, we need to analyze the input sample once again:

(defn get-superposition [sample]
  (into #{} (flatten sample)))

This gives us all possible variants for a single cell. To define a world we can just generate a new “empty” matrix that we’ll later populate with a cell superposition state.

(defn gen-world [max-x max-y]
  (mapv vec (for [_ (range max-x)]
              (for [_ (range max-y)] nil))))

(defn populate-world [world sample]
  (let [superpos (get-superposition sample)]
    (mapv (fn [r] (mapv (fn [c] (if (nil? c) superpos c)) r)) world)))

As the last preparation step, we need a way of checking if the world is fully built. This can be done by checking if any of the cells is still a hash-set and not a concrete value:

(defn done? [world]
  (not (some set? (flatten world))))

A more optimal way would be to track how many cells were fully collapsed and compare it with the world size to avoid walking the whole world repeatedly on each step, but for now, this will do. The last preparation step we need to do is to write a function that chooses which cell to collapse next. The first cell can be selected at random, but the following must be selected more carefully, or we’ll corner ourselves pretty quickly. To do that we need to measure world entropy and select a cell with the lowest one. Since every cell can only contain a set of unique elements, we can measure the entropy by counting the number of elements in a cell. Thus, a function that returns the lowest entropy cell can be defined as follows:

(defn lowest-entropy-cell [world]
  (let [enthropies (->> world
                        (map-indexed
                         (fn [x r]
                           (keep-indexed
                            (fn [y cell]
                              (when (set? cell)
                                [(count cell) [x y]])) r)))
                        (apply concat)
                        shuffle
                        (sort-by first))]
    (if-some [c (first enthropies)]
      (second c)
      [0 0])))

This will produce uniform distribution, so we might want to change it a bit later, but for now, it’ll do.

Now to the meat and bones of the algorithm. To actually collapse a cell we need a function that can choose a random element of a cell:

(defn collapse
  [world x y val]
  (if (and (coll? val)
           (= 1 (count val)))
    (assoc-in world [x y] (first val))
    (assoc-in world [x y] val)))

After the cell is collapsed, we need to constrain its neighbors, so their superposition only contained possible elements that can be connected to this cell. This is a bit harder part of the algorithm, as it involves waling a grid of cells recursively and constraining every cell that is a set and skipping others that are not. If a cell itself is a set, its content should be treated as a series of cells that also affect how the surrounding cells should be constrained:

(defn collapse-neighbors
  [world recipe x y]
  (let [cell (get-in world [x y])
        neighbors (get-neighbors world x y)
        neighboring-cells (shuffle (map :pos (vals neighbors))) ; ❶
        world' (reduce
                (fn [world [dir {[x' y' :as pos] :pos}]]
                  (let [c (get-in world pos) ; ❷
                        variants (set/intersection
                                  (if (coll? c) (set c) #{c})
                                  (if (set? cell)
                                    (apply set/union (map #(get-in recipe [% dir]) cell))
                                    (get-in recipe [cell dir])))] ; ❸
                    (if (and (set? c) (seq variants))
                      (collapse world x' y' variants) ; ❹
                      world)))
                world neighbors)]
    (if (= world' world)
      world
      (reduce (fn [world [x y]]
                (collapse-neighbors world recipe x y))
              world' neighboring-cells)))) ; ❺

This function is the heart of the algorithm, as it does all of the heavy liftings on constraining cells, so let’s break it down. First, we get all neighbors and extract a sequence of cells that we’re going to constrain (❶). We then iterate over these neighbors inside reduce, getting the current world state for this cell (❷). For this cell, we need to compute all remaining variants. This is done by intersecting this cell’s state with variants from a neighbor in a given direction. And if the cell itself is a set, this is done for each element in a set (❸). Finally, a cell is collapsed (❹), except when it was a set and the variant list wasn’t empty.

After that process is done for all four neighbors, we need to repeat it for each of the neighbors’ neighbors. So we check if our last run actually produced any change in the world, and if it is, we recursively walk through these neighbors (❺), otherwise, we return current world state. This may actually cause a stack overflow error if there are too many neighbors to collapse, which depends both on the world size and how general the recipe is. To avoid that, this function can be turned into iterative, but it still will maintain the stack of neighbors to collapse, which will grow in memory, instead of on a stack. I’ve decided to go with recursion, as it’s a bit easier to understand in the context of the post.

The last bit needed is a loop that will repeat this process until the whole world is collapsed. The process is:

pick a cell with the lowest entropy, first one is random
collapse it
constrain neighbors
check if not done
- repeat

Here’s the code:

(defn wfc [world sample]
  (let [recipe (build-recipe sample)]
    (loop [world (populate-world world sample)
           [x y] [(rand-int (count (first world)))
                  (rand-int (count world))]]
      (if-not (done? world)
        (let [cell (get-in world [x y])
              world (-> world
                        (collapse x y (rand-nth (vec cell)))
                     (collapse-neighbors recipe x y))]
          (recur world
                 (lowest-entropy-cell world)))
        world))))

Now, we can actually try it! Let’s create some helpers, that will print the resulting world, and the input recipe:

;; add [clojure.string :as str] to :require

(defn print-sample [sample]
  (->> sample (map str/join) (str/join "\n") (println)))

(defn print-world
  ([world] (print-world world ""))
  ([world sep]
   (->> world
        (map #(map (fn [c] (if (set? c) "?" c)) %))
        (map #(str/join sep %))
        (str/join "\n")
        (println))))

(defn print-result [sample world]
  (println "sample:")
  (print-sample sample)
  (println "gen:")
  (print-world world))

Now, if we use our coast recipe, we should see this in our REPL:

wfc.wfc> (print-result coast (wfc (gen-world 16 16) coast))
sample:
🟫🟫🟫🟫
🟫🟫🟫🟫
🟫🟫🟫🟫
🟫🟩🟩🟫
🟩🟦🟦🟩
🟦🟦🟦🟦
🟦🟦🟦🟦
gen:
🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫
🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫
🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫
🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫
🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫🟫
🟫🟫🟫🟫🟫🟫🟫🟩🟫🟫🟫🟫🟫🟫🟫🟫
🟫🟫🟫🟫🟫🟫🟩🟦🟩🟫🟫🟫🟫🟫🟫🟫
🟫🟫🟫🟫🟫🟩🟦🟦🟦🟩🟫🟫🟫🟫🟫🟫
🟫🟫🟫🟫🟩🟦🟦🟦🟦🟦🟩🟩🟫🟫🟫🟫
🟫🟫🟫🟩🟦🟦🟦🟦🟦🟦🟦🟦🟩🟫🟩🟩
🟫🟫🟩🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟩🟦🟦
🟩🟩🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦
🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦
🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦
🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦
🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦

We can try with a bit more interesting examples, like these trees:

(def snowy-trees
  [["*" " " " " " " " " "*" " " " "]
   [" " " " " " " " " " " " " " "*"]
   [" " " " "*" "╱" "╲" " " "*" " "]
   ["*" " " "╱" "v" "v" "╲" " " " "]
   [" " "╱" "v" "v" "v" "v" "╲" " "]])

wfc.wfc> (print-result snowy-trees (wfc (gen-world 16 60) snowy-trees))
sample:
*    *
       *
  *╱╲ *
* ╱vv╲
 ╱vvvv╲
gen:
 *  *  *   *   *      *   *     *    *   *  * *    * *  *  *
   *  *  *    * * * *   *  * *    *    *     *  * * *  *
 *      *      *              *  *       * *   *   *  * * *
  * * *   *   * * *  * *  *     *    * *  *   * *      * *
 *   *   *   * *   *  *  *  * *  *  *   *  * * * *        *
   *    *  *      *       *  *  *  *  *  *    * * *
 *        * * *  *  *  * *     *  * *     * *      * * * * *
  *  *  *    *  * *  *     *  *  * *  *  * *    *   *   * *
         * *   * * *      *    *  *     * *  * *  ╱╲  *  *
   *  * * *   *       *  *    *      *        * *╱vv╲  *   *
*   *  *   * *     * * *   *     *  *  * *  *  *╱vvvv╲
  *   *   * *   * *     *   *   *  *    * *  * ╱vvvvvv╲
 *  *   *     *   ╱╲ *    *   *   *  ╱╲  *  * ╱vvvvvvvv╲ *
         *     * ╱vv╲ *  *  ╱╲ * * *╱vv╲   * ╱vvvvvvvvvv╲ *
 *   *     *    ╱vvvv╲  * *╱vv╲ * *╱vvvv╲ * ╱vvvvvvvvvvvv╲
*  ╱╲ *  ╱╲  * ╱vvvvvv╲   ╱vvvv╲ *╱vvvvvv╲ ╱vvvvvvvvvvvvvv╲

Noticeable, the spread is too uniform. This is because we pick a random choice, and the choices have equal distribution. Instead, it’d be nicer if we had a bit more control over what elements are more present and what is less present.

To do that, we need to replace our random choice picking with weighted random. First, we need to calculate the weights:

(defn sample-weights [sample]
  (frequencies (apply concat sample)))

This will do - the more times a certain tile appears in a recipe, the higher its weight is. Now we need a weighted random:

(defn weighted-random [elements weights]
  (let [variants (reduce (fn [m k] (assoc m k (weights k))) {} elements)
        weights (reductions #(+ % %2) (vals variants))
        rnd (rand-int (last weights))]
    (nth (keys variants) (count (take-while #(<= % rnd) weights)))))

And now, that we have weights, we can upgrade our lowest-entropy-cell function to take weights into account when calculating the entropy. We also use a better entropy calculation algorithm, based on Shannon entropy:

(defn cell-enthropy [cell weights]
  (let [weight-sum (reduce + (map #(get weights %) cell))
        log-weight-sum (reduce + (map #(let [weight (get weights %)]
                                         (* weight (Math/log (double weight)))) cell))]
    (Math/log (- weight-sum (/ log-weight-sum weight-sum)))))

(defn lowest-entropy-cell [world weights]
  (let [enthropies (->> world
                        (map-indexed
                         (fn [x r]
                           (keep-indexed
                            (fn [y cell]
                              (when (set? cell)
                                [(cell-enthropy cell weights) [x y]])) r)))
                        (reduce into (sorted-map)))]
    (if-some [[_ c] (first enthropies)]
      c
      [0 0])))

The last change needed is in the wfc function - we need to use weighted-random when we collapse a cell:

(defn wfc [world sample]
  (let [recipe (build-recipe sample)
        weights (sample-weights sample)]
    (loop [world (populate-world world sample)
           [x y] [(rand-int (count (first world)))
                  (rand-int (count world))]]
      (if-not (done? world)
        (let [cell (get-in world [x y])
              world (-> world
                     (collapse x y (weighted-random cell weights))
                     (collapse-neighbors recipe x y))]
          (recur world
                 (lowest-entropy-cell world weights)))
        world))))

Now the algorithm is done, and we can see that the snowy-trees example has a bit less snow now:

wfc.wfc> (print-result snowy-trees (wfc (gen-world 16 60) snowy-trees))
sample:
*    *
       *
  *╱╲ *
* ╱vv╲
 ╱vvvv╲
gen:
   *    *    *   *  *       *      *           * *         *
  *        *    *         *     *       *       * *   * *
       *      *        *   *         *    *   *    *   *
   *                *        *     *  *    *     *   *   *
*             *  * *      *          *       *
           *           *   *    *       * *             *  *
              *  *    *            *   *      *      *
    *     *  *     * *     *    *    *     *           * *
   * *     *          * *   *  *
          *    *       *  *       *   * *   *     *  * *
  * *       * *    * *   *     *   * * *            *   *
       *   *    *                 *      *        ╱╲ *     *
      *      *        * *            *      *  * ╱vv╲
     * ╱╲            *    * *          *  *     ╱vvvv╲
      ╱vv╲   ╱╲  *       *      *        *  *  ╱vvvvvv╲
  *  ╱vvvv╲ ╱vv╲   ╱╲  *  * *           * *  *╱vvvvvvvv╲  *╱

Working with images

At the beginning of this article, I’ve shown you an image of a coast. This image is generated by the code above, but right now it can’t handle images, only text. This isn’t a problem, really, because the text is just used in place of unique identifiers, so we can plug in anything, and then use the resulting world as a recipe to paint it on a canvas. Let’s do exactly that, but before we can do it, we need to be able to upload an image and splice it into tiles.

To do that, we’ll need an index.html file in our public/ directory, and a <canvas> tag in it with an appropriate id:

<canvas id="sample_view" width="512" height="512"></canvas>
<input type="file" id="sample_input" accept="image/*"></input>

<script type="text/javascript" src="/js/main.js"></script>
<script>
  window.onload = function() {
    wfc.core.init();
  }
</script>

I’m also adding an <input> tag, to open an image. Additionally to that, there should be the <script> tag that loads our core module and runs the init function. With this in place, we can add an event listener to the button, and load the image to canvas. In core.cljs add:

(ns wfc.core
  (:require [wfc.sample :as sample]))

(defn ^:export init []
  (when-let [sample-input (.getElementById js/document "sample_input")]
    (.addEventListener sample-input "change" sample/upload)))

And in sample.cljs create the upload function:

(defonce ^:dynamic *image* {:image nil
                            :width 0
                            :height 0})

(defn draw [event]
  (when-let [viewer (.getElementById js/document "sample_view")]
    (let [image (js/Image.)
          ctx (.getContext viewer "2d")
          handler (fn []
                    (let [width (.-width image)
                          height (.-height image)]
                      (set! *image* {:image image
                                     :width width
                                     :height height})
                      (set! (.-width viewer) width)
                      (set! (.-height viewer) height)
                      (.clearRect ctx 0 0 (.-width viewer) (.-height viewer))
                      (.drawImage ctx image 0 0)))]
      (.addEventListener image "load" handler)
      (set! (.-src image) (-> event .-target .-result)))))

(defn upload [event]
  (when-let [files (-> event .-target .-files)]
    (let [reader (js/FileReader.)]
      (.addEventListener reader "load" draw)
      (.readAsDataURL reader (aget files 0)))))

This should allow us to upload an image. Now we need to split it into tiles. To do that, let’s add another button to our index.html:

<button type="button" id="split_to_tiles">Split to tiles</button>

In core.cljs we add another event listener:

(ns wfc.core
  (:require [wfc.sample :as sample]))

(defn ^:export init []
  (when-let [sample-input (.getElementById js/document "sample_input")]
    (.addEventListener sample-input "change" sample/upload))
  (when-let [tile-size (.getElementById js/document "split_to_tiles")]
    (.addEventListener tile-size "click" sample/split-to-tiles))
  (when-let [render-button (.getElementById js/document "render")]
    (.addEventListener render-button "click" render/render)))

And define the function that does the work:

(defonce ^:dynamic *sample* [])
(defonce ^:dynamic *tiles* {})

(defn split-to-tiles [_]
  (if (:image *image*)
    (let [canvas (.createElement js/document "canvas")
          _ (set! (.-width canvas) (:width *image*))
          _ (set! (.-height canvas) (:height *image*))
          ctx (.getContext canvas "2d")
          _ (.drawImage ctx (:image *image*) 0 0)
          hashes-imgs (for [x (range 0 (:width *image*) 32)]
                        (for [y (range 0 (:height *image*) 32)]
                          (let [img (.getImageData ctx x y 32 32)]
                            [(hash (vec img.data)) img])))]
      (set! *sample* (mapv #(mapv first %) hashes-imgs))
      (set! *tiles* (into {} (apply concat hashes-imgs))))
    (js/alert "Please upload an image first")))

We do basic error checking, that an image was uploaded by checking *image* to have anything under the :image key. If there’s an image, we create a canvas, that we draw this image on, and then iterate thru it row by row, tile by tile, with a fixed tile size of 32. In this loop, we get an array of pixels, representing the given tile, and we calculate its hash, which we will use in our wave function collapse algorithm.

Now we can upload an image, and split it into tiles, the only thing left is to actually draw the result!

Drawing the result

We need yet another canvas for that. Actually, we need only one canvas for all of this, as we have the input button that takes care of image loading, and another button for splitting. But I still like to see what sample is loaded, as it gives a better understanding of what the resulting image was constructed from. So let’s add another canvas and a button:

<canvas id="render_view" width="512" height="512"></canvas>
<button type="button" id="render">Generate</button>

Once again, let’s add a handler to this button in core.cljs:

(ns wfc.core
  (:require [wfc.sample :as sample]
            [wfc.render :as render]))

(defn ^:export init []
  (when-let [sample-input (.getElementById js/document "sample_input")]
    (.addEventListener sample-input "change" sample/upload))
  (when-let [tile-size (.getElementById js/document "split_to_tiles")]
    (.addEventListener tile-size "click" sample/split-to-tiles))
  (when-let [render-button (.getElementById js/document "render")]
    (.addEventListener render-button "click" render/render)))

And in render.cljs we need to define the render function:

(ns wfc.render
  (:require [wfc.sample :as sample]
            [wfc.wfc :as wfc]))

(defn render [_]
  (if (:image sample/*image*)
    (when-let [renderer (.getElementById js/document "render_view")]
      (let [ctx (.getContext renderer "2d")
            width (.-width renderer)
            height (.-height renderer)]
        (.clearRect ctx 0 0 width height)
        (solve ctx width height)))
    (js/alert "Please upload an image")))

Nothing too complicated, just a handler that clears the canvas and calls solve. Now, solve is where the work is done:

(defn solve [ctx width height]
  (if (seq sample/*sample*)
    (let [tiles sample/*tiles*
          size 32]
      (loop [world (wfc/wfc (wfc/gen-world (/ width size) (/ height size)) sample/*sample*)
             x 0]
        (when-let [[row & rows] world]
          (loop [row row
                 y 0]
            (when-let [[cell & cells] row]
              (draw ctx (get tiles cell) x y size)
              (recur cells (+ y size))))
          (recur rows (+ x size)))))
    (js/alert "Please split image to tiles")))

First, we compute the result with wfc call, and then we iterate over it calling draw for each cell. The tile is retrieved from the *tiles* variable, we’ve set in sample.cljs when we split the image.

The draw function is simple - it accepts an image, coordinates where we need to draw it, the size, and the canvas’ context. Then it just draws the image:

(defn draw [ctx image x y size]
  (let [arr (js/Uint8ClampedArray. image.data)
        place (.getImageData ctx x y size size)]
    (.set (.-data place) arr)
    (.putImageData ctx place x y)))

The result will probably look a bit different, but the general idea is the same:

You can use this image to try the whole process:

Figure 4: coast

Alternatively, you can try other samples, just beware that the tile size is fixed to 32x32 pixels.

A proper demo

I’ve actually omitted some more things on the JS side, as the post already got a bit to long even after we’ve finished the algorithm. Things like configurable tile size, and custom world sizes, better error handling can be added, it’s just mostly the same stuff we already did for other buttons, and thus can get repetitive pretty quickly. So instead I’ve set up a separate page with a better visuals, tile picker, editor, some additional examples to try, and more robust error handling. You can try it here. And a bit more polished code can be found in the repo for that demo page.

I know that this isn’t how ClojureScript is used in production, but it’s still nice that you can build such pages pretty quickly, using your favorite language. In the future I’ll probably learn some proper frontend related stuff, like Lumen or re-frame, but this is a thing for another time. Hope this was an interesting read!

I’m saying lisp as in the language not as in concrete implementation. To be clear, I’ve worked my way thru SICP, and mostly used Racked or GNU Guile, not Common Lisp, so I’m not biased on what is lisp, and I accept Clojure as a valid dialect, even if some may disagree. ↩︎
This includes LÖVE Fabrik, raymarching, raycasting. ↩︎
This is the approach I’ve taken when I’ve implemented my first Scheme-like language, condition-system, a library for asynchronous programming, raymarching algorithm, and many other projects. I think I find this approach fascinating because when the thing finally works, and I go and look how it should be done, and see that I’ve got some things right, it gives me a lot of joy. This also trains to think outside of the box, and solve problems that you don’t exactly know how to solve. ↩︎

Comment via email

Raymarching with Fennel and LÖVE

Thu, 15 Oct 2020 20:33:00 +0300

Previously I decided to implement a rather basic raycasting engine in ClojureScript. It was a lot of fun, an interesting experience, and ClojureScript was awesome. I’ve implemented a small labyrinth game and thought about adding more features to the engine, such as camera shake, and wall height change. But when I started working on these, I quickly understood, that I’d like to move on to something more interesting, like a real 3D rendering engine, that also uses rays. <!–more–> Obviously, my first thought was about writing a ray-tracer¹. This technique is widely known and gained a lot of traction recently. With native hardware support for ray tracing, a lot of games are using it, and there are a lot of tutorials teaching how to implement one². In short, we cast a bunch of rays in 3D space, and calculate their trajectories, looking for what ray will hit and bounce off. Different materials have different bounce properties, and by tracing rays from the camera to the source of light, we can imitate illumination. There are also a lot of different approaches how to calculating bouncing, e.g. for global illumination, and ambient light, but I’ve felt that it is a rather complicated task, for a weekend post. And unlike raycasting, most ray-tracers require polygonal information in order to work, whereas raycasting only needs to know wall start and end points.

I’ve wanted a similar approach for 3D rendering, where we specify an object in terms of its mathematical representation. Like for a sphere, we’ll just specify coordinates of a center, and a radius, and our rays will find intersection points with it, providing us sufficient data to draw this sphere on screen. And recently, I’ve read about a similar technique, that uses rays for drawing on the screen, but instead of casting infinite rays as in raycasting, it marches a ray in terms of steps. And it also uses a special trick, to make this process very optimized, therefore we can use it for rendering real 3D objects.

I’ve decided to structure this post similarly to the one about raycasting, so this will be another long-read, often more about Fennel rather than raymarching, but at the end, I promise that we’ll get something that looks like this:

So, just as in raycasting, first we need to do is to understand how the raymarching engine works on paper.

Raymarching basics

Raymarching can be illustrated similarly to raycaster, except it requires more steps until we could render our image. First, we need a camera, and an object to look at:

Our first step would be to cast a ray, however, unlike with raycasting, we’ll cast a portion of a ray:

We then check if the ray intersects with the sphere. It’s not, so we do one more step:

It’s not intersecting yet, so we repeat again:

Oops, the ray overshot and is now inside the sphere. This is not really good option for us, as we want our rays to end directly at the object’s surface, without calculating the intersection point with the object itself. We can fix this by casting a shorter ray:

However, this is very inefficient! And besides, if we’ll change the angle a bit or move the camera, we will overshoot again. This means that we’ll either have an incorrect result or require a very small step size, which will blow up the computation process. How we can fix this?

Distance estimation

The solution to this is a signed distance function or a so-called Distance Estimator. Imagine if we knew how far we are from the object at any point in time? This would mean that we can shoot a ray of this length in any direction and still don’t hit anything. Let’s add another object to the scene:

Now, let’s draw two circles, which will represent distances from the objects to the point from where we’ll cast rays:

We can see, that there are two circles, and one is bigger than another. This means, that if we choose the shortest safe distance, we can safely cast rays in any direction and not overshoot anything. For example, let’s cast a ray towards the square:

We can see, that we haven’t reached the square, but more importantly, we did not overshoot it. Now we need to march the ray again, but what distance should it cover? To answer this question, we need to take another distance estimation from the ray end to the objects in the scene:

Once again we choose a shorter distance, and march towards the square, then get the distance again, and repeat the whole process:

You can see that with each step the distance to the object becomes smaller, and thus we will never overshoot the object. However, this also means, that we will take a lot of really small steps until we finally fully hit the object if we ever do. This is not a good idea, because it is even more inefficient than using fixed distance, and produces too accurate results, which we don’t really need. So instead of marching up until we exactly hit the object, we will march enough times. E.g., until the distance to the object is small enough, then there’s no real point to continue marching, as it is clear that we will hit the object soon. But this also means, that if the ray goes near the edge of an object, we do a lot of expensive steps of computing distance estimations.

Here’s a ray that is parallel to the side of the square, and marches towards the circle:

We do a lot of seemingly pointless measurements, and if a ray was closer to the square’s side, we would do even more steps. However, this also means, that we can use this data (since we’re already computed it) to render such things as glow, or ambient occlusion. But more on this later.

Once a ray hit an object we have all the data we need. Ray represents a point on the screen, and the more rays we cast the higher resolution of our image will be. And since we’re not using triangles to represent objects, our spheres will always be smooth, no matter how close we are to them, because there are no polygons involved.

This is basically it. Ray marching is a quite simple concept, just like raycaster, although it’s a bit more complicated, as we do have to compute things in 3D space now. So let’s begin implementing it by installing the required tools, and setting up the project.

Project structure

As you know from the title we will use two main tools to create ray-marcher, which are LÖVE, a free game engine, and Fennel the programming language. I’ve chosen Fennel, because it is a Lisp-like language, that compiles to Lua, and I’m quite a fan of Lisps. But we also needed to draw somewhere, and I know no GUI toolkit for Lua. But there is LÖVE - a game engine that runs Lua code, which is capable of running on all systems, thus a perfect candidate for our task.

Installation steps may differ per operating system, so please refer to manuals³^,⁴. At the time of writing this post, I’m using Fedora GNU/Linux, so for me it means:

$ sudo dnf install love luarocks readline-devel
$ luarocks install --local fennel
$ luarocks install --local readline # requires readline-devel
$ export PATH="$PATH:$HOME/.luarocks/bin"

It’s better to permanently add $HOME/luarocks/bin (or another path, if your installation differs) to the PATH variable in your shell, in order to be able to use installed utilities without specifying the full path every time. You can test if everything is installed correctly, by running fennel in your command line.

$ fennel
Welcome to Fennel 0.5.0 on Lua 5.3!
Use (doc something) to view documentation.
>> (+ 1 2 3)
6
>>

For other distributions, installation steps may vary, and for Windows, I think it’s safe to skip the readline part, which is fully optional but makes editing in a REPL a bit more comfortable.

Once everything is installed, let’s create the project directory and the main.fnl file, where we will write our code.

$ mkdir love_raymarching
$ cd love_raymarching
$ touch main.fnl

And that’s it! We can test if everything works by adding this code to main.fnl:

(fn love.draw []
  (love.graphics.print "It works!"))

Now we can compile it with fennel --compile main.fnl > main.lua, thus producing the main.lua file, and run love . (dot is intentional, it indicates current directory).

A window should appear, with white text It works! in the upper left corner:

Now we can begin implementing our ray marcher.

Scene setup

Just as in raycaster, we need a camera that will shoot rays, and some objects to look at. Let’s begin by creating a camera object, that will store coordinates and rotation information. We can do so, by using var to declare a variable that is local to our file, and that we can later change with set⁵:

(var camera {:pos [0.0 0.0 0.0]
             :x-rotate 0.0
             :z-rotate 0.0})

For those unfamiliar with Lisps, and especially Clojure, let me quickly explain what this syntax is. If you know this stuff, feel free to skip this part.

We start by using a var special form, that binds a value to a name like this: (var name value). So if we start the REPL, using the fennel command in the shell, and write (var a 40), a new variable a will be created. We then can check, that it has the desired value by typing a, and pressing return:
>> (var a 40)
>> a
40
We can then alter the contents of this variable by using set special form, which works like this (set name new-value):
>> (set a (+ a 2))
>> a
42
Now to curly and square brackets. Everything enclosed in curly braces is a hashmap. We can use any Lua value as our key, and the most common choice is a string, but Fennel has additional syntax for defining keys - a colon followed by a word: :a. This is called a keyword, and in Fennel, it is essentially the same as "a", but we don’t need to write a pair of quotes. However, keywords can’t contain spaces and some other symbols.

So writing this {:a 0 :b 2 :c :hello} in the REPL will make a new table, that holds three key-value pairs, which we can later get with another syntax - the dot .. Combining it with var, we can see that it works:
>> (var m {:a 1 :b 2 :c :hello})
>> (. m :b)
2
There’s also a shorthand for this syntax, that is, we can type m.b and access the :b key’s value:
>> m.b
2
>> m.c
"hello"
Notice that even though we’ve specified the value for :c as :hello, the REPL printed it to us as "hello".

We’re left with square brackets now, and this is a plain simple vector. It can grow and shrink, and store any Lua values in it:
>> [0 :a "b c" (fn [x] x)]
[0 "a" "b c" #<function: 0x56482230e090>]
However Lua doesn’t really have vectors or arrays, and it utilizes tables for this, where keys are simply indexes. So the code above is equivalent to this Fennel expression {1 0 2 "a" 3 "b c" 4 (fn [x] x)}, but we can use square brackets for convenience.

Note, that we can combine indexed tables (vectors) and ordinary tables (hashmaps) together. We can do it as shown above, by specifying indexes as keys, or defining a vector var and set a key in it to some value:
>> (var v [0 1 :a])
>> (set v.a 3)
>> v
{:a 3
 1 0
 2 1
 3 "a"}

So camera is essentially a Lua table, that stores keys :pos, :x-rotate, and :y-rotate, each storing a respective value. We use a vector as our position, and two floats as our rotation angles. Now we can make objects, but before that, we need a scene to store those objects:

(var scene [])

Yep, that’s our scene. Nothing fancy, simply an empty vector to which we will later add objects.

Now we can create these objects, so let’s start with perhaps the simplest one - a sphere. And I’ll also briefly explain what makes raymarching different from other methods of creating 3D graphics.

Creating objects

What is a sphere? That depends on the domain, we’re working in. Let’s open up Blender, remove the default cube, and create sphere with Shift+a, Mesh, UV Sphere:

To me, this looks nothing like a sphere, because it consists of rectangles. However, if we subdivide the surface, we can get a more correct representation:

This looks more like a sphere, but this is still just an approximation. Theoretically, if we move very close to it, we will see the edges and corners, especially with flat shading. Also, each subdivision adds more points, and it gets more and more expensive to compute:

We have to make these trade-offs because we don’t need very accurate spheres when we need real-time processing. But raymarching doesn’t have this limitation, because the sphere in raymarching is defined by the point and radius length. Which we can then work with by using the signed distance function.

So let’s create a function, that will produce a sphere:

(fn sphere [radius pos color] ➊
  (let [[x y z] ➋ (or pos [0 0 0])
        [r g b] (or color [1 1 1])]
    {:radius (or radius 5)
     :pos [(or x 0) (or y 0) (or z 0)]
     :color [(or r 0) (or g 0) (or b 0)]
     :sdf sphere-distance ➌}))

There’s a lot of stuff going on, so let’s dive into it.

This is a so-called constructor - a function, that takes some parameters and constructs an object with these parameters applied, then returns it. In most typed languages we would define a class, or structure to represent this object, however, in Fennel (and hence in Lua) we can just use a table. And this is my favorite part of such languages.

So we used fn special form to create a function named sphere, that takes three parameters: radius, position in space pos, and color ➊. Then we see another special form let. It is used to introduce locally scoped variables and has another nice property - destructuring ➋.

Let’s quickly understand how let works in this case. If you know how destructuring works, you can skip this part.

Here’s a simple example:
>> (let [a 1
         b 2]
     (+ a b))
3
We’ve introduced two local variables a and b, which hold values 1 and 2 respectively. Then we computed their sum and returned it as a result.

This is good, but what if we wanted to compute a sum of three vector elements multiplied by b? Let’s put a vector into a:
>> (let [a [1 2 3]
         b 2]
     <???>)
There are many ways to do this, such as reduce over a vector with a function that sums elements, or getting values from the vector in a loop and putting those into some local variable. However, in the case of our project, we always know exactly how many elements there will be, so we can just take these out by indexes without any kind of loop:
>> (let [a [1 2 3]
         b 2
         a1 (. a 1)
         a2 (. a 2)
         a3 (. a 3)]
     (* (+ a1 a2 a3) b))
12
Yet, this is very verbose, and not really good. We can make it a bit less verbose by skipping local variable definitions and using values directly in the sum:
>> (let [a [1 2 3]
         b 2]
     (print (.. "value of the second element is " (. a 2)))
     (* (+ (. a 1) (. a 2) (. a 3)) b))
value of the second element is 2
12
However, again, this isn’t really great, as we have to repeat the same syntax three times, and what if we want to use the second value from the vector in several places? Like here, I’ve added print since I particularly about the second element’s value, and want to see it in the log, but I have to repeat myself and get the second element twice. We could use a local binding for this, but we don’t want to do this manually.

That’s where destructuring comes in handy, and trust me, it is a very handy thing. We can specify a pattern, that is applied to our data, and binds variables for us like this:
>> (let [[a1 a2 a3] [1 2 3]
         b 2]
     (print (.. "value of the second element is " a2))
     (* (+ a1 a2 a3) b))
value of the second element is 2
12
This works somewhat like this:
[1  2  3]
 ↓  ↓  ↓
[a1 a2 a3]
This is much shorter than any of the previous examples and allows us to use any vector values in several places.

We can also destructure maps like this:
>> (var m {:a-key 1 :b-key 2})
>> (let [{:a-key a
          :b-key b} m]
     (+ a b))
3
And this also has a shorthand for when the name of the key and the name of desired local binding will match:
>> (var m {:a 1 :b 2})
>> (let [{: a : b} m]
     (+ a b))
3
Which is even shorter.

All this essentially boils down to this kind of Lua code:
-- vector destructuring
-- (let [[a b] [1 2]] (+ a b))
local _0_ = {1, 2}
local a = _0_[1]
local b = _0_[2]
return (a + b)

-- hashmap destructuring
-- (let [{: a : b} {:a 1 :b 2}] (+ a b))
local _0_ = {a = 1, b = 2}
local a = _0_["a"]
local b = _0_["b"]
return (a + b)
This is nothing special really, but this example still shows the power of Lisp’s macro system, in which destructuring is implemented. But it gets really cool when we use this in function forms, as we will see later.

If we were to call (sphere) now, we would get an error, because we specified a value ➌ for a key :sdf, that doesn’t yet exist. SDF stands for Signed Distance Function. That is a function, that will return the distance from a given point to an object. The distance is positive when the point is outside of the object and negative when the point is inside the object.

Let’s define an SDF for a sphere. What’s great about spheres, is that to compute the distance to the sphere’s surface, we only need to compute the distance to the center of the sphere, and subtract the sphere’s radius from this distance.

Let’s implement this:

(local sqrt math.sqrt) ➊

(fn sphere-distance [{:pos [sx sy sz] : radius} [x y z]] ➋
  (- (sqrt (+ (^ (- sx x) 2) (^ (- sy y) 2) (^ (- sz z) 2)))
     radius))

For performance reasons we declare math.sqrt as a local variable sqrt, that holds function value, to avoid repeated table lookup.

As was later pointed out, Luajit does optimize such calls, and there is no repeated lookup for method calls. This is still true for plain Lua, so I’m going to keep this as is, but you can skip all these local definitions if you want and use methods directly.

And at ➋ we again see destructuring, however not in the let block, but in the function argument list. What essentially happens here is this - function takes two parameters, the first of which is a hashmap, which must have a :pos keyword associated with a vector of three numbers, and a :radius keyword with a value. The second parameter is simply a vector of three numbers. We immediately destructured these parameters into a set of variables local to the function body. Hashmap is being destructured into sphere position vector, which is immediately destructured to sx, sy, and sz, and a radius variable storing sphere’s radius. Second parameter is destructured to x, y, and z. We then compute the resulting value by using the formula above. However, Fennel and Lua only understand definitions in the order from the top to the bottom, so we need to define sphere-distance before sphere.

Let’s test our function by passing several points and a sphere of radius 5:

>> (sphere-distance (sphere 5) [5 0 0])
0.0
>> (sphere-distance (sphere 5) [0 15 0])
10.0
>> (sphere-distance (sphere 5) [0 0 0])
-5.0

Great! First, we check if we’re on the sphere’s surface, because the radius of our sphere is 5, and we’ve set x coordinate to 5 as well. Next, we check if we’re 10 something away from the sphere, and lastly, we check that we’re inside the sphere because the sphere’s center and our point both are at the origin.

But we also can call this function as a method with : syntax:

>> (local s (sphere))
>> (s:sdf [0 0 0])
-5

This works because methods in Lua are syntactic sugar. When we write (s:sdf p) it is essentially equal to (s.sdf s p), and our distance function takes sphere as its first parameter, which allows us to utilize method syntax.

Now we need a distance estimator - a function that will compute distances to all objects and will return the shortest one, so we could then safely extend our ray by this amount.

(local DRAW-DISTANCE 1000)

(fn distance-estimator [point scene]
  (var min DRAW-DISTANCE)
  (var color [0 0 0])
  (each [_ object (ipairs scene)]
    (let [distance (object:sdf point)]
      (when (< distance min)
        (set min distance)
        (set color (. object :color)))))
  (values min color))

This function will compute the distance to each object in the scene from given point, using our signed distance functions, and will choose the minimum distance and the color of this ray. Even though it makes little sense to return color from the distance-estimator, we’re doing this here because we don’t want to compute this whole process again just to get the color of the endpoint.

Let’s check if this function works:

>> (distance-estimator [5 4 0] [(sphere) (sphere 2 [5 7 0] [0 1 0])])
1.0     [0 1 0]

It works, we obtained the distance to the second sphere, and its color because the point we specified was closer to this sphere than to the other.

With the camera, object, a scene, and this function we have all we need to start shooting rays and rendering this on screen.

Marching ray

Just as in raycaster, we cast rays from the camera, but now we do it in 3D space. In raycasting, our horizontal resolution was specified by a number of rays, and our vertical resolution was basically infinite. For 3D this is not an option, so our resolution now depends on the 2D matrix of rays, instead of the 1D matrix.

Quick math. How many rays we’ll need to cast in order to fill up 512 by 448 pixels? The answer is simple - multiply width and height and here’s the amount of rays you’ll need:

>> (* 512 448)
229376

A stunning 229376 rays to march. And each ray has to do many distance estimations as it marches away from the point. Suddenly, all that micro-optimizations, like locals for functions do not feel that unnecessary. Let’s hope for the best and that LÖVE will handle real-time rendering. We can begin by creating a function that marches a single ray in the direction our camera looks. But first, we need to define what we would use to specify coordinates, directions, and so on in our 3D space.

My first attempt was to use spherical coordinates to define ray direction and move points in 3D space relative to the camera. However, it had a lot of problems, especially when looking at objects at angles different from 90 degrees. Like here’s a screenshot of me looking at the sphere from the “front”:

And here’s when looking from “above”:

And when I added the cube object, I noticed a slight fish-eye distortion effect:

Which was not great at all. So I’ve decided that I would remake everything with vectors, and make a proper camera, with a “look-at” point, will compute projection plane, and so on.

And to do this we need to be able to work with vectors - add those, multiply, normalize, e.t.c. I’ve wanted to refresh my knowledge on this topic, and decided not to use any existing library for vectors, and implement everything from scratch. It’s not that hard. Especially when we already have vectors in the language, and can destructure it to variables with ease.

So we need these basic functions:

vec3 - a constructor with some handy semantics,
vec-length - function that computes magnitude of vector,
arithmetic functions, such as vec-sub, vec-add, and vec-mul,
and other unit vector functions, mainly normalize, dot-product, and cross-product.

Here’s the source code of each of these functions:

(fn vec3 [x y z]
  (if (not x) [0 0 0]
      (and (not y) (not z)) [x x x]
      [x y (or z 0)]))

(fn vec-length [[x y z]]
  (sqrt (+ (^ x 2) (^ y 2) (^ z 2))))

(fn vec-sub [[x0 y0 z0] [x1 y1 z1]]
  [(- x0 x1) (- y0 y1) (- z0 z1)])

(fn vec-add [[x0 y0 z0] [x1 y1 z1]]
  [(+ x0 x1) (+ y0 y1) (+ z0 z1)])

(fn vec-mul [[x0 y0 z0] [x1 y1 z1]]
  [(* x0 x1) (* y0 y1) (* z0 z1)])

(fn norm [v]
  (let [len (vec-length v)
        [x y z] v]
    [(/ x len) (/ y len) (/ z len)]))

(fn dot [[x0 y0 z0] [x1 y1 z1]]
  (+ (* x0 x1) (* y0 y1) (* z0 z1)))

(fn cross [[x0 y0 z0] [x1 y1 z1]]
  [(- (* y0 z1) (* z0 y1))
   (- (* z0 x1) (* x0 z1))
   (- (* x0 y1) (* y0 x1))])

Since we already know how destructuring works, it’s not hard to see what these functions do. vec3, however, has some logic in it, and you can notice that if has three outcomes. if in Fennel is more like cond in other lisps, which means that we can specify as many else if as we want.

Therefore, calling it without arguments produces a zero-length vector [0 0 0]. If called with one argument, it returns a vector where each coordinate is set to this argument: (vec 3) will produce [3 3 3]. In other cases we either specified or not specified z, so we can simply create a vector with x, y, and either 0 or z.

You may wonder, why this is defined as functions, and why I didn’t implement operator overloading, so we could simply use + or * to compute values? I’ve tried this, however, this is extremely slow, since on each operation we have to do a lookup in meta-table, and this is like really slow.

Here’s a quick benchmark:

(macro time [body]
  `(let [clock# os.clock
         start# (clock#)
         res# ,body
         end# (clock#)]
     (print (.. "Elapsed " (* 1000 (- end# start#)) " ms"))
     res#))

;; operator overloading
(var vector {})
(set vector.__index vector)

(fn vec3-meta [x y z]
  (setmetatable [x y z] vector))

(fn vector.__add [[x1 y1 z1] [x2 y2 z2]]
  (vec3-meta (+ x1 x2) (+ y1 y2) (+ z1 z2)))

(local v0 (vec3-meta 1 1 1))
(time (for [i 0 1000000] (+ v0 v0 v0 v0)))

;; basic functions
(fn vec3 [x y z]
  [x y z])

(fn vector-add [[x1 y1 z1] [x2 y2 z2]]
  (vec3 (+ x1 x2) (+ y1 y2) (+ z1 z2)))

(local v1 (vec3 1 1 1))
(time (for [i 0 1000000] (vector-add (vector-add (vector-add v1 v1) v1) v1)))

If we run it with lua interpreter, we’ll see the difference:

$ fennel --compile test.fnl | lua
Elapsed 1667.58 ms
Elapsed 1316.078 ms

Testing this with luajit claims that this way is actually faster, however, I’ve experienced a major slowdown in the renderer - everything ran about 70% slower, according to the frame per second count. So functions are okay, even though are much more verbose.

Now we can define a march-ray function:

(fn move-point [point dir distance] ➊
  (vec-add point (vec-mul dir (vec3 distance))))

(local MARCH-DELTA 0.0001)
(local MAX-STEPS 500)

(fn march-ray [origin direction scene]
  (var steps 0)
  (var distance 0)
  (var color nil)

  (var not-done? true) ➋
  (while not-done?
    (let [➍ (new-distance
              new-color) (-> origin
                             (move-point direction distance)
                             (distance-estimator scene))]
      (when (or (< new-distance MARCH-DELTA)
                (>= distance DRAW-DISTANCE)
                (> steps MAX-STEPS) ➌)
        (set not-done? false))
      (set distance (+ distance new-distance))
      (set color new-color)
      (set steps (+ steps 1))))
  (values distance color steps))

Not much, but we have some things to discuss.

First, we define a function to move points in 3D space ➊. It accepts a point, which is a three-dimensional vector, a direction vector dir, which must be normalized, and a distance. We then multiply the direction vector by a vector that consists of our distances and add it to the point. Simple and easy.

Next, we define several constants, and the march-ray function itself. It Defines some local vars, that hold initial values, and uses a while loop to march a given ray enough times. You can notice, that at ➋ we created a not-done? var, that holds true value, and then use it in the while loop as our test. And you also can notice that at ➌ we have a test, in case of which we set not-done? to false and exit the loop. So you may wonder, why not use for loop instead? Lua supports index-based for loops. Fennel also has support for these. So why use while with a variable?

Because Fennel has no break special form for some reason.

Here’s a little rant. You can skip it if you’re not interested in me making unconfirmed inferences about Fennel :).

I think that Fennel doesn’t support break because Fennel is influenced by Clojure (correct me if I’m wrong), and Clojure doesn’t have break either. However, looping in Clojure is a bit more controllable, as we choose when we want to go to the next iteration:
(loop [i 0]
  ;; do stuff
  (when (< i 10)
    (recur (+ i 1))))
Which means that when i is less then 10 I want you to perform another iteration.

In Fennel, however, the concept isn’t quite like this, because we have to define a var explicitly, and put it into the while test position:
(var i 0)
(while (< i 10)
  ;; do stuff
  (set i (+ i 1)))
You may not see the difference, but I do. This also can be trivially expressed as a for loop: (for [i 0 10] (do-stuff)). However, not every construct can be defined as for loop, when we don’t have break. And in Clojure we don’t have to declare a variable outside the loop, since loop does it for us, but the biggest difference is here:
(loop [i 0]
  (when (or (< i 100)
            (< (some-foo) 1000))
    (recur (inc i))))
Notice, that we’re looping until i reaches 100, or until some-foo returns something greater than 1000. We can easily express this as for loop in Lua:
for i = 0, 100 do
   if some_foo() > 1000 then
      break
   end
end
However, we can’t do the same in Fennel, because there’s no break. In this case we could define i var, put some_foo() < 1000 to the while loop test, and then use break when i reaches 100, like this:
(var i 0)
(while (or (< i 100)
           (< (some-foo) 1000))
  (set i (+ i 1)))
This is almost like the Clojure example, and you may wonder why I complain, but in the case of march-ray function, we can’t do this either! Because the function we call returns multiple values, we need to destructure ➍ to be able to test those. Or in some loops, such a function may depend on the context of the loop, so it has to be inside the loop, not in the test.

So not having break, or the ability to control when to go to the next iteration is a serious disadvantage. Yes, Clojure’s recur is also limited, since it must be in the tail position, so you can’t use it as continue or something like that. But it’s still a bit more powerful construct. I’ve actually thought about writing a loop macro, but it seems that it’s not as easy to do in Fennel, as in Clojure, because Fennel lacks some inbuilt functions to manipulate sequences. I mean it’s totally doable, but requires way too much work compared to defining a Boolean var and setting it in the loop.

At ➍ we see the syntax that I didn’t cover before: (let [(a b) (foo)] ...). Many of us, who are familiar with Lisp and especially Racket may be confused. You see, in Racket, and other Scheme implementations (that allow using different kinds of parentheses) let has this kind of syntax:

(let [(a 1)   ;; In Scheme square brackets around bindings
      (b 41)] ;; are replaced with parentheses
  (+ a b))

Or more generally, (let ((name1 value1) (name2 value2) ...) body). However, in the case of the march-ray function, we see a similar form, except the second element has no value specified. This is again a valid syntax in some lisps (Common Lisp, for example), as we can make a binding that holds nothing and later set it, but this is not what happens in this code, as we don’t use foo at all:

(let [(a b) (foo)]
  (+ a b))

And, since in Fennel we don’t need parentheses, and simply specify bindings as a vector [name1 value1 name2 value2 ...], another possible confusion may happen. You may think that (a b) is a function call that returns a name, and (foo) is a function call that produces a value. But then we somehow use a and b. What is happening here?

But this is just another kind of destructuring available in Fennel.

Lua has 1 universal data type, called a table. However Lua doesn’t have any special syntax for destructuring, so when a function needs to return several values, you have two options. First, you can return a table:

function returns_table(a, b)
   return {a, b}
end

But the user of such function will have to get values out of the table themselves:

local res = returns_table(1, 2)
local a, b = unpack(res) -- or use indexes, e.g. local a = res[1]
print("a: " .. a .. ", b: " .. b)
-- a: 1, b: 2

But this is extra work, and it ties values together into a data structure, which may not be really good for you. So Lua has a shorthand for this - you can return multiple values:

function returns_values(a, b)
   return a, b
end

local a, b = returns_values(1, 2)
print("a: " .. a .. ", b: " .. b)
-- a: 1, b: 2

This is shorter and more concise. Fennel also support this multivalue return with values special form:

(fn returns-values [a b]
  (values a b))

This is equivalent to the previous code, but how do we use these values? All binding forms in Fennel support destructuring, so we can write this as:

(local (a b) (returns-values 1 2))
(print (.. "a: " a ", b: " b))
;; a: 1, b: 2

Same can be done with vectors or maps when defining, local, var, or global variables:

(local [a b c] (returns-vector)) ;; returns [1 2 3]
(var {:x x :y y :z z} (returns-map)) ;; returns {:x 1 :y 2 :z 3}
(global (bar baz) (returns-values)) ;; returns (values 1 2)

And all of this works in let or when defining a function!

OK. We’ve defined a function that marches a ray, now we need to shoot some!

Shooting rays

As with math functions, let’s define some local definitions somewhere at the top of the file:

(local love-points love.graphics.points)
(local love-dimensions love.graphics.getDimensions)
(local love-set-color love.graphics.setColor)
(local love-key-pressed? love.keyboard.isDown)
(local love-get-joysticks love.joystick.getJoysticks)

This is pretty much all we’ll need from LÖVE - two functions to draw colored pixels, one function to get the resolution of the window, and input handling functions for the keyboard and gamepad. We’ll also define some functions in love namespace table (IDK how it is called properly in Lua, because it is a table that acts like a namespace) - love.load, love.draw, and others along the way.

Let’s begin by initializing our window:

(local window-width 512)
(local window-height 448)
(local window-flags {:resizable true :vsync false :minwidth 256 :minheight 224})

(fn love.load []
  (love.window.setTitle "LÖVE Raymarching")
  (love.window.setMode window-width window-height window-flags))

This will set our window’s default width and height to 512 by 448 pixels and set the minimum width and height to 256 by 224 pixels respectively. We also add title "LÖVE Raymarching" to our window, but it is fully optional.

Now we can set love.draw function, which will shoot 1 ray per pixel, and draw that pixel with the appropriate color. However, we need a way of saying in which direction we want to shoot our ray. To define the direction we will first need a projection plane and a look-at point.

Let’s create a look-at point as a simple zero vector [0 0 0] for now:

(local lookat [0 0 0])

Now we need to understand how we define our projection plane. In our case, a projection plane is a plane that is our screen, and our camera is some distance away from the screen. We also want to be able to change our field of view, or FOV for short, so we need a way of computing the distance to projection, since the closer we are to the projection plane, the wider our field of view:

We can easily compute the distance if we have an angle, which we also can define as a var:

(var fov 60)

Now we can compute our projection distance (PD), by using this formula:

Where fov is in Radians. And to compute radians we’ll need this constant:

(local RAD (/ math.pi 180.0))

Now we can transform any angle into radians by multiplying it by this value.

At this point, we know what is the distance to our projection plane, but we don’t know its size and position. First, we need a ray origin (RO), and we already have it as our camera, so our ro will be equal to the current value of camera.pos. Next, we need a look-at point, and we have it as a lookat variable, which is set to [0 0 0]. Now we can define a direction vector, that will specify our forward direction:

And with this vector F if we move our point the distance that we’ve computed previously, we’ll navigate the center of our projection plane, which we can call C:

The last thing we need to know, in order to get our orientation in space, is where is up and right. We can compute this by specifying an upward vector and taking a cross product of it and our forward vector, thus producing a vector that is perpendicular to both of these vectors, and pointing to the right. To do this we need an up vector, which we define like this [0 0 -1]. You may wonder why it is defined with the z-axis negative, but this is done so positive z values actually go up as we look from the camera, and the right is to the right. We then compute the right vector as follows:

And the up vector U is a cross product of R and F. Let’s write this down as in love.draw:

(fn love.draw []
  (let [(width height) (love-dimensions)
        projection-distance (/ 1 (tan (* (/ fov 2) RAD)))
        ro camera.pos
        f (norm (vec-sub lookat ro))
        c (vec-add ro (vec-mul f (vec3 projection-distance)))
        r (norm (cross [0 0 -1] f))
        u (cross f r)]
    nil)) ;; TBD

Currently, we only compute these values but do not use those, hence the nil at the end of the let. But now, as we know where our projection plane is, and where our right and up are, we can compute the intersection point, where at given x and y coordinates of a plane in unit vector coordinates, thus defining a direction vector.

So, for each x from 0 to width and each y from 0 to height we will compute a uv-x and uv-y coordinates, and find the direction vector rd. To find the uv-x we need to make sure it is between -1 and 1 by dividing current x by width and subtracting 0.5 from it, then multiplying by x/width. For uv-y we only need to divide current y by height, and subtract 0.5:

(for [y 0 height]
  (for [x 0 width]
    (let [uv-x (* (- (/ x width) 0.5) (/ width height))
          uv-y (- (/ y height) 0.5)]
      nil))) ;; TBD

Now as we have uv-x and uv-y, we can compute intersection point i, by using the up and right vectors and the center of the plane:

And finally, compute our direction vector RD:

And now we can use our march-ray procedure to compute the distance and color of the pixel. Let’s wrap everything up:

(local tan math.tan)
(fn love.draw []
  (let [projection-distance (/ 1 (tan (* (/ fov 2) RAD)))
        ro camera.pos
        f (norm (vec-sub lookat ro))
        c (vec-add ro (vec-mul f (vec3 projection-distance)))
        r (norm (cross [0 0 -1] f))
        u (cross f r)
        (width height) (love-dimensions)]
    (for [y 0 height]
      (for [x 0 width]
        (let [uv-x (* (- (/ x width) 0.5) (/ width height))
              uv-y (- (/ y height) 0.5)
              i (vec-add c (vec-add
                            (vec-mul r (vec3 uv-x))
                            (vec-mul u (vec3 uv-y))))
              rd (norm (vec-sub i ro))
              (distance color) (march-ray ro rd scene)]
          (if (< distance DRAW-DISTANCE)
              (love-set-color color)
              (love-set-color 0 0 0))
          (love-points x y))))))

Now, if we set the scene to contain a default sphere, and place our camera at [20 0 0], we should see this:

This is correct because our default sphere has white as the default color.

You can notice, that we compute distance and color by calling (march-ray ro rd scene), and then check if distance is less than DRAW-DISTANCE. If this is the case, we set the pixel’s color to the color found by march-ray function, otherwise, we set it to black. Lastly, we draw the pixel to the screen and repeat the whole process for the next intersection point, thus the next pixel.

But we don’t have to draw black pixels if we didn’t hit anything! Remember, that in the beginning, I’ve written, that if we go past the object, we do many steps, and we can use this data to render glow. So if we modify love.draw function a bit, we will be able to see the glow around our sphere. And the closer the gay got to the sphere, the stronger the glow will be:

;; rest of love.draw
(let [ ;; rest of love.draw
      (distance color steps) (march-ray ro rd scene)]
  (if (< distance DRAW-DISTANCE)
    (love-set-color color)
    (love-set-color (vec3 (/ steps 100))))
  (love-points x y))
;; rest of love.draw

Here, I’m setting the color to the number of steps divided by 100, which results in this glow effect:

Similarly to this glow effect, we can create a fake ambient occlusion - the more steps we did before hitting the surface, the more complex it is, hence less ambient light should be able to pass. Unfortunately, the only object we have at this moment is a sphere, so there’s no way of showing this trick on it, as its surface isn’t very complex.

All this may seem expensive, and it actually is. Unfortunately, Lua doesn’t have real multithreading to speed this up, and the threads feature, provided by LÖVE results in even worse performance than computing everything in a single thread. Well, at least the way I’ve tried it. There’s a shader DSL in LÖVE, which could be used to compute this stuff on GPU, but this is currently out of the scope of this project, as I wanted to implement this in Fennel.

Speaking of shaders, now, that we can draw pixels on the screen, we also can shade those, and compute lighting and reflections!

Lighting and reflections

Before we begin implementing lighting, let’s add two more objects - a ground plane, and an arbitrary box. Much like a sphere object, we first define the signed distance function, and then the constructor for the object:

(local abs math.abs)

(fn box-distance [{:pos [box-x box-y box-z]
                   :dimensions [x-side y-side z-side]}
                  [x y z]]
  (sqrt (+ (^ (max 0 (- (abs (- box-x x)) (/ x-side 2))) 2)
           (^ (max 0 (- (abs (- box-y y)) (/ y-side 2))) 2)
           (^ (max 0 (- (abs (- box-z z)) (/ z-side 2))) 2))))

(fn box [sides pos color]
  (let [[x y z] (or pos [0 0 0])
        [x-side y-side z-side] (or sides [10 10 10])
        [r g b] (or color [1 1 1])]
    {:dimensions [(or x-side 10)
                  (or y-side 10)
                  (or z-side 10)]
     :pos [(or x 0) (or y 0) (or z 0)]
     :color [(or r 0) (or g 0) (or b 0)]
     :sdf box-distance}))

(fn ground-plane [z color]
  (let [[r g b] (or color [1 1 1])]
    {:z (or z 0)
     :color [(or r 0) (or g 0) (or b 0)]
     :sdf (fn [plane [_ _ z]] (- z plane.z))}))

In case of ground-plane we incorporate :sdf as a anonymous function, because it is a simple one-liner.

Now, as we have more objects, let’s add those to the scene and see if those work:

(var camera {:pos [20.0 50.0 0.0]
             :x-rotate 0.0
             :z-rotate 0.0})

(local scene [(sphere nil [-6 0 0] [1 0 0])
              (box nil [6 0 0] [0 1 0])
              (ground-plane -10 [0 0 1])])

With this scene and camera we should see this:

It’s a bit sadistic in the eyes, but we can at least be sure that everything works correctly. Now we can implement lighting.

In order to calculate lighting, we’ll need to know a normal to the surface at the point. Let’s create get-normal function, that receives the point, and our scene:

(fn get-normal [[px py pz] scene]
  (let [x MARCH-DELTA
        (d) (distance-estimator [px py pz] scene)
        (dx) (distance-estimator [(- px x) py pz] scene)
        (dy) (distance-estimator [px (- py x) pz] scene)
        (dz) (distance-estimator [px py (- pz x)] scene)]
    (norm [(- d dx) (- d dy) (- d dz)])))

It is a nice trick, since we create three more points around our original point, use the existing distance estimation function, and get a normalized vector of subtraction of each axis from the original point, with the distance to the new point. Let’s use this function to get normal for each point, and use the normal as our color:

;; rest of love.draw
(if (< distance DRAW-DISTANCE)
    (love-set-color (get-normal (move-point ro rd distance) scene))
    (love-set-color 0 0 0))
;; rest of love.draw

Notice that in order to get endpoint of our ray we move-point ro along the direction rd using the computed distance. We then pass the resulting point into get-normal, and our scene, thus computing the normal vector, which we then pass to love-set-color, and it gives us this result:

You can see that the ground-plane remained blue, and this isn’t an error. Blue in our case is [0 0 1], and since in our world, positive z coordinates indicate up, we can see it directly in the resulting color of the plane. The top of the cube and the sphere are also blue, and the front side is green, which means that our normals are correct.

Now we can compute basic lighting. For that we’ll need a light object:

(var light [70 40 100])

Let’s create a shade-point function, that will accept a point, point color, light position, and a scene:

(fn shade-point [point color light scene]
  (vec-mul color (vec3 (point-lightness point scene light))))

It may seem that this function’s only purpose is to call point-lightness, which we will define a bit later, and return a new color. And this is true, at least for now. Let’s create point-lightness function:

(fn clamp [a l t]
  (if (< a l) l
      (> a t) t
      a))

(fn above-surface-point [point normal]
  (vec-add point (vec-mul normal (vec3 (* MARCH-DELTA 2)))))

(fn point-lightness [point scene light]
  (let [normal (get-normal point scene) ➊
        light-vec (norm (vec-sub light point))
        (distance) (march-ray (above-surface-point point normal) ➋
                              light-vec
                              scene)
        lightness (clamp (dot light-vec normal) 0 1)] ➌
    (if (< distance DRAW-DISTANCE)
        (* lightness 0.5)
        lightness)))

What this function does, is simple. We compute the normal ➊ for given point, then we find a point that is just above the surface, using above-surface-point function ➋. And we use this point as our new ray origin to march towards the light. We then get the distance from the march-ray function and check if we’ve gone all the way to the max distance or not. If not, this means that there was a hit, and we divide total lightness by 2 thus creating a shadow. In the other case, we return lightness as is. And lightness is a dot product between light-vec and normal to the surface ➌, where light-vec is a normalized vector from the point to the light.

If we again modify our love.draw function like this:

;; rest of love.draw
(if (< distance DRAW-DISTANCE)
    (let [point (move-point ro rd distance)]
      (love-set-color (shade-point point color scene light)))
    (love-set-color 0 0 0))
;; rest of love.draw

We should see the shadows:

This already looks like real 3D, and it is. But we can do a bit more, so let’s add reflections.

Let’s create a reflection-color function:

(var reflection-count 3)

(fn reflection-color [color point direction scene light]
  (var [color p d i n] [color point direction 0 (get-normal point scene)]) ➊
  (var not-done? true)
  (while (and (< i reflection-count) not-done?)
    (let [r (vec-sub d (vec-mul (vec-mul (vec3 (dot d n)) n) [2 2 2])) ➋
          (distance new-color) (march-ray (above-surface-point p n) r scene)] ➌
      (if (< distance DRAW-DISTANCE)
          (do (set p (move-point p r distance))
              (set n (get-normal p scene))
              (set d r) ➍
              (let [[r0 g0 b0] color
                    [r1 g1 b1] new-color
                    l (/ (point-lightness p scene light) 2)]
                (set color [(* (+ r0 (* r1 l)) 0.66)
                            (* (+ g0 (* g1 l)) 0.66)
                            (* (+ b0 (* b1 l)) 0.66)]) ➎))
          (set not-done? false) ➏))
    (set i (+ i 1)) ➐)
  color)

This is quite a big function, so let’s look at it piece by piece.

First, we use destructuring to define several vars ➊, which we will be able to change using set later in the function. Next, we go into the while loop, which checks both for maximum reflections reached, and if the ray went to infinity. The first thing we do in the loop, computes the reflection vector r ➋, by using this formula:

This is our new direction, which we will march from new above-surface-point ➌. If we’ve hit something, and our distance will be less than DRAW-DISTANCE, we’ll set our point p to new point, compute new normal n, and set direction d to previous direction, which was reflection vector r ➍. Next, we compute the resulting color. I’m doing a simple color addition here, which is not an entirely correct way of doing it, but for now, I’m fine with that. We also compute lightness of the reflection point, and divide it by 2, so our reflections appear slightly darker. Then we add each channel and make sure it is not greater than 1, by multiplying it by 0.66 ➎. The trick here is that maximum lightness we can get is 0.5, so if we add two values, one of which is multiplied by 0.5 overall result can be averaged by multiplying by 0.66. This way we do not lose brightness all the way and the reflection color blends with the original color nicely.

In case we don’t hit anything, it means that this is the final reflection, therefore we can end ➏ the while loop on this iteration. Lastly, since I’ve already ranted on the absence of break in Fennel, we have to increase the loop counter manually ➐ at the end of the loop.

Let’s change shade-point so it will pass color into this function:

(fn shade-point [point color direction scene light]
  (-> color
      (vec-mul (vec3 (point-lightness point scene light)))
      (reflection-color point direction scene light)))

You can notice that I’ve added the direction parameter, as we need it for computing reflections, so we also have to change the call to shade-point in love.draw function:

;; rest of love.draw
(if (< distance DRAW-DISTANCE)
    (let [point (move-point ro rd distance)]
      (love-set-color (shade-point point color rd scene light))) ;; rd is our initial direction
    (love-set-color 0 0 0))
;; rest of love.draw

Let’s try this out (I’ve brought ground-plane a bit closer to objects so we could better see reflections):

We can see reflections, and reflections of reflections in reflections, because previously we’ve set reflection-count to 3. Currently, our reflections are pure mirrors, as we reflect everything at a perfect angle, and shapes appear just as real objects. This can be changed by introducing materials, that have different qualities like roughness, and by using better reflection algorithms like Phong shading, but maybe next time. Refractions also kinda need materials, as refraction angles can be different, depending on what kind of material it goes through. E.g. glass and still pool of water should have different refraction angles. And some surfaces should reflect rays at certain angles, and let them go through at other angles, which will also require certain modifications in the reflection algorithm.

Now, if we would set our camera, lookat, and light to:

(local lookat [19.75 49 19.74])

(var camera {:pos [20 50 20]
             :x-rotate 0
             :z-rotate 0})

(local scene [(box [5 5 5] [-2.7 -2 2.5] [0.79 0.69 0.59])
              (box [5 5 5] [2.7 2 2.5] [0.75 0.08 0.66])
              (box [5 5 5] [0 0 7.5] [0.33 0.73 0.42])
              (sphere 2.5 [-2.7 2.5 2.5] [0.56 0.11 0.05])
              (sphere 10 [6 -20 10] [0.97 0.71 0.17])
              (ground-plane 0 [0.97 0.27 0.35])])

We would see an image from the beginning of this post:

For now, I’m pretty happy with the current result, so lastly let’s make it possible to move into our 3D space.

User input

We’ll be doing two different ways of moving in our scene - with keyboard and gamepad. The difference mostly is in the fact, that gamepads can give us floating point values, so we can move slower or faster depending on how we move the analogs.

We’ve already specified needed functions from LÖVE as our locals, but to recap, we’ll need only two:

(local love-key-pressed? love.keyboard.isDown)
(local love-get-joysticks love.joystick.getJoysticks)

But first, we’ll need to make changes to our camera, as currently, it can only look at the origin.

How will we compute the look-at point for our camera so we will be able to move it around in a meaningful way? I’ve decided that a good way will be to “move” the camera forward a certain amount, and then rotate this point around the camera by using some angles. Luckily for us, we’ve already specified that our camera has two angles :x-rotate, and z-rotate:

(var camera {:pos [20 50 20]
             :x-rotate 255
             :z-rotate 15})

And it is also declared as a var, which means that we can set new values into it. Let’s write a function that will compute a new lookat point for current camera position and rotation:

(local cos math.cos)
(local sin math.sin)

(fn rotate-point [[x y z] [ax ay az] x-angle z-angle]
  (let [x (- x ax)
        y (- y ay)
        z (- z az)
        x-angle (* x-angle RAD)
        z-angle (* z-angle RAD)
        cos-x (cos x-angle)
        sin-x (sin x-angle)
        cos-z (cos z-angle)
        sin-z (sin z-angle)]
    [(+ (* cos-x cos-z x) (* (- sin-x) y) (* cos-x sin-z z) ax)
     (+ (* sin-x cos-z x) (* cos-x y) (- (* sin-x sin-z z)) ay)
     (+ (* (- sin-z) x) (* cos-z z) az)]))

(fn forward-vec [camera]
  (let [pos camera.pos]
    (rotate-point (vec-add pos [1 0 0]) pos camera.x-rotate camera.z-rotate)))

The first function rotate-point will rotate one point around another point by using two degrees. It is based on aircraft principal axes, but we only have two axes, so we do not need to “roll”, hence we do little fewer computations here.

Next is the forward-vec function, that computes current “forward” vector for camera. Forward, in this case, means the direction camera is “facing”, which is based on two angles we specify in the camera.

With this function we can implement basic movement and rotation functions for the camera:

(fn camera-forward [n]
  (let [dir (norm (vec-sub (forward-vec camera) camera.pos))]
    (set camera.pos (move-point camera.pos dir n))))

(fn camera-elevate [n]
  (set camera.pos (vec-add camera.pos [0 0 n])))

(fn camera-rotate-x [x]
  (set camera.x-rotate (% (- camera.x-rotate x) 360)))

(fn camera-rotate-z [z]
  (set camera.z-rotate (clamp (+ camera.z-rotate z) -89.9 89.9)))

(fn camera-strafe [x]
  (let [z-rotate camera.z-rotate]
    (set camera.z-rotate 0)
    (camera-rotate-x 90)
    (camera-forward x)
    (camera-rotate-x -90)
    (set camera.z-rotate z-rotate)))

And if we modify our love.draw again, we’ll be able to use our computed look-at point as follows:

(fn love.draw []
  (let [;; rest of love.draw
        lookat (forward-vec camera)
        ;; rest of love.draw

Now we don’t need a global lookat variable, and it is actually enough for us to compute new lookat every frame.

As for movement, let’s implement a simple keyboard handler:

(fn handle-keyboard-input []
  (if (love-key-pressed? "w") (camera-forward 1)
      (love-key-pressed? "s") (camera-forward -1))
  (if (love-key-pressed? "d")
      (if (love-key-pressed? "lshift")
          (camera-strafe 1)
          (camera-rotate-x 1))
      (love-key-pressed? "a")
      (if (love-key-pressed? "lshift")
          (camera-strafe -1)
          (camera-rotate-x -1)))
  (if (love-key-pressed? "q") (camera-rotate-z 1)
      (love-key-pressed? "e") (camera-rotate-z -1))
  (if (love-key-pressed? "r") (camera-elevate 1)
      (love-key-pressed? "f") (camera-elevate -1)))

Similarly, we can implement controller support:

(fn handle-controller []
  (when gamepad
    (let [lstick-x  (gamepad:getGamepadAxis "leftx")
          lstick-y  (gamepad:getGamepadAxis "lefty")
          l2        (gamepad:getGamepadAxis "triggerleft")
          rstick-x  (gamepad:getGamepadAxis "rightx")
          rstick-y  (gamepad:getGamepadAxis "righty")
          r2        (gamepad:getGamepadAxis "triggerright")]
      (when (and lstick-y (or (< lstick-y -0.2) (> lstick-y 0.2)))
        (camera-forward (* 2 (- lstick-y))))
      (when (and lstick-x (or (< lstick-x -0.2) (> lstick-x 0.2)))
        (camera-strafe (* 2 lstick-x)))
      (when (and rstick-x (or (< rstick-x -0.2) (> rstick-x 0.2)))
        (camera-rotate-x (* 4 rstick-x)))
      (when (and rstick-y (or (< rstick-y -0.2) (> rstick-y 0.2)))
        (camera-rotate-z (* 4 rstick-y)))
      (when (and r2 (> r2 -0.8))
        (camera-elevate (+ 1 r2)))
      (when (and l2 (> l2 -0.8))
        (camera-elevate (- (+ 1 l2)))))))

Only for a controller, we make sure that our l2 and r2 axes are from 0 to 2, since by default these axes are from -1 to 1, which isn’t going to work for us. Similarly to this, we can add the ability to change the field of view or reflection count, but I’ll leave this out for those who are interested in trying it themselves. It’s not hard.

As a final piece, we need to detect if the controller was inserted and handle keys somewhere. So let’s add these two final functions that we need for everything to work:

(var gamepad nil)

(fn love.joystickadded [g]
  (set gamepad g))

(fn love.update [dt]
  (handle-keyboard-input)
  (handle-controller))

love.joystickadded will take care of watching for new controllers, and love.update will ask for new input every now and then.

By this moment we should have a working raymarching 3D renderer with basic lighting and reflections!

Final thoughts

I’ve decided to write this post because I was interested in three topics:

Fennel, a Lisp-like language, which is a lot like Clojure syntax-wise, and has great interop with Lua (because it IS Lua)
LÖVE, is a nice game engine I’ve been watching for a long time already and played some games written with it, which were quite awesome,
and Lua itself, a nice, fast scripting language, with the cool idea that everything is a table.

Although I didn’t use much of Lua here, I’ve actually tinkered with it a lot during the whole process, testing different things, reading Fennel’s compiler output, and benchmarking various constructs, like field access, or unpacking numeric tables versus multiple return values. Lua has some really cool semantics of defining modules as tables and incorporating special meaning to tables via setmetatable, which is really easy to understand in my opinion.

Fennel is a great choice if you don’t want to learn Lua syntax (which is small, but, you know, it exists). For me, Fennel is a great language, because I don’t have to deal with Lua syntax AND because I can write macros. And even though I didn’t write any macro for this project, because everything is already presented in Fennel itself, the possibility of doing this is worth something. Also, during benchmarking various features, I’ve used self-written time macro:

(macro time [body]
  `(let [clock# os.clock
         start# (clock#)
         res# ,body
         end# (clock#)]
     (print (.. "Elapsed: " (* 1000 (- end# start#)) " ms"))
     res#))

So the ability to define such things is a good thing.

LÖVE is a great engine, and although I’ve used a very little bit of it, I still think that this is a really cool project, because there is so much more in it. Maybe someday I’ll make a game that will realize LÖVE’s full potential.

On a downside note… The resulting raymarching is very slow. I’ve managed to get around 25 FPS for a single object in the scene, and a 256 by 224 pixel resolution. Yes, this is because it runs in a single thread, and does a lot of expensive computations. Lua itself isn’t a very fast language, and even though LÖVE uses Luajit - a just-in-time compiler that emits machine code, it’s still not fast enough for certain operations, or techniques. For example, if we implement operator overloading for vectors we’ll lose a lot of performance for constant table lookups. This is an existing problem in Lua, since it does its best of being small and embeddable, so it could work nearly on anything, therefore it doesn’t do a lot of caching and optimizations.

But hey, this is a raymarching in ~350 lines of code with some cool tricks like destructuring! I’m fine with the results. A slightly more polished version of the code from this article is available at this repository, so if anything doesn’t work in the code above, or you got lost and just want to play with the final result, you know where to go :)

Till next time, and thanks for reading!

https://en.wikipedia.org/wiki/Ray_tracing_(graphics) ↩︎
https://github.com/ssloy/tinyraytracer ↩︎
https://fennel-lang.org/setup ↩︎
https://love2d.org/wiki/Getting_Started ↩︎
there’s no need to declare a variable as var if it is a table and we’re only going to change the values stored inside the table, not the table itself. ↩︎

Comment via email

Simple Ray Casting with ClojureScript

Thu, 04 Jun 2020 13:49:00 +0300

Ray casting is quite an old technique, that was heavily used in the early days of game development in a lot of games to create an illusion of 3D space. The most known example, and perhaps the first widely successful game that used this technique, was Wolfenstein 3D, made by ID Software in 1992. There were a lot of other games for all kinds of platforms, that used ray casting, for example, I remember playing the labyrinth game on Siemens C35 in around 2001:

Yup, this phone is still alive, and still has this labyrinth game

There’s probably no reason to use ray casting for rendering pseudo-3D environments today, since this technique is very limited, and modern hardware is heavily optimized for working with triangles, which allows us to create very complex geometry that is impossible to model with ray casting. But I think that ray casting is a kinda cool idea, a simple concept, and definitively was a very smart move in the nineties game development. Additionally, ray casting has a lot more use cases than a simple rendering engine. Also, raycasting seems not to be a real word, but I’m going to refer to this technique like that further on, because it is convenient, and the engine itself can be referred to as raycaster.

For this project, I’ve chosen ClojureScript because I want to get into it, and into Clojure as well. Although my experience with Lisps is not very rich, the main usage right now is for writing functions in Emacs Lisp, but those are rather basic. I’m also going through SICP with GNU Guile and Racket, and though exercises in this book are sometimes brutal, this is not real programming experience. So the real goal of this post is rather not to implement a basic raycaster, but learn some Clojure. What, you thought we’re here for games? Just kidding, we’ll make a simple maze game too, which will be playable on this page.

But first, let’s understand what raycasting is, by going through some basic examples.

Ray casting basics

The general idea behind this technique is that we can imitate a 3D environment based only on 2D information. This is done by casting rays from the point, where the camera stands, and measuring the length of each ray until it hits any of the line segments, that represent walls on a 2D plane. I’ve prepared some pictures to illustrate this idea:

We can look at this as a top-down view of our scene. But how would we convert it to a first-person pseudo-3D view? The answer, as you might expect, is rays. Our camera will shoot a certain amount of rays in front of it, and we will see which rays have intersection points with our red and green walls. Let’s shoot 6 rays:

Now we can find intersections with our walls. I’ve cut those rays, and calculated their lengths - this is the only information we need to make this 2D plane into a pseudo-3D scene. Going from left to right, lengths are roughly 23.7, 24.2, inf, 34.8, 30.3, 27.5 pixels each:

So, in order to make a 3D scene out of these lengths we, first, have to create an empty scene. Let’s make it 256 by 224 pixels. We then divide this scene’s width by amount of rays, to compute the width of each ray, and fill this scene with rectangles of this width, which gives us roughly 42.7 pixels wide rectangles:

This doesn’t look like 3D yet, and you can notice that there are only 5 out of the total 6 rectangles presented. This is due to the fact that one ray had infinity length, since it did not intersect with anything, so we don’t draw anything there. And to make it look 3D we need to change the height of each rectangle accordingly to the length of each ray. General rule – the shorter the ray, the bigger the height:

Now, this looks more like a 3D scene, isn’t it? But the walls don’t exactly look like walls, more like a set of rectangles. We can fix this by increasing our resolution, which we do by casting more rays. Also, let’s add background and remove rectangle outlines:

We can also change the field of view, by keeping the same amount of rays but changing the angle between those:

Which is more convincing, but still not as smooth as it could be. But, we can think about rays as our resolution, so if we would cast 256 rays, one ray for each pixel of image width, we would get something like this:

More advanced raycasting engines can produce various perspective corrections for such rectangles, making things appear at different heights. This is often used to imitate a camera shake while walking. Textures can be mapped to walls and the floor, and very basic lighting can be achieved by changing texture brightness depending on the distance. Even more advanced engines allow changing the vertical angle of the camera to imitate looking up and down. But we will implement pretty basic untextured raycasting, extending it further can be an interesting task, but I don’t feel like doing it with canvas. Maybe later, with WebGL.

Project structure

I’ll be using shadow-cljs to manage my project. I’ve found this one very straightforward and simple to set up with Leiningen. To create cljs project via lein type this in the command line (I’m using Linux, so) some details on project setup may vary for different operating systems:

$ lein new shadow-cljs raycasting

As a result, it should create the following file structure for us:

raycasting/
├── package.json
├── public
│   ├── css
│   │   └── style.css
│   └── index.html
├── README.md
├── shadow-cljs.edn
└── src
    └── raycasting
        └── core.cljs

Let’s look at shadow-cljs.edn:

;; shadow-cljs configuration
{:source-paths ["src"]
 :dependencies [[binaryage/devtools "0.9.7"]
                [reagent "0.8.0-alpha2"]]
 ;; set a nrepl port for connection to a REPL.
 :nrepl {:port 8777}
 :builds {:app {:target :browser
                :output-dir "public/js/compiled"
                :asset-path "/js/compiled"
                :modules {:main {:entries [raycasting.core]}}
                :devtools
                ; before live-reloading, any code calls this function
                {:before-load raycasting.core/stop
                 ;; after live-reloading finishes call this function
                 :after-load raycasting.core/start
                 ;; serve the public directory over http at port 8700
                 :http-root    "public"
                 :http-port    8700
                 :preloads     [devtools.preload]}}}}

Probably you won’t need to change much here, but I’ve removed reagent dependency, because I don’t need it, so my shadow-cljs.edn looks like this:

{:source-paths ["src"]
 :dependencies [[binaryage/devtools "0.9.7"]]
 :nrepl {:port 8777}
 :builds
 {:app {:target :browser
        :output-dir "public/js/compiled"
        :asset-path "/js/compiled"
        :compiler-options {:optimizations :advanced}
        :modules {:main
                  {:entries [raycasting.core]}}
        :devtools {:http-root "public"
                   :http-port 8700
                   :preloads  [devtools.preload]}}}}

I’ve also added :compiler-options {:optimizations :advanced} to produce smaller js file, and removed :before-load and :after-load functions, because I don’t think we need those, and script initialization on page load is sufficient enough.

One last thing - we need a test page to see the results of our code, so let’s create public/index.html file, where we will add our canvas, and other elements as we go.

With the project setup and ready we now can begin working on ray casting by creating a camera.

Creating a camera

Since we’re going to cast rays out from the camera, we need a camera in the first place. Camera will be represented as a single point on the plane with x and y coordinates, and degree parameter. Let’s create a file src/raycasting/camera.cljs and define camera by using atom so we could later update it:

(ns raycasting.camera)

(def camera (atom {:x 0.0 :y 0.0 :degree 0.0}))

Code Snippet 1: Contents of src/raycasting/camera.cljs

Our camera is a hash map with three key-value pairs for each of its parameters. We can later access these parameters by calling keys on this map like this:

raycasting.camera> (:degree @camera)
0.0

This is quite handy, and we can update our map with assoc procedure:

raycasting.camera> (assoc @camera :degree 45.0)
{:x 0.0 :y 0.0 :degree 45.0}

Or use merge-with procedure to change the value currently stored in the map, by using some procedure, which is + in our case:

raycasting.camera> (merge-with + @camera {:degree 90.0})
{:x 0.0 :y 0.0 :degree 90.0}

You can notice that while I’ve used assoc to change my :degree to 45.0 and then used merge-with with + to add 90.0 degrees to current :degree, I’ve still got 90.0 as the result, and not the expected 135.0. This is because camera is a value, and can’t really change, and instead we’re producing a new value based on old one. And since our old value never changed, it still had 0.0 as :degree. To understand how this works we need to understand what is considered a value and why. You can skip explanations of this if you want, since it mostly has nothing to do with raycasting itself, but this still may explain certain things that we will see later in the code.

In Clojure, we mostly work with values, and there are no variables as presented in other languages. To make it more clear, let’s talk about what is considered a value. For example, in Rust 42 is a value, that we can assign to a variable like this:
let mut a = 42;
We’ve created a mutable variable a, and put 42 into it. We can later mutate a to hold another value:
a -= 15;
The key here is mutate - we’re not magically transforming 42 itself into 27, we’re changing the contents of a. So a is like a box that contains a value. You can’t really do anything to 42 itself – it is and always will be 42, that’s why it is a value. So when we did a -= 15, we’ve produced a new value based on the old one, and put it into a. So values never change, only variables that hold these values change what they are holding.

As an example of something that is not a value in Rust, we can look at the Vector collection:
let mut b = vec![1, 2, 3];
This is a dynamic array, that holds three elements. And we can actually change this array by using different methods that it provides, like push:
b.push(4); // now collection holds these four elements [1, 2, 3, 4]
After this push, whenever we refer to b it will hold four elements. We’ve declared b as mut, but we’re not mutating b itself, but the collection that b holds - and because of that this is not a value. mut keyword only specifies that we can mutate collection. But even if we were to drop the mut keyword in both examples, e.g. let a = 42, let b = vec![1, 2, 3], we would not be able to mutate both of these, but it still would not turn [1, 2, 3] into a value, although we can treat it as a value, underlying semantics of a collection has not changed.

(Semi-)real-world example - I give you an apple, and ask you to give me back half of it. You slice the apple and give me back one half. This apple is not a value, because you’ve literally changed it by slicing, and now the original apple is no longer available for both of us. You now hold half of the apple, and I hold another half. This is what happens when you modify a vector or any other collection.

Then I give you an apple made out of a material that once cast, can’t be destroyed, and ask you to give me half of it. You can’t slice it, or do anything to it at all, so you take very precise measures of this apple, cast a new piece out of the same material, and give it back to me. We now have the original apple and an apple slice. Then you can throw this apple in the garbage because you can’t really do anything with it. This is what essentially happens when you do math with numbers - you can’t change 42, you can take the measure (15) and produce 27 by subtraction. And this is what makes such an apple to be a value.

So in Clojure, we work with such type of data, and all Clojure collections are immutable. But the other major aspect of Clojure’s collections is persistence. The apple I’ve described isn’t really persistent, because once you’ve made a new slice, nothing really tells me what its past state was - was it a whole apple or 3/4 of an apple? So in order to make things persistent, we must provide additional information with apple, like a serial number for example. When you cast a new slice, you create a new serial number, that contains information about the old serial number. This way we can look at our piece, and determine what apple was used as a reference.

Now, whenever we create new copies, we encode the previous serial number into the current serial number, and from any point, we are able to trace back to the original state of the apple.

You can argue, that this can be done with an ordinary apple just as with an indestructible one, but the difference is, that an ordinary apple can be changed. Imagine that you’ve made a new apple based on it, added a serial number, that encodes that it was derived from the original apple, and then someone bit off a piece of the original apple. Then any holder of your copy of apple will try to refer to the original one and will find out not what they expected. Or maybe what they expected, since the apple could have been bitten before and you’ve restored the original form of an apple when made it. There’s no way to tell and preserve correct history. So even though we can enforce mutation restrictions in Rust, this does not make the vector into a value.

This is kinda what Clojure does with its collections. But instead of using identifiers, Clojure uses path copying for sharing structure between states. So newer state refers to some point in the old state. There are many different ways to maintain persistence, which are nicely described on this Wikipedia page.

A very simple example of persistent collection we can refer to is a single linked list, that grows at the front. Let’s start with a list of these three items (1 2 3). This can be represented as boxes that hold values, and have pointers to what should be the next value:

So 1 refers to 2, 2 refers to 3, and 3 refers to nothing, which indicates end of the list. Now we add another element to it at the front, which produces a new list (0 1 2 3):

You can see that all we did is created a box to hold 0 and told it to point to a box that holds 1. The rest thing is our old list, marked with green boxes, and we did not copy anything from it. And old list did not change at all, only a new node was added to it at the front, but the old list knows nothing about it. So if we stored our original list somewhere, and added 0 to it, our original list was not changed.

Furthermore, if we check the identity of our new list without its first element, it will be the same as in the original list:
user=> (identical? '(1 2 3) '(1 2 3))
false
user=> (def a '(1 2 3))
user=> (identical? a (rest (conj a 0)))
true
First identical? test gives us false because these are two different objects, even though their values are the same. The second identical? test gives us true, because, as I’ve said, by adding a new value to the list, and then removing it, we get back the original list.

And all of the collections in Clojure work this way, with a promise of fast change and low memory cost. Although such collections are not as fast as mutable non-persistence collections, they are much more reliable, especially when it comes to concurrent programming, and reliability is much more important than speed most of the time.

But in our raycasting we will have to really change camera position, so how do we do it if collections can’t be changed, and we’re using a hash map to hold camera coordinates and angle?

Moving the camera

When we’ve created camera we’ve used the atom procedure to produce a reference type that can be later atomically swapped to hold another value, and the swapping mechanism is concurrently safe. So, in order to update our map, all we need to do is to call swap! procedure, and pass our atom and a procedure that will update the value:

raycasting.camera> (swap! camera (fn [c] (assoc c :degree 45.0)))
{:x 0.0 :y 0.0 :degree 45.0}

Now, when we dereference camera with @, we can actually see the updated value:

raycasting.camera> @camera
{:x 0.0 :y 0.0 :degree 45.0}

Using swap with anonymous procedures is kinda tedious, so instead, let’s create a set of procedures that we will use to move the camera around:

(def radian (/ Math/PI 180.0)) ➊

(defn move-point [[x y] degree amount] ➋
  (let [angle (* degree radian)]
    [(+ x (m/three-decimal (* (Math/sin angle) amount)))
     (+ y (m/three-decimal (* (Math/cos angle) amount)))]))

(defn move-forward
  "Move `camera` forward given `amount` respecting the `degree`."
  ([camera] (move-forward camera 1))
  ([camera amount]
   (let [{x :x
          y :y
          degree :degree} camera ➌
         [x y] (move-point [x y] degree amount)]
     (assoc camera :x x :y y))))

This procedure will move our camera forward relatively to where the camera is pointed at. We compute ➊ only once, to later convert degrees to radians by multiplication. The move-point ➋ procedure will later be used in several places of our program, so it is good to have it as a separate procedure, while move-forward is used exclusively for camera movement. And inside we have weird construction ➌ which is called Associative Destructuring. We essentially bind x, y, and degree within our let block, to the values contained in camera. Now let’s try to move our camera around:

raycasting.core> (move-forward (assoc @camera :degree 0.0) 10)
{:x 0, :y 10, :degree 0}
raycasting.core> (move-forward (assoc @camera :degree 90.0) 10)
{:x 10, :y 6.123233995736766e-16, :degree 90}

Uh oh. Moving forward with 0 degrees was fine, but when we’ve turned 90 degree, we’ve got 6.123233995736766e-16 as our y coordinate. This value is very close to 0, but we don’t really need such precision, and there are some problems with such small values in JavaScript. Let’s write a macro, that will truncate it to three decimal places, which would be more than enough for our needs:

(defmacro three-decimal
  "Truncate `double` to three decimal places."
  [num]
  `(/ (int (* 1000 ~num)) 1000.0))

(defn move-forward
  "Move `camera` forward given `amount` respecting the `degree`."
  ([camera] (move-forward camera 1))
  ([camera amount]
   (let [rad (* (:degree camera) (/ Math/PI 180.0))]
     (merge-with + camera {:x (three-decimal (* (Math/sin rad) amount))
                           :y (three-decimal (* (Math/cos rad) amount))}))))

This will not work though. The problem is, that we can’t just define a macro in the same file that we’ve declared procedure. This is a difference between Clojure and ClojureScript, so we have to create new file src/raycasting/macros.cljc, and use :require-macros in our namespace definition for camera.cljs:

(ns raycasting.camera
  (:require-macros [raycasting.macros :as m]))

Now we can update move-forward to refer to macro:

(defn move-forward
    "Move `camera` forward given `amount` respecting the `degree`."
    ([camera] (move-forward camera 1))
    ([camera amount]
     (let [rad (* (:degree camera) (/ Math/PI 180.0))]
       (merge-with + camera {:x (m/three-decimal (* (Math/sin rad) amount))
                             :y (m/three-decimal (* (Math/cos rad) amount))}))))

Let’s try it:

raycasting.core> (move-forward (assoc @camera :degree 0.0) 10)
{:x 0, :y 10, :degree 0}
raycasting.core> (move-forward (assoc @camera :degree 90.0) 10)
{:x 10, :y 0, :degree 90}

Nice. Now, we can do the same thing to rotate the camera:

(defn rotate
  "Rotate `camera` by a `degree`."
  ([camera] (rotate camera 0.5))
  ([camera degree]
   (assoc camera :degree (mod (+ (:degree camera) degree) 360.0))))

And if we call this:

raycasting.core> (rotate @camera 420)
{:x 0.0, :y 0.0, :degree 60.0}

The rotate procedure ensures that our :degree stays inside 360 degrees, so when we specify a turn that is more than 360 degrees, we wrap around. These are two main procedures we will later use.

Drawing

Now we can draw our camera on <canvas>. Let’s add this to our index.html:

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="UTF-8">
    <script src="js/compiled/main.js"></script>
  </head>
  <body>
    <canvas id="raycaster" width="512" height="224"></canvas>
    <script>
      window.onload = function() {
        raycasting.core.init();
      }
    </script>
  </body>
</html>

We’ve added our <canvas> and gave it an id. We will later be able to refer to this canvas via this id, so let’s create two vars to hold the canvas object, and its context:

(ns raycasting.core
  (:require [raycasting.camera :as cam]))

(defonce *canvas* nil)
(defonce *ctx* nil)

(defn ^:export init []
  (when-let [canvas (. js/document getElementById "raycaster")]
    (set! *canvas* canvas)
    (when (. *canvas* -getContext)
      (set! *ctx* (. *canvas* getContext "2d")))))

We use defonce here, so when we save file, and shadow-cljs hot reloads the code, we will not redefine our *canvas* and *ctx* to nil. And init procedure will run on onload event, and set our *canvas* and *ctx*.

Let’s create draw-camera procedure, that will take current camera state, and draw it to canvas:

(defn draw-line
  ([[x1 y1] [x2 y2]]
   (draw-line [x1 y1] [x2 y2] "#000000"))
  ([[x1 y1] [x2 y2] color]
   (set! (. ctx -strokeStyle) color)
   (doto ctx
     (.beginPath)
     (.moveTo x1 y1)
     (.lineTo x2 y2)
     (.stroke))))

(defn draw-camera [camera]
  (let [[x y :as pos] [(:x camera) (:y camera)]
        pointer (cam/move-point pos (:degree camera) 7)
        width 5]
    (draw-line pos pointer "#000000")
    (set! (. ctx -fillStyle) "#000000")
    (. ctx fillRect (- x (/ width 2)) (- y (/ width 2)) width width)))

Now, if we write this to the REPL:

raycasting.core> (draw-camera @cam/camera)
nil

We should see our camera:

Now let’s add some walls to look at.

Creating walls

I need to mention, that many raycasting engines define stages in terms of squares on the grid. This is useful because we can check intersections a lot faster since we only need to perform checks along the ray in fixed points of space. While this is quite fast, I want arbitrarily placed walls in my raycaster. Because of this, our algorithm will not be as optimal, but we will be able to handle more complex wall placement.

Let’s create new file src/raycasting/stage.cljs. In this file, we will define our stages. Each stage is a vector, with line segments, that have three components - beginning coordinate, endpoint, and color. Let’s define stage, as on our example picture.

(ns raycasting.stage)

(def example-stage
  [ ➊
   [ ➋
    [23.468 126.290] ➌
    [106.189 87.527] ➍
    "#89a02c"] ➎
   [[124.947 40.268] [166.507 95.415] "#916f6f"] ➏])

So what we’re doing here is, we begin by creating a vector ➊. This vector will hold all lines that our stage uses. We define another vector ➋, that will hold beginning point ➌, ending point ➍, and wall color ➎. Lastly, we specify another line ➏, and this process can continue on and on. Bigger stages will require a lot of walls, and this can be a performance hit, but we’re not aiming for the best efficiency.

Now we can implement wall drawing with our draw-line procedure, that we’ve already used in draw-camera procedure. Let’s create draw-stage procedure, that will walk through our vector of walls and draw each on the canvas:

(defn draw-stage [stage]
  (doseq [line stage]
    (apply draw-line line)))

doseq is a great way to iterate on a collection for producing side effects, such as drawing on the screen. Let’s move our camera to the position 119.5,180, and rotate it to 180 so it is placed as on our example. Now if we call this procedure, we should see our stage:

raycasting.core (swap! cam/camera #(assoc % :x 119.5 :y 180 :degree 180))
{:x 119.5 :y 180 :degree 180}
raycasting.core> (draw-camera cam/camera)
nil
raycasting.core> (draw-stage stage/example-stage)
nil

While we are at this, notice how awkward we’ve been setting our position for camera:

(swap! cam/camera #(➊ assoc ➋ % ➌ :x 119.5 :y 180 :degree 180))

➊ #() is a shorthand for creating an anonymous procedure. This procedure will call assoc ➋, and % ➌ will be our cam/camera. A more elaborate way to write the same code would be (fn [camera] (assoc camera …)). We could simplify this by using reset!:

(reset! cam/camera {:x 119.5 :y 180 :degree 180})

Which is much simpler, but still very error-prone, because we’ll have to remember what keys should be in the map. This is not an issue for three key-value pair maps, but for huge maps, it will be better to create some kind of initialization procedure. Let’s create one in raycasting.camera namespace:

(defn set-position
  "Set position of the `camera` to a certain `x`, `y`, and `degree`.")
➊ ([camera] (set-position camera 0 0 0))
➋ ([camera x y] (set-position camera x y 0))
➌ ([camera x y degree] (assoc camera :x x :y y :degree (mod degree 360.0)))

This is called Multi-arity function, we’ve been using it before, but I’ve never explained what it is. In Clojure and ClojureScript it is possible to define procedure overloading based on the number of given arguments. In this example we create three possible ways to call our procedure: ➊ - we only pass our camera parameter, and it resets its position to 0,0 coordinates, and set’s 0 degree angle, ➋ - we specify coordinates, but we don’t care about our angle, so we reset it, and ➌ - we provide all needed parameters, and set those accordingly with assoc. The beauty of multi-arity procedures is that it can call itself with another amount of arguments, so in this case, there’s only one real body, that does the work (➌), and others (➊, ➋) are only calling it with all needed parameters. With this procedure we can quickly set the desired position for our camera:

raycasting.core> (swap! cam/camera cam/set-position) ;; reset
{:x 0 :y 0 :degree 0}
raycasting.core> (swap! cam/camera cam/set-position 10 20) ;; set coordinates
{:x 10 :y 20 :degree 0}
raycasting.core> (swap! cam/camera cam/set-position 10 20 90) ;; fully specify position
{:x 10 :y 20 :degree 90}

We can use this later when we initialize our stages in the game.

Casting rays

Now, when we have our camera and walls, we can finally cast some rays. Although, we’re not casting rays, but really long line segments because our algorithm will check for intersections between line segments of stage walls, and our rays.

First, we need some linear algebra. In particular, we need to check if two line segments intersect or not. This is done by three procedures. First one checks if a point lies on the line segment:

(defn on-segment?
  "Checks if point `[ax ay]` lies on segment defined by two points `[b
  c]`, where each point is defined as a vector `[x y]`."
  [[ax ay] [[bx by] [cx cy]]]
  (and (<= ax (max bx cx))
       (>= ax (min bx cx))
       (<= ay (max by cy))
       (<= ay (min by cy))))

This procedure accepts a point, and a line segment defined as two points and checks whenever the point lies on that line segment. We will need this procedure because when we will check for intersections, we need to ensure, that we’re staying inside line segments.

Next bit is orientation procedure:

(defn orientation [[ax ay] [bx by] [cx cy]]
  (let [orientation (- (* (- by ay) (- cx bx))
                       (* (- bx ax) (- cy by)))]
    (cond (> orientation 0) :cw
          (< orientation 0) :cc
          :else :colinear)))

This procedure checks the relationship of point a, and points b and c. These relationships can be :cw (for clockwise), :cc (for counter clockwise), and :colinear:

Now we can check for the intersection itself:

(defn intersect?
  "Checks if two line segments intersect. Line segments are defined as
  vector of two points `[a1 a2]`, and each point is a vector of two
  coordinates `[x y]`."
  [[a1 a2] [b1 b2]]
  (let [o1 (orientation a1 a2 b1)
        o2 (orientation a1 a2 b2)
        o3 (orientation b1 b2 a1)
        o4 (orientation b1 b2 a2)]
    (or
     (and (not (= o1 o2))
          (not (= o3 o4)))
     (and (= o1 :colinear)
          (on-segment? b1 [a1 a2]))
     (and (= o2 :colinear)
          (on-segment? b2 [a1 a2]))
     (and (= o3 :colinear)
          (on-segment? a1 [b1 b2]))
     (and (= o4 :colinear)
          (on-segment? a2 [b1 b2])))))

To find the point of the intersection itself, we need to calculate these two formulas:

Let’s write those as intersection procedure:

(defn intersection [[[x1 y1] [x2 y2] :as ray] [[x3 y3] [x4 y4] :as wall]]
  (let [x (/ (- (* (- (* x1 y2) (* y1 x2)) (- x3 x4)) (* (- x1 x2) (- (* x3 y4) (* y3 x4))))
             (- (* (- x1 x2) (- y3 y4)) (* (- y1 y2) (- x3 x4))))
        y (/ (- (* (- (* x1 y2) (* y1 x2)) (- y3 y4)) (* (- y1 y2) (- (* x3 y4) (* y3 x4))))
             (- (* (- x1 x2) (- y3 y4)) (* (- y1 y2) (- x3 x4))))]
    [x y]))

I’ve added :as ray and :as wall to make it more clear what these points are related to. The order doesn’t really matter, since we’re computing a point, but I think it gives a slight idea of what this procedure expects.

As a final piece, we need a procedure, that will find all intersections for our ray, and return those in some form, that will be usable for us later. I’ve created this procedure, that takes our stage, and two points as ray:

(defn find-intersections [stage [origin end :as ray]]
➊ (->> stage
       (map (fn [wall]
              (if (intersect? ray wall)
                (let [new (intersection ray wall)]
                  [(distance origin new) new])
                [10000000 end])))
       (into {})))

Here we’re using thread last macro ➊, which essentially takes the result of our expression, and puts it in the last position in the next expression. We then map with an anonymous procedure, that takes wall, from our stage, and checks if it intersects? with our ray. If it does, we calculate new intersection point, and return a vector of the distance between ray origin and intersection point, and this new point. When map finishes, it produces this kind of list ([10 [0 15]] [11 [4.2 22.8]] … [length [x y]]). We then convert it into a hash map, where a length will be our key, and a set of coordinates will be our value. The distance procedure is defined as follows:

(defn distance [[x1 y1] [x2 y2]]
  (m/three-decimal
   (Math/sqrt (+ (Math/pow (- x1 x2) 2)
                 (Math/pow (- y1 y2) 2)))))

Now we finally can cast our rays. First, let’s cast a set of rays and draw those without truncation at the intersection point:

(defn cast-rays [camera]
  (let [ray-count 16
        step (/ fov ray-count)
        ray-start [(:x camera) (:y camera)]]
    (loop [n (dec ray-count)
           degree (:degree (cam/rotate camera (- (/ fov 2.0))))]
      (when (>= n 0)
        (let [ray-end (cam/move-point ray-start degree 5000)]
          (draw-line ray-start ray-end "#ffe680")
          (recur (dec n)
                 (+ degree step)))))))

Now if we call our procedures for drawing rays, camera, and stage like this:

raycasting.core> (draw-stage stages/example-stage)
nil
raycasting.core> (cast-rays @cam/camera)
nil
raycasting.core> (draw-camera @cam/camera)
nil

We should see this result:

Now let’s change this procedure, so it will find ray ends before drawing:

(defn cast-rays [camera stage]
  (let [step (/ fov rayCount)
        ray-start [(:x camera) (:y camera)]]
    (loop [n (dec rayCount)
           degree (:degree (cam/rotate camera (- (/ fov 2.0))))]
      (when (>= n 0)
        (let [ray-end (cam/move-point ray-start degree 5000)]
            ➊ intersections (find-intersections stage [ray-start ray-end])
            ➋ shortest-ray (apply min (keys intersections))
            ➌ ray-end (intersections shortest-ray)
          (draw-line ray-start ray-end "#ffe680")
          (recur (dec n)
                 (+ degree step)))))))

First, we compute a map of intersections ➊, then find the shortest intersection length from the map by applying the min procedure to the list of keys in the map ➋, and lastly get the closest endpoint for given ray ➌.

This way we can find all intersections of the given ray with all walls, but we will draw only the shortest one, like this:

To illustrate this a bit better, let’s create simple animation by making our camera rotate:

Now we can use the cast-rays procedure to make our pseudo-3D image.

Making a 3D view of our scene

We’ll need to modify our cast-rays procedure, so it would return a list of rays instead of drawing it:

➊ (defn angle-between [[[x1 y1] [x2 y2]] [[x3 y3] [x4 y4]]]
     (let [theta1 (Math/atan2 (- y1 y2) (- x1 x2))
           theta2 (Math/atan2 (- y3 y4) (- x3 x4))
           diff (Math/abs (- theta1 theta2))]
       (min diff (Math/abs (- 180 diff)))))

(defn cast-rays [camera stage]
  (let [step (/ fov rayCount)
        ray-start [(:x camera) (:y camera)]]
      ➋ central-ray [ray-start (cam/move-point ray-start (:degree camera) 100)]
    (loop [n (dec rayCount)
           degree (:degree (cam/rotate camera (- (/ fov 2.0))))
           rays ()]
      (if (>= n 0)
        (let [ray-end (cam/move-point ray-start degree 5000)
              intersections (find-intersections stage [ray-start ray-end])
              shortest-ray (apply min (keys intersections))
              ray-end (intersections shortest-ray)]
            ➌ ray-angle (angle-between [ray-start ray-end] central-ray)
          (recur (dec n)
                 (+ degree step)
               ➍ (conj rays [ray-end shortest-ray ray-angle n]))))
      ➎ rays)))

(defn draw-rays [camera rays]
  (let [pos [(:x camera) (:y camera)]]
    (doseq [[ray] rays]
      (draw-line pos ray "#ffe680"))))

First, we’ve defined an angle-between ➊ procedure, which takes two line segments and computes the angle between those in radians. We then added one extra computation before we cast rays - we compute central-ray ➋, a direction where the camera is looking. Then, we compute the angle between the current ray we’re casting and the central ray ➌. After that we’re conjing ➍ vector with endpoint, shortest length, angle, and ray number to a list of rays. Finally, we return a list of rays ➎ to the caller. draw-rays will later use these rays afterward and draw each one ray by ray.

Now, whenever we call this procedure, we get all the useful information that we will later need to produce an image. First, let’s create another procedure, that will render all our elements on screen in a sequence:

(defn render []
  (let [height (. *canvas* -height)
        width (. *canvas* -width)
        camera @cam/camera
        rays (cast-rays camera stage)]
    (. *ctx* clearRect 0 0 width height)
    (draw-rays rays)
    (draw-camera camera)
    (draw-stage stage)))
➊ (. js/window requestAnimationFrame render)

This is a skeleton, not a fully realized procedure. Note that at ➊, we request another frame to be drawn on our canvas. So this is more like a game loop, though not quite. We will use it as our game loop though.

So, what we do here, is we create a set of bindings on each frame, and we dereference our cam/camera to get its position and angle, and then cast rays from the camera on our stage. Later we clear canvas and call draw-rays, draw-camera, and draw-stage.

Calling this procedure should initiate an animation sequence, so if we add (swap! cam/camera cam/rotate 1), at some point we will have an animation of the rotating camera. Now let’s create a 3D view:

(defn draw-3d-stage [rays]
  (let [ray-width (/ (/ (. canvas -width) 2) rayCount)
        height (. canvas -height)
        canvas-width (/ (. canvas -width) 2)])

  ➊ (set! (. ctx -fillStyle) "#333")
    (. ctx fillRect canvas-width 0 canvas-width (/ height 2))
    (set! (. ctx -fillStyle) "#666")
    (. ctx fillRect canvas-width (/ height 2) canvas-width (/ height 2))

  ➋ (loop [rays rays]
      (when (not (empty? rays))
        (let [[_ distance ray-degree n] (first rays)]
            ➌ wall-height (- height distance)
              wall-height (if (< wall-height 0)
                            0
                            wall-height)
            ➍ wall-color wall-height
          (set! (. ctx -fillStyle) (str "rgb("wall-color","wall-color","wall-color")")))
        ➎ (. ctx
             fillRect
             (+ canvas-width (* n ray-width))
             (- (/ height 2) (/ wall-height 2))
             (+ ray-width 1) ;; extra pixel for border
             wall-height)
        (recur (rest rays)))))

This procedure first fills background ➊, then, we loop through each ray, we calculate wall height by simply subtracting canvas height and distance to the wall ➌, and since our canvas is 256 pixels high, we use this value as our color as well ➍. Not really a pretty solution, but will do it for now. Then we fill a rectangle of this height, and width, with an offset of half of the canvas width plus the number of the ray, times its width. Calling this procedure in our render procedure gives us such a view:

Sure this gives us the desired 3d view, but something is not right. When we look at our walls we can see that we get some kind of fish eye effect, which we can see in its full form if we look directly at the wall:

There’s a good reason for this, which we can fix, although it requires a few additional calculations.

Fisheye compensation

The reason for this effect is the method we’re using to calculate wall heights. Here’s how we currently view our would:

This curve is our screen, so if we were to display this on a non-flat screen with the opposite curve, our image would look natural. However our screens are flat, so we need to compensate for this. In order to do this, we need to compute distances while taking into account the number of degrees between camera direction and the ray we currently casting.

First, let’s declare angle-between procedure, that will return the angle between two line segments, one of which will be the direction where the camera is facing, and the other one is the ray we currently casting:

(defn angle-between [[[x1 y1] [x2 y2]] [[x3 y3] [x4 y4]]]
  (let [theta1 (Math/atan2 (- y1 y2) (- x1 x2))
        theta2 (Math/atan2 (- y3 y4) (- x3 x4))
        diff (Math/abs (- theta1 theta2))]
    (min diff (Math/abs (- 180 diff)))))

Now we can use it in our cast-rays procedure:

(defn cast-rays [camera stage]
  (let [step (/ *fov* *ray-count*)
        ray-start [(:x camera) (:y camera)]
        central-ray [ray-start (cam/move-point ray-start (:degree camera) 100)]]
    (loop [n (dec *ray-count*)
           degree (:degree (cam/rotate camera (- (/ *fov* 2.0))))
           rays ()]
      (if (>= n 0)
        (do (let [ray-end (cam/move-point ray-start degree 5000)
                  intersections (find-intersections stage [ray-start ray-end])
                  shortest-ray (apply min (keys intersections))
                  ray-end (intersections shortest-ray)]
                ➊ ray-angle (if *compensate-fisheye*
                              (angle-between [ray-start ray-end] central-ray)
                              0)
              (recur (dec n)
                     (+ degree step)
                   ➋ (conj rays [ray-end shortest-ray ray-angle n]))))
        rays))))

We store calculated angle ➊, and then add it to our ray and conj it to our rays collection. This vector already is quite big, so it would be better to use some associative collection instead. Let’s change it:

(conj rays {:end ray-end :length shortest-ray :angle ray-angle :n n})

Now, that cast-rays returns a list of hash maps, we need to update our other procedures that expected a list of vectors. I’ll omit these steps, as it ain’t much different from what I’ve previously described, and this post is already way longer than I’ve thought, but using hash maps will prove more usable when we will need to incorporate other information into our ray, such as color.

Now we can use angles in draw-3d-scene procedure. We’ll change our distance computation to use Math/cos procedure, to compute corrected distance:

distance (* distance (m/three-decimal (Math/cos ray-degree)))

This should give us the such result:

This looks correct when we face the wall at a 90-degree angle. But if we’re aligned with the wall, we get this:

Which is not right. Wall is curved for some reason.

Note: To be completely honest, up to this point I did everything without using existing raycasting tutorials. But when I applied a seemingly correct fisheye compensation, and it has gone away only partially, I got stuck for a while. So in order to find a correct way to compensate for this fisheye effect, I’ve read this one, but for some reason the formula there didn’t work for me, so I’ve altered it.

So it seems that we’re missing the projection plane. Let’s create one:

(defn projection-distance [width]
  (m/three-decimal (/ (/ *ray-count* 2) (Math/atan (* (/ *fov* 2) cam/radian)))))

It is better to compute this once, but since we can change the ray count, we have to recompute this.

With this distance we can add computation in our wall-height computation process:

(defn draw-3d-stage-example9 [rays]
  (let [ray-width (/ (/ (. *canvas* -width) 2) *ray-count*)
        height (. *canvas* -height)
        canvas-width (/ (. *canvas* -width) 2)
        projection-distance (projection-distance canvas-width)]
    (set! (. *ctx* -fillStyle) "#333")
    (. *ctx* fillRect canvas-width 0 canvas-width (/ height 2))
    (set! (. *ctx* -fillStyle) "#999")
    (. *ctx* fillRect canvas-width (/ height 2) canvas-width (/ height 2))
    (loop [rays (sort (fn [{l1 :length} {l2 :length}] (> l1 l2)) rays)]
      (when-let [ray (first rays)]
        (let [{distance :length ray-degree :angle n :n} ray
              angle-step (/ *fov* *ray-count*)
              distance (if *compensate-fisheye*
                         (* distance (m/three-decimal (Math/cos ray-degree)))
                         distance)
              wall-height (* (/ (/ height *ray-count*) distance) projection-distance (/ *fov* 4))
              wall-height (if (> wall-height height)
                            height
                            wall-height)
              wall-color (+ wall-height 10)]
          (set! (. *ctx* -fillStyle) (str "rgb(" wall-color ", " wall-color "," wall-color ")"))
          (. *ctx*
             fillRect
             (+ canvas-width (* n ray-width))
             (- (/ height 2) (/ wall-height 2))
             (+ ray-width 1) ;; extra pixel for border
             wall-height))
        (recur (rest rays))))))

This looks much better in both examples:

Although walls now appear further. I’ve tried to make up constants that will play nice to make the wall occupy the whole height when we near the wall, so I’ll keep it this way. I’m sure I have some misunderstanding of the algorithm, but it works, so I’m ok with that.

Handling input and focus

Now, when we have our camera working, we can make it move by pressing arrow keys. We already have needed procedures for handling camera position and rotation, so the only thing we really need is input handlers, and a way to focus our canvas, so pressing arrows would not scroll the page.

There are some libraries for handling keyboard input, but I’m a purist, so we’ll implement this without dependencies. All we need is two procedures, that check if a key is pressed, and that it is released. Let’s create raycasting/input.cljs:

(ns raycasting.input)

(defonce key-states (atom {}))
(defonce focus false)

We start by defining another atom for our key states. It will hold a map of keys and their states, like this {"Up" false, "Down" true}, which means that currently the Down key is pressed down. Another one is focus which we will use to determine whether should we handle input or not.

Let’s add these three procedures:

(defn valid-key? [key]
  (or (= key "Escape")
      (= key "Shift")
      (= key "ArrowLeft")
      (= key "ArrowUp")
      (= key "ArrowRight")
      (= key "ArrowDown")))

(defn on-key-press [event]
  (when focus
    (let [event (if event event (. js/window -event))
          key (. event -key)]
      (when (valid-key? key)
        (. event preventDefault)
        (swap! key-states assoc key true)))))

(defn on-key-release [event]
  (when focus
    (let [event (if event event (. js/window -event))
          key (. event -key)]
      (when (valid-key? key)
        (swap! key-states assoc key false)
        (. event preventDefault)))))

We’ll get our keys as strings, and check if this is one of the keys we need. If it is, and we’re focused, we swap! our key state with either true or false, so our key-states atom always holds most recent state. Now we need to assign these procedures to events:

(set! (. js/window -onkeyup) on-key-release)
(set! (. js/window -onkeydown) on-key-press)

We also have these procedures to handle focus:

(defn on-click [event]
  (set! focus true))

(defn release-focus []
  (set! focus false))

But we set these in the initialization code:

(defn ^:export init []
  (set! *canvas* (. js/document getElementById "raycaster"))
  (when *canvas*
    (. *canvas* addEventListener "mousedown" input/on-click)
    (swap! cam/camera cam/set-position 10 10 45)
    (when (. *canvas* -getContext)
      (set! *ctx* (. *canvas* getContext "2d"))
      (render))))

The final step would be to poll our keys on each frame in our render procedure. For this, we create another procedure, but in raycasting.core this time:

(defn move-camera [stage key-states]
  (let [{x :x y :y :as camera} @cam/camera]
    (when (key-states "Escape")
      (input/release-focus)
      (reset! input/key-states {}))

    (when (key-states "ArrowRight")
      (if (key-states "Shift")
        (let [{x' :x y' :y} (cam/strafe camera -1.5)]
          (when (not (detect-collision stage [[x y] [x' y']]))
            (swap! cam/camera cam/strafe -1)))
        (swap! cam/camera cam/rotate -1.5)))

    (when (key-states "ArrowLeft")
      (if (key-states "Shift")
        (let [{x' :x y' :y} (cam/strafe camera 1.5)]
          (when (not (detect-collision stage [[x y] [x' y']]))
            (swap! cam/camera cam/strafe 1)))
        (swap! cam/camera cam/rotate 1.5)))

    (when (key-states "ArrowUp")
      (let [{x' :x y' :y} (cam/move-forward camera 1.5)]
        (when (not (detect-collision stage [[x y] [x' y']]))
          (swap! cam/camera cam/move-forward 1.5))))

    (when (key-states "ArrowDown")
      (let [{x' :x y' :y} (cam/move-forward camera -1.5)]
        (when (not (detect-collision stage [[x y] [x' y']]))
          (swap! cam/camera cam/move-forward -1.5))))))

We then, call this procedure each frame as early as possible. You can notice that we’re calling another procedure detect-collision, it is much like our intersection finding stuff, but it calculates the end position of our camera, and checks if the path intersects with any of our walls. Not very optimal, but works well.

The last thing I want to add is a way to control the amount of rays, and field of view, as well as a fisheye compensation toggle. For that we’ll need these <input> tags:

<div>
  <input type="range" id="rayCountSlider"
         min="10" max="256" step="1"></input>
  <label for="rayCountSlider">Ray Count: </label>
  <output name="rayCountValue" id="rayCountOutput"></output>
</div>
<div>
  <input type="range" id="fovSlider"
         min="10" max="360" step="1"></input>
  <label for="fovSlider">Field of View: </label>
  <output name="fovSliderValue" id="fovSliderOutput"></output>
</div>
<div>
  <input type="checkbox" id="fishEyeCompensation"></input>
  <label for="fishEyeCompensation"> FishEye compensation</label><br>
</div>

And we need a way to control those. For this, let’s add these procedures:

(def max-fov 360)
(def max-compensated-fov 180)

(defn update-ray-count [event]
  (let [value (.. event -target -value)]
    (set! *ray-count* (js/parseInt value))
    (when-let [output (. js/document getElementById "rayCountOutput")]
      (set! (. output -innerHTML) value))))

(defn update-fov [event]
  (let [value (.. event -target -value)]
    (set! *fov* (js/parseInt value))
    (when-let [output (. js/document getElementById "fovSliderOutput")]
      (set! (. output -innerHTML) value))))

(defn update-fish-eye-compensation [event]
  (let [value (.. event -target -checked)]
    (set! *compensate-fisheye* value)
    (when-let [fov-slider (. js/document getElementById "fovSlider")]
      (set! (. fov-slider -max) (if value max-compensated-fov max-fov))
      (when (and value
                 (> *fov* max-compensated-fov))
        (set! *fov* max-compensated-fov)
        (set! (. fov-slider -value) max-compensated-fov)
        (when-let [fov-output (. js/document getElementById "fovSliderOutput")]
          (set! (. fov-output -innerHTML) *fov*))))))

(defn init-inputs []
  (when-let [ray-count-slider (. js/document getElementById "rayCountSlider")]
    (set! (. ray-count-slider -value) *ray-count*)
    (. ray-count-slider addEventListener "input" update-ray-count))
  (when-let [ray-count-output (. js/document getElementById "rayCountOutput")]
    (set! (. ray-count-output -innerHTML) *ray-count*))

  (when-let [fov-slider (. js/document getElementById "fovSlider")]
    (. fov-slider addEventListener "input" update-fov)
    (set! (. fov-slider -max) (if *compensate-fisheye* max-compensated-fov max-fov))
    (set! (. fov-slider -value) *fov*))
  (when-let [ray-count-output (. js/document getElementById "fovSliderOutput")]
    (set! (. ray-count-output -innerHTML) *fov*))

  (when-let [compensate (. js/document getElementById "fishEyeCompensation")]
    (. compensate addEventListener "click" update-fish-eye-compensation)
    (set! (. compensate -value) *compensate-fisheye*)))

In short, these are event handlers, which are called when we’re interacting with these inputs. We’re setting initial values as well, as the handlers in init-input procedure.

Coloring walls

Up until now, we were creating gray walls, which are fine, but boring. And you could notice that we’re drawing our lines in color, so walls have color information. Let’s update our find-intersections procedure to include color information, and use it to color our walls:

(defn find-intersections [stage [origin end :as ray]]
  (->> stage
       (map (fn [[_ _ color :as wall]]
              (if (intersect? ray wall)
                (let [new (intersection ray wall)]
                  [(distance origin new) {:end new :color (or color color "#eeeeee")}])
                [10000000 {:end end :color "#000000"}])))
       (into {})))

Now, we return a map that has length as its key, and another map, which holds endpoint and wall color as a value. We need to update our cast-rays procedure to use this information:

(defn cast-rays [camera stage]
  (let [step (/ *fov* *ray-count*)
        ray-start [(:x camera) (:y camera)]
        central-ray [ray-start (cam/move-point ray-start (:degree camera) 100)]]
    (loop [n (dec *ray-count*)
           degree (:degree (cam/rotate camera (- (/ *fov* 2.0))))
           rays ()]
      (if (>= n 0)
        (do (let [ray-end (cam/move-point ray-start degree 5000)
                  intersections (find-intersections stage [ray-start ray-end])
                  shortest-ray (apply min (keys intersections))]
                ➊ {ray-end :end color :color} (intersections shortest-ray)
                  ray-angle (if *compensate-fisheye*
                              (angle-between [ray-start ray-end] central-ray)
                              0)
              (recur (dec n)
                     (+ degree step)
                     (conj rays {:end ray-end :length shortest-ray :angle ray-angle :n n :color color}))))
        rays))))

We destructure our map ➊, and then use its values when we conj rays. If we use this color in our draw-3d-stage procedure, we’ll finally get results similar to what I showed in the very beginning:

But it would be nice if we keep the effect that more distant walls appear darker. To do that we’ll have to parse color, and dim it by some factor:

(defn dim [color amount]
  (let [dim-factor (Math/pow 1.1 (/ (inc amount) 7))
        color (int (/ color dim-factor))]
    (if (< color 25)
      25
      color)))

(defn dim-color [color distance]
  (let [red (js/parseInt (str "0x" (subs color 1 3)))
        green (js/parseInt (str "0x" (subs color 3 5)))
        blue (js/parseInt (str "0x" (subs color 5)))]
    (str "rgb("
         (dim red distance)
         ", "
         (dim green distance)
         ", "
         (dim blue distance)
         ")")))

These two procedures will dim colors encoded as six-digit hex colors, or #ffffff. We use our distance as the dim factor with some computations to make it look nice. Now we can use it in our draw-3d-stage procedure:

(defn draw-3d-stage [rays]
  (let [ray-width (/ (/ (. *canvas* -width) 2) *ray-count*)
        height (. *canvas* -height)
        canvas-width (/ (. *canvas* -width) 2)
        projection-distance (projection-distance canvas-width)
        gradient (. *ctx* createLinearGradient 0 0 0 height)]
    (doto gradient
      (.addColorStop 0 "#424242")
      (.addColorStop 0.5 "#111111")
      (.addColorStop 1 "#e2e2e2"))
    (set! (. *ctx* -fillStyle) gradient)
    (. *ctx* fillRect canvas-width 0 canvas-width height)
    (loop [rays (sort (fn [{l1 :length} {l2 :length}] (> l1 l2)) rays)]
      (when-let [ray (first rays)]
        (let [{distance :length ray-degree :angle n :n color :color} ray
              angle-step (/ *fov* *ray-count*)
              distance (if *compensate-fisheye*
                         (* distance (m/three-decimal (Math/cos ray-degree)))
                         distance)
              wall-height (* (/ (/ height *ray-count*) distance) projection-distance (/ *fov* 4))
              wall-height (if (> wall-height height)
                            height
                            wall-height)
              color (dim-color color distance)]
          (set! (. *ctx* -fillStyle) color)
          (. *ctx*
             fillRect
             (+ canvas-width (* n ray-width))
             (- (/ height 2) (/ wall-height 2))
             (+ ray-width 1) ;; extra pixel for border
             wall-height))
        (recur (rest rays))))))

I’ve also added a bit more nice gradient for our background color there. This will be our final version of this procedure.

Labyrinth game

Now we can create a small labyrinth game, but we need a way to determine if the goal was reached. But first, we need a stage to play on, as our current one isn’t really a good one. I’ve come up with this:

Our goal is to reach that colored corridor. To check if we succeeded we’ll simply check if our camera is inside the square. To check that we’ll use our raycasting facilities. The algorithm is pretty easy:

We cast rays from our point to the right,
We count with how many walls of a given square we intersect with,
If the amount of intersections is odd then we’re inside.

We can see that this works for us:

Of course, there are special cases, like when a point lies on either of the rectangle sides, but we can’t intersect with walls, because we detect collisions, so we’ll be fine. Here’s the code:

(defn inside-rectangle [camera [[ax ay] [bx by] [cx cy] [dx dy]]]
  (let [walls [[[ax ay] [bx by]]
               [[bx by] [cx cy]]
               [[cx cy] [dx dy]]
               [[dx dy] [ax ay]]]
        {x :x y :y} camera
        {x' :x y' :y} (cam/move-forward {:x x :y y :degree 90} 1000)]
    (->> walls
         (map (fn [wall]
                (if (intersect? [[x y] [x' y']] wall) 1 0)))
         (reduce + 0)
         odd?)))

We receive four points that define our goal and move the camera 90 degrees right to some amount. Then we map intersect? procedure across our walls, returning either 1 or 0 depending on collision detection, and reduce results with +, to finally check if the result is odd? or not.

Though we need some way to extract goals from our stage, I’ll just define it as a constant because I don’t want to make stage code even more complex than it is now, and we’re not going to change stages. So when we’ve reached our goal, we’ll just teleport the camera back to starting point:

(defn render []
  (move-camera stage @input/key-states)
  (when (inside-rectangle @cam/camera stage/goal)
    (swap! cam/camera cam/set-position 12 195 180))
  (let [height (. *canvas* -height)
        width (. *canvas* -width)
        camera @cam/camera
        rays (cast-rays camera stage)]
    (. *ctx* clearRect 0 0 width height)
    (draw-rays camera rays)
    (draw-camera camera)
    (draw-stage stage)
    (draw-3d-stage rays)
    (. js/window requestAnimationFrame render)))

Combining all this stuff should give us this small game:

Ray Count:

Field of View:

FishEye compensation

You can click on this canvas, and use Up, Down, Left, Right to move, you also can strafe to the side while holding Shift, and pressing Esc will return focus to the page so you could scroll it with arrow keys as usual.

What I’ve learned

This project was extremely fun to do in ClojureScript, and Clojure itself is quite an awesome language, although those have some differences. If you’re learning Clojure, I highly recommend Clojure for the Brave and True book, and although I didn’t finish it yet, I’ve borrowed a lot of ideas from there, like using these little Unicode circles (➊) to mark stuff for further explanations. This book has a “Peg Thing” game example, which got me thinking about trying something a bit more complex and real-time with Clojure, but I wasn’t sure how to draw graphics with Java stuff, so I’ve chosen ClojureScript because the canvas was very easy to reach.

After implementing this, I think that while you don’t really need all these class objects like point, line, e.t.c. as long as you’re passing those in meaningful contexts, which I didn’t really do through this post, and I expect that this code will be really hard to read after some point in time. But certainly, maps provide most of what you need from a class or object and are more generic than objects.

The cleaned-up source code for this project can be found here if you’re interested in looking more closely. I hope you’ve enjoyed the read, and got interested in Clojure or Lisp in particular if you’re not a Lisp hacker already.

Comment via email

Andrey Listopadov

Slopes in AABB collision systems

AABB collisions

Implementing slopes with bump.lua

TIC-80

Creating a project and adding bump.lua

Creating sprites and using the map editor

Loading entities to the world

Working with bump.lua

Handling mouse events

Implementing slopes with AABB collisions

Calculating slope collision coordinates

Handling slope collisions

Conclusion

Interactive game development with LÖVE

Adding the REPL

Changing code at runtime

Modules and state

Using the REPL

Boredom and gamedev

Making games on Android

Making games on Android with LÖVE

Drawing

Game4 and Autumn Lisp Game Jam

Game3 - Results

Game3 w2/3

Game3 W?/4

Game2 W4/4

Game2 W3/4

Game2 W2/4

Game2 W1/4

Game1 - Results

Graphic overhaul

Enemy AI

Level design

Music and SFX

Up next

Game1 W4/4 progress

Game1 W3/4 (again)

Game1 W3/4

Game1

Fennel Game Jam 2022

Day 1

Day 2

Day 3

Day 4

Day 5

Jam results

Wave Function Collapse Algorithm in ClojureScript

The algorithm

Text version of the algorithm

Collapsing cells

Working with images

Drawing the result

A proper demo

Raymarching with Fennel and LÖVE

Raymarching basics

Distance estimation

Project structure

Scene setup

Creating objects

Marching ray

Shooting rays

Lighting and reflections

User input

Final thoughts

Simple Ray Casting with ClojureScript

Ray casting basics

Project structure

Creating a camera

Moving the camera

Drawing

Creating walls

Casting rays

Making a 3D view of our scene

Fisheye compensation

Handling input and focus

Coloring walls

Labyrinth game

What I’ve learned

Implementing slopes with `bump.lua`

Creating a project and adding `bump.lua`

Working with `bump.lua`