An open mind is like a fortress with its gates unbarred and unguarded.

This is the story of the Super Castle Game, a js13k game jam entry.

Naturally, it begins with the theme of the 2023 edition of the compo: 13th Century. When it dropped, I was completely lost. Medieval history is like Warhammer 40,000 to me, where in the grim darkness of ages past, there is mostly war. Doesn't give off warm fuzzies.

So I began coding a simple board game thing: a square grid with pieces on it. Such an enjoyable experience, that. Writing clean code for small, easy to understand systems.

Smooth brain energy

Herein lies my first mistake, thinking that a square-grid-based game will be easy to make. Full of unwarranted enthusiasm, I added clusters of pieces that should move together as a single large object, and whipped up some sort of a collision solver: a piece pushes another piece, so we recursively solve for that piece moving. And its entire cluster moving.

So when there are two interlocked clusters, they push one another into a stack overflow. This terrible algorithm haunted me for the entirety of the compo, and I'm still unsure how to implement it properly, edge cases and all. In a feat of peak gamedev, I settled on making levels that don't break the solver, and that was it.

Of ducks and men

At this stage the game spontaneously ended up being about a duck going on a crusade, under the working title of Super Holy Chalice and bearing the following description:

• Embark on a crusade

• Solve challenges

• Reclaim the Holy Chalice

• In the 13th century

To be honest I wasn't feeling it, so at work I discussed the matter with a brilliant engineer on my team, who suggested a different take: the siege of Baghdad. We're a scholar at the House of Wisdom, about to be sacked by the culturally diverse Mongol migrants. We need to prevent this from happening using magic. Puzzle solving is the compulsory magic ritual.

Super Siege of Baghdad

In the heart of ancient Baghdad, a shining beacon of knowledge, the House of Wisdom, stands as a testament to the golden age of enlightenment. As the Mongol forces close in on the city in 1258, threatening to obliterate centuries of accumulated wisdom, one scholar embarks on a mission wielding not a sword, but the power of sacred geometry.

Set in the 13th century, Super Siege of Baghdad immerses you in a world where geometry is more than an empirical science; it's a mystical force with the potential to change the course of history. Can you harness this power and save the House of Wisdom from its impending doom?

I don't hate this fluff piece, but to me it feels way forced. This is not something I would've considered if not for the compo theme.

When talking about this issue with a friend, the third and final take on the 13th Century theme was born: a game about building a castle. Castles are vaguely medieval. The level is a quarry, where you arrange the stone blocks. Suddenly it all made sense.

Super Castle Game

The fortress of the mind will rise

Now I needed to render a castle. Isometric projection in hand, I made this model by starting with a cube and poking holes in it for the gate, windows and battlements on top. This is only done once while the game is loading, then the model is stored as three one-dimensional arrays for x, y and z coordinates of each block.

Optimizing the rendering of this thing was a fun little challenge. I'm working with the regular 2D canvas, where each separate draw call is expensive, and acceptable performance is achieved by making a single large path and then filling it all at once. But at the same time I rely on rendering the model back to front, one block at a time, else it looks all messed up.

To stress test the rendering (so that the effect of any optimizations is easier to see), I ran a solid cube 121212, or about 1700 blocks. Three sides per block are visible, amounting to roughly 20,000 calls to .lineTo() and 5000 calls to .fill().

You can imagine it was REALLY slow in this setting. We're talking barely 30 FPS on a half-decent Intel MacBook, and budget smartphones would be seeing fractional frame rates. So I tried two things to make it faster:

1. Group the .fill() calls so that a run of blocks can be filled with just three calls per run, down from three calls per individual block. This only works if there's no depth order fighting, so I made it render vertical columns of blocks together: first the top side of each block (this is important!), and then right and left sides. And it's super effective! Like I anticipated, calls that add a subpath are cheap, it's .fill() and .stroke() that are costly.

2. Then, in the mood for some more performance optimization, I made a hash function for blocks to check if they're occupying the same exact spot on screen. The function is rather straightforward: (x - y) * 999 + (x + y - z - z). With this, culling the blocks that are fully covered by others closer to the camera became very easy. I also decided to bake the culling into the model itself, since there's no camera rotation anyway. This reduced the number of blocks by about 20% when applied to my actual castle model, so it's a small win.

After these changes, the test bench ran smoothly and capped at the screen refresh rate on any computer I tried.

Level design

This entire performance story is, of course, about procrastination: instead of doing the hard thing, such as making levels that are fun to play, I worked on parts that are fun to fiddle with. So now I had a fast isometric renderer for the title screen, but no level design for the bulk of the game.

Here I made a decision which, for a change, I didn't regret immediately: to use Aseprite for a level editor. If you're not familiar, Aseprite is an open source pixel art editor, and it's as gorgeous as it is convenient to work in.

Having made a Python script to convert PNG files to a BigInt EEBE format, I now had a toolchain to iterate on the levels very efficiently. And iterate on the levels I did: turns out it's so hard to come up with a clever puzzle! Who would've thunk.

Some of my earlier designs were laughably broken. One of the stages I thought was impressively challenging could be solved by pressing, quite literally, right, up, right. That's it, that's the entire solution. I have failed to see this (elegant, but very much unintended) answer for the longest time, and only discovered it thanks to a teammate, whom I coerced into early playtesting.

Decentralized

This time I wanted to make a real appearance in the Decentralized category of the compo, so I decided I'll make a level editor. Levels are relatively compact, so I put them in the URL of the game. This way anyone can make a level and share it via any means: on a social network, git repository, by email, or a graffiti of a QR code on a neighbor's house. (Please send me a picture of that!)

There's a Community Levels page with a collection of stages made by you. Send pull requests, or just drop me a link to the stage you've made, and I'll add it.

InterPlanetary

The game is also available on IPFS: ipfs://bafybeie5x57m5gdh6r3bz7wnfeifo22wvcb2efas2l5hplvnwl5vz6myua

There's a number of HTTP gateways to choose from, in case your browser doesn't support IPFS. (Most of them don't.)

Coding highlights

In case you're interested in low-level stuff, in no particular order:

Super Castle Game uses natlib, a highly composable library for small games. I wrote both, so it's not a sound endorsement.

I also run Michikoid, a JavaScript macro processor that allows me to manually control how things are inlined in the resulting JS bundle. (I made this one too.)

Speaking of build, this year I wrote my build scripts in both bash and PowerShell. The PowerShell one is very slow for no apparent reason, but it made switching between a MacBook and a Windows PC so easy that I'm not even mad. Compared to Windows Subsystem for Linux, which is low key abominable, PowerShell hits different.

Having no artistic ability whatsoever, I chose the Sweetie 16 palette by GrafxKid as my main driver. Best choice ever made in the history of choices.

The pixel font is from the TIC-80 fantasy computer.

There's also gamepad support, and turns out it's really easy to implement! Of course I only read the left analog stick and the B button, but it's still impressive how straightforward the Gamepad API is, especially compared to others. (I am truly convinced that the Web Audio API was designed by a committee of sentient guacamoles from hell.)

Anyway, have fun with the source code, it's a tangled mess! I'll try to clean up some of the more egregious parts. It's under the GPLv3 license, so feel free (as in freedom) to do whatever.

Fin

Thank you for reading! Or scrolling to the end! If the js13k voting is still happening, please play Super Castle Game and vote. Then play other games, too, there are some truly phenomenal ones in there.

Follow me on GitHub for more spaghetti code.

Temperature

The temperature (a floating-point number in the range 0.01.0) is used for sampling during response generation, which occurs when topP and topK are applied. Temperature controls the degree of randomness in token selection. Lower temperatures are good for prompts that require a more deterministic and less open-ended or creative response, while higher temperatures can lead to more diverse or creative results. A temperature of 0 is deterministic, meaning that the highest probability response is always selected.

Maximum Output Tokens

Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 6080 words.

• For OpenAI, this parameter should be in the range 12048

• For PaLM, this parameter should be in the range 11024

Top-K

Top-K (an integer in the range 140) changes how the model selects tokens for output. A top-K of 1 means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a top-K of 3 means that the next token is selected from among the three most probable tokens by using temperature.

For each token selection step, the top-K tokens with the highest probabilities are sampled. Then tokens are further filtered based on top-P with the final token selected using temperature sampling.

Specify a lower value for more deterministic responses and a higher value for more diverse responses. The default top-K is 40.

Top-P

Top-P (a floating-point number in the range 0.01.0) changes how the model selects tokens for output. Tokens are selected from the most (see top-K) to least probable until the sum of their probabilities equals the top-P value. For example, if tokens A, B, and C have a probability of 0.3, 0.2, and 0.1 and the top-P value is 0.5, then the model will select either A or B as the next token by using temperature and excludes C as a candidate.

Specify a lower value for more deterministic responses and a higher value for more diverse responses. The default top-P is 0.95.

import csvwith open('file.csv', 'r') as f:    reader = csv.reader(f)    lines = [ln for ln in reader]

And as one would expect, the result of running this code was Error: field larger than field limit (131072)

The 128 KiB field size boundary is so beautifully arbitrary. Use the following workaround to fix that:

import syscsv.field_size_limit(sys.maxsize)

Doesn't have to be specifically sys.maxsize, any sufficiently large number would do.

There's no moral to this story, just mild suffering.

The ZX Spectrum system font is a nice example of this. It's an 8x8 pixel bitmap font used on the ZX Spectrum, a home computer released in the United Kingdom in 1982, and it's still recognized today (more than 40 years later!) as part of the machine's unique visual identity.

I mean, just look at it:

Sure, the font is a bit of a mess, but it's a charming mess.

By the way, the screenshots in this post were made using Fuse, the Free Unix Spectrum Emulator. It's a delightful application, and I had a blast playing around with it.

The Sinclair BASIC program producing the output above is as follows:

Typing this in on a regular keyboard was interesting: the BASIC keywords are their own code points, so pressing P while in keyword mode produces PRINT as a single character, R is RUN, and so on. Had to look some of them up, since I never remembered the ZX Spectrum's keyboard layout in the first place.

To better appreciate the original font design, compare it to a modern ZX Spectrum font, Clairsys, designed by Paul van der Laan in 2002:

Clairsys features less blocky letters, generally narrower than in the original font, and with larger counters. The letter spacing, as a result, is super wide.

And here's the same one-liner from before, typeset in Clairsys:

Dotted zero is a retribution for our collective sins. Other than that, I don't have any overarching conclusions for this post.

I'll try to make this into a series on pixel fonts. Let's see how that goes.

My friend Roman pointed out that I was, in fact, doing things suboptimally in the EEBE post:

• The array of scanlines can be replaced with a single BigInt literal, bringing substantially less syntactic overhead.
• The use of integer bpp for color depth can be wasteful if the number of colors isn't a power of two, and we're not seeing any performance gains from it either. More compact results can be achieved by using the number of distinct colors directly.

The updated example is as follows:

// ECMAScript Embedded Bitmap Encoding (EEBE)// Required fields:export const value = 0x61e3c70891a1c08nexport const width = 7export const height = 9export const cardinality = 2// Optional fields:export const palette = [  0x000000,  0xffffff,]

The following fields are exported:

• value is a BigInt literal containing the bitmap contents.
• width and height are self-explanatory.
• cardinality is the number of distinct colors in the bitmap.
• palette is an optional array of integers, each representing a color.

The updated playground for this version is here.

// ECMAScript Embedded Bitmap Encoding (EEBE)// Required fields:export const lines = [  0b0001000,  0b0111000,  0b1101000,  0b1001000,  0b0001000,  0b0001110,  0b0001111,  0b0001111,  0b0000110,]export const width = 7export const bpp = 1// Optional fields:export const palette = [  0x000,  0xfff,]

Let's call it ECMAScript Embedded Bitmap Encoding (EEBE). EEBE is a format used to store bitmap images within ECMAScript code in an efficient manner. It is designed to be compact and easy to parse, suitable for scenarios with hard size constraints such as js13kGames, and isn't at all intended to be a general purpose image format.

An EEBE file is an ECMAScript module that exports the following fields:

• lines: an array of integers, each representing a scanline of the image. Each integer is a bitfield of size width * bpp, with the least significant bit(s) representing the leftmost pixel of the scanline.

• width: the width of the image in pixels.

• bpp: the number of bits per pixel.

• palette: an optional array of integers, each representing a color. The number of colors in the palette should equal 2 ** bpp. Nullish values are treated as transparent. If this field is omitted, the rendering is implementation-defined.

• Any other fields, depending on the implementation.

Optimized for size, the above example is 116 bytes long (99 bytes gzipped) and produces the following image:

EEBE Playground

// This is the same example as above, written in a compact form.export const lines=[8,56,104,72,8,14,15,15,6]export const width=7export const bpp=1export const palette=[0,4095]

The footprint can be further reduced during build:

• Using a module bundler such as Rollup will eliminate the export statements.
• Running a minifier (e.g. Terser) will shorten the field names and inline some of the constants.

It's also possible to save bytes by using 12-bit color (#9d5 instead of #99dd55) and sharing the palette between multiple images.

Decoding the image

An EEBE image can be decoded as follows:

function readBitmap(lines, width, bpp, readFunction) {  const shift = 1 << bpp  for (let y = 0; y < lines.length; ++y) {    for (let x = 0; x < width; ++x) {      const value = lines[y] / shift ** x & shift - 1      readFunction(x, y, value)    }  }}

(This function is available in natlib.)

For each pixel in the image, the readFunction(x, y, value) is invoked. The pixel's value is an integer in the range [0, 2 ** bpp - 1] that can be used to retrieve the corresponding color from the palette.

You might be wondering why the readBitmap function uses the division operator instead of a << bit shift. It's because the bitwise operations in JS truncate their operands to 32 bits, whereas the Number type is a 64-bit floating point, allowing for integer values of up to 53 bits. So the tradeoff here is that we can either

• Enjoy the full 53-bit stride for images, but use the (slower) division operator, or
• Use the fast << bit shift operator, but only get 32 bits of stride.

Real-world usage

I've used this format in my js13kGames entries, including The Neatness, with good results.

It's clear that variations of this storing bitmaps as int[] have been in use since at least ZX Spectrum days. The motivation for writing this short spec and giving EEBE its name is to promote interoperability, not to claim originality.

Questions

Absolutely none of these questions have been asked.

What about extensibility?

You can include extra fields. For example, in The Neatness levels contain hotspots (entry and exit points) in addition to the level geometry represented by the bitmap.

Where's the tooling?

It's in the planning phase.

How to pronounce "EEBE"?

Try [jebi].

Why did the chicken cross the road?

To gather intelligence. It was a Chinese surveillance chicken.

type PositiveInteger<T extends number> =  `${T}` extends '0' | `-${any}` | `${any}.${any}` ? never : T

It can then be used as follows:

function test<T extends number>(n: PositiveInteger<T>) { /***/ }

The function's argument will be correctly checked at compile time, as shown here:

Things that can't be checked at compile time, such as variables, are passed through. This is obviously unsolvable without resorting to runtime checks (type predicates), because TypeScript types don't exist at runtime.

Similarly, a non-negative integer type, aka unsigned int, can be defined as follows:

type NonnegativeInteger<T extends number> =  `${T}` extends `-${any}` | `${any}.${any}` ? never : T

Both the PositiveInteger and NonnegativeInteger types will be available in the next version (0.1.10) of natlib. They can be found in the prelude module.

// npm i natlibimport type { PositiveInteger, NonnegativeInteger } from './node_modules/natlib/prelude'

Implementation note: all instances of any in the template literal types can be changed to string or even infer _ this shouldn't matter.

html, button, input {  font-family: -apple-system, 'Segoe UI', 'DejaVu Sans',    system-ui, sans-serif;}code, kbd, pre, samp {  font-family: 'SF Mono', SFMono-Regular, ui-monospace,    'DejaVu Sans Mono', Menlo, 'Cascadia Mono', monospace;}

(The CSS selectors are provisionary.)

System Fonts

Monospaced Fonts

To produce a node_modules folder as if natlib was installed as a dependency, the following Python script was used:

#!/usr/bin/env python3from contextlib import contextmanager, ExitStackfrom pathlib import Pathimport shutilfrom but.external.typescript import typescript_callOUR_ROOT = Path(__file__).resolve().parents[1]@contextmanagerdef create_symlink(path: Path):    node_modules = path / 'node_modules'    node_modules.mkdir()    (node_modules / 'natlib').symlink_to(OUR_ROOT / 'out', target_is_directory=True)    try:        yield    finally:        shutil.rmtree(node_modules)def build():    examples = OUR_ROOT / 'examples'    projects = (        ('..', False),        ('couch2048', True),        ('notfound', True),    )    for path_str, need_symlink in projects:        path = examples / path_str        with ExitStack() as stack:            if need_symlink:                stack.enter_context(create_symlink(path))            typescript_call(['--project', path])

Here, OUR_ROOT / 'out' is where TypeScript puts the resulting JS files.

This way the code that runs inside the context manager block has its node_modules folder set up correctly.

Thankfully there's the following macOS hidden setting:

defaults write -g NSTextInsertionPointBlinkPeriodOff -float 0defaults write -g NSTextInsertionPointBlinkPeriodOn -float 4000000000

This worked for me on macOS Big Sur. I hope Obsidian adds this option before Apple kills the workaround, bless its little soul.

It all started when I began playing The Looker, a brilliant game by Bradley Lovell. Line-based puzzles in The Looker are mostly satire, the player being able to bypass many of those by scribbling madly. I was instantly convinced, however, that it was the perfect game mechanic.

The title of the game, The Neatness, is absolutely a nod to Jonathan Blow's work, which I'm a huge fan of. So this was the easiest decision ever.

Level design was done entirely on paper, which naturally worked great for this type of game mechanic. That's not to say it was an especially easy task, I found myself iterating on puzzles for the entire duration of the compo.

And here's how the actual development went:

Algorithms

The most basic feature of The Neatness is drawing lines on screen. Of course, the first thing that comes to mind is the Bresenham's line algorithm. However, Bresenham's algo makes diagonal connections; if we're going to check the connectivity on a square grid, it makes more sense to only account for neighbors in four main directions (left, up, right, down).

Having that in mind, I implemented the digital differential analyzer (DDA) algorithm for drawing lines, and it worked flawlessly, first try. And I totally didn't have to debug it for like two hours because of a subtle bug.

The second feature I needed was the ability to tell if one control point was connected to the other, to signal level completion. And nope, I didn't go with the A* algo for that. I wanted the code to be as efficient as possible at this point, since I had no idea how computationally intensive the other parts of the game would end up being.

Instead of A*, I decided to flood fill any new lines that are drawn with the first nonzero neighboring thing they meet (either a control point, or another line). Then the code checks if we've met a different neighboring thing, meaning the two are now connected.

Despite using the flood fill algorithm, this is very cheap to compute: the player shouldn't be able to cover any significant length between pointer events, and we never update the same spot twice.

Thanks to Lode Vandevenne's excellent Computer Graphics Tutorial, I was even able to implement this stuff reasonably fast.

Colors

Being incapable of producing a color scheme that doesn't look horribly wrong, I left this task to professionals and went with BLK NEO and TwilioQuest 76 palettes.

However, the main set of colors didn't work on a bright background. To remedy this situation, I used the entirety of my severely limited knowledge about colors to do the following:

1. Convert the main colors from sRGB to linear RGB
2. Take that into the Oklab color space
3. Tone down the L channel ever so slightly
4. Retrace the steps all the way back to sRGB

I'm immensely grateful to Bjrn Ottosson, the man, the legend, who bestowed the Oklab color space upon us. It's magical.

Pixels

Another decision made very early into the competition was to use non-square pixels (kind of like SNES) for the painting layer. Ideally I'd like to simulate a proper CRT screen with shaders, but that feat of engineering surpasses my WebGL abilities rather dramatically.

What I've learned about the SNES video output is as follows:

• Internal SNES aspect ratio is 8:7, at the resolution of 256224
• Contemporary CRT TV aspect ratio was 4:3
• So the pixel aspect ratio (PAR) should be 7:6 (4:3 8:7)
• However PAR of an NTSC TV is 8:7 because reasons

So in the end I went with the PAR of 8:7, which gives a nice subtle anti-aliasing effect.

Sprites

The Neatness uses both 1-bit and 2-bit sprites, encoded as plain bitmaps and represented using Array<Number> in JS. I don't think that implementing any form of compression (such as RLE) for these bitmaps is productive, because the js13kGames' compulsory submission format ZIP will outperform RLE anyway.

2-bit sprites (which amounts to transparency + 3 colors) are used for the skulls, gravestones, the princess, and her crown (the crown being a separate sprite because I wanted it to have a distinct color). The levels and the buttons on the right side of the screen are 1-bit sprites.

In order to iterate on the level design somewhat efficiently, I wrote a Python encoder that takes a bunch of picture files and outputs bitmaps as JS arrays. Using Aseprite as a level editor is wonderfully convenient.

One caveat to pay attention to when working with bitmaps in JS: bitwise operations truncate their operands to 32 bits! Meaning that you can't use the entirety of JavaScript's 53-bit integers if you do shift right, either >> or >>> you have to divide by a power of 2 instead.

natlib

natlib is a highly composable library for small games, cannibalized from my previous js13kGames entries. The part that I'm especially fond of is the fixed-step game loop, I use it at every opportunity (which is not often).

The Neatness uses the following bits and pieces from natlib:

• 2D vector math
• Viewport auto-scaling
• Mouse and touch event handling
• PRNG (the PRNG of choice being Mulberry32, designed by Tommy Ettinger)
• The fixed-step game loop mentioned earlier

Package size

One of the prominent challenges of the js13kGames compo is the package size, which is required to be no larger than 13,312 bytes.

A 13 KB ZIP file is a good 7090 KB of JS. Turns out I physically cannot write that much code in a month. By the end of the compo I still had some 2 KB to spare, before any optimizations (and I maintained a list of possible code size optimizations just in case.)

By the way, The Neatness source code is released under the GNU General Public License version 3.

Kudos

I'd like to thank my friends @iiSatana and Andrey Shuster for beta testing my stuff.

Super special thanks to Andrzej Mazur for organizing this amazing event.

And thank you for reading this wall of text.