hxdefold/hxdefold

Haxe/Lua externs for Defold game engine

Haxe support library for the Defold game engine

This library allows writing beautiful Haxe code for the Defold game engine \o/

Features

• Fully typed Defold API with proper compile-time errors and IDE services.
• Type-safe game object messages and properties with zero overhead.
• Strengths of Haxe without compromises: powerful type system, meta-programming, static optimizations, dead code elimination and cross-target code sharing.
• Defold hot reloading is now supported!

Quick start

(assuming you already installed Haxe😊)

• Install this library:
  • From this repo: haxelib git hxdefold https://github.com/hxdefold/hxdefold
  • Or from lib.haxe.org: haxelib install hxdefold
• Run haxelib run hxdefold init inside your Defold project. It will create a sample Hello.hx script component class and a build.hxml for building it.
• Read the comments in these files to quickly get some idea.
• Build with haxe build.hxml to get the lua output.
• Add Hello.script to your game object in the editor and observe the greeting in the debug console.
• Proceed with writing well-structured, expressive and type safe code for your Defold game.

How does it look like

import defold.support.Script;

// component class that defines the callback methods
// after compiling Haxe, the `Hello.script` will appear in the Defold project that can be attached to game objects
class Hello extends Script<HelloData> {

    // fields with @property annotation will show up in the editor
    @property var power:Int = 9000;

    // the `init` callback method
    override function init() {
        trace('Haxe is over ${power}!'); // will be printed to the debug console
    }

    // the `update` callback method
    override function update(dt:Float) {}
}

Documentation

Here is the API reference.

Migration to v2 is documented in the v2 pull request.

Details about usage can be found on the wiki.

And here are some example Defold projects, ported from Lua:

• https://github.com/hxdefold/hxdefold-bunnymark

How does it work?

Since version 3.4, Haxe supports compiling to Lua, making it possible to use Haxe with Lua-based engines, such as Defold.

However, this requires a bit of autogenerated glue code, because Defold expects scripts to be in separate files, while Haxe compiles everything in a single lua module. So what we do, is generate a simple glue .script file for each class extending the magic defold.support.Script base class (there are also GuiScript and RenderScript).

For example, for the Hello script from this README, this glue code is generated in the Hello.script file:

-- Generated by Haxe, DO NOT EDIT (original source: src/Hello.hx:11: lines 11-16)

go.property("power", 9000)

require "main"

function init(self)
    _hxdefold_.Hello_init(self)
end

You can then add this script to the game objects in the Defold Editor.

Versions

• Major number will be incremented for significant reworks that are certainly forward-breaking.
• Minor number will be incremented when updating to a new Defold API version. These updates may come with forward-breaking changes.
• Patch version will be incremented for bug fixes and potentially backwards-breaking changes.

Note that this is not standard semver, since we might potentially ship backwards-breaking changes that increment only the patch number.

hxdefold	Haxe	Defold API
2.0.*	4.3	1.6.4

Logo

Made by the awesome @markknol. Check out his website for more art&code!

hxdefold's Issues

write some documentation

• write a step-by-step tutorial, starting with installing haxe and vscode and implementing some scripts
• write overview of type-safety features (typed messages, typed properties)
• document MessageBuilder/PropertyBuilder sugar magic

Optional float arguments should have a default value of 0

Haxe 4.0.0-rc.2 breaks defold bundling.

I was using haxe 3.4.7 and that works fine but updated to haxe 4.0.0-rc.2 to get better support in vscode. It works when I build in the editor, but when I try to make a bundle for MacOS or Linux I get
/main.lua the module '/bit32.lua' can't be found.
I haven't tested other platforms yet.

I checked why it happens and found this part of the generated code has changed:
Version 3.4.7:

pcall(require, 'bit')
if bit then
  _hx_bit = bit
elseif bit32 then
  local _hx_bit_raw = bit32
  _hx_bit = setmetatable({}, { __index = _hx_bit_raw });
  _hx_bit.bnot = function(...) return _hx_bit_clamp(_hx_bit_raw.bnot(...)) end;
  _hx_bit.bxor = function(...) return _hx_bit_clamp(_hx_bit_raw.bxor(...)) end;
else
  _G.error("Bitop library is missing.  Please install luabitop");
end

Version 4.0.0-rc2:

pcall(require, 'bit')
if bit then
  _hx_bit = bit
else
  local _hx_bit_raw = _G.require('bit32')
  _hx_bit = setmetatable({}, { __index = _hx_bit_raw });
  _hx_bit.bnot = function(...) return _hx_bit_clamp(_hx_bit_raw.bnot(...)) end;
  _hx_bit.bxor = function(...) return _hx_bit_clamp(_hx_bit_raw.bxor(...)) end;
end

I also tried the lastest nightly build of haxe and it generates the same code as 4.0.0-rc2.
Is there a solution or workaround for this?

generate code from assets

we can generate some nice code for easy/typesafe access to known game objects/collections based on their structure.

that would require a macro that parses .go files and such (they are in the "text protobuf" format) and generates types with properties/methods based on them.

the question is what exactly do we want to access through that? my guess would be:

• urls for known children/components
• abstract-wrapping with nice methods based on component types (that requires #8)
• what else?

automate hot-reload

Apparently it's possible to talk to the running Defold IDE from outside and invoke hot-reloading! \o/

It is implemented in the Atom Defold plugin: https://github.com/dapetcu21/atom-defold-ide/blob/dd62d0d15149a456a0bf05b71c6540068db5c71a/lib/hot-reload.js#L99

We can try doing this after haxe recompilation and/or provide a VS Code plugin that does that.

Release on haxelib through Travis?

Is there any interest for the library to be released on lib.haxe.org?

If so I could make a PR to update .travis.yml to automatically push a new version to haxelib whenever there is a tag. For example tag v1.2.3 would publish version 1.2.3.

adapt to 1.2.150

https://www.defold.com/release-notes/1.2.150/

Two questions about type abstracts

I am new to haxe and in the process of writing lua extern definitions. Looking at abstract types definitions in hxdefold i don't understand two things:

1. Why extern abstract? I understand enum extern abstract, but what extern changes in this case, shouldn't it be simply an abstract?

2. In lua untyped interpolation calls variables are wrapped in additional round brackets. Why are they needed? Can't create the case when they would be necessary by looking at lua compiled from haxe.

Compile Haxe to C++/Java/JS insted and then to native extension?

Haxe can be transpiled to C++, Java and Javascript.

Is it possible to do that and then convert it to a native extension instead?
The game performance and battery usage would be astonishing.

lua libs

what to do if i want to use other lua libs in haxe project?

DELETE THIS

implement higher-level API on abstract

it should be possible with Haxe to implement a very nice OO-ish API on top of the basic defold api with zero run-time cost using abstracts. look into that.

simplify build process

ideas:

• have a haxelib run hxdefold init command that will create a very basic hxdefold project with sane defaults
• hide ScriptMacro calls in extraParams.hxml, so it just works (tm), with customization through defines
• add @:keepSub to Script classes, because if we extend one we want the script to appear in the defold project. if we do that, we can have full DCE mode so our main.lua is clean.

Logo

I don't have any Photoshop skills, but if this project somehow becomes popular, I think we need a logo for it :-) I have this idea:

take defold logo and replace "plus" with haxe logo shape.

Haxe > 4.0.5 does not generate main.lua (it deletes it!)

Haxe: 4.1.0
hxdefold: master
OS: Ubuntu Linux 20.04

Created a new project in defold, then ran:
haxelib run hxdefold init
haxe build.hxml

I get a generated script in scripts/Hello.script but I do not have a main.lua in the root of the project and building in defold results in the following error:

/scripts/Hello.script
	The file '/main.lua' could not be found.

haxe build.hxml --verbose output:
https://gist.github.com/thejustinwalsh/6e78a41ea731d17378812b69db96e248

defold.Buffer or defold.types.Buffer

defold.Buffer.create returns a defold.Buffer object. Other methods also require a defold.Buffer object as argument.

But there's a defold.types.Buffer class.When I write import defold.types.* and import defold.Buffer, Buffer does not behavior as excepted.

How to generic-extend the Script class?

Hello, I am trying to create a generic subclass of the Script class, but I am getting the following error message:

But the type parameter seems correct to me, since it will just be specified on the classes that then extend this, no?

Hot Reload does not work

This is probably due to Lua module reload: https://www.defold.com/manuals/modules/#_hot_reloading_modules

The easiest way is to use a global variable, instead of Lua modules for generated code.

is running "haxe build.hxml" in the terminal necessary for every change?

I must run "haxe build.hxml" each time to see my changes. is this a common use case or have I missed some things?
If this is always required, is there a way to do it automatically?

Defold Foundation should be mentioned as in control of Defold now.

King has given Defold over to an independent foundation, the readme should reflect that it's no longer under the ownership of King.

error 'The file '/luv.lua' could not be found'

Hi, folks. I took last hxDefold and Haxe 4.3.2. I did every steps in Quick start, but when I build Default project (F5), and receive error: main.lua: The file '/luv.lua' could not be found'. How to correct it?

vectors can be of any dimension, it seems

The vmath.vector function can receive a table of any size and make a vector of it. This is used for e.g. animation curves, so we need to express that somehow.

From the go.animate doc:

    local values = { 0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1 }
     local vec = vmath.vector(values)

typed properties

add this: HaxeFoundation/haxe#5282 (comment)

How to require and work with extensions from the asset portal?

hi, it's not mentioned anywhere and me as a total haxe noob have no idea how to do it.
maybe @:luaRequire('...') or something?

thanks

Import Dependencies specified in game.project file using Haxe

I'm using Rive dependency inside my Defold project but I don't know how to import these dependencies inside my Haxe file

Look into supporting haxe 4.2 module-statics for script callbacks somehow.

Question/Feature Request

Is there a way to add ( ) and ; automaticlly at the end of a function call in VS code?
Thanks.