#Canned Heat

This is a "game engine", well... More like a framework... Actually, rather a mindset for developing games in Racket with the Urlang language.

It compiles your game to run standalone in a web browser.

#Installing

You will need to get Racket. Start it up, then install the "urlang" package with the File -> Package Manager. (You should be able to type "urlang" under the "Do What I Mean" tab and let Racket take it from there.)

What? You want to install Canned Heat itself? Read the next section.

#Running

To try out the sample games, you don't need Racket at all -- just go to the appropriate sample directory and load %index.html into your browser. The game should start running.

However, if you want to be a real pioneer, load one of the sample source files into the Racket editor:

#Old-style Examples (not updated yet)

• %soko.rkt -- Simple Sokoban implementation (initial Canned Heat prototype).
• %brick.rkt -- Breakout clone with three levels.
• %invade.rkt -- Invasion from space thing where the aliens don't shoot back.
• %wump.rkt -- Graphical version of "Hunt the Wumpus".
• %kiplkat.rkt -- 2024 Autumn Lisp Game Jam, third place entry. Endless runner.
• %gotcsl.rkt -- Very incomplete text-style adventure game. Example of non-real-time game implementation.
• %edit.rkt -- Spatial text editor. (Not a game, but uses Canned Heat anyway...)

#New-style Examples

• %c4.rkt -- Two-player "connect four" experience.
• %class6.rkt -- 2025 Spring Lisp Game Jam, puzzler with four levels and complete soundtrack.

Use Ctrl-R to run it. Racket will compile it and launch the game with your favourite web browser.

Where's the game engine? Well, Grasshopper, the game engine is inside all of us -- or rather inside each of these game files. It actually consists of a simple data structure, some helper functions and an ordered way of calling them.

There's seriously not even enough for a proper library, although I suppose I'll try to do one at some point.

The idea is that Canned Heat provides a "conceptual toolbox" for you to structure your games with. This allows you infinite configurability while making sure that you can always find everything you need. It's a mindset. Like I said.

#OK, Really, How am I Supposed to Use This?

Canned Heat implements a very simplified version of an Entity-Component-System (really great article, BTW!). Except it's so simplified, it's just an Entity-System -- that is, an Entity includes its Components because it's just a dictionary/object/hash.

Check the presentation for a quick(ish) overview. There is also a %hints.md file that describes how to do some common things.

The elements of your game are described with an array of dictionaries. This is the Entity Store. Or just the STORE, if you're reading the source.

Canned Heat also provides a couple of functions (old style: grabs and grab, new style: qm, q1 and qx) to query the Entity Store so you can filter out just the data you need, when you need it.

There are also some default Systems (operations that run against the Store):

• sys-tick -- Increment the age component of an Entity, mark ones that have exceeded their span component for death.
• sys-event -- Fire events that have come due.
• sys-overlay -- Manage overlays for levels, rooms or whatever.
• sys-cull -- Remove entities that are marked for termination.

You will almost certainly write your own systems to implement your game. One of them will probably be sys-win? to check if the player has finished the game. But that's just a suggestion.

The program architecture is divided into a few well-marked chunks (especially in the %soko.rkt example):

• App -- Sets up initial variables (SV and STORE) and housekeeping.
• Utility -- Things I couldn't live without. Your mileage may vary.
• Entity-Sys -- Store query functions and systems. Add your own here.
• Render -- Program output. This can be text, 2D (canvas) or 3D (WebGL, three.js). For now though, all my examples are with canvas.
• Animate -- Apply systems in appropriate order.
• Game Loop and Events -- Start things up and deal with inputs.
• Build/Launch -- Urlang machinery to compile and start the game in a browser. Once it's run, you have a directory with all the files you need.

To make your own game, pick whichever example is closest to what you want to do. Copy it and then delete anything that you don't need. Add the parts you do.

If you have a good idea of what you want to do, start with the %skel.rkt file. It's been stripped down to (almost) the bare essentials.