"Integrations" (simple) API layer

.github/instructions/babylon-native-debugging.instructions.md

@@ -24,7 +24,7 @@ For pure RenderDoc CLI usage (any app, not BN-specific), see
 |---|---|
 | `Apps/Playground/Shared/CommandLine.{h,cpp}` | Argument parser. Single source of truth for supported flags. |
 | `Apps/Playground/Shared/Diagnostics.{h,cpp}` | Crash handler, `DumpFailure`, finish-line, exit-code tracking. |
-| `Apps/Playground/Shared/AppContext.cpp` | Wires `UnhandledExceptionHandler` + `console.error` into `DumpFailure`; injects `_playgroundOptions` into JS. |
+| `Apps/Playground/Win32/App.cpp` (and the other per-host `App.*`) | Wires the `RuntimeOptions::log` callback into `DumpFailure` (`JS CONSOLE ERROR` for `LogLevel::Error`, `UNCAUGHT JS ERROR` for `LogLevel::Fatal`) and injects `_playgroundOptions` into JS via `Runtime::RunOnJsThread`. |
 | `Apps/Playground/Scripts/validation_native.js` | Test runner. Reads `_playgroundOptions`, picks tests, calls `TestUtils.captureNextFrame()`. Reference-image load failures arrive via `BABYLON.Tools.LoadFile`'s `onLoadFileError` and are tagged with `MISSING_REFERENCE_IMAGE:`. |
 | `Apps/Playground/Scripts/config.json` | Test catalog. Each entry has `title`, `playgroundId`/`scriptToRun`, `referenceImage`, optional `excludeFromAutomaticTesting`/`reason`/`onlyVisual`/`renderCount`/`capture`/`threshold`/`errorRatio`. |
 | `Plugins/TestUtils/Source/TestUtils.cpp` | Native side of `TestUtils.captureNextFrame()` -- calls `m_deviceContext.RequestCaptureNextFrame()`. |
@@ -80,13 +80,15 @@ When you see `[Error] Error: Cannot load X` in stdout, **scroll up** --
 short error line. The short line is kept so legacy log scrapers still match.
 
 ### 3. JS stack on every `console.error`
-`AppContext.cpp`'s `Console::Initialize` callback calls
+The Integrations layer's `Console::Initialize` callback calls
 `Babylon::Polyfills::Console::CaptureCurrentJsStack(env)` on every
-`LogLevel::Error` message and appends the captured stack to the
-`DumpFailure` banner body. The capture is best-effort -- if the JS engine
-can't produce a stack (no JS context active, etc.) the helper returns an
-empty string and the banner just shows the message.
-Do not add per-callsite stack capture -- it's automatic.
+`LogLevel::Error` message and appends the captured stack to the message
+body that the host's `RuntimeOptions::log` callback receives (which the
+Playground hosts then route into the `DumpFailure` banner). The capture is
+best-effort — if the JS engine can't produce a stack (no JS context active,
+unsupported engine, etc.) the helper returns an empty string and the host
+just gets the bare message.
+Do not add per-callsite stack capture — it's automatic.
 
 ### 4. Colored finish line
 `Playground: Finished in <time>. (exit <code>)` is printed once at every exit

Apps/Playground/Android/BabylonNative/CMakeLists.txt

@@ -8,41 +8,30 @@ project(BabylonNative)
 get_filename_component(PLAYGROUND_DIR "${CMAKE_CURRENT_LIST_DIR}/../.." ABSOLUTE)
 get_filename_component(REPO_ROOT_DIR "${PLAYGROUND_DIR}/../.." ABSOLUTE)
 
+# Build the cross-platform Integrations facade *and* the Android JNI
+# interop layer (`libBabylonNativeIntegrations.so`). The Playground
+# Android app loads that library directly via `BabylonNative.java`
+# (in the `com.babylonjs.integrations` package).
+set(BABYLON_NATIVE_INTEGRATIONS ON CACHE BOOL "" FORCE)
+set(BABYLON_NATIVE_INTEGRATIONS_ANDROID ON CACHE BOOL "" FORCE)
+
 add_subdirectory(${REPO_ROOT_DIR} "${CMAKE_CURRENT_BINARY_DIR}/BabylonNative")
 
-add_library(BabylonNativeJNI SHARED
-    src/main/cpp/BabylonNativeJNI.cpp
-    ${PLAYGROUND_DIR}/Shared/AppContext.cpp
-    ${PLAYGROUND_DIR}/Shared/Diagnostics.cpp)
+# Append a Playground-specific JNI helper to the generic
+# BabylonNativeIntegrations target so the bootstrap script list can stay
+# in Apps/Playground/Shared/PlaygroundScripts.{h,cpp} (shared with the
+# Win32 / iOS / macOS hosts) instead of being duplicated on the Java
+# side. Compiling these into the same .so keeps the Integrations layer
+# as a single in-process instance — handles produced by one entry point
+# can be safely consumed by another.
+target_sources(BabylonNativeIntegrations
+    PRIVATE src/main/cpp/PlaygroundJNI.cpp
+            ${PLAYGROUND_DIR}/Shared/Diagnostics.cpp
+            ${PLAYGROUND_DIR}/Shared/PlaygroundScripts.cpp)
 
-target_include_directories(BabylonNativeJNI
+target_include_directories(BabylonNativeIntegrations
     PRIVATE ${PLAYGROUND_DIR})
 
-target_link_libraries(BabylonNativeJNI
-    PRIVATE GLESv3
-    PRIVATE android
+target_link_libraries(BabylonNativeIntegrations
     PRIVATE bx
-    PRIVATE EGL
-    PRIVATE log
-    PRIVATE -lz
-    PRIVATE AndroidExtensions
-    PRIVATE AppRuntime
-    PRIVATE Blob
-    PRIVATE Canvas
-    PRIVATE Console
-    PRIVATE GraphicsDevice
-    PRIVATE NativeCamera
-    PRIVATE NativeCapture
-    PRIVATE NativeEncoding
-    PRIVATE NativeEngine
-    PRIVATE NativeInput
-    PRIVATE NativeOptimizations
-    PRIVATE NativeTracing
-    PRIVATE NativeXr
-    PRIVATE Performance
-    PRIVATE ScriptLoader
-    PRIVATE ShaderCache
-    PRIVATE TestUtils
-    PRIVATE TextDecoder
-    PRIVATE Window
-    PRIVATE XMLHttpRequest)
+    PRIVATE Foundation)     # for <Babylon/PerfTrace.h> in PlaygroundScripts.cpp

Apps/Playground/Android/BabylonNative/consumer-rules.pro

@@ -0,0 +1,2 @@
+-keep class com.babylonjs.integrations.BabylonNative { *; }
+-keep class com.babylonjs.integrations.BabylonNative$RuntimeOptions { *; }

Apps/Playground/Android/BabylonNative/src/main/cpp/PlaygroundJNI.cpp

@@ -0,0 +1,39 @@
+// Playground-specific JNI helper. Built into the same .so as the generic
+// Integrations/Android JNI (added via target_sources in the Playground
+// CMakeLists), so there's a single copy of Babylon::Integrations across
+// the process — avoids cross-library handle-passing UB.
+//
+// Sole purpose: surface Apps/Playground/Shared/PlaygroundScripts.{h,cpp}
+// to Java so the bootstrap script list stays in one place, shared with
+// the other Playground hosts.
+
+#include <Babylon/Integrations/Runtime.h>
+#include <Babylon/Integrations/Android/RuntimeHandle.h>
+
+#include <Shared/PlaygroundScripts.h>
+
+#include <jni.h>
+
+extern "C"
+{
+
+JNIEXPORT void JNICALL
+Java_com_android_babylonnative_playground_PlaygroundActivity_loadBootstrapScripts(
+    JNIEnv*, jclass, jlong runtimeHandle)
+{
+    auto* runtime = Babylon::Integrations::Android::RuntimeFromHandle(runtimeHandle);
+    if (runtime == nullptr)
+    {
+        return;
+    }
+
+    // Idempotent process-wide setup (PerfTrace level, etc.).
+    Playground::Initialize();
+
+    // Queue bootstrap scripts; they run after the first View attach
+    // completes engine init on the JS thread.
+    Playground::LoadBootstrapScripts(*runtime);
+}
+
+} // extern "C"
+