Skip to content
Back to skills

Target Openfl Native

ASecurity

OpenFL/hxcpp native target gotchas

  • 6 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
developmentrustgoc++awstestingdebuggingapibackendperformance

Works with

  • cli
  • api

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add AxGord/claude-workflow --skill target-openfl-native --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Target Openfl Native?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Target Openfl Native
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/axgord-target-openfl-native/badge)](https://www.skillsdirectory.com/skills/axgord-target-openfl-native)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: target-openfl-native
description: OpenFL/hxcpp native target gotchas
---

# OpenFL/Lime Native (hxcpp) — Gotchas & Pitfalls

See `references/` for build config and version notes.

## Versions

Reference baseline (verify against current toolchain): OpenFL 9.5.0, Lime 8.3.0. Android: NDK r28c, SDK 35 (JDK 17+), 16KB alignment.
Default Android archs: ARM64 + x86_64 (ARMv7 removed). iOS: ARM64 only.

## hxcpp GC ↔ C++ Interop

### GC roots — heap-stored Haxe objects are invisible to GC

GC scans the stack, not the C++ heap. Storing a Haxe object in a C++ member → premature collection.

```cpp
// WRONG — invisible to GC
class NativeHelper { value myHaxeObj; };

// RIGHT
class NativeHelper {
    AutoGCRoot *root;
    NativeHelper(value obj) { root = new AutoGCRoot(obj); }
    value get() { return root->get(); }
};
```

### @:unreflective suppresses GC scanning

`@:unreflective` on a field prevents GC from tracing it. Only use on fields with native C++ types, never on fields holding Haxe objects.

### Moving GC (HXCPP_GC_MOVING)

Invalidates raw C++ pointers to Haxe objects after collection. Also shows erratic memory growth during long load/unload cycles — may exceed non-moving GC over time.

## Static Init Boot Order (`__boot_all`)

Each class's static-variable initializers AND its RTTI payload (`__mClass->__rtti__`, from `@:rtti`) are set inside that class's generated `__boot()`. `__boot_all()` calls these in a generator-chosen order — not declaration order, not strictly alphabetical.

**Observed (hxcpp 4.x)**: for a class `A` with an eager static `static var _instance:A = new A();`, dependency objects constructed inside `A`'s **constructor body** get hoisted to boot before `A`. The same dependency constructed in a **field-declaration initializer** (`public final child:B = new B();`) does NOT get hoisted — it boots after `A`, in roughly module-alphabetical order.

Consequence: a runtime guard that inspects another class's boot state during construction (e.g. `haxe.rtti.Rtti.hasRtti(Type.getClass(this))` in a base-class constructor) passes when `new B()` sits in the ctor body, but throws ("requires @:rtti notation") when the identical init is moved to the field declaration — `B.__boot()` hasn't assigned `__rtti__` yet.

```haxe
// RISKY — field-decl init boots AFTER A; RTTI guard in B's base ctor can fire too early
class A {
    public static var _instance:A = new A();
    public final child:B = new B();
}

// SAFER — construct in ctor body; observed to hoist B ahead of A
class A {
    public static var _instance:A = new A();
    public final child:B;
    public function new() { child = new B(); }
}
```

Nothing at compile time catches this (typecheck clean, lint clean) — only launching the binary does, and it crashes before any test runner starts. Check the process exit code and log tail, not just "did output stop".

**Robust fix**: never build an object graph that depends on other classes' boot state (RTTI guards, static registries) from an EAGER static initializer — make the static lazy (nullable, create on first accessor call). Fighting generator-chosen boot order from Haxe code is not controllable.

## Diff the GENERATED C++ — a typecheck is blind, a full build is not the only alternative

"Does this refactor change anything on hxcpp?" (moving a ctor init to a field declaration, relocating an `untyped __cpp__` splice, reordering statics) reads as unanswerable without a full native build, so it gets settled by guessing — either shipping the change unverified or reverting a harmless one. Both are avoidable: hxcpp's `-D no-compilation` emits the whole C++ tree and skips the compiler, so the question becomes a text diff that costs seconds.

```sh
haxe <target>.hxml            # hxml already carries -D no-compilation + -cpp <objdir>
cp -R <objdir> /tmp/gen-before
# apply the change
haxe <target>.hxml
diff -r /tmp/gen-before <objdir>
```

Diff the WHOLE output dir, not one class's `.cpp`. Per-class emit lives in `<Class>.cpp`; the boot ordering the section above warns about lives in the generated `__boot__.cpp`, whose `__boot_all()` is an explicit ordered list of `__boot()` calls. Only a tree-wide diff covers both.

Expect line-number churn: `HX_STACKFRAME` / `HXDLIN(n)` macros embed source line numbers, so a pure statement move shows up as renumbering with identical bodies — that IS the "no-op" verdict, not noise to explain away.

What this does and does not prove: it settles CODEGEN equivalence (same emitted statements, same boot order). It says nothing about whether the emitted C++ compiles when the change introduces new native constructs — for that you still need the real build.

## Pointer Types

| Type | C++ | GC? | Use case |
|------|-----|-----|----------|
| `cpp.RawPointer<T>` | `T*` | No | Native C++ function params |
| `cpp.Pointer<T>` | wrapper | **Yes** | Dynamic typing, array indexing |
| `cpp.Star<T>` | `T*` typedef | No | Extern signatures |
| `cpp.Reference<T>` | `T&` | No | C++ reference params |

`addressOf()` on `Dynamic` → pointer to stack wrapper, NOT the object. Crashes after stack frame changes.

## Threading

### Foreign threads MUST register with GC

```cpp
void foreign_thread_func() {
    int stackTop;
    SetTopOfStack(&stackTop, true);  // MUST be stack variable, not heap
    // ... use hxcpp APIs ...
    SetTopOfStack(0, false);
}
```

### Blocking operations need GC-free zone

GC is stop-the-world. Blocking without GC-free zone deadlocks entire GC. This includes mutex waits — Thread A holds mutex, GC triggers on Thread B, deadlock.

```haxe
cpp.vm.Gc.enterGCFreeZone();
// blocking I/O, network, sleep, mutex wait...
cpp.vm.Gc.exitGCFreeZone(); // MUST also exit on error paths
```

**CAUTION**: Only use GC-free zones on threads that are properly registered with GC. Calling enter/exitGCFreeZone from `Thread.create()` threads that haven't done GC work yet can cause "GCFree Zone mismatch" errors.

### NEVER wrap Sys.sleep() (or other hxcpp std functions) with GC-free zone

`mGCFreeZone` is a **boolean, NOT a counter** (`Immix.cpp:5830`). `Sys.sleep()` internally calls `enterGCFreeZone()`/`exitGCFreeZone()` (`Sys.cpp:125,147`). Wrapping it with additional enter/exit causes nested mismatch:

```haxe
// WRONG — double enter/exit, intermittent CriticalGCError → SIGTRAP crash
cpp.vm.Gc.enterGCFreeZone();
Sys.sleep(0.001);  // internally: enter(sets true) → sleep → exit(sets false)
cpp.vm.Gc.exitGCFreeZone();  // mGCFreeZone already false → "GCFree Zone mismatch"

// RIGHT — Sys.sleep() handles GC-free zone internally
Sys.sleep(0.001);
```

The crash is **intermittent** — depends on whether GC collection triggers between inner exit and outer exit. Same applies to all `_hx_std_*` functions in `Sys.cpp` that wrap with GC-free zones: `sys_command`, `sys_exists`, `file_delete`, `file_stat`, etc.

### Bool flags invisible across threads in release mode

C++ optimizer (`-O2`) hoists field reads out of loops. A `Bool` flag set from thread A is never seen by thread B's `while (!flag)` loop — the read is optimized to a single load before the loop.

```haxe
// WRONG — _stopped may never be seen as true by other threads
while (!_stopped) { Sys.sleep(0.1); }

// RIGHT — Mutex acquire/release creates memory barrier
private final _flagsMutex:Mutex = new Mutex();

// Writer (any thread):
_flagsMutex.acquire();
_stopped = true;
_flagsMutex.release();

// Reader (any thread):
_flagsMutex.acquire();
final stopped:Bool = _stopped;
_flagsMutex.release();
```

### Stopping worker threads — the pattern

Worker threads typically loop with `Sys.sleep()` + condition checks. To stop them reliably:

1. **Flag visibility**: Use Mutex-protected reads/writes for stop flags (see above)
2. **Blocking operations can't check flags**: If a thread is stuck inside a long-running method (DB query, file I/O, network), no flag check will help until the method returns
3. **Timeout + skip cleanup**: When waiting for a thread to stop, use a timeout. If timeout expires, the thread is stuck in a blocking op — skip `close()`/cleanup and just null out references. The OS will clean up on process exit
4. **Don't close resources held by stuck threads**: Calling `db.close()` while a worker thread still holds a DB lock → deadlock. Skip close on timeout

```haxe
// Stopping pattern
_worker.stopRequested = true;  // Mutex-protected setter
var waited:Int = 0;
while (!_worker.isStopped() && waited < TIMEOUT_MS) {
    Sys.sleep(0.1);
    waited += 100;
}
if (_worker.isStopped()) {
    // Thread stopped cleanly — safe to close resources.
    // Re-check the flag, NOT the timer: the worker may have stopped
    // during the final sleep, right as the timeout expired.
    try db.close() catch (e:Dynamic) {};
}
// Always null out regardless
_worker = null;
```

### Display tree detach for background threads

`DisplayObject.parent = null` does NOT remove the object from the parent's `__children` array. The parent's render loop (OpenGL on main thread) still iterates `__children` and renders the "detached" object concurrently → segfault.

```haxe
// WRONG — parent field nulled but still in __children → main thread renders it
child.parent = null;

// RIGHT — remove from __children, then null parent
@:privateAccess parent.__children.remove(child);
child.parent = null;
```

To restore, save the child index before removing and re-insert at the same position:

```haxe
// Save
final savedIndex:Int = @:privateAccess parent.__children.indexOf(child);
@:privateAccess parent.__children.remove(child);
child.parent = null;

// Restore
@:privateAccess parent.__children.insert(savedIndex, child);
child.parent = savedParent;
```

**Why not `removeChild()`?** It dispatches REMOVED/REMOVED_FROM_STAGE events, nulls stage, and triggers side effects. Direct `__children` manipulation is a lightweight detach for thread isolation.

### Sys.exit() doesn't flush stdout

`Sys.exit()` calls C `exit()`. In worker threads, stdout buffer may not flush. Always call `Sys.stdout().flush()` before `Sys.exit()`.

### Sys.exit() races hxcpp GC mutex destruction → `mutex lock failed: Invalid argument`

`Sys.exit()` → libc `exit()` → runs C++ static destructors, including hxcpp's GC mutexes (`sThreadPoolLock` in `hx::gc::Immix.cpp`, `g_threadInfoMutex` in `hx::Thread.cpp`). The GC worker thread is NOT stopped by `exit()`. Its next `pthread_mutex_lock` on a now-destroyed mutex returns EINVAL → libc++abi terminates with `mutex lock failed: Invalid argument`. Manifests differently per platform: Linux shows `terminate ... std::system_error ... Invalid argument`, Windows is silent or AV, macOS crashes at unit test exit.

Fix: after cooperative cleanup, skip C++ static destructors by calling `_Exit` (see below).

### `_exit` from `<unistd.h>` is NOT available; use `_Exit` from `<cstdlib>`

hxcpp does NOT auto-include `<unistd.h>`. `untyped __cpp__("::_exit({0})", code)` fails with `error: no type named '_exit' in the global namespace`.

Use C99 `_Exit` (capital E) from `<cstdlib>` — skips C++ static destructors and atexit handlers, identical to `_exit` in effect, portable across Darwin/Linux/Windows MSVC.

```haxe
// WRONG — <unistd.h> not included by hxcpp; compile error
untyped __cpp__("::_exit({0})", code);

// RIGHT — <cstdlib> is safe; _Exit skips static destructors
@:cppFileCode("#include <cstdlib>")
final class CleanExit {
    public static function exit(code:Int):Void {
        try Sys.stdout().flush() catch (_:Exception) {}  // see "doesn't flush stdout" above
        try Sys.stderr().flush() catch (_:Exception) {}
        #if cpp
        untyped __cpp__("std::_Exit({0})", code);
        #else
        Sys.exit(code);
        #end
    }
}
```

**Warning**: `_Exit` skips ALL atexit handlers. Any pending writes (DB flushes, file saves) are lost. Only call after cooperative cleanup. Keep this as a small shared utility class.

## Sockets

### Read-timeout error string differs by platform — classify by elapsed time, not text

hxcpp's `block_error()` throws `"Blocking"` only for EAGAIN/EWOULDBLOCK/EINPROGRESS/EALREADY on POSIX and WSAEWOULDBLOCK/WSAEALREADY on Windows; everything else — including WSAETIMEDOUT, what `SO_RCVTIMEO` actually produces on Windows — falls into the generic `"EOF"` string. The Haxe std maps `"Blocking"` → `haxe.io.Error.Blocked`, anything else → `Error.Custom(e)`. So a `socket.setTimeout()` / `Http.cnxTimeout` read timeout surfaces as `Blocked` on macOS/Linux and over TLS on every platform (mbedtls maps its own WANT_READ to `"Blocking"`), but as `Custom(EOF)` for a plain socket on Windows — `sys.Http.customRequest` hands that string straight to `onError`.

```haxe
// WRONG — misses the timeout on Windows plain sockets; treats it as a connection error, retries a non-idempotent POST
if (msg == "Blocked") isTimeout = true;

// RIGHT — classify by elapsed time, not error text
if (failed && Timer.stamp() - started >= timeoutSeconds) isTimeout = true;
```

A real peer close is `haxe.io.Eof` (0-byte recv) on every platform — distinct from the `"EOF"` string above, which is a read-error code, not end-of-stream.

## Extern Patterns (@:native)

### Pointer suffix for heap-allocated types

```haxe
@:native("Greeter*")  // ← asterisk required for `new`-allocated C++ objects
@:include("greeter.h")
extern class Greeter { ... }
// WITHOUT "*" → error only when multiple methods called (optimizer masks single-method case)
```

### Linc-style extern — all four metadata needed

```haxe
@:include("SDL.h")       // header
@:native("SDL_Window")   // C++ name
@:structAccess           // . not -> (value types)
@:unreflective           // skip GC scan (native type)
extern class SDLWindow { ... }
```

### @:nativeGen restrictions

Cannot extend non-@:nativeGen class. Cannot implement interfaces (rely on Dynamic). Leaf classes or full hierarchies only.

### Code injection

| Metadata | Location | Use for |
|----------|----------|---------|
| `@:headerCode` | Top of .h | #include directives |
| `@:headerClassCode` | Inside class in .h | Private C++ members |
| `@:cppFileCode` | Top of .cpp | Static helpers |
| `@:functionCode` | Function body top | Local C++ vars |

`@:functionCode` does NOT work in inline methods. `@:include` is NOT propagated to child classes — re-declare.

## @:cppFileCode with ObjC headers on iOS — Foundation/NSString conflict

Including `<OpenGLES/EAGL.h>` or any header that pulls in `Foundation.h` inside `@:cppFileCode` causes a compile error on iOS. The generated `.cpp` file includes hxcpp headers first (which define `hx::String` in the `hx` namespace and typedef it as `String`). When Foundation.h is then included, its `NSString` definition conflicts with the already-defined `String` symbol.

```haxe
// WRONG — Foundation.h (pulled by EAGL.h) conflicts with hxcpp's String typedef
@:cppFileCode('
    #include <OpenGLES/EAGL.h>
    EAGLContext* getContext() { return [EAGLContext currentContext]; }
')
```

**Workaround**: use `<objc/runtime.h>` + `objc_msgSend` to call ObjC class methods without importing the framework header. Define C helper functions in `@:cppFileCode` that wrap `objc_msgSend` calls with proper casts.

```haxe
// RIGHT — no Foundation.h import, no conflict
@:cppFileCode('
    #include <objc/runtime.h>
    #include <objc/message.h>

    static void* get_eagl_context() {
        Class cls = objc_getClass("EAGLContext");
        SEL sel = sel_registerName("currentContext");
        return ((void* (*)(id, SEL))objc_msgSend)((id)cls, sel);
    }
')
```

For methods that return structs (e.g. `CGRect`, `CGSize`), use `objc_msgSend_stret` on 32-bit and regular `objc_msgSend` on 64-bit ARM (stret is deprecated on arm64).

## Build System

`<files>` → compile step (includes). `<target>` → link step (libraries). Mixing → silent failures.

hxcpp does NOT auto-create directories. `<copyFile>` with subdirs fails silently — use `<mkdir>` first.

### Platform conditionals: `macos` not `mac`

hxcpp Build.xml uses `macos` for macOS conditionals — NOT `mac`. Using `mac` silently fails (condition never matches), producing `.dylib` instead of `.ndll`. At runtime, `<ndll>` loads the stale `.ndll` which lacks `__prime` symbols → `Could not find primitive` errors.

```xml
<!-- WRONG — 'mac' is not a valid hxcpp platform identifier -->
<ext value=".ndll" if="windows || mac || linux" />

<!-- RIGHT — 'macos' matches hxcpp's HX_MACOS define -->
<ext value=".ndll" if="windows || macos || linux" />
```

Other valid platform identifiers: `windows`, `linux`, `android`, `iphoneos`, `iphonesim`.

### project.xml: `if="release"` does NOT gate — use `unless="debug"`

In Lime's project.xml, the `release` define can be set even in `-debug` builds, so `if="release"` entries (haxedefs, sections) silently leak into debug. Unknown identifiers ARE falsy — `release` is specifically unreliable, not a parser quirk. The reliable gate is the `debug` define, set only by `-debug`:

```xml
<!-- WRONG — leaks into -debug builds -->
<haxedef name="analyzer-optimize" if="release" />

<!-- RIGHT — 'debug' is set only by -debug -->
<haxedef name="analyzer-optimize" unless="debug" />
```

Verify gating with `lime display <target> -debug | grep <define>` vs `-release` — never trust the conditional by reading it.

### Build.xml `outdir` resolves against the CWD, not the Build.xml location — and a misplaced artifact still prints `Link:` and exits 0

A relative `outdir` is joined to the directory hxcpp was INVOKED from. The standard Lime extension layout puts Build.xml in `project/` and writes `<outdir name="../ndll/${BINDIR}" />`, which is correct **only when the build runs from `project/`** — that is what `lime rebuild` does. Invoke the same file from the extension root and `../ndll/` climbs one level ABOVE the extension:

```sh
# WRONG — ../ndll/ resolves against the extension root → <parent-of-extension>/ndll/
cd <extension> && haxelib run hxcpp project/Build.xml -D<platform>

# RIGHT — ../ndll/ resolves to <extension>/ndll/, where the app links from
cd <extension>/project && haxelib run hxcpp Build.xml -D<platform>
```

This fails in the worst possible way: compilation succeeds, the build prints `Link: ../ndll/<BINDIR>/<lib>` (its own relative spelling, so it reads as correct), and the exit status is 0. Nothing is stale-checked, so the app keeps linking the OLD artifact and a newly added `DEFINE_PRIME*` entry point is simply absent at runtime — surfacing as a `Could not find primitive` / signature-mismatch crash far from the build.

**Never treat a green build as proof the artifact landed.** Check the file the app actually bundles:

```sh
stat -f "%Sm %z" <extension>/ndll/<BINDIR>/<lib>   # did the mtime move?
nm -gU <extension>/ndll/<BINDIR>/<lib> | grep <new_symbol>
```

A stray `ndll/` tree one level above an extension is the fingerprint of this mistake — from this build or an earlier one.

### `lime display` prints the CACHED hxml when the project file is older than it — it is not a fresh parse

`lime display <target> [-Dfoo]` reuses `<app path>/<target>/haxe/<buildType>.hxml` left by the last `lime build`/`update`, and only re-generates it when the project file's mtime is newer than that hxml (`MacPlatform.getDisplayHXML`, same in the other desktop platforms). So the output reflects the LAST BUILD's defines, not the flags on the command line: after a `-DUNIT_TESTS` build every later `lime display mac` still lists `-D UNIT_TESTS`, with the test haxelibs and `-D HEADLESS`, while `-D` flags you pass now are silently absent. Nothing in the output marks it as stale. Bisecting project.xml with copies under another name "works" only because a freshly copied file is newer than the hxml — the copy is parsed, the original is not, which makes the two look different for reasons that have nothing to do with their content.

```sh
# WRONG — reads the hxml of whatever was built last
lime display mac -debug -DFOO | grep '^-D'

# RIGHT — regenerate first, then read the file lime wrote
lime update mac -debug -DFOO >/dev/null && grep '^-D' dist/macos/haxe/debug.hxml
# (or: touch project.xml before `lime display`)
```

`buildType` is `debug` / `release` / `final`, so a `-debug` display reads `debug.hxml` — a test build (release) and an IDE debug build only collide on the `.app` bundle they both write into `<app path>/<target>/bin/`, not on the hxml.

### Native assets

Assets are **synchronous** on native — `Assets.getImage()` etc. return immediately. For runtime-added assets (not in project.xml): use `sys.io.File` directly — `lime.Assets` only knows compile-time manifest.

No leading slashes in asset paths — `"/manifest/default.json"` crashes on some native targets.

### SWF assets: Graphic symbols lose instance names

`getChildByName()` fails on children that are **Graphic** symbols in the SWF — OpenFL renders them inline and assigns auto-names (`instance1425`). Only **MovieClip** symbol type preserves the Animate instance name. If name-based access is needed on a Graphic, convert it to MovieClip in Animate and re-publish.

## Display Filters (GlowFilter, DropShadowFilter, etc.)

**GlowFilter on Label/Sprite container** — apply to the parent container (Label, Sprite), NOT to TextField directly. `label.filters = [new GlowFilter(...)]` works. `textField.filters` inside a Label wrapper does NOT produce visible results.

**BitmapData.draw() does NOT capture filters** — `bmd.draw(stage)` uses the software renderer and skips GPU filters. Use `window.readPixels()` instead — reads from the GPU framebuffer and captures everything including filters. Screenshot tooling (e.g. a debug bridge) should use readPixels with draw() as fallback.

**Search codebase first** — before implementing text outlines, shadows, or effects, grep for existing `GlowFilter`/`DropShadowFilter` usage in the project. Likely already solved with correct params.

**`DisplayObject.filters != null` forces `cacheAsBitmap = true`** — the getter is `return (__filters == null ? __cacheAsBitmap : true)`. Any non-null filters array (even a filter with alpha=0 or zero-radius) causes the object to render through the intermediate bitmap-cache path. Symptoms:

- Setting `obj.cacheAsBitmap = false` has NO effect when `filters != null` — the getter still returns `true`.
- At high render scales (video export, offscreen `BitmapData.draw` with large matrix), the intermediate cache bitmap can be sized wrong for the target, visually clipping the right/bottom of content (elements near those edges silently disappear from the output).

```haxe
// WRONG — unselected state keeps a zero-alpha filter "to avoid allocations"
override private function set_isSelected(value:Bool):Bool {
    final alpha:Float = value ? 1 : 0;
    obj.filters = [new GlowFilter(color, alpha, 4, 4, 1)];  // still forces cacheAsBitmap
    return isSelected = value;
}

// RIGHT — null out filters when not needed
override private function set_isSelected(value:Bool):Bool {
    obj.filters = value ? [new GlowFilter(color, 1, 4, 4, 1)] : null;
    return isSelected = value;
}
```

For batch operations (video export, offscreen render): if you cannot change the per-object filter logic, strip `filters` AND `cacheAsBitmap` on every descendant before the batch, save both values, and restore them after. Stripping only `cacheAsBitmap` is insufficient because the filter-override re-enables the cache path.

**BitmapData.draw() ignores source scaleX/scaleY** — setting `bitmap.scaleX = 0.5` then calling `bmd.draw(bitmap)` renders at full size, clipping to BitmapData bounds. The source object's transform properties are NOT applied. Use the Matrix parameter instead:

```haxe
// WRONG — draws at full size, clips
final src:Bitmap = new Bitmap(largeBmd);
src.scaleX = src.scaleY = 0.5;
smallBmd.draw(src);  // full-size render, clipped to smallBmd bounds

// RIGHT — Matrix applies the scale
final m:Matrix = new Matrix();
m.scale(0.5, 0.5);
smallBmd.draw(new Bitmap(largeBmd), m);
```

Affects both Cairo and GL renderers. Children inside a Sprite container DO get their transforms composed during rendering — only standalone DisplayObject transforms are ignored.

## BitmapData GPU Rendering (render-to-texture)

**Non-readable BitmapData triggers GL path** — `BitmapData.draw()` checks `!readable && context3D != null` and routes to `__drawGL` (render-to-texture via FBO). To enable: call `bmd.getTexture(ctx)` then `bmd.disposeImage()`.

**`copyPixels` silently no-ops on non-readable targets** — `if (!readable) return;`. When compositing a static background into a GPU BitmapData, use `draw(bitmap)` instead of `copyPixels`.

**`Context3D.__bindGLFramebuffer` is non-nullable** — the parameter type is `GLFramebuffer` (no `Null<>`). Passing `null` to bind the default framebuffer fails `@:nullSafety`. Workaround: skip the restore if the next `draw()` call will rebind via `setRenderToTexture` anyway — `__drawGL` always saves/restores FBO state.

**`GL.readPixels` returns rows bottom-up** — OpenGL origin is bottom-left. After reading from an FBO, flip rows vertically (swap top↔bottom) before passing to encoders that expect top-down pixel order.

**`UInt8Array` has NO `blit` method** — Lime's `UInt8Array` (abstract over `ArrayBufferView` on native) does not expose a static or instance `blit`. For byte-level copy/swap (e.g. row flipping after `glReadPixels`), convert to `haxe.io.Bytes` via `.toBytes()` — on native this returns the underlying buffer (no copy), then use `Bytes.blit()`:

```haxe
final bytes:Bytes = readbackArray.toBytes(); // no-copy on native
final tmp:Bytes = Bytes.alloc(rowStride);
tmp.blit(0, bytes, topOff, rowStride);       // top → tmp
bytes.blit(topOff, bytes, botOff, rowStride); // bottom → top
bytes.blit(botOff, tmp, 0, rowStride);        // tmp → bottom
```

### BitmapData.draw pixelRatio vs cache bitmaps (text blur on Windows)

`BitmapData.draw()` sets `renderer.__pixelRatio = window.scale`. TextFields with filters (GlowFilter, DropShadowFilter) go through `__updateCacheBitmap` which creates the cache bitmap at `pixelRatio` resolution. On Windows (`window.scale=1`), cache bitmaps are 1x — if the draw matrix scales up (e.g. a ~2x video-export draw matrix), the 1x cache is upscaled → blurry text.

**Fix**: set `pixelRatio = max(window.scale, transform_scale)` in `BitmapData.draw()` so cache bitmaps are rasterized at the final output resolution. This fixes BOTH code paths — text with filters (cache bitmap) and text without filters (Context3DTextField.render).

**Key insight**: fixing `pixelRatio` only in `Context3DTextField.render` (via `renderer.__worldTransform` scale) does NOT help text with filters — those bypass `render()` entirely and go through `__updateCacheBitmap` → `Context3DBitmap.render`.

**Testing gotcha**: on Mac (`window.scale=2`), simulating `pixelRatio=1` only in `BitmapData.draw` doesn't reproduce the bug — screen rendering already created 2x cache bitmaps. Must also force `pixelRatio=1` in `Stage.hx` (screen render) to accurately simulate Windows.

## Raw GL + Context3D Mixing

Context3D has TWO state objects: `__state` (desired) and `__contextState` (cached GL state). Cache invalidation must target `__contextState`, NOT `__state` — modifying `__state` corrupts desired state and causes unpredictable rendering.

When mixing raw GL calls (`glBindTexture`, `glUseProgram`, `glBindBuffer`, `glBindFramebuffer`) with Context3D rendering, the cached state in `__contextState` becomes stale. Context3D's flush methods (e.g. `__flushGLFramebuffer`) compare `__contextState` vs `__state` to decide whether to issue GL calls — stale cache means skipped rebinds.

**Preferred fix: ORDER OPERATIONS so Context3D rendering happens AFTER raw GL calls.** Each `BitmapData.draw()` creates a fresh `OpenGLRenderer` that fully reinitializes GL state through Context3D, making any prior raw GL state pollution irrelevant. This is far simpler than trying to save/restore GL state.

If you must interleave raw GL and Context3D:
- After raw GL calls, unbind everything (`gl.bindTexture(gl.TEXTURE_2D, null)`, etc.)
- Invalidate matching `__contextState` fields: `__currentGLFramebuffer`, `__currentGLTexture2D`, `__currentGLArrayBuffer`, `renderToTexture`, `program`, `shader`
- Note: `__bindGLTexture2D` cache is commented out in OpenFL (always calls `gl.bindTexture`), but framebuffer cache IS active in `__flushGLFramebuffer`
- Setting `__contextState` fields to `cast null` makes Context3D think "no current binding" — next flush will rebind. But if `__state` is ALSO null, Context3D sees them as matching and skips the rebind entirely

### Custom shader sampling Context3D textures — set texture params explicitly

`RectangleTexture` does NOT set `TEXTURE_MIN_FILTER`/`TEXTURE_MAG_FILTER` on creation. GL default is `GL_NEAREST_MIPMAP_LINEAR` which requires mipmaps — without them, `texture2D()` returns black (incomplete texture). Context3D's `__setSamplerState` sets these params during normal rendering, but custom GL shaders bypass it.

```haxe
// After bindTexture, before drawArrays:
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
```

## Edge Overlap for Gradient Fade Covers

OpenFL (like Flash) — elements at the same edge can leak 1-2px due to anti-aliasing, rounding, or offset children (e.g. scrollbar with `barPad > 0` extends past container width). Classic fix: **extend covering shapes a few pixels past the container edge**.

```haxe
// Gradient fade: alpha 0→1 over FADE_WIDTH
graphics.beginGradientFill(GradientType.LINEAR, [bg, bg], [0, 1], [0, 255], matrix);
graphics.drawRect(0, 0, FADE_WIDTH, h);
graphics.endFill();
// Solid overlap BEYOND container edge — covers scrollbar overshoot, sub-pixel artifacts
graphics.beginFill(bg);
graphics.drawRect(FADE_WIDTH, 0, OVERLAP, h);
graphics.endFill();
shape.x = containerWidth - FADE_WIDTH;  // gradient at edge, solid extends past it
```

Key: solid rect goes PAST `containerWidth`, not before it. Parent mask clips the visual excess, but the fill covers any children that overshoot the boundary (e.g. scrollbar offset by `barPad`). Verify by inspecting the display tree (debug-bridge query, runtime trace) — check child positions and widths to confirm the cover extends past all children.

## Actuate (Tween Library)

`Actuate.tween(target, duration, {prop: value})` — starting a new tween on the same target+property automatically stops the previous one. No need for `Actuate.stop(target)` before `Actuate.tween(target, ...)`.

`onUpdate` fires on the last frame too — inside `complete()`, before `onComplete`. So `onUpdate` + `onComplete` with the same callback = double call on the final frame. Use only `onUpdate` when you need per-frame sync (e.g. scrollbar position during tween).

**Per-frame polling during tween → `.onUpdate()`, NOT `addEventListener(ENTER_FRAME)`**. Actuate's `.onUpdate()` fires on every tween update — same cadence as ENTER_FRAME but tied to the tween lifecycle. No manual add/remove listener management needed, automatically cleaned up when tween stops.

**dispatchEvent during tween kills animation** — when a method starts a tween AND dispatches an event synchronously, event listeners may call a property setter that instantly sets the animated property to its target value, killing the tween. Fix: add early-return guard in setter when value unchanged (`if (_field == value) return`), and `Actuate.stop(target)` before instant-setting for programmatic changes.

**`Actuate.stop(target)` FIRES `onComplete`** — its defaults are `complete = false, sendEvent = true`, and with no `properties` the actuator runs `complete(sendEvent)`, which invokes the `onComplete` handler synchronously (Actuate 1.9.0, `SimpleActuator.stop` → `GenericActuator.complete`). A "stop the fade-in" in `dispose()` therefore starts the chained fade-out on the disposed object, and stopping the previous overlay inside a re-triggered flash runs its handler against state not yet reassigned. Pass `Actuate.stop(target, null, false, false)` whenever the tween has a completion you do not want.

## Built-in Utility Methods

OpenFL provides utility methods that are easy to miss. Use them instead of writing manual implementations:

- `Point.interpolate(pt1, pt2, t)` — linear interpolation between two points. Note: `pt1` is the end point, `pt2` is the start point, `t` is progress (0→pt2, 1→pt1)
- `Point.distance(pt1, pt2)` — distance between two points
- `Point.polar(len, angle)` — create point from polar coordinates
- `Rectangle.intersection()`, `Rectangle.union()` — rectangle math

## TextField Line Metrics

**A line advances by `ascent + descent + format.leading` — the FONT's line gap is ignored.**
`TextEngine` reads `leading` from the `TextFormat` (default 0), never from the face's `hhea.lineGap`
/ `OS/2.sTypoLineGap`. So a 12 px face whose file says ascent 750 / descent 250 / lineGap 200
advances 12.0 per line in OpenFL, not 14.4 — a line height derived from the font file (fontTools,
FreeType metrics) over-reserves by the gap on every line. Measure instead:
`field.getLineMetrics(0).height` after setting text, or `TextLineMetrics.ascent + descent`.

**Every line after the first renders 1 px below where that advance puts it.** A multi-line field
sized as `lines * advance + 4` (the 2 px gutter above and below) shears the descenders of its last
line by exactly one pixel per extra line. Reserve `(lines - 1)` extra pixels on top of the advance
sum; a height helper that walks `getLineMetrics(i)` per line has to add the same term.

## Performance

**Null\<Float\> is 50x slower** — C++ boxes as heap GC object, allocates on every assignment. Use sentinel values.

**Dynamic allocates on null check** — comparing callback to null creates a Dynamic wrapper. Avoid in hot loops.

**Modulo goes through fmod()** — `x % n` on ints converts to double → `fmod()`. Use `x & (n - 1)` for power-of-2.

**Iterator for-loops allocate** — `for (item in array)` creates GC iterator object. Use `for (i in 0...array.length)`.

**Map degrades after ~50k keys** — becomes 50%+ slower than neko at 100k. Use custom structures for large maps.

**A declaration's SCOPE is transliterated 1:1 — narrowing one into a loop costs nothing.** hxcpp emits a local exactly where it was written: `var x:Int;` inside a `while` body becomes `int x;` inside that C++ block, not a hoisted slot. The frame is allocated once on function entry and the value lives in a register, so the hoisted and the sunk spelling produce identical machine code — there is no per-iteration allocation to fear. Same for a reference type: `::String s = …` in a loop body is a stack slot with an empty constructor, and heap traffic comes from the INITIALIZER, which ran per-iteration in the hoisted spelling too. So "will moving this declaration inside the loop re-allocate?" is always no; the only reason to refuse is SEMANTIC (a value carried across iterations, or a closure that captured one shared binding). Settle any such question in seconds with the `-D no-compilation` recipe above rather than reasoning about it.

## Cross-Target Differences

**ByteArray endianness**: native defaults `LITTLE_ENDIAN`, Flash hardcoded `BIG_ENDIAN`. Always set explicitly.

**DPI scaling**: iOS/macOS Retina `window.width` = DPI-scaled, `stage.stageWidth` = actual pixels. Android: both = device pixels.

**TextField HTML5**: AutoSize NONE gives incorrect textWidth/textHeight and wraps regardless of `wordWrap`.

## Debugging

| Define | Effect | Overhead |
|--------|--------|----------|
| `HXCPP_DEBUG_LINK` | Symbol tables | Minimal |
| `HXCPP_CHECK_POINTER` | NULL → exception not segfault | Small |
| `HXCPP_STACK_TRACE` | Function names in traces | Small |
| `HXCPP_STACK_LINE` | Line numbers (implies above) | Medium |
| `-debug` | All above + no optimization | ~80% |

**Crash investigation builds**: When building a binary to reproduce a crash, always add `-DHXCPP_CHECK_POINTER` to the build flags. Without it, a Null Object Reference is a silent segfault with no stack trace — useless for diagnosis. `-debug` includes it automatically, but if already building with `-debug`, you're covered.

**Null function pointer = hard crash**: `var f:Void->Void = null; f();` → C++ NULL dereference, not catchable. Check before calling.

## Touch vs Hover: runtime detection, not `#if mobile`

iOS supports hover (Apple Pencil 2, trackpad, mouse). Some Android devices too (Samsung S Pen, USB mouse). `#if mobile` is too coarse for touch vs hover distinction.

Use `event.buttonDown` in ROLL_OVER handler for runtime detection:
- Touch: ROLL_OVER fires with `buttonDown=true` (finger already pressing) → register one-shot stage MOUSE_UP to reset highlight
- Mouse/trackpad hover: ROLL_OVER fires with `buttonDown=false` → rely on ROLL_OUT as usual

ROLL_OVER on a direct finger tap is UNRELIABLE (observed missing on iPad native) — don't depend on it for press feedback. `MOUSE_DOWN` IS reliable (SDL synthesizes it from touch, `SDL_HINT_TOUCH_MOUSE_EVENTS="1"` in Lime): add a MOUSE_DOWN handler with the same body as the ROLL_OVER one, keep TOUCH_END for reset. No ENTER_FRAME/flags needed.

```haxe
private function hoverInHandler(event:MouseEvent):Void {
    _icon.color = Colors.HIGHLIGHT;
    if (event.buttonDown) {
        final s:Null<Stage> = stage;
        _stageRef = s;
        s?.addEventListener(MouseEvent.MOUSE_UP, stageMouseUpHandler);
    }
}
```

## Stage listener cleanup on dispose

When registering listeners on `stage` from a child display object, always store the stage reference in a `_stageRef` field. If the object is removed from display list before dispose, `stage` returns null and `stage?.removeEventListener` silently leaks the listener.

```haxe
// WRONG — stage is null after removeChild, listener leaks
stage?.removeEventListener(MouseEvent.MOUSE_UP, handler);

// RIGHT — stored reference works regardless of display list state
_stageRef?.removeEventListener(MouseEvent.MOUSE_UP, handler);
_stageRef = null;
```

## Event Listeners

### event.target — no cast needed

OpenFL's `event.target` is `Dynamic`. `Dynamic` implicitly converts to any type in Haxe — no cast required. `Std.downcast` and `cast()` are both unnecessary overhead.

```haxe
// WRONG — unnecessary runtime check + null handling
final target:Null<T> = Std.downcast(event.target, T);

// WRONG — unnecessary cast
_selected = cast(event.target, T);

// RIGHT — Dynamic assigns to any type implicitly
_selected = event.target;
```

### Accessing stage — use displayObject.stage, not Lib.current.stage

Any `DisplayObject` on the display list has a `.stage` property. Use it instead of the global `openfl.Lib.current.stage`:

```haxe
// WRONG — global static access, requires extra import
openfl.Lib.current.stage.addEventListener(Event.RESIZE, handler);

// RIGHT — use any display object already on stage
_button.stage.addEventListener(Event.RESIZE, handler);
this.stage.addEventListener(Event.RESIZE, handler);  // if 'this' is a DisplayObject
```

### `KeyboardEvent.keyCode` is the LAYOUT's character, not the physical key — letter shortcuts die on a non-Latin layout

`switch event.keyCode { case Keyboard.C: copy(); }` silently stops matching the moment the user types in a
Cyrillic/Greek/Hebrew/… layout: SDL reports the keycode the CURRENT layout produces, so the physical C key arrives as
`1089` (`с`), V as `1084` (`м`), Z as `1103` (`я`). Nothing errors — the shortcut just never fires, and the same build
works for anyone on a Latin layout, which is what makes it read as "works on my machine". The modifier keys themselves
also arrive through the handler (`15` = Command, `17` = Control on mac).

The physical scan code IS in the SDL event and lime THROWS IT AWAY at the C++ boundary: `lime/project/include/ui/KeyEvent.h`
declares `{ keyCode, modifier, type, windowID }` and `SDLApplication.cpp` copies only `keysym.sym` / `keysym.mod` — never
`keysym.scancode`. `Window.onKeyDown` is typed `KeyCode -> KeyModifier -> Void`, and openfl's `KeyboardEvent` carries
`keyCode`/`charCode`/`keyLocation`, so no layer downstream can hand it to you. Recovering it first-hand means patching both
forks and rebuilding the native libraries per platform.

What works without touching either fork: `lime.ui.ScanCode.fromKeyCode(keyCode)` — that is `SDL_GetScancodeFromKey` against
the CURRENT keymap (`lime/project/src/backend/sdl/SDLKeyCode.cpp`), i.e. SDL's own reverse lookup, not a hand-built table.
Letter scan codes are alphabetical (`ScanCode.A` = 4 … `ScanCode.Z` = 29), so the Latin code comes back by offset:

```haxe
// Latin layouts keep CHARACTER matching on purpose: on Dvorak/AZERTY the user expects
// cmd+C on the key that produces `c`, not on the QWERTY position of C. Only a layout
// with no `c` at all falls back to the physical key — the rule macOS and Windows follow.
if (keyCode >= Keyboard.A && keyCode <= Keyboard.Z) return keyCode;
final scanCode:Int = ScanCode.fromKeyCode(keyCode);
final firstLetterScanCode:Int = ScanCode.A;
final lastLetterScanCode:Int = ScanCode.Z;
return scanCode < firstLetterScanCode || scanCode > lastLetterScanCode ? keyCode : Keyboard.A + scanCode - firstLetterScanCode;
```

Two consequences worth carrying: "always use the scan code" is WRONG (it would move Dvorak/AZERTY shortcuts onto QWERTY
positions), and on a target without `lime_cffi` the lookup answers `ScanCode.UNKNOWN` (0), so the fallback must return the
original `keyCode` rather than trusting the result. Non-letter shortcuts (`ESCAPE`, `ENTER`, arrows) need none of this —
their key codes are layout-independent by construction.

### A listener's throw never reaches `dispatchEvent`'s caller once uncaught-error events are on

When any `UncaughtErrorEvent.UNCAUGHT_ERROR` listener exists on `loaderInfo.uncaughtErrorEvents` (typical for crash reporters), `stage.__uncaughtErrorEvents.__enabled` is true and `EventDispatcher.__dispatchEvent` wraps EACH listener call in try/catch, handing the error to `stage.__handleError`.

- **Tell:** `try dispatcher.dispatchEvent(e) catch (...)` is dead code in such an app - the throw goes to the crash handler (which usually exits), never to the caller.
- **Consequence:** "still fire the follow-up event if a listener throws" logic is moot - the app crashes instead.
- **Tests:** a unit test that adds a throwing listener and expects the throw to propagate fails, and takes the runner down through the crash handler.
- Without such a listener the throw propagates normally: behaviour depends on app setup, not on the dispatcher.

## OpenFL Internal APIs (for synthetic events / debug bridges)

### Coordinate pipeline for synthetic mouse events

Logical coords → `stage.__onMouse()` requires display-matrix input space, NOT stage coordinates:

```haxe
// logical (app coordinate space) → stage global → display input
final globalPoint:Point = contentRoot.localToGlobal(new Point(logicalX, logicalY));
final inputPoint:Point = stage.__displayMatrix.transformPoint(globalPoint);
stage.__onMouse(MouseEvent.MOUSE_DOWN, inputPoint.x, inputPoint.y, 0);
```

`__displayMatrix` on Retina: `scale(window.scale, window.scale)` — e.g. `scale(2,2)` for Retina.

### Hit-testing with shapeFlag=true

`stage.__hitTest(x, y, true, stack, true, stage)` — only **visible pixels** register. `graphics.beginFill(color, 0.0)` (alpha 0) is invisible to shape-flag testing. This affects transparent hit rects commonly used in UI components.

Display list hit-test order: **highest index first** (front-to-back). If a transparent hit rect at index 2 fails shape test, hit falls through to a lower-index sibling with visible pixels (e.g., a shadow at index 0).

### Scroll events bypass OS natural-scrolling inversion

Real scroll events: OS/SDL applies natural scrolling → Lime → OpenFL. Apps typically compensate with their own inversion flag on the scroll component.

Synthetic `stage.__onMouseWheel(deltaX, deltaY, mode)` bypasses OS/SDL, so the app's compensation causes **double inversion**. Fix: when the app's inversion flag is active, negate the delta before passing it to `__onMouseWheel`.

### __onMouseWheel needs __mouseX/Y set first

`__onMouseWheel` uses `stage.__mouseX/__mouseY` for hit-testing (not explicit coordinates). Send a `MOUSE_MOVE` first to position the internal mouse:

```haxe
stage.__onMouse(MouseEvent.MOUSE_MOVE, inputX, inputY, 0);  // sets __mouseX/Y
stage.__onMouseWheel(0, delta, MouseWheelMode.LINES);
```

## EGL Context and FBO Sharing (Android GPU Path)

**FBOs are NOT shared between EGL contexts** — even shared contexts (created with `eglCreateContext(..., shared_ctx, ...)`) do NOT share FBO objects. Only textures, renderbuffers, and buffer objects are shared.

**When blitting from an FBO created in context A to a surface created for context B**: use context A with the target surface (`eglMakeCurrent(display, target_surface, target_surface, context_A)`), not context B. This keeps the FBO visible while redirecting output to the target surface.

**eglPresentationTimeANDROID is required for correct timestamps**: Without calling `eglPresentationTimeANDROID()` before `eglSwapBuffers()`, MediaCodec uses wall-clock time instead of the intended presentation timestamp. Resolve the function pointer via `eglGetProcAddress("eglPresentationTimeANDROID")` at init time.

**EGL config compatibility for window surfaces**: When creating an EGL window surface for MediaCodec's ANativeWindow, use the same config as the caller's context (`eglQueryContext` → `EGL_CONFIG_ID` → `eglChooseConfig`). For test contexts, include `EGL_WINDOW_BIT` in `EGL_SURFACE_TYPE` alongside `EGL_PBUFFER_BIT`.

Files in this skill

  • SKILL.md44.9 KB
  • references/build-and-versions.md2.4 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.