Adding HTTP support

Hey folks!

Except for the first article, most of this blog has been about gameplay, the game in itself from a player point of view, and content. But technical updates have been rather rare.

I (@fasterthanlime) have had my fun with the interview format, even bringing innocent outsiders in for comedy factor, but perhaps it is time to come back to a more classical format for this week.

The big picture

I’d like to talk a bit about the stack behind Jaakan: how we go about integrating a new functionality in the game that requires new native code.

When I think of the game’s stack, I see this in my head, mostly:

I put game assets in there too, because, honestly, what’s the difference between a song sheet, a level file, a story file, and character script? None! They’re all part of what makes the game what it is, how it behaves, looks, and feels.

So, any day where I only have to edit one of the green areas, e.g. integrate a new animation @bigsylvain just drew, is a walk in the park: I copy a file, maybe add a line or two of typescript, and I’m done.

Well, I lied — TypeScript is compiled too, to JavaScript — but the point is, I don’t have to make a new executable. As long as all I change are the game’s assets or TypeScript source, all the old builds are still just as good, on any platform.

Now, “compile once, run anywhere” is not a new thing by any stretch of the imagination, so don’t go thinking I’m bragging or anything, I’m just explaining how we work :)

If we have to modify the yellow parts however, then we need to make a new executable. ooc code is compiled to C code, then via gcc or clang, it’s compiled to native code, so you have to update the actual binary file and maybe some libraries.

Every time the game starts, first the operating system loads all the native libraries it needs, then it hands off control to the app, which does a minimal amount of set up, creates a Duktape engine instance, starts loading all the JavaScript code (that was, remember, compiled from our TypeScript code), and runs it.

In fact, the “ooc app” cell on the diagram above is a mere 20 lines of code, not more. All the important work is done from the TypeScript code, which really ends up being JavaScript code, interpreted by Duktape, and which itself uses ooc and C libraries via some more glue generated by… a ruby tool.

Confused yet? Let’s try another way to visualize it:

Whether libraries are written in C or ooc doesn’t matter — as far as we’re concerned, they’re just a big bag of goodie we want to be able to access from JavaScript.

Adding HTTP support

Now that you have a comprehensive understanding of the intricacies of Jaakan’s technical stack, let’s try and change it up a bit. Last week we added a brand new sound engine, this week we’ll try to add some http server functionality.

Why an HTTP server? Well, browser are a fantastic platform we can leverage for development. An application I can definitely see being useful is a remote debugger/inspector for the game — since 99% of the game’s logic is in JavaScript, we can easily evaluate JavaScript code in the game’s context, it wouldn’t be too hard to create a comfy interface around that (similar to node-inspector)

The first thing we’re going to need is an HTTP library. We could write one in ooc, but I don’t have that kind of free time, so let’s use an existing one. For The Stanley Enigma, I’ve used libmongoose, which is very easy to use but unfortunately it’s GPLv2-licensed so, no go for a commercial indie game (and honestly I don’t have time to contact them and get a quote)

Instead, let’s turn our attention to [libmicrohttpd][] which, although it seems to live under the GNU umbrella, is licensed under the LGPL2, which allows us to use it in a commercial project without disclosing our source code, as long as it’s dynamically linked.


The thing with libmicrohttpd, as with most GNU things, is that it seems a tad complicated at first taste. Then again, it’s C, what do you expect, Sinatra?

Here’s how a basic example looks:

The first thing we need to do is write a set of ooc bindings for this library, so we can use from ooc code. Why do we need to write bindings? Because the ooc compiler has its own type system, type checking and so on, it allows us to handle some things as if they were object, which can make for more readable code sometimes. Let’s just go through the motions.

After downloading libmicrohttpd, building and installing it with the traditional:

./configure --prefix=/usr make install -j4

We can take a look at the header file:

Looks like some sort of flags needed for initializing a server. We can cover that easily enough in ooc with:

Then we look up some functions used in the tutorial:

And we can wrap them as if they were an object:

The result of this binding work is available on Github at fasterthanlime/ooc-microhttpd, if you’re curious

And finally, our microhttpd tutorial, the very same, looks like that in ooc:

Higher and higher

But that’s not very satisfying. First of all, the ooc version is just as long (if not longer) than the C version. What of the terseness we promised? Secondly, we can’t use such a binding directly from JavaScript (via Duktape), because it relies on types like CString (which is really a pointer to an area in memory that contains C characters).

So we need to buy a higher-level interface to libmicrohttpd. Let’s call it gonzales.

Here’s a first shot at it:

And then we can write a simple sample in ooc like so:

Much shorter!

The interpreter

And now, let’s try and use Gonzales from our JavaScript code. All we need to do is import gonzales from our ooc app, and tell collar to generate glue for that. Then we can write TypeScript code directly, with type checking and everything!

And that’s about it!

Until next time, take care.

– Amos