BabylonJS / BabylonJS/JsRuntimeHost

RFC: WebWorker interface via an N-API module

Open
#187 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
22
Forks
23
Avg merge
3d 14h
Merged PRs (30d)
6

Description

## Intent

Land the N‑API + underlying JS‑runtime updates needed to expose a **WebWorker interface as an N‑API module**, so the **Factotum** BabylonJS app can lift‑and‑shift from the browser/PWA into **BabylonNative** with minimal code change.

## Why this matters

- Factotum's data pipeline was moved onto a Web Worker; on‑device that gave a **~10 fps uplift** on Quest 1/2, Pico 4, and similar standalone headsets (pulling the pipeline off the render thread).
- To carry that architecture into BabylonNative, BabylonNative needs a Worker‑compatible surface — cleanest delivered as an **N‑API module** exposing the `Worker` interface (construct, `postMessage`, transferables, `onmessage`/`onerror`, `terminate`), backed by the runtime's threading/isolate model.
- **Revenue imperative**: in‑app purchases are broken/non‑existent for immersive PWAs on the **Meta Horizon Store** and **Pico Store** (even as of June 2026). Shipping as a native (BabylonNative) app is currently the only viable monetization path on those stores, so unblocking Factotum → BabylonNative is business‑critical for BabylonJS‑community devs whose complex BabylonJS apps depend on revenue (and storefront placement).

## Why the N‑API track comes first

A Worker‑as‑N‑API‑module needs a solid, modern N‑API surface across the runtimes BabylonNative ships:

- N‑API conformance + cross‑engine parity (the #116 + v7 track) so addons behave the same on V8 / JSC / Chakra.
- A shared `libnapi` so in‑process addons resolve modules dynamically, allowing for less hacky build setups to exclude N-API plug-ins that aren't used and align to other runtimes (#183).
- On Android specifically, a JSC that can keep up (see the jsc‑android → Bun‑JSC RFC, #186) — Worker payloads use modern JS (structured clone, BigInt, transferables) that 2019 JSC can't even parse.

## Proposed shape (for discussion)

- An N‑API module exposing a `Worker` class: construct from a script/module; `postMessage` with structured‑clone + transferable `ArrayBuffer`s; `terminate`; `onmessage`/`onerror`.
- Backed by a second runtime instance/isolate on a worker thread, with a thread‑safe channel (`napi_threadsafe_function` or equivalent).
- Reuse BabylonNative's existing JS dispatch / task‑runner where possible.

## Open questions

- Per‑engine threading model (V8 isolate‑per‑worker; JSC `JSContextGroup`; Chakra runtime‑per‑worker) and which `napi_*` primitives we standardize on.
- Structured‑clone + transferable depth (ties into the v7 `ArrayBuffer` detach work).
- Lifecycle/GC ownership across the thread boundary.

Related N‑API track: #116, #183, #185 (+ the v7 work staged as fork PR rebeckerspecialties/JsRuntimeHost#4).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.