Disclaimer: This is not an officially supported Google product.

LLMs and developers excel at writing concise Three.js code—not hundreds of lines of platform-specific native 3D, shader, and AR boilerplate. Three-Live compiles standard Three.js (THREE.Mesh, THREE.CSG, userData.xr, KHR_interactivity) on-device in a sandboxed Rust VM and renders natively in Google Filament and Jetpack XR SceneCore on Android, Apple RealityKit and Quick Look on iOS and visionOS, headless 4-up PNG contact sheets (three-live-cli) for AI coding agents, and WebGL2 / WebXR on the Web.

Quickstarts

1. Run Three.js natively on Android (Google Filament & Jetpack XR SceneCore)

Compile standard Three.js code over zero-copy JNI and drive native Google Filament rendering, 60 Hz physics, and Jetpack XR SceneCore spatial entities:

import com.google.threelive.FilamentHelper
import com.google.threelive.XRLiveRuntimeSession
import com.google.threelive.XRLiveSceneCoreHelper

val threeJsCode = """
  const core = new THREE.Mesh(
    new THREE.IcosahedronGeometry(0.55, 3),
    new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.85, roughness: 0.15 })
  );
  core.userData.xr = { grab: '2-hand', orbit: { speed: -0.4 } };
  scene.add(core);
""".trimIndent()

// Compile Three.js to a zero-copy GLB ByteBuffer and load directly into Google Filament
val holder = FilamentHelper.loadModelZeroCopy(threeJsCode) { buffer ->
    assetLoader.createAssetFromBinary(buffer)
}

// Step live KHR_interactivity graphs, 60 Hz rigid-body physics, and spatial traits per frame
val runtime = XRLiveRuntimeSession.fromGlb(holder.byteBuffer)
runtime.step(dtSeconds = 1.0 / 60.0)

// Or attach interactive spatial traits (grab, scale, billboard, anchor) in Android XR SceneCore
XRLiveSceneCoreHelper.attachTraitsFromGlb(xrSession, entity, holder.byteBuffer)

2. Run Three.js natively on iOS, macOS, and visionOS (Apple RealityKit)

Compile the exact same Three.js code into Apple RealityKit (ARView / RealityView) or .usdz:

import ThreeLiveCompiler
import RealityKit

@MainActor
func loadSpatialScene(from threeJsCode: String, into arView: ARView) async throws -> XRLiveRealityKitSession? {
    let glb = try ThreeCompiler.compileToGLB(script: threeJsCode)
    let entity = try await RealityKitHelper.loadEntity(fromGLB: glb)
    XRLiveRealityKit.installTraits(on: entity, in: arView)

    // Bind live KHR_interactivity, 60 Hz physics, and spatial traits to RealityKit SceneEvents.Update
    let session = XRLiveRealityKitSession(glbData: glb, root: entity)
    session?.installInputTargets()
    session?.start()
    return session
}

3. Verify & compile Three.js headlessly for AI agents (three-live-cli)

Render a 4-up orthographic/camera contact sheet (zero GPU required), run the spatial linter for JSON frustum/overlap telemetry, or compile scene.js to .glb / .usdz:

$ npx three-live-cli render scene.js --view=quad --grid --annotations -o contact_sheet.png
$ npx three-live-cli validate scene.js --json
$ npx three-live-cli convert scene.js -o model.usdz

4. Run on the Web (<three-live> and <xr-live>)

On the web, <three-live> (< 30 KB gz viewer, < 70 KB gz with the live Three.js compiler) and <xr-live> (< 82 KB gz) render the same Three.js scenes in WebGL2 and 6DoF WebXR with 1-tap mobile AR handoff:

// Standard Three.js scene (runs identically in Android, iOS, CLI, and Web)
const mesh = new THREE.Mesh(
  new THREE.TorusKnotGeometry(0.4, 0.14, 64, 16),
  new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.8, roughness: 0.15 })
);
mesh.userData.xr = { grab: '1-hand', billboard: 'capsule' };
scene.add(mesh);

Install packages and bundles

Package installation

• 1. Android (JitPack, GitHub Packages Maven, prebuilt release AAR, or source):

  • JitPack (https://jitpack.io, no authentication required): Add
    maven("https://jitpack.io") to settings.gradle.kts, then add:

    dependencies {
      implementation("com.github.google.three-live:compiler:v1.3.0")
      // Optional adapters: :filament, :firebase-ai, :detect-mlkit, :hands-androidxr, :hands-mediapipe
    }
    

  • GitHub Packages Maven
    (https://maven.pkg.github.com/google/three-live): Configure the
    repository in settings.gradle.kts and add
    implementation("com.google.threelive:compiler:1.3.0") (plus optional
    :filament, :firebase-ai, :detect-mlkit, :hands-androidxr,
    :hands-mediapipe).

  • Prebuilt AAR: Download three-live-compiler-release.aar (includes
    arm64-v8a, armeabi-v7a, and x86_64 JNI .so libraries) and
    optional adapter AARs (three-live-filament-release.aar, etc.) from
    GitHub Releases
    into app/libs/ and add
    implementation(files("libs/three-live-compiler-release.aar")).

  • Maven Local (com.google.threelive:compiler:1.3.0): Run
    ./gradlew :mobile:android:publishReleasePublicationToMavenLocal and
    add implementation("com.google.threelive:compiler:1.3.0").

  • From source: Run make android (or
    bash scripts/build_android_aar.sh).

• 2. iOS, macOS, and visionOS (Swift Package Manager):

  .package(url: "https://github.com/google/three-live.git", from: "1.0.0")
  

  Swift Package Manager automatically resolves the prebuilt, checksum-pinned
  ThreeLiveCompiler.xcframework.zip archive from GitHub Releases—no local
  Rust or Node.js toolchain is required.

• 3. Rust CLI (three-live-cli) and library crate (Crates.io, prebuilt binaries, or source):

  • Crates.io (library & CLI):

    cargo add three-live-compiler
    # Or install the standalone CLI binary from Crates.io:
    cargo install three-live-compiler --bin three-live-cli
    

  • Prebuilt binaries: Download standalone binaries for macOS (arm64
    and x86_64), Linux (x86_64 and aarch64), and Windows
    (x86_64.exe) from
    GitHub Releases.

  • From source: Run make rust (npm run build && cargo build --manifest-path compiler/Cargo.toml --release --bin three-live-cli).

• 4. Web (npm, CDN, prebuilt release, or source):

  • npm:

    npm install three-live xr-live
    

  • Hosted ES module (jsDelivr or GitHub Pages CDN):
    Load https://cdn.jsdelivr.net/npm/three-live/dist/three-live.min.js or
    https://google.github.io/three-live/dist/three-live.min.js.

  • Prebuilt bundle archive: Download three-live-web-dist.zip from
    GitHub Releases.

  • From source: Run git clone https://github.com/google/three-live.git && cd three-live && npm install && npm run build.

Why Three-Live and XR-Live

Native mobile and headset AR/XR from Three.js

In practice, browser WebXR (navigator.xr) only covers part of the device
landscape:

• Android System WebView, iOS Safari, and iOS WKWebView don't support
  WebXR. A WebXR-only app can't run inside an embedded WebView or
  WKWebView in a native Android or iOS app, and can't enter AR in Safari on
  iPhone or iPad.
• Static OS handoffs (Scene Viewer and AR Quick Look) strip
  interactivity. Exporting a static .glb or .usdz file to the OS
  previewer works for viewing a model, but drops Three.js animate() loops,
  60 Hz physics, custom state, and interactive plugins.
• Browser WebXR doesn't use native spatial compositors. On Android,
  browser WebXR renders WebGL2 in the browser process rather than using Google
  Filament or Jetpack XR SceneCore's HomeSpace shared space. On visionOS,
  browser WebXR runs in an isolated fullscreen VR session without camera
  passthrough or SwiftUI Shared Space integration.

Three-Live solves this by compiling the same Three.js code on-device and running
it natively on each platform's own engine:

Compare <three-live> and <xr-live>

The following table compares the two runtime tiers across Android, iOS, and Web:

Modular plugins across Android, iOS, and Web

Every capability works on both prebuilt .glb, .usdz, and .spz assets and
live Three.js scenes:

• Compact core (< 30 KB to < 82 KB gz on Web): The 3D viewer
  (three-live-viewer.min.js) is < 30 KB gz (< 70 KB gz with the live
  Three.js compiler in three-live.min.js), and the WebXR viewer
  (xr-live-viewer.min.js) is < 53 KB gz (< 82 KB gz with the live
  Three.js compiler in xr-live.min.js).
• Core 3D, CAD, and animation plugins (three-live, 15 plugins): Optional
  domain bundles (three-live-studio.min.js at < 29 KB gz,
  three-live-cad.min.js at < 10 KB gz, and three-live-animation.min.js
  at < 11 KB gz, or < 111 KB gz combined in three-live-full.min.js) add
  KHR_interactivity behavior graphs, PBR Next materials,
  KHR_materials_variants, EXT_meshopt_compression, HDRI and
  spherical-harmonics lighting, contact shadows, 3D hotspots, post-processing
  (bloom and outline), automatic multi-tier Level-of-Detail (lod /
  THREE.LOD / MSFT_lod), 2D Shape/ExtrudeGeometry, 3D CSG Booleans,
  3D vector TextGeometry, 64-joint GPU skeletal skinning, morph targets,
  keyframe cross-fading, and two-bone / FABRIK inverse kinematics (ik).
• Hardware XR sensors (xr-live-sensors.min.js, < 10 KB gz): Adds
  hardware XR depth occlusion (XRDepthManager), analytical heightfield
  physics (XRHeightfieldPhysics), 25-joint hand gesture classification
  (XRHandGestureClassifier), the desktop 6DoF keyboard/mouse simulator
  (XRDesktopSimulator), HRTF spatial audio earcons, and WebMCP agent tools.
• Spatial computing plugins (xr-live-spatial.min.js, 15 plugins,
  < 63 KB gz): Each advanced spatial capability in
  xr-live-spatial.min.js is a standalone, zero-dependency plugin
  (~2 to 5 KB gz each) with a matching native implementation in the Android
  and iOS SDKs.
• Simulation and scenario plugins (xr-live-sim.min.js, 6 plugins,
  < 26 KB gz): Six plugins for games, training drills, and safety
  walkthroughs add a controllable character, autonomous steering agents,
  deterministic 60 Hz rigid-body physics (rigid-body), integrity and trigger
  zones, checklist objectives with scoring and timers, and procedural audio
  cues across Android, iOS, and Web.

Core 3D, CAD, and animation plugins (three-live)

The following table lists the fifteen modular 3D, CAD, and animation plugins:

Spatial perception, splat, audio, and multimodal AI plugins (xr-live)

The following table lists the eight perception, rendering, audio, and AI plugins
across Android Filament, iOS RealityKit, and WebXR:

CAD review, spatial layout, locomotion, and co-presence plugins (xr-live)

The following table lists the seven CAD, layout, locomotion, and multi-user
plugins across Android Filament, iOS RealityKit, and WebXR:

Interactive simulation, agent, and scenario plugins (xr-live-sim)

The following table lists the six simulation plugins across Android Filament,
iOS RealityKit, and Web:

JavaScript bundles and enforced size budgets (Web)

Every web bundle targets es2020, strips full license blocks
(--legal-comments=none), and emits a single four-line SPDX header:

Safe execution for live, AI-generated Three.js

Because LLMs already know Three.js, an agent or backend can generate a complete
interactive 3D or XR scene in 15 to 30 lines of JavaScript without external
binary assets. Three-Live executes Three.js scripts inside a sandboxed Rust
Boa/QuickJS VM on Android and iOS, and inside a dedicated Web Worker or
opaque-origin <iframe sandbox="allow-scripts"> (connect-src 'none') on the
web—with network and storage globals removed, Object.prototype frozen, CPU
instruction fuel limits, and scene geometry memory quotas.

Project status

Three-Live is in Beta. Its core 3D, mobile AR/XR, and spatial computing
runtime, versioned userData.xr trait schema (schemaVersion: 1), sandboxed
JIT compiler, and three-target parity across Android XR, Apple RealityKit, and
Web are feature-complete and ready for integration and evaluation.

• Prebuilt distributions: The Android release AAR
  (three-live-compiler-release.aar), the Apple XCFramework
  (ThreeLiveCompiler.xcframework.zip), native three-live-cli binaries for
  macOS, Linux, and Windows, and standalone web JavaScript bundles
  (three-live-web-dist.zip) are published on
  GitHub Releases.
• Package registries: Published on JitPack / GitHub Packages Maven,
  Swift Package Manager,
  Crates.io (three-live-compiler),
  npm (three-live),
  npm (xr-live), GitHub
  Releases, and the jsDelivr / GitHub Pages CDNs (see
  Install packages and bundles).
• Release notes: See CHANGELOG.md for release history
  and architectural notes.

Documentation guide

The following guides cover the native mobile SDKs, spatial plugins, web
components, and LLM authoring workflows:

Build and run demos

Run make (or make help) from the repository root to build packages, run tests, or open the interactive studio demos:

$ make doctor        # Check installed toolchains (Android NDK, Xcode, Rust, Node)
$ make android-demo  # Build JNI .so slices and debug Compose APK, and open Android Studio
$ make ios-demo      # Build XCFramework, generate .xcodeproj, and open in Xcode (macOS)
$ make test          # Run full Android, iOS, Rust compiler, and Web parity test suites
$ make web           # Compile all <three-live> and <xr-live> JS bundles and embedded engine
$ make web-demo      # Launch web playgrounds at http://localhost:8888/three/ and /xr/

Security

Untrusted client Three.js script execution is disabled by default on the web (allow-client-scripts required) and always runs inside an isolated QuickJS/Boa VM on Android and iOS or a sandboxed Worker / opaque-origin <iframe> (connect-src 'none') on Web—with network and storage globals stripped, Object.prototype frozen, CPU instruction fuel limits, and geometry memory quotas.

To report a vulnerability, please follow the instructions in SECURITY.md.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting a pull request.

License

Licensed under the Apache License, Version 2.0.