Blog › ICP guides

Haxe developer on retainer: multi-target compilation, abstract types, macros, and cross-platform systems on monthly retainer

October 1, 2026 · ~19 min read

A Haxe 4 game built with OpenFL and compiled to both HTML5 and iOS/C++ had a save system that worked perfectly in the browser and crashed immediately on iOS. The crash was a null pointer dereference. The line was identical on both targets: var value = saveData.get(key); where saveData was a Map<String, Dynamic> deserialized from JSON. The Haxe developer on retainer diagnosed it in the first session. In the JavaScript target, Map.get for a missing key returns null — the same behavior as JavaScript’s underlying object property access for undefined keys. In the C++/HXCPP target, the same Map.get call on a missing key throws cpp.NullAccess because HXCPP enforces stricter null semantics than JavaScript. The save data keys had been added in a newer version of the save format; older saves loaded on iOS were missing those keys, and the null access crashed the game on the first property read of the returned null value.

The fix was a defensive existence check before every map.get call: var value = saveData.exists(key) ? saveData.get(key) : defaultValue; — or more concisely using Haxe 4’s null coalescing operator once the null safety flag was enabled: var value = saveData.get(key) ?? defaultValue;. The developer also found a second issue during the audit: an abstract GameState(Int) type used for game state enumeration had two separate @:from implicit conversion operators both accepting Int as the source type — one in the original GameState abstract and one in a newer LegacyGameState abstract that had been added during a migration. When both abstracts were imported in the same module, the Haxe compiler’s implicit conversion selection was import-order-dependent: the abstract whose module was imported last had its @:from Int operator take precedence. On builds where the import order was stable, the game worked correctly. On builds where the file was regenerated with a different import ordering, the wrong abstract was selected and save states were decoded with the wrong enumeration values. Both issues were invisible to the JavaScript target CI build and appeared only on iOS.

Haxe type system: structural typing, null safety, and multi-target compilation

Haxe is a statically typed, multi-paradigm language that compiles to eleven official targets: JavaScript (browser and Node.js), C++/HXCPP, C# (.NET), Java/JVM, Python, PHP, Lua, HashLink (native bytecode), ActionScript 3, Neko (VM), and Eval (interpreter). The Haxe compiler performs full type inference, so var x = 42 infers x : Int and var s = "hello" infers s : String. Structural typing means that a class satisfying the field requirements of a typedef or an anonymous structure type is assignable to it without an explicit declaration: var pos : {x:Float, y:Float} = new Point(0, 0) is valid if Point has x and y fields of type Float. This structural type compatibility is the mechanism that enables Haxe’s cross-target abstractions — extern classes for each target declare the same field signatures, and the structural type system accepts them all.

Null safety in Haxe 4 is opt-in per module or globally: -D nullSafety (or -D nullSafety:Strict for exhaustive mode) enables compile-time tracking of nullable types. A nullable field must be declared as Null<T>: var name:Null<String> = null. Accessing a Null<T> value without a null check is a compile warning (in default mode) or error (in Strict mode). The null-conditional access operator ?. short-circuits on null: object?.field returns null if object is null, otherwise returns object.field. The null coalescing operator ?? provides a default: nullable ?? defaultValue returns nullable if it is non-null, otherwise returns defaultValue. These operators, combined with Null<T> type annotations, make cross-target null handling explicit and compiler-verified: code that assumes non-null values available in the JavaScript target but fails in the C++ target is caught at compile time rather than at iOS runtime. A retainer engagement migrating an existing Haxe codebase to null safety starts by enabling -D nullSafety and addressing each compiler warning, converting implicit nullable returns to Null<T> signatures and adding ?. / ?? access patterns at each call site.

Multi-target compilation differences are the most operationally significant aspect of Haxe development at the retainer level. The JavaScript target uses JavaScript semantics for null and undefined interchangeably in some contexts (a missing Map key returns null, which is falsy), while the C++ target uses HXCPP’s strict native null handling (a missing Map key returns null as a C++ null pointer, and dereferencing it throws cpp.NullAccess). Integer arithmetic overflows differ: on JavaScript, Haxe Int operations overflow to floating-point beyond 32-bit range; on C++, they wrap at 32-bit boundaries. Std.string(value) on a Dynamic produces "null" on JavaScript but "null" (or nothing) on C++ depending on the null safety context. Type.typeof(value) reflection returns different ValueType enumerations on different targets for the same runtime values. Conditional compilation using #if js ... #elseif cpp ... #else ... #end isolates target-specific code paths, but the correctness of the common code path (the non-conditional code executed on all targets) depends on using only operations with identical semantics across all compilation targets.

Haxe’s generics use type parameter syntax: class Container<T> { var value:T; }. Type parameter constraints restrict what types can be used: class SortableList<T:Comparable<T>> requires T to implement the Comparable interface. Haxe’s structural typing means that type parameter constraints are checked structurally, not nominally: if Comparable<T> requires a compareTo(other:T):Int method, any class with that method signature satisfies the constraint. The Dynamic type opts out of the type system entirely: var x:Dynamic = anything accepts any value and any field access compiles without type checking, with errors deferred to runtime. Using Dynamic is a common cause of target-divergence bugs because the JavaScript target’s permissive null/undefined handling masks type errors that produce exceptions on the C++ target. A retainer engagement auditing Dynamic usage identifies each Dynamic field access and replaces it with a typed access pattern (strongly typed cast, null-checked accessor, or typed typedef matching the expected structure).

Abstract types, macro system, and OpenFL game development

Abstract types are one of Haxe’s most distinctive features. An abstract type wraps an underlying type and provides a different compile-time API without runtime overhead — all abstract operations are inlined and compile away to direct operations on the underlying type. The syntax is: abstract Meters(Float) { public inline function new(v:Float) this = v; }. The this keyword inside an abstract refers to the underlying value. Abstract types support implicit conversion operators: @:from static inline function fromFloat(v:Float):Meters return new Meters(v) allows a Float to be used where a Meters is expected (implicit widening), and @:to inline function toFloat():Float return this allows a Meters where a Float is expected (implicit narrowing). Operator overloading uses @:op(A + B): @:op(A + B) static inline function add(a:Meters, b:Meters):Meters return new Meters(a.toFloat() + b.toFloat()). The @:enum abstract pattern defines exhaustive value sets: @:enum abstract Direction(Int) { var North = 0; var South = 1; var East = 2; var West = 3; } — with null safety enabled, a Direction value is statically guaranteed to be one of the four declared values.

The implicit conversion ambiguity issue described in the opening incident — two abstract types both declaring @:from Int operators — is a category of abstract design error that a retainer engagement audits systematically. When two abstract types are in scope in the same module and both have @:from T for the same source type T, the Haxe compiler must select one of them for implicit conversion. The selection rule is import-order-dependent (the most recently imported module’s abstract takes precedence), which means that the behavior changes whenever the import order changes. The fix is to give each abstract a distinct underlying type (so their @:from operators have different source types), or to remove the @:from operator from one abstract and require explicit construction at call sites, or to merge the two abstracts into one with an explicit conversion method that handles both value spaces. A retainer engagement covering abstract type architecture maintains a rule: no two abstract types in the same module should have @:from operators accepting the same source type.

Haxe’s macro system operates at compile time before code generation. Expression macros are called at use sites and return Expr values that replace the macro call in the AST: macro function logTyped(v:Dynamic):Void { return macro trace($v{v} + " : " + $v{haxe.macro.Context.typeof(v)}); }. The return type ExprOf<T> constrains the macro return to a specific type, enabling the caller’s type context to verify the generated expression. Build macros add fields to types at compile time: decorated with @:build(MyMacro.build()), the type’s fields are intercepted by the macro’s Context.getBuildFields() call, modified or augmented, and returned. A build macro that injects a serialize() method must check whether a serialize field already exists before injection — failing to do so produces a duplicate field error on targets that check for it (C++) and silently shadows on targets that don’t (JavaScript). The canonical guard pattern is: if (!fields.exists(f -> f.name == "serialize")) fields.push(serializeField).

OpenFL is a cross-platform implementation of the Flash API — openfl.display.Sprite, openfl.display.Bitmap, openfl.display.TextField, openfl.display.Stage, openfl.events.Event, openfl.events.MouseEvent, openfl.events.TouchEvent — that compiles to HTML5/Canvas, native C++, and HashLink. The display list is a tree of DisplayObject and DisplayObjectContainer instances; addChild/removeChild manage the tree, stage.addEventListener(Event.ENTER_FRAME, onEnterFrame) drives the game loop, and stage.stage3D.requestContext3D provides GPU access for 3D rendering. WebAssembly developer retainers and TypeScript developer retainers address adjacent parts of the cross-platform web stack that sometimes share a project scope with Haxe/OpenFL development. Heaps.io is a lower-level 2D/3D framework with a h2d.Scene / h2d.Object / h2d.Sprite hierarchy and h3d.scene.Scene for 3D, used when the Flash API abstraction is less relevant than direct GPU control. A retainer engagement covering OpenFL/Heaps architecture designs the display object tree to minimize per-frame allocation (creating DisplayObject instances at level load rather than per-frame, using object pools for frequently-created entities), manages addEventListener/removeEventListener symmetry to prevent memory leaks from orphaned listeners, and designs openfl.Assets.getBitmapData/getBitmapData.dispose() lifecycle for GPU texture memory management.

How HourTab tracks Haxe developer retainer hours

Haxe retainers produce an invisibility problem with a specific shape: the work that is most valuable — diagnosing target-divergence root causes, resolving abstract implicit conversion ambiguities, auditing macro field injection for cross-target correctness — produces the fewest lines of diff. The iOS save crash fix described at the top of this post was twelve lines: eight map.exists(key) guard additions and four null-coalescing ?? operators replacing direct map.get(key) calls. The abstract type @:from Int ambiguity fix was two lines: one @:from operator removed from LegacyGameState and a comment explaining the invariant. A client reviewing the diff without context sees fourteen lines changed and fourteen hours billed. The gap between the artifact (fourteen lines) and what the lines represent (diagnosis of a cross-target null semantics difference requiring understanding of HXCPP's null enforcement model, plus identification of an abstract implicit conversion ambiguity that required understanding of Haxe compiler import-order resolution) is the communication problem that every Haxe retainer faces.

HourTab gives Haxe developers a public retainer-hours URL they paste into the first message of every client engagement. The client opens the URL and sees the burn-down: hours purchased, hours used, hours remaining, and a work log of every session. For Haxe retainers specifically, each work log entry should name the Haxe mechanism involved (multi-target divergence: null Map access semantics JS vs C++; abstract @:from Int ambiguity with import-order resolution; build macro Context.getBuildFields() duplicate field injection; conditional #if cpp/#if js compilation path isolation; null safety Null<T>/?./?? migration; haxelib dependency version conflict), the specific class/abstract/macro and the target pair where divergence occurred, the diagnostic approach (HXCPP compile log showing cpp.NullAccess at map.get(key); Haxe compiler import-order warning on ambiguous @:from selection; --macro trace showing duplicate field error on C++ build), the change made and why it was necessary (map.exists(key) guard required because JavaScript Map.get returns null for missing keys without exception while HXCPP Map.get throws cpp.NullAccess — identical Haxe source code produces different runtime behavior on the two targets, so the null contract must be explicit; @:from Int removed from LegacyGameState because two @:from operators with the same source type in the same module create import-order-dependent implicit conversion selection — the compiler does not report an error, it silently picks one), and the before-and-after observable metric (iOS save load crash rate: daily → 0; abstract conversion correctness: non-deterministic → 100%; build macro field injection errors on C++ builds: 3 per release deploy → 0). Entries at that level of specificity turn a fourteen-line diff and fourteen hours billed into a documented cross-platform systems improvement that the client can reference when evaluating the retainer.

Haxe retainers share the multi-target diagnostic challenge with no other language ecosystem. A TypeScript developer on retainer works with one target runtime and one type system. A WebAssembly developer on retainer works with one compilation target with consistent semantics. The Haxe developer’s retainer work spans up to eleven different compilation targets, each with distinct semantics for null access, integer overflow, reflection availability, and standard library behavior. The diagnostic work required to identify that a crash is a target-divergence issue rather than a logic error — that the code is correct but the null contract is target-dependent — is invisible in the diff. HourTab’s work log makes that reasoning visible: the entry names the target pair, the semantic difference, the mechanism that caused the divergence, and the pattern applied to resolve it, so the client understands why the fix required the hours it required, even without understanding Haxe’s multi-target compilation model in detail.

FAQ: Haxe developer retainers