Skip to content

Installation

Setting up Heaps for game development requires three components: Haxe (the language), Heaps (the engine), and a runtime (HashLink or JavaScript).

Prerequisites

1. Install Haxe

Haxe is the programming language that Heaps is built with.

Download and run the installer from haxe.org

# Using Homebrew
brew install haxe

# Ubuntu/Debian
sudo apt install haxe

# Or download from haxe.org

Verify installation: 

haxe --version  # Should show 4.x.x

2. Install Visual Studio Code

While any editor works, VS Code offers the best Heaps development experience.

  1. Download from code.visualstudio.com
  2. Install the Haxe Extension Pack from the marketplace

HashLink is a virtual machine designed for Haxe, providing native performance.

Download the installer from hashlink.haxe.org

brew install hashlink

Build from source or use the provided binaries at hashlink.haxe.org

Apple Silicon Users

HashLink doesn't fully support ARM64 yet. Use the web target for development on M1/M2/M3 Macs.

Install Heaps

Install Heaps and its dependencies using haxelib (Haxe's package manager):

haxelib install heaps
haxelib install hlsdl     # For native builds
haxelib install hxnodejs  # For Node.js builds (optional)

Create Your First Project

  1. Create a new directory: 

    mkdir my-heaps-game
cd my-heaps-game

  2. Create build.hxml for HashLink: 

    -cp src
-lib heaps
-lib hlsdl
-hl bin/game.hl
-main Main

  3. Create build-web.hxml for web builds: 

    -cp src
-lib heaps
-js bin/game.js
-main Main
-dce full

  4. Create src/Main.hx: 

    class Main extends hxd.App {
    override function init() {
        // Your game starts here
    }

    static function main() {
        new Main();
    }
}

  5. Build and run: 

    # For HashLink
haxe build.hxml
hl bin/game.hl

# For Web
haxe build-web.hxml
# Open bin/index.html in browser

IDE Setup

VS Code Configuration

  1. Create .vscode/tasks.json: 

    {
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build HashLink",
            "type": "shell",
            "command": "haxe build.hxml",
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Run HashLink",
            "type": "shell",
            "command": "hl bin/game.hl",
            "dependsOn": "Build HashLink"
        }
    ]
}

  2. Create .vscode/launch.json for debugging: 

    {
    "version": "0.2.0",
    "configurations": [
        {
            "name": "HashLink",
            "type": "hl",
            "request": "launch",
            "program": "${workspaceFolder}/bin/game.hl",
            "preLaunchTask": "Build HashLink"
        }
    ]
}

Verify Installation

Create this test file as src/Main.hx:

class Main extends hxd.App {
    override function init() {
        var text = new h2d.Text(hxd.res.DefaultFont.get(), s2d);
        text.text = "Heaps is working!";
        text.scale(3);
        text.center();
    }

    override function update(dt:Float) {
        // dt is in seconds
    }

    static function main() {
        new Main();
    }
}

If you see "Heaps is working!" on screen, you're ready to build games!

Troubleshooting

Common Issues

"Library heaps not found" : Run haxelib install heaps again

"Type not found: hxd.App" : Make sure -lib heaps is in your build.hxml

HashLink crashes on launch : Ensure hlsdl is installed: haxelib install hlsdl

Black screen on web build : Create an HTML file that includes your JS: 

<!DOCTYPE html>
<html>
<head>
    <title>Heaps Game</title>
    <style>
        body { margin: 0; padding: 0; }
        canvas { width: 100%; height: 100vh; }
    </style>
</head>
<body>
    <script src="game.js"></script>
</body>
</html>

Next Steps

You're ready to create your first game! Continue to Hello World →