LÖVE for Haxe

This is an updated fork of the original love-haxe-wrappergen by bartbes. It uses the awesome love-api project, which provides a Lua tables representation of the LÖVE documentation, to generate Haxe wrappers.

This project is currently only tested to work on LÖVE 11.5.

Table of contents

1. Installation
2. Examples
3. Changes from upstream
4. Source maps with Local Lua Debugger

Installation

Installing prebuilt externs

haxelib install love

Using haxelib git

This requires that you have the Lua standalone interpreter installed.

Run, in a terminal:

haxelib git love https://github.com/pkhead/love-haxe-wrappergen

# PowerShell: cd $env:HAXEPATH/lib/love/git
# Windows Command Prompt: cd %HAXEPATH%/lib/love/git
# Bash:
cd $HAXEPATH/lib/love/git

git submodule update --init love-api
lua haxify.lua

Using haxelib dev

This requires that you have the Lua standalone interpreter installed.

Run, in a terminal:

git clone https://github.com/pkhead/love-haxe-wrappergen
cd love-haxe-wrappergen
git submodule update --init love-api
lua haxify.lua
haxelib dev love .

Examples:

build.hxml

-lib love
-cp src
-D lua-vanilla
--lua out/main.lua

--main MyGame

Code samples

import love.graphics.GraphicsModule as LoveGraphics;

class TextDrawing extends love.Application {
    override function draw() {
        LoveGraphics.print("Hello, world!", 400, 300);
    }

    public static function main() {
        new TextDrawing();
    }
}

import love.graphics.GraphicsModule as LoveGraphics;

class ImageDrawing extends love.Application {
    var whale:love.graphics.Texture;

    override function load(args:Array<String>, unfilteredArgs:Array<String>) {
        whale = LoveGraphics.newImage("whale.png");
    }

    override function draw() {
        LoveGraphics.draw(whale, 300, 200);
    }

    public static function main() {
        new ImageDrawing();
    }
}

import love.audio.AudioModule as LoveAudio;

class SoundPlaying extends love.Application {
    override function load(args:Array<String>, unfilteredArgs:Array<String>) {
        var sound = LoveAudio.newSource("music.ogg", Stream);
        LoveAudio.play(sound); // or sound.play();
    }

    public static function main() {
        new SoundPlaying();
    }
}

Changes from upstream:

• love.Application class, which allows classes that extend it to set LÖVE callbacks by overriding functions from the base class.
• love.filesystem.FilesystemRead class for type-safe file reading.
• Emitted documentation for functions and classes.

Source Maps with Local Lua Debugger

Note: This only applies to users with Haxe 5+ or a nightly version, since as of 01/26/2025 the current stable version of Haxe (4.3.6) cannot generate Lua source maps.

This section is for if want to use the Visual Studio Code extension Local Lua Debugger by Tom Blind to debug your Love2D project. This debugger has the option to use source maps following the JavaScript format. Setup is required in order for it to work properly.

1. Fix Local Lua Debugger

Because of this issue (#84), the extension does not work properly with Haxe-generated source maps. If the bug has been fixed by the time you are reading this, you do not need to follow this step. Otherwise, there is a fork which fixes this issue, so I have detailed to steps required to get it working.

1. Uninstall the Marketplace extension. (obviously.)
2. Ensure you have git and npm installed.

3. Run in a terminal:

   git clone https://github.com/Zorbn/local-lua-debugger-vscode
   cd local-lua-debugger-vscode
   
   npm install
   npm run build
   npx vsce package
   
   code --install-extension <path to newly created .vsix file>
   # or, you can install the .vsix file through the vscode command palette
   # or from the right-click menu of the file inside vscode.

2. Create launch configuration

You need to add the following entry to the .vscode/launch.json file (assumes the out folder is where the Love2D project is generated):

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Love2D Debug",
            "type": "lua-local",
            "request": "launch",
            "program": {
                "command": "lovec"
            },
            "cwd": "${workspaceFolder}/out",
            "args": ["."],
            "scriptFiles": ["*.lua"],
        }
    ]
}

3. Launch lldebugger hook on application startup

At the very top of your application's main function (chosen because it is the earliest point at which code can execute), add the following code:

untyped __lua__("
if os.getenv('LOCAL_LUA_DEBUGGER_VSCODE') == '1' then
    require('lldebugger').start()

    function assert(a, b)
        return a or error(b or 'assertion failed!', 2)
    end

    function love.errorhandler(msg)
        error(msg, 3)
    end
end
");

Once all required steps have been followed, breakpoints set in your Haxe source code (hopefully) should work, and the Visual Studio Code call stack should (hopefully) display the correct Haxe functions rather than the Lua code.