Game Development with Clojure/ClojureScript

This weekend it’s Ludum Dare again, the world’s longest running game jam. The idea is that, alone or with a team, you build a game in a weekend based on a certain theme.

We got a little team together here in Berlin, and so I’ve been reviewing what options there are for someone wanting to build a game in Clojure or Clojurescript.

The good news is there are plenty of options, as you’ll see from the list below. You can do desktop games, browser based games with canvas or webgl, and you can even create Unity 3D games, all from your comfortable Clojure parentheses.

That’s more or less where the good news ends. Most of these frameworks and libraries are still alpha-level software, many have a “use at your own risk, you’re on your own” kind of warning on the project page. And the documentation… well… let’s just say that you’re likely better off studying cracked turtle bones to figure out how these libraries work.

Disclaimer: most of these I haven’t actually tried, certainly not in anger, so much of what follows is from what I could gather looking at the project page and perusing some code samples and (if present) docs. Feel free to “well actually” me on Twitter if you feel I’m misrepresenting things.

Desktop/mobile offerings

Quil

Platforms: desktop, web
Based on: Processing / Processing.js
Maturity: 👴
Documentation: 😊

Quil is Clojure’s version of the graphics programming toolkit Processing. It’s beginner friendly, and really lends itself to exploration, which is also why ClojureBridge chose it for the official curriculum.

It’s been around for a while and “just works”. The project site has decent API docs, there’s a wiki with useful info, and you can find plenty of examples floating around, like the ones I created last year for The Land of Quil, or the ones that are being worked on as part of the ClojureBridge Berlin Study Group Curriculum.

It’s also the only offering on this list that’s actually cross platform. You do have to keep a few small things in mind, but it’s very doable to have a single code base work for both desktop and in the browser, which is pretty cool.

The only downside is that for game development Quil is pretty limited. Its sweet spot lies more in generative art and interactive graphics. You get a bunch of drawing primitives, and some functions for mouse and keyboard input, but beyond that you’re on your own. No sprites, physics, collision detection, scenes, layers, sound, tweening, or event system. It’s still a lot of fun to play around with, but if you only have a weekend then maybe tone down your ambitions.

Play-clj

Platforms: desktop, Android
Based on: libGDX
Maturity: 👩
Documentation: 😊

Play-clj is Zach Oakes game framework for Clojure. There’s a big warning on the README that he’s focusing his efforts now on Play-cljs, which I’ll cover further down. Zach is the author of Nightcode, a beginner friendly editor/IDE for Clojure. He’s also created a Nightcode spin-off called Nightmod, specifically for game development using Play-clj. It calls itself “a tool for making live-moddable games”. The idea is clear: bring REPL-like interactive development to game dev.

Despite the warning Play-clj seems pretty solid. It’s the only offering in this list that explicitly mentions mobile as a target. Play-clj games use a Entity-Component System which is pretty standard in game development nowadays. It’s based on libGDX which is a feature rich game dev framework, and as such provides many features you’d expect, like sprites or physics simulation.

There’s also comprehensive documentation, not just API docs but also (bless the author) and actual step-by-step tutorial. It doesn’t seem like much to ask but it’s a rare offering in the documentation wasteland you’ll encounter further down.

Oh and Zach (I can say Zach, right?) spoke about Play-clj at Clojure/conj! Check out the talk: Making Games at Runtime With Clojure.

Arcadia

Platforms: desktop
Based on: Unity
Maturity: 👦
Documentation: 🤔

Arcadia is definitely the odd in one out in this list, but it’s such a cool and promising project that it wouldn’t stand not to mention it. Most readers of this blog will know that there is a JVM and a Javascript based version of Clojure, but there’s a lesser known implementation called ClojureCLR, targeting Microsoft’s Common Language Runtime, the virtual machine that powers .NET.

This is what enabled Arcadia to integrate Clojure with Unity, a bona fide A-level professional game development environment. This also means the workflow is a bit other than usual. Unity comes with its own coding environment, and to get started with Arcadia you clone the Arcadia source into your Unity project, although this might change as the project matures.

Unity is a commercial offering, it is not free software/open source, but there’s a free plan for hobby use.

Documentation is still limited, but there are a handful of wiki pages that do seem to contain all you need to get rolling.

Arcadia is development by Tim Gardner and Ramsey Nasser from Kitchen Table Coders, the same group that David Nolen is part of.

Browser based

Now we come to the web part, games that are playable directly in your browser. Note that we already mentioned Quil at the top. Since it’s cross platform it really belongs in both categories.

To evaluate these libraries it’s good to first have a look at what powers them under the hood. Whatever superpowers they have will be inherited directly from whatever javascript library is driving them.

Some of these only provide a thin wrapper for Clojurescript, meaning they don’t bring anything new to the table, but merely provide a more idiomatic syntax, avoiding lots of interop calls. Others try to add value of their own.

Play-cljs

Platforms: browser
Based on: p5.js Maturity: 👶
Documentation: 🤔

P5.js is a reimagination of Processing.js, the library Quil is based on. It wants to “make coding accessible for artists, designers, educators, and beginners”. That’s a great goal, but just like with Quil this means that handy features specifically for game development are a bit thin on the ground.

Play-cljs seems to mostly be a thin wrapper around p5.js, although it’s possible the author plans to build more gaming features in. Note that despite the one letter difference, play-clj and play-cljs are completely different animals, with completely different feature sets and APIs.

Zach tends to do a pretty good job at documenting things, although there’s no step-by-step tutorial in this case. You do get a bunch of example games, and generated API docs, which for such a minimal library really might be enough.

Chocolatier

Platforms: browser
Based on: Pixi.js
Maturity: 👶
Documentation: 😠

Chocolatier seems pretty impressive, it’s based on Pixi.js which prizes itself at being “the fastest, most flexible 2D WebGL renderer”. It has few hundred Github stars, and it seems a lot of thought has gone into its design. The author even did a conj talk about Functional Game Design, and the README talks a lot about its “modified entity component system”, but I’m really missing a gentler introduction on how to actually use the thing.

There’s a big example in the README that’s more or less provided without comment. There’s a documentation folder, with a single file Intro.md, containing a single line: “TODO: write great documentation”.

It’s really unfortunate, I feel like if I had a day or two to sink my teeth into this, preferrably well rested and with few distractions, I could get to a point where I could have a lot of fun with it. Sigh… oh well, I guess as a creator of accessible technical content it’s good to know there’s still plenty of work to be done.

Phzr

Platforms: browser
Based on: Phaser
Maturity: 👶
Documentation: 🤔

Phzr is just a thin wrapper around Phaser, one of the more popular Javascript game engines. Documentation is limited, and instead you’re simply referred to the Phaser docs. This of course is the benefit of thin wrappers, as long as the underlying library is well documented you’re all golden. So I think this actually would make a pretty good choice, although the question is if you really need a wrapper then.

re-frame + SVG

Platforms: browser
Based on: Reagent/React
Maturity: 👦
Documentation: 🤔

Not a game library as such, but still something I would consider a valid option. Browser support for SVG has improved rapidly in recent years, and React hasn’t missed the boat either. The result is that you get drawing primitives right in your DOM, which can then be styled and animated, and which generate DOM events that you can respond to.

In that sense it’s no less basic than Quil or play-cljs. You could use and React wrapper like Reagent, Om, Quiescent, or Rum, but my favorite by far is re-frame, and I believe its event system is uniquely suited for use with games.

And re-frame has some pretty decent docs. It’s a bit of a weird style, and the README is a bit of work to get through, but it does explain well how it works, and there are wiki pages explaining all the core concepts. Some even say the re-frame docs are like the hidden documentation for Reagent, the library re-frame is built on. Some Reagent concepts are only properly explained here.

You might have to be a bit more performance-conscious than with other options, but make good use of React/Reagent’s optimizations to avoid unnecessary rendering, and keep in mind that some things are cheaper to animate than others.

Finally if I would go this route I would combine it with the excellent thi.ng/geom 2D/3D geometry toolkit for Clojure/Clojurescript. The same goes for Quil or Play-cljs.

Javascript engines

Platforms: browser
Maturity: 👵
Documentation: 😃

Finally a very compelling option is to simply forget about Clojurescript specific libraries, and instead pick any of the popular Javascript game engines. There are literally dozens of high quality libraries out there. Forget about being idiomatic, just interop the shit out of it!

The benefits are obvious: you get a battle tested foundation backed by a large community, and actual documentation. Just use it as is, and wrap as you go where it makes sense.

More blog posts

Announcing lambdaisland/uri 1.0.0

I just released lambdaisland/uri, a pure Clojure/ClojureScript URI library. It is available on Github and Clojars.

This is a small piece of the code base that powers lambdaisland.com. It’s inspired by Ruby’s Addressable::URI, the most solid URI implementation I’ve seen to date, although it only offers a small part of the functionality that library offers.

It’s written in pure Clojure/ClojureScript, with only minimal use of .cljc reader conditionals to smooth over differences in regular expression syntax, and differences in core protocols. It does not rely on any URI functionality offered by the host, such as java.net.URL, so it’s usable across all current and future Clojure implementations (Clojure, ClojureScript, ClojureCLR).

re-frame Subscriptions Got Even Better

Up until recently, to use re-frame subscriptions in Reagent views, you had to use a form-2 component.

A form-2 component is a function that returns another function, which does the actual rendering of the component to hiccup. In contrast, a form-1 component renders the hiccup directly.

;; form-1
(defn todo-item [todo]
  [:div.view
   [todo-checkbox (:id todo) (:completed todo)]
   [:label {:unselectable "on"} title]
   [:button.destroy {:on-click #(dispatch [:todos/remove (:id todo)])}]])

;; form-2
(defn todo-item [todo]
  (fn [todo]
    [:div.view
     [todo-checkbox (:id todo) (:completed todo)]
     [:label {:unselectable "on"} title]
     [:button.destroy {:on-click #(dispatch [:todos/remove (:id todo)])}]]))

Union Types with Clojure.Spec

Elm and other statically typed languages have a great feature called Union Types (also called Sum Types or Algebraic Data Types).

Here’s an example taken from Elm. Suppose your system used to represent users as integers, maybe just an auto-incrementing primary key, but then switched to UUIDs represented as strings.

To correctly model this situation, you need a way to create a type that can be either an integer or a string, that’s what union types give you.