Native integration 🤖🍎🖥️

How the neutral Java code (in core) reaches OS features that vary by platform.

`PlatformUtils` — the single abstraction point

PlatformUtils.instance is the platform façade. Each launcher installs its implementation (the web installs PlatformUtilsWeb). Key methods:

IWebView wv = PlatformUtils.instance.createWebView();   // null where there is no webview (web)
PlatformUtils.instance.view(url);                        // opens external URL
PlatformUtils.instance.dial(numero);                     // dials

The `crossfly-lib` native library

Loaded at startup by SharedLibraryLoader.load("crossfly-lib") inside Main.create() — on all targets, except WebGL:

if (Gdx.app.getType() != Application.ApplicationType.WebGL)
   new SharedLibraryLoader().load("crossfly-lib");

For this reason, everything that depends on it (e.g., NativeImage via JNI) does not exist on the web — there the pure Java implementation (JavaImageOps) or the stub applies.

The “native feature with fallback” pattern

Always check before using a feature that may not exist:

if (PlatformUtils.instance.createWebView() != null) {
   WebContainer c = new WebContainer();     // Android/iOS/Desktop
   painel.add(LAY_FILL, c);
   c.show(url);
} else {
   PlatformUtils.instance.view(url);        // Web: opens externally
}

The same applies to null returns from camera/map and to Device.platform:

if (Device.platform.isDesktop()) { /* desktop path */ }

Writing your own native implementation

Concrete services (webview, GPS, etc.) live outside core, in each launcher. For a new feature, define the interface in core and implement it per launcher, installing it in PlatformUtils/a service field at startup. The image abstraction follows this model: ImageOps → JavaImageOps (JVM) vs NativeImage (JNI).

Best practices

Never assume a device feature exists — check != null/Device.platform.
Place OS-specific code in the launcher, not in core.

Common mistakes

Calling a native feature without a fallback (breaks on the web).
Expecting crossfly-lib/JNI on the web (it is not loaded on WebGL).