Haxe Externs For Phaser

When I started preparations for my online multiplayer game attempt, I realized I will need to create Phaser externs for Haxe.

Haxe externs are a way for Haxe to know about types of methods and properties of external objects like Phaser.

Surprisingly generating them took me a week and not the expected hour or two. And they still aren’t perfect (and probably never will be).

Turns out that taking Phaser’s source and parsing the JSDoc using tools like js2hx isn’t good enough. JavaScript’s dynamic nature allows for runtime injection of functionality, which makes it difficult to know which properties are available on which object.

Which is why Phaser offers TypeScript definition files, which were written manually. TypeScript definitions are the same thing as haxe externs, but for TypeScript. “Great,” I thought. Well, it is great that they exist. That’s for sure. But converting them to Haxe proved challenging for many reasons.

I wish I kept notes as I iteratively wrote the conversion code, but I went into it with “this will only take a short while” mindset. How wrong I was.

Among the problems I do remember, are JavaScript/TypeScript specific things, like module and class not entirely mapping to haxe’s package and class. Or static properties/methods with the same name as non-static ones.
More Phaser related issues were repeating of properties in subclasses that are also in the superclass (with different comment on them too – so they are worth keeping).

How I ended up implementing it, is by taking advantage of TypeScript’s Compiler API to parse the definition files. With that I iteratively wrote code to process the AST tree and export Haxe externs files.

The end result is a pretty ugly code that can be found here.

But it works :)