I didn’t finish this week’s lap, and frankly I don’t have the motivation to do it. I’m in a bit of a weird position–I feel like I haven’t delved deep enough to really give this engine a fair shake, and yet what I have seen so far doesn’t inspire the confidence I need to keep going… all of this is to say that I don’t like Heaps.io, but I’m not confident enough to say that it’s entirely the engine’s fault.

Regardless, let’s talk about that experience a little.


My initial impression of Heaps.io was actually pretty good. The basic introductory text seemed to imply a pretty sane modern structure based on a scene graph, and the setup seemed simple enough. I didn’t really like the focus on specific applications, but I figured that was mostly just to help out beginners.

My problems began immediately after that. The next major section of the documentation goes over 2D rendering, and shows a simple example of resource loading (here, scroll down to the Image section for that). What it doesn’t mention is that you need to initialize a resource loader. Indeed, it doesn’t mention those loaders at all! The first reference I found was a 1-line comment in a code sample several pages later.

If you don’t realize this because you’re not psychic, you’ll get this helpful exception when you try that code:

“Resource loader not initialized: call to hxd.Res.initXXX() required”

…ok, so clearly a loader needs to be initialized, and the functions are in the hxd.Res namespace. See? I’m not being sarcastic, it is helpful!

Well, except that if you check the API docs you’ll notice that there are no init functions listed. I’m not really sure why that is, but it’s a problem. I also checked a good half-dozen of the official samples and conveniently, none of them had any sort of resource loader initialization either. Nice. The time I spent setting up loading code and searching the API and samples is a waste, because what I really had to do was:

  1. Skip from the second section of the documentation (H2D) to the fourth section (HXD). (And as an aside, what does HXD even stand for?????)
  2. Go into “Resource Management”
  3. …and read that instead of the example that was given in the first place.

This is enough to progress, but there’s no simple way to work out what resource loaders even exist. ‘Embed’ is used as an example, but if you look at the API page for it… Weird, there’s nothing at all. And by the way, don’t bother checking hxd.res.Loader. I know it seems like the obvious next place to look, but it contains nothing relevant to this search. To this day, I still don’t know if there’s a list of resource loaders out there.


After all that hassle, we finally have textures onscreen. At this point, I was pretty miffed but not nearly ready to throw in the towel. The apparent lack of vector math (more on that later) also didn’t deter me, since I saw that collision detection code was available. Most of the math I’ve been doing in these demos has been bouncing a ball off of rectangles, so a basic collision API would cover that pretty well.

I’m going to spoil the punchline now and tell you that it doesn’t cover that at all. You might think it would after looking at this sample, where they use built-in API calls to get the normals of a rotating collision object from a point in space. Amazingly, this function is entirely exclusive to the capsule collider class, for…some reason? Beats me. All I really need is the closest point from a circle-to-rectangle collision check though, so let’s see what we get from that…oh. We get a bool, and nothing else.

At this point, I was starting to question how Heaps.io games handle physics, seeing as the built-in collision detection code doesn’t seem to give anything that’s needed for collision resolution. On a whim, I decided to check the hxd.col.Point class. It has all the vector math you could want! I should’ve been happy, but the only thought racing through my head was: “Wait, if this exists then why do all the scene graph nodes exclusively take raw floats???????”


And then, I stopped. Throughout these past 2 1/2 months, I’ve seen and dealt with a lot of weird and arbitrary API design, broken or incomplete docs, and a handful of runtime bugs. I’ve pushed through it all to bring you my opinions, but now? Now, I’m tired of this. Heaps.io put the last dagger in the back of my desire to try new game engines. I just don’t have it in me to keep wondering about these things, and I think it’s time to settle down and change gears.

Thankfully, that’s already what’s next on the agenda! We have one more post to round up all of the past engines and frameworks, and to declare a “winner” that I’ll be playing with further.

← Back to Blog