Repository navigation
feat(compiler,mobile): support host JS engine reuse and Boa-free native kernels - #105
Merged
Merged
Conversation
…ve kernels
Unify GLB serialization on TypeScript `sceneToGLB`, publish a self-contained hosted compiler bundle (`dist/three-live-compiler-bundle.min.js`) paired with `dist/engine-requirements.json` and a Boa-free C ABI (`three_live_kernels.h`), and split the Android and Apple SDKs into JS-engine-free runtime, Boa-free kernel, and turnkey compiler artifacts behind a pluggable `ThreeCompilerBackend` SPI.
- **Unified TypeScript GLB Serialization**: Remove the duplicate Rust `glb.rs::write_glb` serializer so both native (`ThreeEngine::compile_glb`) and web compilation paths emit identical glTF 2.0 binaries via `three-convert.ts::sceneToGLB` with zero-copy native buffer capture.
- **Hosted Compiler Bundle & Engine Manifest**: Add `three-live-compiler-bundle.{js,cjs,min.js}` (`< 260 KB gz`) exposing `ThreeEngine.{compileToGLB, compileToUSDZ, glbToUSDZ, aiCall, installSandboxHardening}`, UTF-8 polyfills for bare ES2020 realms, `globalThis.__three_live_host__` v1 shims, and `engine-requirements.json`.
- **Boa-Free `three_live_kernels` C ABI & JNI**: Split Cargo features into `kernels` (zero `boa_engine`) and `boa`, adding `compiler/include/three_live_kernels.h` (`THREE_LIVE_KERNELS_ABI_VERSION = 1`), `three_live_kernels_table(&count)` (24 self-describing geometry, CSG, procedural texture, image, and USDZ kernels), `ThreeLiveKernels` JNI/Swift wrappers, and disjoint linker version scripts (`exported_symbols_kernels.lds` / `exported_symbols_compiler.lds`).
- **Android & Apple Artifact Split (`ThreeCompilerBackend`)**:
- Android: `:mobile:android-runtime` (`com.google.threelive:runtime`, zero JNI/Boa), `:mobile:android-kernels` (`com.google.threelive:kernels`), and `:mobile:android` (`com.google.threelive:compiler` auto-registering `NativeThreeCompilerBackend` via `Class.forName` fallback). Optional `:filament`, `:firebase-ai`, `:detect-mlkit`, `:hands-androidxr`, and `:hands-mediapipe` adapters now depend only on `:runtime`.
- Apple SwiftPM: `ThreeLiveRuntime` (zero C/Boa), `ThreeLiveKernels` (`ThreeLiveKernels.xcframework`, zero Boa), `ThreeLiveCompilerNative` (`ThreeLiveCompiler.xcframework`), and umbrella `ThreeLiveCompiler` (`@_exported import ThreeLiveRuntime` + `NSClassFromString` auto-registration).
…rve 1.4.0 version
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Applications that already embed a JavaScript engine (Boa, QuickJS, JavaScriptCore, Hermes, or V8) previously had to link
three-live's bundled Boa VM as well, duplicating engine binary size, per-realm memory overhead, and native symbol surfaces. In addition, maintaining separate Rust (glb.rs::write_glb) and TypeScript (three-convert.ts::sceneToGLB) GLB serializers risked subtle behavioral drift between native and web compilation paths.This PR enables one JS engine per host application while keeping turnkey
com.google.threelive:compilerandThreeLiveCompilerintegrations 100% drop-in compatible:Unified TypeScript GLB Serialization (
sceneToGLB)compiler/src/glb.rs::write_glb(~1,150 lines) and routesThreeEngine::compile_glbandtranscode_three_to_glbthroughthree-convert.ts::sceneToGLBwith zero-copy nativeUint8Arraycapture (__three_live_capture_output__).glb::read_glbandextractMeshesFromGLBagainst oversizedcount/componentTypeallocations, interleavedbyteStrideaccessors,Uint8indices, and scene/mesh/vertex/texture quotas.Hosted Compiler Bundle &
engine-requirements.jsondist/three-live-compiler-bundle.{js,cjs,min.js}(< 260 KB gz) anddist/engine-requirements.json(contractVersion: 1).TextEncoder/TextDecoderUTF-8 polyfills for bare ES2020 realms,ThreeEngine.{compileToGLB, compileToUSDZ, glbToUSDZ, aiCall, installSandboxHardening}, and optionalglobalThis.__three_live_host__v1 host/kernel acceleration.%TypedArray.prototype%, iterator prototypes,JSON,getSharedRegistry(), and all native hook slots ({writable: false, configurable: false}), hides__three_live_host__from user scripts, and isolates top-level lexical declarations across warm compiles.Boa-Free Native
three_live_kernelsLibrary (THREE_LIVE_KERNELS_ABI_VERSION = 1)compiler/Cargo.tomlfeatures intokernels(zeroboa_engineincargo treeandnm),boa,cli,wasm, andjni.compiler/include/three_live_kernels.handthree_live_kernels_table(&count)exposing 24 self-describing C-ABI kernels (primitives,ExtrudeGeometry,TextGeometry,CSG,ProceduralTexturePBR + height-to-normal + AO, PNG/JPEG decode, and USDZ packaging) with panic-catching boundaries and bounded slice/scalar validation.exported_symbols_kernels.ldsandexported_symbols_compiler.lds.Pluggable
ThreeCompilerBackend& Mobile Artifact Split:mobile:android-runtime(com.google.threelive:runtime, pure Kotlin/JVM with zero JNI),:mobile:android-kernels(com.google.threelive:kernels,libthree_live_kernels.so+ThreeLiveKernels), and:mobile:android(com.google.threelive:compiler,api(project(":mobile:android-runtime"))+NativeThreeCompilerBackend). Optional:filament,:firebase-ai,:detect-mlkit,:hands-androidxr, and:hands-mediapipemodules now depend on:mobile:android-runtime.ThreeLiveRuntime(zero C/Boa),ThreeLiveKernels(ThreeLiveKernels.xcframework),ThreeLiveCompilerNative(ThreeLiveCompiler.xcframework), and umbrellaThreeLiveCompiler(@_exported import ThreeLiveRuntime+ automaticNativeThreeCompilerBackendfallback).ThreeLiveFirebaseAInow depends only onThreeLiveRuntime.Testing
node scripts/build.js && node scripts/build.js --test): all 24 bundle budgets,compiler_bundle_test(including sandbox hardening, lexical breakout rejection, warm realm reuse,aiCallparity, and host kernel dispatch),three-live,xr-live, andevalssuites pass.cargo testacross--no-default-features --features kernels,jniand default features):kernelsunit tests, C-ABIkernels_embedder_test,three_compiler_test(87/87), and zeroboa_enginedependencies/symbols verified onkernels.ThreeCompilerBackendTest,ThreeLiveKernelsTest,ThreeLiveKernelsTests,ThreeLiveCompilerTests, iOS XCFramework build + symbol isolation verification (verify_xcframework.sh), and Android/iOS demo builds pass.