Andrey Listopadov

Better slopes in AABB collision systems

Wed, 17 Jun 2026 19:14:00 +0300

Earlier this year I published a guide on how to implement slopes in AABB collision resolution using bump.lua. The resulting system worked, but was a bit hard to use in-game and had a few issues, so I wouldn’t consider it a viable solution.

The main issue with the old approach was the use of the cross collision response. It allowed the object to move through the slope as if it wasn’t there at all, and then the update loop corrected the y position after the fact. This alone makes writing code the game a lot more complicated than it needs to be:

(fn player-collision-filter [_ obj]
  (if (not= nil obj.slope)
      :cross
      :slide))

(fn grounded? [obj]
  (let [(_ y collisions l)
        (world:check obj obj.x (+ obj.y 1) player-collision-filter)]
    (and (or (faccumulate [res nil i 1 l :until res]
               (let [col (. collisions i)]
                 (when col.other.slope ;; <- eeeeeh...
                   (= obj.y (col.other.slope obj)))))
             (= obj.y y))
         collisions)))

(fn update [player main]
  ;; ---8<---
  (let [(x y collisions l)
        (world:move
         player
         (+ player.x player.x-vel)
         (+ player.y player.y-vel)
         player-collision-filter)]
    (doto player
      (tset :x x)
      (tset :y y))
    (for [i 1 l]
      (let [collision (. collisions i)
            other collision.other]
        (when other.slope
          (case (other.slope player)
            y* (when (>= player.y y*)
                 (world:update player player.x y* player.w player.h) ;; <- yikes!
                 (doto player
                   (tset :y y*)))))))
    ;; ---8<---
    ))

I had to resort to calling the world:update method, which, as described in the bump’s docs, is used to update object’s position in the world without checking collisions. This made slopes really awkward to use and work with. And while I suspected that this was a wrong approach, I decided to go with it anyway, because at the time I didn’t knew better.

Then, while working on the game for the Spring Lisp Game Jam I again needed a custom collision handling that is not supported by bump.lua directly, but a bit simpler this time around. It’s a common thing in games, where you can pass through the block from one side, but not from the other. Like clouds usually behave in platformers - you can cross them from below, but still land on them:

Your browser does not support the video tag.

A cloud platform in the game Rayman (1995)

However, bump.lua by default only supports the following type of collisions: slide, cross, touch, and bounce:

Figure 1: Response types from bump.lua documentation

Solving this using the cross handler seemed wrong, and after a bit of searching I learned that in bump.lua you can define your own collision response functions. So I defined my own collision response called slide-cross (because the main intention was to be able to go through from the sides with the slide response but cross over it from below):

(fn slide-cross [world col x y w h goal-x goal-y filter]
  (let [goal-x (or goal-x x)]
    (var goal-y (or goal-y y))
    (if (<= (+ y h) col.otherRect.y)
        (let [tch col.touch
              move col.move]
          (when (or (not= move.x 0) (not= move.y 0))
            (set goal-y tch.y))
          (set col.slide {:x goal-x :y goal-y})
          (let [(cols len) (world:project col.item tch.x tch.y w h goal-x goal-y filter)]
            (values goal-x goal-y cols len)))
        (let [(cols len) (world:project col.item x y w h goal-x goal-y filter)]
          (values goal-x goal-y cols len)))))

(world:addResponse :slide-cross slide-cross)

With such colliders in place, I could replicate cloud platform behavior:

Your browser does not support the video tag.

I didn’t use clouds themselves in the actual game - instead, this collider was assigned to specific blocks I wanted to be able to run past, acting more as background structures you can still jump on, i.e. pedestals, but the idea of making a custom collider got me thinking. If I can make a custom collision response function, why not try to do it for slopes too?

So that’s what I did. But before that, I had to redo slopes a bit.

Slopes in `bump.lua`

First, let’s start with how slopes are defined:

(fn make-slope [x y x0 y0 x1 y1 slope-type]
  (let [(nx ny) (slope-normal x0 y0 x1 y1 slope-type)]
    {:slope slope-type
     :surface #(+ y0 (/ (* (- y1 y0) (- (clamp x0 $ x1) x0)) (- x1 x0)))
     : x : y : nx : ny
     :h (m/max y0 y1) :w (m/max x0 x1)}))

For example, to define a slope at coordinates x,y that is 16px long and 8px tall (), we can call make-slope like this:

(make-slope x y 0 8 16 0 :floor)

A 45° 8x8 slope () can be defined as follows:

(make-slope x y 0 8 8 0 :floor)

These slopes get taller from left to right, if we want a slope that goes lower from left to right (), we swap the coordinates:

(make-slope x y 0 0 16 8 :floor)

This function returns an object representing the slope. Of course, we’re not limited to defining 16x8 and 8x8 slopes - these are just the most logical choices for a platformer in TIC-80. We can define steeper slopes like 8x16, or use an arbitrary size altogether. As long as it can be clearly represented by the underlying spritework given resolution constraints you work in.

The make-slope constructor computes the slope’s normal vector:

(fn slope-normal [x0 y0 x1 y1 slope-type]
  (let [dx (- x1 x0)
        dy (- y1 y0)
        len (m/sqrt (+ (* dx dx) (* dy dy)))
        nx (/ (- dy) len)
        ny (/ dx len)]
    (if (or (and (= slope-type :floor) (> ny 0))
            (and (= slope-type :ceiling) (< ny 0)))
        (values (- nx) (- ny))
        (values nx ny))))

It will be used in our response function to implement bouncing off the slope surface correctly - one of the things I fell short while making the previous version.

Slope response function for `bump.lua`

Now we can define the response function itself:

(fn slope-response [world col x y w h goal-x goal-y filter]
  (let [goal-x (or goal-x x)
        {: surface :slope slope-type : nx : ny} col.other
        {:x ox :y oy} col.otherRect
        {:y touch-y} col.touch]
    (var goal-y (or goal-y y))
    (case slope-type
      :floor (let [surf-y (m/min (+ oy (surface (- goal-x ox)))
                                 (+ oy (surface (- (+ goal-x w) ox))))]
               (if (> (+ goal-y h) surf-y)
                   (if (> col.normal.y 0)
                       (set goal-y touch-y)
                       (set [goal-y col.normal.x col.normal.y] [(- surf-y h) nx ny]))
                   (set [col.normal.x col.normal.y] [0 0])))
      :ceiling (let [surf-y (m/max (+ oy (surface (- goal-x ox)))
                                   (+ oy (surface (- (+ goal-x w) ox))))]
                 (if (< goal-y surf-y)
                     (if (< col.normal.y 0)
                         (set goal-y touch-y)
                         (set [goal-y col.normal.x col.normal.y] [surf-y nx ny]))
                     (set [col.normal.x col.normal.y] [0 0])))
      _ (error (.. "unknown slope type: " (tostring _))))
    (set col.slide {:x goal-x :y goal-y})
    (local (cols len) (world:project col.item x y w h goal-x goal-y filter))
    (values goal-x goal-y cols len)))

It has two case branches - one that I’ve omitted in the above explanation of make-slope.

The slope-type argument, set to floor in those examples, determines if a slope is a ground one or a one on the ceiling. Another thing that wasn’t supported in the old method.

This response function works as follows:

It gets goal-x and goal-y, as well as other usual parameters, and the collision object.
The slope is always in col.other, because slope itself never collides with anything (they’re never passed to world:move calls).
We get the slope’s rectangle to adjust our object’s position across the slope’s width.
Then we check slope-type
- For floor slopes we get the min of the y coordinate of the slope y.
- Then we check if the goal-y received by the collision response function is below the slope’s surface.
- If so, and the normal vector points up, meaning the collision comes from above the slope, we set the goal-y and normal vector.
For ceiling slopes, the logic is the same, only some signs and checks are inverted.
If approached from the other side of the slope, i.e. from below - the collision acts like a regular AABB, so the slope forms a right triangle.

Handling goal-y and normal vector inside the response function provides much cleaner slopes:

Your browser does not support the video tag.

Note: it may seem that balls float over the slopes without touching, but that's only a visual quirk because ball's collider is still a 8x8 square - it touches the slope wiht a corner, but the sprite makes it look that it's floating. A more precise collider for the ball is needed, but it's out of the scope of this post.

The old implementation couldn’t achieve such smooth gliding over the slope’s surface. Balls get stuck on adjacent slopes, and incorrect normals prevent balls from rolling off smoothly:

Your browser does not support the video tag.

Note: in this clip the ball seems to touch the slope properly, but again, it's just a visual thing - in reality the slope is a little below the sprite's visual representation of it.

Now, when slopes are defined better, we can integrate them into a mock-up platformer to test them in a game environment:

Your browser does not support the video tag.

I don’t use normal vectors here, since in a platformer the jump usually goes up, regardless of the terrain, but depending on the player’s state one could use normals as well, given that we have them in the collision info.

The old implementation of slopes had problems, that can be seen here:

Your browser does not support the video tag.

Notice that when transitioning from slope to solid ground, the player transitions to the falling state for one frame. This was because we had to handle slope collisions outside of the collider itself, in the update loop - we couldn’t cross slopes unless they’re a tiny bit higher than the ground next to it. This problem is now eliminated by handling slopes during bump’s collision resolution step.

But we don’t have to stop there - what we have now is basically an extension to normal AABB with custom height functions that are bound by bounding boxes. So we can create any kind of slopes, like ramps - we just need a proper height function. However, we did a small optimisation that prevents us from doing it right now - we pre-computed slope normals. If we use a height function whose normal vector changes along the x coordinate, we need to handle that in the slope-response function:

 (fn slope-response [world col x y w h goal-x goal-y filter]
   (let [goal-x (or goal-x x)
-        {: surface :slope slope-type : nx : ny} col.other
+        {: surface :slope slope-type} col.other
         {:x ox :y oy} col.otherRect
-        {:y touch-y} col.touch]
+        cx (- (+ goal-x (/ w 2)) ox)
+        (nx ny) (slope-normal (- cx 1) (surface (- cx 1))
+                              (+ cx 1) (surface (+ cx 1)) slope-type)]
     (var goal-y (or goal-y y))
     (case slope-type
       :floor (let [surf-y (m/min (+ oy (surface (- goal-x ox)))
                                  (+ oy (surface (- (+ goal-x w) ox))))]
                (if (> (+ goal-y h) surf-y)
-                   (if (> col.normal.y 0)
-                       (set goal-y touch-y)
-                       (set [goal-y col.normal.x col.normal.y] [(- surf-y h) nx ny]))
+                   (set [goal-y col.normal.x col.normal.y] [(- surf-y h) nx ny])
                    (set [col.normal.x col.normal.y] [0 0])))
       :ceiling (let [surf-y (m/max (+ oy (surface (- goal-x ox)))
                                    (+ oy (surface (- (+ goal-x w) ox))))]
                  (if (< goal-y surf-y)
-                     (if (< col.normal.y 0)
-                         (set goal-y touch-y)
-                         (set [goal-y col.normal.x col.normal.y] [surf-y nx ny]))
+                     (set [goal-y col.normal.x col.normal.y] [surf-y nx ny])
                      (set [col.normal.x col.normal.y] [0 0])))
       _ (error (.. "unknown slope type: " (tostring _))))
     (set col.slide {:x goal-x :y goal-y})

With that in place, we can even make dynamic slopes, like a moving sine wave, and objects will correctly respond:

Your browser does not support the video tag.

For my purposes, I don’t need this kind of flexibility yet, but it’s nice to be able to do it still. I could see this being used in a game like Sonic, where you have loops, which are circles. Defining four slopes for each circle quadrant (two bottom ones as floor slopes and upper ones as ceiling slopes), and handling how to enter and exit them by marking some of them inactive via the cross collision response. Handling normals in this case would prove handy, as Sonic jumps perpendicular to the normal at the current position on the slope.

Your browser does not support the video tag.

However, we lost one additional feature our original slope-response had: these slopes don’t have solid opposite side. Triangular floor slopes prevented objects from entering the slope from beneath, only from the sides and from above the slope. Sine-wave slope will teleport objects to the slope side if an object entered inside - it’s a correctness measure, because of a more complicated geometry.

That’s not a bad thing on its own, since slopes are usually surrounded by other types of ground anyway, but still a thing to consider.

With that, I have almost perfect slopes for bump.lua, and I can use it in systems where I can’t access more sophisticated collision detection systems like Box2D. There are still things to be aware of, though. First, because bump’s collision resolution does a single pass, we can’t handle cases well where a ball touches the slope, another wall, and another ball. Second, the order of collisions can give different outcomes - if a ball lands exactly in the middle of two slopes, the outcome is determined by which slope bump.lua will check first. So it’s good for simple cases, but not a proper slope collision simulation, like one found in non-AABB systems.

On that note, I think I’m satisfied with what I have, and I’ll try to use this in my next game projects! And, as always, the you can try this online here, and a downloadable version of a cart is provided below:

Comment via email

Spring Lisp Game Jam 2026

Sun, 24 May 2026 08:08:00 +0300

This year I decided to participate in the Spring Lisp Game Jam. It’s an annual event, where you have to make a game in any kind of lisp in a limited time, usually a week.

I’ve been putting this away for several years, because every time the jam started I wasn’t ready to spend time on it, because of work or other duties I had at the time. This year, however, I decided to take a vacation, and give it my all. Life, of course, had other plans, but I managed to persevere.

This game jam doesn’t have a particular theme, which is good, as I always wanted to make a particular kind of a game - a movement-oriented platformer. I really enjoyed games like Metroid Fusion and Metroid Dread, which, to my taste, have great platforming, especially in Dread, so I wanted to make something akin to it. On paper, this idea seemed doable. In practice, well, you’ll see.

I decided to make “speed” the main thing of my game, thinking that the core idea will be to maintain speed, and complete room-based obstacle courses. My engine of choice was again TIC-80 as I had some experience with it already, and it’s the most frictionless environment I know for making small games. That’s debatable, of course, given TIC’s restrictions of resolution of 240x136 pixels and a 16-color-only palette. But I like restrictions, they breed creativity, as we all know.

This is more of a postmortem post, as I’m writing this after finishing the game - I simply had no capacity of writing this during the development. So information below is more of how I remember this, and of notes I made along the way.

Day 1

First things first, I chose TIC-80, and it supports programming in lisp out of the box. The language in question is Fennel, which is a nice lisp that compiles to Lua. I needed a few things though.

TIC doesn’t have any built-in functionality besides the essential things for drawing on the screen and reading user’s input. My game needs to deal with collisions, and while other game engines, like LOVE, include a library for that, TIC is certainly not.

A popular library for this is bump.lua, however, TIC doesn’t allow filesystem interactions, so the library must be bundled inside the cart. However, this is a Lua library, and I’m making a game in Fennel.

Fennel has a way of inlining dependencies via the --require-as-include option that could be used, however, it only works when compiling Fennel code to Lua. And I’m not sure if this will pass for the game jam. Plus, Fennel doesn’t compile comments, so I couldn’t just write the game cart in Fennel and then compile it to Lua, I’d need to translate all of the cart metadata by hand.

Luckily, a few years ago I made a port of bump.lua to Fennel for cases like this. I used it in the other game I was making at the time. You can read my old dev-log here. Anyhow, I needed to make an actual game, not just mess with libraries, so I picked a palette and began working.

First day was all about player controller. I needed a solid foundation to build the game around, and none of my previous player controllers were adequate for this. They were too stiff.

At the end of the day I ended up with this:

Your browser does not support the video tag.

This is a bit more than just a player controller - I have a camera system, level editor, placeholder graphics, and powerups already coded.

This is my camera system:

(local camera
  {:x 96
   :y 40
   :update
   (fn [self {: x : y}]
     (doto self
       (tset :x (* (// x 240) 240))
       (tset :y (* (// y 136) 136))))
   :draw
   (fn [{: x : y} remap]
     (map (// x 8) (// y 8) (+ (// x 8) 31) (+ (// y 8) 18) 0 0 0 1 remap))
   :translate
   (fn [{:x cam-x :y cam-y} x y]
     (values (- x cam-x) (- y cam-y)))})

It’s a simple object that has three main methods.

The update method is responsible for camera positioning. It is called on each frame, and it simply clamps the x, y position into the one full screen range. Thus, this is not a free camera, it is locked to the current screen.

I had dynamic cameras in the past, and while I like them, for this game I wanted something different. Essentially, my vision was that each screen will be an obstacle course, although even at this point I already knew this would be a bit problematic.

The draw method simply draws the current visible range of tiles via the map command. I have a remap callback ready in case I’ll need to change some tiles dynamically.

The final method translate is an interesting one. When I draw anything, like the player, or interactable objects, I need to do so in the camera space. So I call (camera:translate obj.x obj.y) to get screen-space coordinates. In other words, object’s coordinates may be 1337,420, but in camera space they as well may be 42,27.

The camera draws the level from the map editor built into TIC, but we need to load it into the game to interact with it properly. So we need a system to do that.

The level editor is another thing I reused from the last game I made with TIC.

(local objects
  {1 :player
   17 :speed-up
   33 :jump-up})

(macro id [x y]
  `(mget (// ,x 8) (// ,y 8)))

(fn obj? [x y]
  (. objects (id x y)))

(fn solid? [x y]
  (fget (id x y) 0))

(fn load-map-to-world []
  (for [x 0 (* 240 8) 8]
    (for [y 0 (* 136 8) 8]
      (case (obj? x y)
        :player (do (mset (// x 8) (// y 8) 0)
                    (doto player
                      (tset :x x)
                      (tset :y y)
                      (tset :spawn-x x)
                      (tset :spawn-y y))
                    (doto camera
                      (tset :x (* x 8))
                      (tset :y (* y 8)))
                    (world:add player player.x player.y player.w player.h))
        :speed-up
        (let [obj {: x : y :h 8 :w 8 :type :cross
                   :handle (fn [self target]
                             (world:remove self)
                             (mset (// self.x 8) (// self.y 8) 0)
                             (set target.max-xvel (+ target.max-xvel 1)))}]
          (world:add obj obj.x obj.y obj.w obj.h))
        :jump-up
        (let [obj {: x : y :h 8 :w 8 :type :cross
                   :handle
                   (fn [self target]
                     (world:remove self)
                     (mset (// self.x 8) (// self.y 8) 0)
                     (set target.jump-vel (- target.jump-vel 2)))}]
          (world:add obj obj.x obj.y obj.w obj.h))
        _ (if (solid? x y)
              (let [obj {: x : y :h 8 :w 8}]
                (world:add obj obj.x obj.y obj.w obj.h)))))))

It’s a simple loop that goes over each map tile, and decides if it is a thing that we need to register in bump’s world. To decide that I use a combination of tile ids and flags. It’s called at the start of the game, and loads the map once.

Finally, the most convoluted part was the player controller:

(fn player.update [self _transition-target]
  (let [grounded? (grounded? self collision-filter)
        wall-bound? (wall-bound? self collision-filter)]
    (echoes:update self)
    (when (bonk? self collision-filter)
      (set self.yvel 0))
    (if grounded?
        (set self.yvel 0)
        (apply-gravity self wall-bound?))
    (if (and (btn right) (or grounded? (not wall-bound?)))
        (doto self
          (tset :flip 1)
          (tset :xvel (lerp self.xvel (if wall-bound? (/ self.max-xvel 5) self.max-xvel) (if grounded? acc 0.01))))
        (and (btn left) (or grounded? (not wall-bound?)))
        (doto self
          (tset :flip -1)
          (tset :xvel (lerp self.xvel (if wall-bound? (/ self.max-xvel -5) (- self.max-xvel)) (if grounded? acc 0.01))))
        grounded?
        (if wall-bound?
            (set self.xvel 0)
            (let []
              (set self.xvel (snap-to-zero (round (lerp self.xvel 0 0.1)))))))
    (when (or (btnp A) (btnp B) (btnp X) (btnp Y))
      (if grounded?
          (set self.yvel self.jump-vel)
          wall-bound?
          (doto self
            (tset :flip (- self.flip))
            (tset :xvel (if (= self.xvel 0)
                            (* 3 (- wall-bound?))
                            (- self.xvel)))
            (tset :yvel (* self.jump-vel 0.75)))))

    (let [(x y cols len) (world:move self (+ self.x self.xvel) (+ self.y self.yvel) collision-filter)]
      (for [i 1 len]
        (let [{: other} (. cols i)]
          (if other.handle
              (other:handle self))))
      (set self.x x)
      (set self.y y))))

This is again a method in the player object, which holds some state, like coordinates and other attributes of the player, like max speed. It’s fairly simple right now, but it’ll get worse in the future days.

One of the things you may have noticed was a trail effect, when the player reaches a certain speed. I wanted it in the game, inspired by Super Metroid’s speed booster effect. However, my small brain couldn’t figure out how to do it properly, so I simply used linear interpolation so each echo lags behind the player object just enough, and used time offsets to delay their animations. Later, I realized that I can do it simply by storing last player position every few frames and drawing the echo this way, but I had no time to fix it.

The animation system is another thing I needed to make myself, as TIC doesn’t have anything like that. There’s a popular library for doing that, called anim8, by the same author of bump.lua. I didn’t use it, as I had to learn it, and wasn’t sure if it’s compatible with TIC at all.

So my animation system is as follows:

(fn draw-anim [self x y flip? speed]
  (when (= (% t speed) 0)
    (set self.frame (% (+ self.frame 1) self.frames)))
  (spr (+ self.start (* self.frame 2)) (- x 4) y 0 1 flip? 0 2 2))

(local run-anim
  {:start 258
   :end 268
   :frames 6
   :frame 0
   :draw draw-anim})

(local jump-anim
  {:start 288
   :end 302
   :frames 8
   :frame 0
   :draw draw-anim})

;; etc

In the player.draw method I call this depending on the player’s state:

(fn player.draw [self]
  (let [(x y) (camera:translate self.x self.y)
        flip? (if (< self.flip 0) 1 0)]
    (echoes:draw self)
    (if (<= 0 (m/abs self.xvel) 0.01)
        (if (not= 0 self.yvel)
            (slow-jump-anim:draw x y flip? player)
            (idle-anim:draw x y flip? 60))
        (not (grounded? self))
        (case (wall-bound? player)
          1 (spr 256 x y 0 1 1 0 1 2)
          -1 (spr 256 x y 0 1 0 0 1 2)
          _ (if (> (m/abs self.xvel) 3)
                (jump-anim:draw x y flip? (m/floor (lerp 10 1 (/ (m/abs self.xvel) (m/abs self.max-xvel)))))
                (slow-jump-anim:draw x y flip? player)))
        (run-anim:draw x y flip? (m/floor (lerp 10 3 (/ (m/abs self.xvel) (m/abs self.max-xvel))))))))

As you can see, I don’t yet have a state machine or anything like it in my player object, which I fixed in later days. However, this was enough to make the animations you’ve seen in the video.

Animation speed is determined by the speed parameter, which is named incorrectly, as it is more of an update interval in frames. I use linear interpolation to play animations faster when player’s speed increases, interpolating from 10 tics to 1 tic. Each frame is 60 tics.

Day 2

Second day I focused on improving animations, as currently they look very janky.

I have Aseprite installed, so I picked up my drawing tablet and sat down working on the run animation. Or I would have done that if Wacom wasn’t a piece of crap.

I had to install drivers, but not just any drivers - the newest drivers are incompatible with my rather old tablet. They are quite big size-wise, and with slow internet it was a pain, since I blindly downloaded the latest driver, and was met with a message, that I should upgrade my device. Luckily, the official web page still has a working driver for my OS and tablet combination, but I was afraid for a second that I would have to resort to using my phone. Not that it is a problem, but I wanted to try Aseprite for this project.

The result is as follows:

Your browser does not support the video tag.

I also added sliding animation, and spikes, as no platformer is complete without spikes, am I right or am I right?

Jumping also has two states now - a slow jump, and a fast jump, each with their own animation. For slow jumps the player sprite is mostly static, changing only when the vertical velocity goes from negative to positive. When a certain amount of speed is reached, however, the jump changes into a Salto Mortale mode, where the player spins frantically, like Samus Aran. Did I mention that Metroid was a huge inspiration for me this time around?

In addition to sliding, I added wall slide, which is not only a visual aid, but also slows you down when falling a bit.

Day 3

I felt satisfied with my player controller so far, so I started working on the level itself. This includes decorations, and level design in general.

Here’s what I got by the end of day three:

Your browser does not support the video tag.

I designed a few tiles for the ground and walls, as well as variants for different biomes:

It’s hard to show the whole map in TIC, so here’s a screenshot from the built-in overview:

Aesthetics for this game were inspired by the palette I’ve chosen, and by the game Animal Well, which I’ve played recently. Or at least I wanted to think that way, as I liked the artstyle, and limited resolution of that game.

Days 4-7

The rest of the days I’ve been working on the level design. I even started to plan out the level on a piece of paper, like so:

Here’s map progress by day:

Figure 1: Day 4

Figure 2: Day 4, again

Figure 3: Day 5

Figure 4: Day 6

At some point I completed the paper plan:

Figure 5: Day 7

Figure 6: Day 8

I was ready to start working on the last bit of the map, when I realized that I made a mistake. My plan contained an extra row on top, when in reality I had just two more.

This meant that I had to trim down the last section, as I couldn’t really throw anything from the middle section, and it wouldn’t make sense to make the top section penetrate down.

Figure 7: Day 9

Still, I had the full map complete by day nine, out of ten days available for the jam. A bit of a close call, but I could release this game any time, as it is essentially complete now.

During these days I also made a main menu screen, and the end screen. The end screen feels a bit barebones, but I had no time to do anything more with it, as I still had to do the most difficult part - sounds and music.

SFX

Sound effects weren’t as hard, when it comes to the player itself. I’m using simple effects for steps, jumps, and slides based on white noise that TIC provides. Timing them to animation frames is easy enough, as I can call sfx from the animation pipeline itself.

Because of that, things like steps are actually in sync with the animation, which I like. However, in the browser the sound may lag, I don’t really know why, but it did for all my previous games. Maybe it also depends on the browser.

Day 10 - Music

As I usually do, I left the hardest part to the last day. If I fail at it, I won’t include it in the game, and release it as is - it’s still a complete game. But, if I succeed, the game will be a bit better.

Music composition is not of my top skills, I’d say I’m pretty bad at it. There are few reasons for that, first and foremost being it’s so clunky to do that on a computer. If I had a MIDI keyboard, or an iPad with GarageBand, I think I would spend more time doing that.

So I reached out to a friend with whom we did a collaboration before, and asked them to help me out. They were kind enough to provide me with an original piece, which I had to port to TIC with the best of my ability.

TIC’s music tracker is a bit weird, and very limiting for someone who’s not versatile enough with trackers in general.

Adapting the song was quite a challenge for me. First of all, the song was written in non-tracker software, as MIDI. Having a piano-roll view of it helped with adapting, but some of the effects that were used were hard to recreate, so I did my best.

For example, delay. I had to create a wave that modulated its volume to act like its two notes repeating after a short delay.

Then there were drums. I need to mention that I’m limited by three channels out of four available. One channel is reserved for in-game sound effects, like steps, jumps, powerups, etc. This leaves me with three channels for music.

I used the first channel for the lead melody, second one for the bass, and the third one for the drum beat. Drums proved that it’s not really feasible to do them in one channel. You can’t overlay two samples, like in a modern MIDI editor. So you have to choose between kick and snare. Or snare and cymbal. Or kick and cymbal. You get the idea.

The game

Anyway, this concludes this dev log, and the game is now available on itch.io. If you like it, consider voting for it on the jam’s page. And if you wish to download it, here’s the cart:

I can complete this game in about 10 minutes, but I think it’ll take a fair bit more time for players unfamiliar with it. After all, I spent a lot of time playing this game during development, and I know it pretty well.

I know that some levels in this game are probably very janky. Many jumps are probably not as obvious as they should have been, or unnecessarily hard. I’ve had no time to get this game play-tested by other people, so that’s that. Still, I fixed the most annoying places that drove even me nuts. And overall, I’m satisfied with what I made.

I hope you like this game, but don’t forget to check other submissions too! If you’re a fellow participant, I wish you luck, and let’s see who’s gonna be the winner! And if not, I encourage you to try it next year. It’s fun :)

Comment via email

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

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 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

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

Andrey Listopadov

Better slopes in AABB collision systems

Slopes in bump.lua

Slope response function for bump.lua

Spring Lisp Game Jam 2026

Day 1

Day 2

Day 3

Days 4-7

SFX

Day 10 - Music

The game

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

Game4 and Autumn Lisp Game Jam

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

Fennel Game Jam 2022

Day 1

Day 2

Day 3

Day 4

Day 5

Jam results

Slopes in `bump.lua`

Slope response function for `bump.lua`

Implementing slopes with `bump.lua`

Creating a project and adding `bump.lua`

Working with `bump.lua`