Heaps: A Haxe Game Framework for GPU-Driven 2D and 3D Games

What Heaps Solves and Who It Is For

Heaps is a graphics engine, not a full game engine. The README describes it as a cross platform graphics engine designed for high performance games, built to use the GPUs found on desktop, mobile and consoles. That wording sets the boundary: it gives you a renderer, a scene graph, a shader system and platform backends, and leaves scene management, physics, asset pipelines and gameplay architecture to you or to other libraries.

The audience is therefore narrow and specific. You need to be writing Haxe already, or be willing to learn it, because every part of the framework is Haxe source compiled to the target. You need a project where the same rendering code must run on the web through WebGL, on iOS and Android, on desktop through OpenGL or DirectX, and possibly on a console. The README lists console support for Nintendo Switch, Sony PS4 and XBox One, and states plainly that it requires being a registered developer. That is not a formality: console targets are gated behind platform holder approval, so the framework's broadest claim is also its least accessible one.

If your team is comfortable with TypeScript or C# and has no Haxe experience, the value proposition weakens considerably. Haxe's cross-compilation is the reason the multi-target story works at all, and fighting that toolchain while learning a renderer is a poor first project.

How the Renderer, Scene Graph and Shader Pipeline Fit Together

The repository layout makes the architecture visible before you read a line of code. Four top-level directories carry the framework: h2d for 2D, h3d for 3D, hxd for the lower-level platform and system layer, and hxsl for the shader language and pipeline. There is a single all.hxml at the root, plus a haxelib.json that declares the package for Haxelib distribution.

That split matters when you are deciding what to learn. h2d and h3d are the two scene graph layers, and a project normally picks one as its primary rendering model. hxd sits underneath both and holds the parts that touch the host system: windowing, input, file access and the backends that map onto OpenGL, DirectX, WebGL or Stage3D. hxsl is the piece that distinguishes Heaps from engines that expect you to write raw GLSL for every target. Shaders are written in Haxe-flavoured shader code and compiled per target, which is how one material definition can end up as GLSL for the web and HLSL for DirectX.

The samples directory shows the intended entry points. samples/Base2D.hx and samples/Base3D.hx are the minimal starting points for the two rendering modes. Beyond those, the file names map to capabilities: GpuParticles.hx, Filters.hx, Blur.hx, CubeTexture.hx, Bindless.hx, DrawingTiles.hx, HtmlText.hx, CollideCheck.hx and Interactive.hx. Reading the sample list is a faster way to judge feature coverage than reading prose documentation, because each file is a working program rather than a claim.

Installing Heaps and Compiling Your First Sample

The README does not inline installation steps. It points to the installation page at heaps.io/documentation/installation.html, and the package is declared in haxelib.json, so the distribution channel is Haxelib. You need a working Haxe compiler and Haxelib before anything else.

The samples are the fastest way to confirm a working setup. The README states that you go to the samples directory and run haxe gen.hxml, which generates a build directory containing project files for all samples. It also notes that Visual Studio Code project files are generated as part of that step.

cd samples
haxe gen.hxml

After generation, the build directory holds per-sample HXML files. For the web target, the README says to run the sample's _js.hxml file and then open index.html.

haxe [sample]_js.hxml

For a native desktop run through HashLink, the README gives a different pair of commands: compile with the _hl.hxml file, then execute the resulting .hl file with the hl runtime. It also notes that this path uses SDL by default, and that replacing -lib hlsdl with -lib hldx in the hxml switches the backend to DirectX.

haxe [sample]_hl.hxml
hl [sample].hl

There is also a Flash path: run the _swf.hxml file and open the resulting .swf. What you should see in each case is a window or browser canvas running the sample, which confirms that the compiler, the library and the platform backend are all wired correctly before you write any of your own code.

Where Heaps Stops Being the Right Tool

The most concrete limitation is documented rather than implied. Console support requires being a registered developer, and the README routes console enquiries to an email address rather than to a public build. If your target list includes a console and you do not already have developer status with that platform holder, that part of the framework is not available to you today, regardless of what the feature list says.

The second limitation is the shape of the project itself. Heaps is a graphics engine. The README's own phrasing is that it is designed for high performance games, and the top-level directories are rendering and system layers. There is no scene editor, no prefab system and no gameplay framework in the repository listing. Teams coming from an editor-centric workflow will find that a significant amount of tooling has to be built or sourced elsewhere.

Third, the web target carries a hard requirement that the README states directly: HTML5 requires WebGL. There is no canvas fallback described. On hardware or browser configurations without WebGL, the web build is not a degraded experience, it is a non-starter.

Finally, the language is the adoption cost. Haxe is a smaller ecosystem than C#, C++ or TypeScript, which affects hiring, third-party library availability and how quickly a new team member becomes productive. That is a real trade-off against the multi-target compilation that makes Heaps attractive in the first place.

Heaps Versus a Full Engine Like Godot or Unity

The honest comparison is not feature-by-feature, because the two categories solve different problems. A full engine such as Godot or Unity bundles an editor, a scene format, an asset pipeline, physics, animation and a scripting layer on top of its renderer. Heaps bundles the renderer and the platform abstraction, and expects you to bring or build the rest.

The difference in approach shows up in how you start a project. In an editor-driven engine you create a scene in a GUI, attach components and press play. In Heaps you write a Haxe class, compile it with an HXML file, and the README's workflow is a command line loop: haxe gen.hxml once to generate project files, then haxe [sample]_js.hxml or haxe [sample]_hl.hxml per build. There is no project file to open in a scene editor.

That is a genuine trade-off in both directions. You give up visual iteration and the library of prebuilt systems that come with a full engine. You gain a codebase where the rendering path is Haxe all the way down, where the shader pipeline compiles to each target rather than being written per platform, and where the same source produces a WebGL build, a HashLink desktop binary and a mobile build. For a team that would rather own the engine layer than work around an editor's opinions, that is the point. For a team that wants to ship a game rather than build a framework on top of a framework, it is friction.

Maintenance, Licensing and What an Upgrade Costs

The repository is not archived, and the last push was on 2026-09-23. Releases are infrequent and clearly versioned: 2.0 on 2024-01-01, 2.1 on 2025-03-23 and 2.1.1 on 2025-06-07. The gap between 2.0 and 2.1 is over a year, and 2.1 to 2.1.1 is under three months. A project that plans around a monthly release cadence will be disappointed; one that pins to a tagged version and tracks the CHANGELOG.md at the repository root will be fine.

Upgrade cost is dominated by the shader pipeline. Because hxsl compiles shader code per target, a change in the shader layer can surface differently on WebGL, OpenGL and DirectX, so a version bump is not a single-platform test. The samples directory is the practical regression suite here: compiling the sample set against your target backends after an upgrade exercises far more of the framework than a single application build would.

The licence is MIT, declared in the LICENSE file and in haxelib.json. That is permissive and permits commercial use and modification. It is worth reading the LICENSE file itself rather than relying on the identifier, and if you ship to a console, the platform holder's own agreement sits on top of the MIT grant and is a separate question entirely. Nothing here is legal advice.

Editorial conclusion

Adopt Heaps if you already write Haxe, need one codebase for WebGL, HashLink desktop and mobile, and want a renderer that hands you the GPU rather than hiding it. Do not adopt it if you need an editor-driven workflow, a large library of ready-made gameplay modules, or a community whose primary language is not Haxe. Before committing, compile samples/Base2D.hx and samples/Base3D.hx with both a _js.hxml and a _hl.hxml target, and read the installation page and API documentation on heaps.io to confirm your target platform is covered.

Frequently asked questions

Official sources

1. HeapsIO/heaps on GitHub
2. License: MIT
3. Project website
4. README
5. Releases