I made a game for LÖVE Jam 2023 written in Teal

[icy-lava]

Intro

Love2D is a game development framework that uses Lua. It recently had a game jam that lasted about 10 days and has ended a few days ago, and I made a game for it written in Teal!

https://github.com/icy-lava/elastiball

I decided from the very beginning that one of my goals for this jam was going to be using Teal and seeing how well it would work for a bigger project (so far this is my biggest Teal project). Fortunately, there already was a teal definition file for the whole Love2D framework provided by MikuAuahDark.

Getting started

I started by setting up my build environment, for that I ended up using Make. I don't know if cyan would've been a better choice or if it could do everything that I needed the build system to do, but I wasn't really aware of it and just went with what I was familiar with.

Then I proceeded to write some boilerplate code - this took about 2 days or so. Love doesn't do too much for you, it mostly let's you use whatever tooling and libraries that you want, the downside is that it may take some time to set everything up how you want it.

To speed this process up, I used some libraries. Most of them had no definition files though, so I had to write those (I will be contributing some of those to the teal-types repo soon-ish).

I wanted to try implementing some simple verlet integration physics, so that's something that I did early on in the jam. I was able to implement some points with links/springs.

The good

I spent about a day implementing loading Tiled map editor files. But then the next day I realized Tiled just wasn't gonna cut it for the type of game I was making. I started working on a custom built-in level editor.

This is kind of where Teal shined, I was able to specify the format for the level data that the editor, level encoder/decoder AND the game could use. The actual encoding/decoding was done by a JSON lib, but as I defined the type of the level, I could be pretty confident as to what I would get from decoding the JSON files. I also had to do a big refactor of the editor to support a new feature, and it went really smoothly with no major hitches or bugs.

And just in general, working on the different systems of the game, Teal saved me from having any obscure bugs.

The bad

But now for the shortcomings...

Just as with some of my previous Love2D games, I decided to use my go-to ECS library tiny-ecs. And this was a huge pain point, as Teal could not do the composition of types that I needed it to do. Instead I had to do a bunch of copy-pasting and manual synchronization to ensure that the entity type for each system matches the filter function for the components.

I recognized that this was error-prone and hard to maintain, so I had a couple of options:

1. Make one entity type that has all of the components.
2. Write a code generator that composes entity types from components.

Option 1 is not ideal, as I'd be missing out on the type safety of Teal (not all entities have all components), not to mention I still would've had to specify the filters for tiny-ecs.

So I decided to go with option 2 - I wrote a code generator, in which I specified what type each component is, and what components each entity had. The generator then outputs a list of entity types, as well as the tiny-ecs filter for each type. I'm kind of disappointed that I had to go this route, but it also works fairly well as I could use these types anywhere in the code, and combined with the <total> flag on variables, I would know if any changes made to the components or entities are incompatible with the rest of the codebase. The only problem is that these entity types are not compatible with each other - for example, if entity A has all the components of entity B, I can't assign entity B to a variable of type A, instead I'm forced to use as.

Scene management was also quite awkward, since there's no inheritance or composition in Teal, so there wasn't a way to say "game-scene type and menu-scene type inherit from scene type". The way I've set up my codebase is that a scene gets called/managed from Lua code, which is probably not a good idea, but by doing that I mostly side-stepped the scene type incompatibility issues. But I had to make sure the type signatures for each function are correct and did a lot of copy pasting.

Final thoughts

With all that said, I really enjoyed working on my game with Teal. It made my project more maintainable compared to if I would've done it in Lua. Most of my previous jam games that I've done with Love2D I abandoned, partly because of the hacky nature of game jams, but also because any changes break everything and you have to keep running the game to see what you broke.

With this project, I feel like I could keep working on it without much pain. There's some refactoring to be done, but it wouldn't be hard to do it.

Perhaps my approach to making this game could be improved by doing things in a more "Teal way", but I'm not sure how I would do that. Some of the current issues I'm having could be solved with more code generation, but I'm apprehensive about doing that.

[hishamhm]

@icy-lava Thank you so much for this writeup! This is super useful feedback.

I'm pretty convinced that some form of interface support is the #1 missing feature in Teal at this point. I outlined my plan in this Mastodon thread, but an in-person conversation with @catwell got me thinking about simplifying it further to get to interfaces faster (at the expense of some soundness, as usual).

[icy-lava]

I'm glad that you find this useful! I'm not exactly sure what you have in mind when you say interfaces, do you mean something like in Go?

I personally would love the ability to merge 2 records, but let the merged record be compatible with the original 2, something like this:

local record Position
    x: number
    y: number
end
local record Radius
    radius: number
end
local record Circle
    -- This syntax is already kind of used by arrayrecords and userdata
    Position
    Radius
end

local circle: Circle = {x = 100, y = 100, radius = 20}
local position: Position = circle -- OK, it's accepted as a Position, this secretly has a radius but we ditch that information

You would be able to add extra functions to the Circle type, which would be invisible in the case of Position and Radius.

I don't know if this is a good idea, just sharing my thoughts.
Edit: I mean I don't know if what I'm proposing is a good idea. Your idea sounds good. Don't know if that was clear :)