some thoughts on bitsybox and game preservation

"a night train to the forest zone" running in bitsybox on a raspberry pi

bitsybox is a desktop bitsy emulator that can run games in the plaintext .bitsy format and supports gamepads - I think it's a pretty fun way to play bitsy games. :)

I've been meaning for a few months to write more about the why and how of bitsybox - this is that post!

(if you haven't seen me post about bitsybox before, I mentioned it in a previous blog about low level refactoring of the engine - more on that later on.)

preserving games

bitsy turned five last fall, and there are now over 4,000 games made with bitsy on alone. it's come a long way from the barebones tool I used to make games in a notes app on my phone in the fall of 2016. more and more I've been thinking about where bitsy will be 5 or 10 years from now. will we still be able to play all these incredible games, worlds, and stories?

digital games and art, and I think web art in particular, have a well-documented preservation problem. platform owners lose interest in maintaining tools and tech, servers get shut down when money runs out, or browser vendors change important APIs, and the history of whole scenes become unplayable or are lost entirely.

bitsy already has some advantages in this area: it's not commercial, it's open source, there is no single centralized distribution platform (though itch comes closest), and it has a plaintext file format.

however, bitsy is still vulnerable to changes to browsers and web APIs, and as the engine and tools have changed and grown over the years, it's become harder to create and maintain alternative players such as candle's bitspy (which powers the very cool bitsy boutique) or BitsySharp.

so what to do?

bitsy system APIs

I think Rekka and Devine of Hundred Rabbits make a good observation when they said this in a recent profile on The Verge:

The projects that survive the treadmill of ever-changing physical hardware, are the ones designed explicitly for small virtual machines (such as Another World), which are easy to play today due to their targeting of a portable and virtual core.

but bitsy doesn't target a virtual machine - or does it? ok, not exactly, but bitsy is written in javascript, and javascript engines have some similar benefits to VMs. javascript source code written for one engine can run in others, and there are many implementations for different platforms. I think the biggest hurdle for porting bitsy today isn't javascript itself, but rather the vast and frequently changing APIs specific to the web that add features beyond the core of the language. it's an intimidating barrier to building and maintaining a bitsy port if you have to worry about supporting the entire HTML canvas spec (much less the rest of the web APIs) to be confident of compatibility with new versions of the engine.

this is where the new bitsy system APIs come in. I recently added these functions as a foundation for the lowest level of the bitsy engine: they wrap all the web APIs (such as the HTML canvas) that the engine relies on, only exposing the parts necessary for bitsy games. to port bitsy, you now only need a javascript engine and implementations of the system API functions (of which there are currently 18).

(one word of warning: I'm still figuring out what I want the APIs to look like, so while they are functional they're still very experimental and I expect them to potentially change a lot from version to version. at some point I will get them to a v1.0, after which they should be a stable base to build on. for now, that's still in the future.)


the same game running on my 2011 macbook

it's nice in theory to have a wrapper around the web APIs, but to prove to myself that they're actually useful I felt I should attempt a bitsy port myself. bitsybox is the result.

overall I'm pretty happy with how it turned out. you can read the source code for yourself, but here's a quick summary of how it's made. the whole implementation of the system APIs is in one C file. for the javascript engine, I used duktape. for cross platform graphics, windowing, and input, I used SDL.

I learned a lot making bitsybox, and I think that will translate into improved APIs as I continue to iterate on them. I'll also continue to update bitsybox as I release new bitsy versions (such as the sound and music update I'm working on now), but I don't consider it the final word on bitsy emulators or ports. my hope is that, as the APIs stabilize, more people will be inspired to make their own ports!

limitations and final thoughts

although I'm excited about the system APIs and bitsybox, I don't want to leave anyone with the idea that this is the only work (or even the most important work) needed for preserving bitsy games.

one thing I personally plan on working on in the near future is documentation of the bitsy file format. there are many good reasons to do that, but one obvious one is if anyone wants to write another non-javascript port of bitsy, it would be super helpful for that kind of effort.

in addition, being able to play games outside the browser is useful, but only if there are games to play! right now, is without a doubt the biggest repository of bitsy games and I have a lot of confidence in itch and how it's run, but - as recent news with bandcamp reminds us - over time platforms can change or even disappear. someday it might make sense for there to be a standalone bitsy archive project similar to museum of zzt.

another important consideration is that many bitsy games use hacks to extend the engine, and supporting those is by nature beyond the scope of what bitsybox can do.

anyway, that turned out kind of long, so thanks for reading to the end! <3

if you have any thoughts on this topic, don't hesitate to leave me a comment below :)


Log in with to leave a comment.


I've had similar worries about web games, and actually rescued one of mine in a similar way: by making a Duktape binding for ncurses. Great minds think alike. :P


cool :D sounds like an interesting project! I've definitely enjoyed using duktape so far - it's easier to work with than I would have expected


Thanks for writing this, this is really important

thank you! and thanks for reading :)


in the process of writing my own parser, I ended up documenting some undocumented and obsolete aspects of the game data format, like the old WAL attribute, optional colours, etc. it's maybe not the most readable thing but might be of interest to someone!


that’s awesome! thanks for sharing :)


A really great and insightful blog post adam! That is some really great work you are doing there even though the current system of browsers, itch and discord works pretty well. I agree that in the long run it is better to play safe.

fyi a really great web series about preserving digital worlds is this one: (if you havent watched it already)


thanks Kai! I agree that browsers and itch and discord has been working well for bitsy so far, and I expect bitsy will always be “web first” - but I also like idea of planning for resilience

thanks for the recommendation! I actually watched one episode of that series at a zone nite - it was really cool! I should check out the rest sometime :)