Skip to content
Back to search

three-live

SkillOfficial: GoogleGitHub

AI-first Native 3D, CAD & spatial computing. Runtime and JIT compiler for Android (Filament & Jetpack XR), iOS/visionOS (RealityKit), and WebGL2/WebXR.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/google/three-live with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/google/three-live'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/google--three-live/badge.svg)](/listings/google--three-live)

HTML

<a href="/listings/google--three-live"><img src="/api/listings/google--three-live/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

```kotlin dependencies { implementation("com.github.google.three-live:compiler:v1.3.1") // 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.1")` (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](https://github.com/google/three-live/releases)** into `app/libs/` and add `implementation(files("libs/three-live-compiler-release.aar"))`. * **Maven Local (`com.google.threelive:compiler:1.3.1`):** Run `./gradlew :mobile:android:publishReleasePublicationToMavenLocal` and add `implementation("com.google.threelive:compiler:1.3.1")`. * **From source:** Run `make android` (or `bash scripts/build_android_aar.sh`). * **2. iOS, macOS, and visionOS (Swift Package Manager):**

```swift .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):**

```bash 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](https://github.com/google/three-live/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:**

```bash 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](https://github.com/google/three-live/releases)**. * **From source:** Run `git clone https://github.com/google/three-live.git && cd three-live && npm install && npm run build`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 732 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!--
  2. Copyright 2026 Google LLC
  3. Licensed under the Apache License, Version 2.0 (the "License");
  4. you may not use this file except in compliance with the License.
  5. You may obtain a copy of the License at
  6. http://www.apache.org/licenses/LICENSE-2.0
  7. Unless required by applicable law or agreed to in writing, software
  8. distributed under the License is distributed on an "AS IS" BASIS,
  9. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  10. See the License for the specific language governing permissions and
  11. limitations under the License.
  12. -->
  13. > **Disclaimer:** This is not an officially supported Google product.
  14. <div align="center">
  15. # Three-Live
  16. **AI-First Native 3D, CAD & Spatial Computing:** On-device JIT compiler turning live, AI-generated **Three.js** into native **Android (Google Filament & Jetpack XR)**, **iOS & visionOS (Apple RealityKit)**, and **WebXR**.
  17. [![CI](https://github.com/google/three-live/actions/workflows/ci.yml/badge.svg)](https://github.com/google/three-live/actions/workflows/ci.yml)
  18. [![Release](https://img.shields.io/github/v/release/google/three-live?include_prereleases&label=Release)](https://github.com/google/three-live/releases)
  19. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
  20. **[🧭 Why Three-Live?](docs/why-three-live.md)** •
  21. **[⚡ Quickstarts (Android • iOS • CLI • Web)](#quickstarts)** •
  22. **[📦 Install (JitPack • SwiftPM • Cargo • npm)](#install-packages-and-bundles)** •
  23. **[▶ Live 3D Studio](https://google.github.io/three-live/three/)** •
  24. **[🧩 Domain Kits Catalog](https://google.github.io/three-live/kits/)** •
  25. **[🥽 Live Spatial XR Studio](https://google.github.io/three-live/xr/)** •
  26. **[📚 Docs](#documentation-guide)**
  27. </div>
  28. **iOS & visionOS · RealityKit** | **Android XR · Google Filament**
  29. :-----------------------------: | :------------------------------:
  30. ![iOS RealityKit Demo][ios-gif] | ![Android XR Demo][android-gif]
  31. [ios-gif]: examples/assets/slide-product-ios.gif
  32. [android-gif]: examples/assets/slide-xr-android.gif
  33. LLMs and developers excel at writing concise **Three.js** code—not hundreds of
  34. lines of platform-specific native 3D, shader, and AR boilerplate. **Three-Live**
  35. compiles standard Three.js (`THREE.Mesh`, `THREE.CSG`, `userData.xr`,
  36. `KHR_interactivity`) on-device in a sandboxed Rust VM and renders natively in
  37. **Google Filament and Jetpack XR SceneCore on Android**, **Apple RealityKit and
  38. Quick Look on iOS and visionOS**, **headless 4-up PNG contact sheets
  39. (`three-live-cli`)** for AI coding agents, and **WebGL2 / WebXR** on the Web.
  40. --------------------------------------------------------------------------------
  41. ## Quickstarts
  42. ### 1. Run Three.js natively on Android (Google Filament & Jetpack XR SceneCore)
  43. Compile standard Three.js code over zero-copy JNI and drive native **Google
  44. Filament** rendering, **60 Hz physics**, and **Jetpack XR SceneCore** spatial
  45. entities:
  46. ```kotlin
  47. import com.google.threelive.FilamentHelper
  48. import com.google.threelive.XRLiveRuntimeSession
  49. import com.google.threelive.XRLiveSceneCoreHelper
  50. val threeJsCode = """
  51. const core = new THREE.Mesh(
  52. new THREE.IcosahedronGeometry(0.55, 3),
  53. new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.85, roughness: 0.15 })
  54. );
  55. core.userData.xr = { grab: '2-hand', orbit: { speed: -0.4 } };
  56. scene.add(core);
  57. """.trimIndent()
  58. // Compile Three.js to a zero-copy GLB ByteBuffer and load directly into Google Filament
  59. val holder = FilamentHelper.loadModelZeroCopy(threeJsCode) { buffer ->
  60. assetLoader.createAssetFromBinary(buffer)
  61. }
  62. // Step live KHR_interactivity graphs, 60 Hz rigid-body physics, and spatial traits per frame
  63. val runtime = XRLiveRuntimeSession.fromGlb(holder.byteBuffer)
  64. runtime.step(dtSeconds = 1.0 / 60.0)
  65. // Or attach interactive spatial traits (grab, scale, billboard, anchor) in Android XR SceneCore
  66. XRLiveSceneCoreHelper.attachTraitsFromGlb(xrSession, entity, holder.byteBuffer)
  67. ```
  68. ### 2. Run Three.js natively on iOS, macOS, and visionOS (Apple RealityKit)
  69. Compile the exact same Three.js code into **Apple RealityKit** (`ARView` /
  70. `RealityView`) or `.usdz`:
  71. ```swift
  72. import ThreeLiveCompiler
  73. import RealityKit
  74. @MainActor
  75. func loadSpatialScene(from threeJsCode: String, into arView: ARView) async throws -> XRLiveRealityKitSession? {
  76. let glb = try ThreeCompiler.compileToGLB(script: threeJsCode)
  77. let entity = try await RealityKitHelper.loadEntity(fromGLB: glb)
  78. XRLiveRealityKit.installTraits(on: entity, in: arView)
  79. // Bind live KHR_interactivity, 60 Hz physics, and spatial traits to RealityKit SceneEvents.Update
  80. let session = XRLiveRealityKitSession(glbData: glb, root: entity)
  81. session?.installInputTargets()
  82. session?.start()
  83. return session
  84. }
  85. ```
  86. ### 3. Verify & compile Three.js headlessly for AI agents (`three-live-cli` & MCP server)
  87. Render a 4-up orthographic/camera contact sheet (zero GPU required), run the
  88. spatial linter for JSON frustum/overlap telemetry, compile `scene.js` to `.glb`
  89. / `.usdz`, generate a scene from a reference image (`from-image`), or attach
  90. `three-live-cli mcp` as a zero-dependency **Model Context Protocol (MCP)** stdio
  91. server (`three_live_validate`, `three_live_render`, `three_live_convert`,
  92. `three_live_from_image`, `three_live_bake_textures`, `three_live_sim`,
  93. `three_live_link`, and the `three_live_gym_reset` / `three_live_gym_step` /
  94. `three_live_gym_close` agent gym) in Gemini CLI, Google Antigravity, Claude
  95. Code, or any MCP client. The agent gym lets an agent play a scene step by step
  96. (act, observe, react) to check a level is winnable; "gym" is the
  97. reinforcement-learning term for such a reset/step environment, and no ML is
  98. involved. Not using MCP? `three-live-cli gym reset level.js --session ep.json`
  99. and `three-live-cli gym step --session ep.json --actions '[...]'` do the same,
  100. one command per step. `three-live-cli link scene.js --qr` prints a playground
  101. link (and a terminal QR code) that opens the scene on a phone, one tap from AR.
  102. Building from a photo, mockup, sketch, or blueprint? Pass `--reference` (or
  103. `reference` in MCP) to get a side-by-side + aligned-overlay + silhouette-diff
  104. sheet with IoU and proportion guidance, or run `from-image` to synthesize and
  105. verify a procedural Three.js scene directly from an image:
  106. ```bash
  107. $ npx three-live-cli render scene.js --view=quad --grid --annotations -o contact_sheet.png
  108. $ npx three-live-cli render scene.js --reference=blueprint.png --view=front -o compare.png
  109. $ npx three-live-cli from-image photo.jpg -o scene.js --visual-turns 2 --render compare.png
  110. $ npx three-live-cli validate scene.js --json
  111. $ npx three-live-cli link scene.js --qr
  112. $ npx three-live-cli convert scene.js -o model.usdz
  113. $ npx three-live-cli textures bake scene.js -o scene.textures.json # AI textures (needs THREE_LIVE_AI_IMAGE_ENDPOINT)
  114. $ npx three-live-cli convert scene.js --texture-pack scene.textures.json -o model.glb
  115. # Or register the built-in MCP server for closed-loop visual + spatial AI verification:
  116. $ claude mcp add three-live -- npx -y -p three-live three-live-cli mcp
  117. ```
  118. ### 4. Run on the Web (`<three-live>` and `<xr-live>`)
  119. On the web, `<three-live>` (`< 35 KB gz` viewer, `< 86 KB gz` with the live
  120. Three.js compiler) and `<xr-live>` (`< 98 KB gz`) render the same Three.js
  121. scenes in WebGL2 and 6DoF WebXR with 1-tap mobile AR handoff:
  122. ```js
  123. // Standard Three.js scene (runs identically in Android, iOS, CLI, and Web)
  124. const mesh = new THREE.Mesh(
  125. new THREE.TorusKnotGeometry(0.4, 0.14, 64, 16),
  126. new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.8, roughness: 0.15 })
  127. );
  128. mesh.userData.xr = { grab: '1-hand', billboard: 'capsule' };
  129. scene.add(mesh);
  130. ```
  131. Add `three-live-ai.min.js` (`< 35 KB gz`; built into the full bundles) to let
  132. users reshape a scene with **any LLM**: every edit is compiled in the sandbox
  133. first, auto-repaired once on failure, and only then hot-swapped, so a bad
  134. generation never breaks the live scene.
  135. ```html
  136. <three-live capabilities="scripts ai network:https@https://your-backend.example"
  137. ai-endpoint="https://your-backend.example/chat" ai-model="gemini-2.5-flash">
  138. <script type="text/three">/* your scene */</script>
  139. </three-live>
  140. <script type="module">
  141. const el = document.querySelector('three-live');
  142. const result = await el.editScene('make the roof red and add a chimney');
  143. if (!result.applied) console.warn(result.error); // live scene unchanged
  144. // el.undoEdit() reverts; el.aiProvider = { complete: async ({messages}) => '...' } plugs in any model.
  145. </script>
  146. ```
  147. `ai-endpoint` speaks the widely supported Chat Completions protocol
  148. (`ai-provider="ai-chat"`): your own backend proxy, Ollama or LM Studio
  149. (`http://localhost:...`, no account needed), vLLM, OpenRouter, or Gemini's
  150. compatibility endpoint. Keep API keys on your server; never put them in pages.
  151. **Tap & Speak:** let users tap a mesh and say what to change. The voice model
  152. talks, and your code model writes the edit through an `edit_scene` tool, so edit
  153. quality never depends on the voice model.
  154. ```html
  155. <three-live capabilities="scripts ai microphone network"
  156. ai-endpoint="https://your-backend.example/chat"
  157. ai-select-on-tap ai-voice-button
  158. ai-voice-url="wss://your-backend.example/realtime">
  159. <script type="text/three">/* your scene */</script>
  160. </three-live>
  161. ```
  162. * `ai-select-on-tap`: tapping a mesh sets `selected-mesh` (tap again to
  163. clear), so "make this red" knows what "this" is.
  164. * `ai-voice-button`: a mic button. With `ai-voice-url` it toggles a realtime
  165. voice conversation (`ai-voice-provider="ai-realtime"`, the default, for any
  166. server speaking the Realtime WebSocket protocol, or `"gemini-live"`).
  167. Without it, it runs push-to-talk with the browser's speech recognizer
  168. (`el.startVoiceEdit()`).
  169. * From code: `await el.connectVoice({provider: 'gemini-live', url})` or
  170. `await el.startVoiceEdit()`. Progress arrives as `three-live-voice` events
  171. (`listening`, `editing`, transcripts, results).
  172. **Talk-to-Select:** users can select by voice instead of tapping, so they can
  173. check that the right objects are highlighted before an edit.
  174. * Say "select the two red chairs on the left", "also select the lamp",
  175. "deselect the small one", or "clear the selection". References are
  176. resolved locally with no model call: names (with synonyms and plurals),
  177. material colors, left / right / front / back from the current camera, top /
  178. bottom, size, ordinals ("the second mug"), counts ("both"), "all … except
  179. …", and lists ("the lamp and the sofa").
  180. * "Select the lamp and make it blue" selects first, then edits right away
  181. when the reference was unambiguous. When it isn't, it asks ("Which one:
  182. Chair Left or Chair Right?") and changes nothing.
  183. * References the local matcher can't resolve ("the cup next to the sofa",
  184. other languages) go to your code model, which picks from a compact scene
  185. index or asks a question.
  186. * Shift / Ctrl / Cmd-tap or a long press adds to the selection.
  187. `el.selectedMeshes` holds it; `three-live-select` events report it.
  188. * Push-to-talk shows confirmation chips: each selected mesh with ×, buttons
  189. for the candidates of a question, and Apply for an edit that is waiting on
  190. a model-resolved selection. Set `ai-select-chips="off"` to hide them.
  191. Realtime voice sessions read the selection back instead, using the
  192. `select_meshes` tool.
  193. * From code: `await el.selectByVoice('the red chairs', {mode: 'add'})`.
  194. **Image to Scene (`compileFromImage`):** turn a photo, sketch, or blueprint into
  195. a live procedural Three.js scene across Web
  196. (`await el.compileFromImage(image, {prompt, priors, visualTurns: 2})`), Android
  197. (`editor.compileFromImage(bitmap, prompt, priors)`), iOS
  198. (`await editor.compileFromImage(imageData: ...)`), CLI
  199. (`three-live-cli from-image --visual-turns 2`), and MCP (`three_live_from_image`
  200. with `visualTurns`). Images are automatically downscaled and JPEG-normalized,
  201. compiled in the sandbox, verified against spatial quality gates (minimum 2
  202. meshes, finite bounds, non-empty frustum coverage, and zero critical overlap
  203. errors) with one-turn auto-repair, optionally refined closed-loop against
  204. rendered `REFERENCE | RENDER | OVERLAY 50/50` (+ 4-up orthographic/iso) sheets
  205. (`visualTurns`: `0..5`), and hot-swapped into the scene (`el.undoEdit()`
  206. reverts). Optional metric spatial priors (`userHeight`, `floorNormal`, and 3D
  207. detected object bounding boxes from ARCore / ARKit / `world-understanding`, or a
  208. whole RoomPlan scan on iOS via `AISpatialPriors.fromCapturedRoom(room)`, or any
  209. room scan via `AISpatialPriors.fromRoomScan` on Android) anchor real-world scale
  210. and placement.
  211. **AI textures (`userData.xr.material.prompt`):** add a texture prompt next to a
  212. material preset. The preset is the offline fallback, so the scene always renders
  213. the same way without a network:
  214. ```html
  215. <three-live capabilities="scripts remote_content ai network" texture-pack="scene.textures.json"
  216. ai-image-endpoint="https://your-backend.example/v1/images/generations">
  217. <script type="text/three">
  218. const wall = new THREE.Mesh(new THREE.BoxGeometry(4, 2.5, 0.2),
  219. new THREE.MeshStandardMaterial());
  220. wall.name = 'TempleWall';
  221. wall.userData.xr = {material: {preset: 'brick',
  222. prompt: 'weathered Kyoto temple stone with moss', size: 512}};
  223. scene.add(wall);
  224. </script>
  225. </three-live>
  226. ```
  227. * The compiler never calls an image model. Textures come from a **texture
  228. pack** (`texture-pack="…json"`, `el.texturePack = json`, or an inline
  229. `<script type="application/three-live-texture-pack">`), keyed by the prompt,
  230. size (256, 512, or 1024), and seed. Normal and roughness maps (up to 512)
  231. are derived on-device.
  232. * With an OpenAI-compatible Images endpoint configured (`ai-image-endpoint` /
  233. `ai-image-model`, or `el.aiImageProvider`), missing textures are generated,
  234. cached in IndexedDB, and hot-swapped in. Set `ai-textures="manual"` to
  235. generate only when you call `await el.generateTextures()`.
  236. * Runtime generation gives each visitor different textures. For consistent
  237. results, save `await el.exportTexturePack()` and ship it with the scene.
  238. Exported `.glb` / `.usdz` files already contain the final textures; GLB
  239. nodes showing an AI texture carry its pack key in
  240. `extras.xr.material.textureKey`.
  241. * Android (`ThreeLiveAITextures`), iOS (`AITextures`), the CLI
  242. (`three-live-cli textures bake`), and MCP (`three_live_bake_textures`) use
  243. the same packs and give the same pixels. On Android and iOS, auto generation
  244. works like the Web once a provider is set (`sceneLoaded`, or
  245. `editor.textures`).
  246. --------------------------------------------------------------------------------
  247. ## Install packages and bundles
  248. ### Package installation
  249. * **1. Android (JitPack, GitHub Packages Maven, prebuilt release AAR, or
  250. source):**
  251. * **JitPack (`https://jitpack.io`, no authentication required):** Add
  252. `maven("https://jitpack.io")` to `settings.gradle.kts`, then add:
  253. ```kotlin
  254. dependencies {
  255. implementation("com.github.google.three-live:compiler:v1.4.0")
  256. // Host-JS-engine apps (zero bundled Boa): use :runtime + :kernels instead of :compiler
  257. // Optional adapters: :filament, :firebase-ai, :detect-mlkit, :hands-androidxr, :hands-mediapipe
  258. }
  259. ```
  260. * **GitHub Packages Maven
  261. (`https://maven.pkg.github.com/google/three-live`):** Configure the
  262. repository in `settings.gradle.kts` and add
  263. `implementation("com.google.threelive:compiler:1.4.0")` (plus optional
  264. `:filament`, `:firebase-ai`, `:detect-mlkit`, `:hands-androidxr`,
  265. `:hands-mediapipe`).
  266. * **Prebuilt AAR:** Download `three-live-compiler-release.aar` (includes
  267. `arm64-v8a`, `armeabi-v7a`, and `x86_64` JNI `.so` libraries) and
  268. optional adapter AARs (`three-live-filament-release.aar`, etc.) from
  269. **[GitHub Releases](https://github.com/google/three-live/releases)**
  270. into `app/libs/` and add
  271. `implementation(files("libs/three-live-compiler-release.aar"))`.
  272. * **Maven Local (`com.google.threelive:compiler:1.4.0`):** Run
  273. `./gradlew :mobile:android:publishReleasePublicationToMavenLocal` and
  274. add `implementation("com.google.threelive:compiler:1.4.0")`.
  275. * **From source:** Run `make android` (or
  276. `bash scripts/build_android_aar.sh`).
  277. * **2. iOS, macOS, and visionOS (Swift Package Manager):**
  278. ```swift
  279. .package(url: "https://github.com/google/three-live.git", from: "1.0.0")
  280. ```
  281. Swift Package Manager automatically resolves the prebuilt, checksum-pinned
  282. `ThreeLiveCompiler.xcframework.zip` archive from GitHub Releases—no local
  283. Rust or Node.js toolchain is required.
  284. * **3. Rust CLI (`three-live-cli`) and library crate (`Crates.io`, prebuilt
  285. binaries, or source):**
  286. * **Crates.io (library & CLI):**
  287. ```bash
  288. cargo add three-live-compiler
  289. # Or install the standalone CLI binary from Crates.io:
  290. cargo install three-live-compiler --bin three-live-cli
  291. ```
  292. * **Prebuilt binaries:** Download standalone binaries for macOS (`arm64`
  293. and `x86_64`), Linux (`x86_64` and `aarch64`), and Windows
  294. (`x86_64.exe`) from
  295. **[GitHub Releases](https://github.com/google/three-live/releases)**.
  296. * **From source:** Run `make rust` (`npm run build && cargo build
  297. --manifest-path compiler/Cargo.toml --release --bin three-live-cli`).
  298. * **4. Web (npm, CDN, prebuilt release, or source):**
  299. * **npm:**
  300. ```bash
  301. npm install three-live xr-live
  302. ```
  303. * **Hosted ES module (`jsDelivr` or GitHub Pages CDN):** Load
  304. `https://cdn.jsdelivr.net/npm/three-live/dist/three-live.min.js` or
  305. `https://google.github.io/three-live/dist/three-live.min.js`.
  306. * **Prebuilt bundle archive:** Download `three-live-web-dist.zip` from
  307. **[GitHub Releases](https://github.com/google/three-live/releases)**.
  308. * **From source:** Run `git clone https://github.com/google/three-live.git
  309. && cd three-live && npm install && npm run build`.
  310. ---
  311. ## Why Three-Live and XR-Live
  312. ### Native mobile and headset AR/XR from Three.js
  313. In practice, browser WebXR (`navigator.xr`) only covers part of the device
  314. landscape:
  315. * **Android System `WebView`, iOS Safari, and iOS `WKWebView` don't support
  316. WebXR.** A WebXR-only app can't run inside an embedded `WebView` or
  317. `WKWebView` in a native Android or iOS app, and can't enter AR in Safari on
  318. iPhone or iPad.
  319. * **Static OS handoffs (`Scene Viewer` and `AR Quick Look`) strip
  320. interactivity.** Exporting a static `.glb` or `.usdz` file to the OS
  321. previewer works for viewing a model, but drops Three.js `animate()` loops,
  322. 60 Hz physics, custom state, and interactive plugins.
  323. * **Browser WebXR doesn't use native spatial compositors.** On Android,
  324. browser WebXR renders WebGL2 in the browser process rather than using Google
  325. Filament or Jetpack XR SceneCore's `HomeSpace` shared space. On visionOS,
  326. browser WebXR runs in an isolated fullscreen VR session without camera
  327. passthrough or SwiftUI Shared Space integration.
  328. Three-Live solves this by compiling the same Three.js code on-device and running
  329. it natively on each platform's own engine:
  330. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  331. | Target environment | What happens with browser WebXR or static AR handoff | What you can do with Three-Live and XR-Live |
  332. | :--- | :--- | :--- |
  333. | **Android phones and tablets (native Compose or View app)** | `android.webkit.WebView` has no WebXR; `Scene Viewer` only shows static `.glb` files | Compile Three.js over JNI and render natively in **Google Filament and ARCore** (`XRLiveRuntimeSession`) inside your app UI. |
  334. | **Android XR and Apple Vision Pro headsets** | Browser WebXR is isolated in a fullscreen WebGL session | Attach native **Jetpack XR SceneCore** (`GltfEntity`, `MovableComponent`, `Anchor`) or **RealityKit** entities that live in the system shared space alongside native panels. |
  335. | **iPhone and iPad (native SwiftUI app)** | `WKWebView` has no WebXR; `AR Quick Look` only shows static `.usdz` files | Run live Three.js scenes, `animate()` loops, `KHR_interactivity`, and spatial plugins natively in **ARKit and RealityKit** (`ARView` and `RealityView`). |
  336. | **Mobile and headset web browsers** | Standard WebXR works on Android Chrome and headsets; iOS Safari has no WebXR | Run 6DoF WebXR where supported, with automatic Stereo SBS, gyroscope, and in-memory `.usdz` and `.glb` AR handoff on iOS Safari. |
  337. <!-- mdformat on -->
  338. ### Compare `<three-live>` and `<xr-live>`
  339. The following table compares the two runtime tiers across Android, iOS, and Web:
  340. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  341. | Capability | `three-live` (Core 3D, CAD & Animation) | `xr-live` (Spatial Computing & Simulation) |
  342. | :---------------------- | :---------------------- | :----------------------- |
  343. | **Primary use case** | 3D product viewers, parametric CAD/CSG, skeletal animation, and 1-tap AR handoff | Interactive 6DoF XR, native mobile AR/XR, spatial UI cards, depth physics, hand tracking, and 60 Hz simulations |
  344. | **Three.js JIT compiler** | Yes (sandboxed Rust `Boa`/QuickJS VM on Android/iOS/CLI, Web Worker on Web) | Yes (inherits `three-author` JIT compiler plus `userData.xr` spatial traits) |
  345. | **Android & iOS runtime** | Google Filament (`FilamentHelper`), Apple RealityKit (`RealityKitHelper`), and `.glb`/`.usdz` export | Native Android (`Filament` + Jetpack XR `SceneCore` + `XRLiveRuntimeSession`) and native iOS/visionOS (`RealityKit` + `XRLiveRealityKitSession`) |
  346. | **Spatial interaction** | Orbit controls, mesh picking, 3D surface hotspots, `KHR_interactivity` | Declarative `userData.xr` traits (`grab`, `scale`, `billboard`, `anchor`, `handles`, `snapTo`, `gaze`, `explode`, `navigable`, `sync`, `audioEmitter`), 15 spatial plugins, 6 `xr-live-sim` simulation plugins, 25-joint hands, and `KHR_interactivity` |
  347. | **Web bundle budget** | **`< 35 KB gz`** (viewer), **`< 86 KB gz`** (`three-live.min.js`), **`< 242 KB gz`** (`three-live-full.min.js`) | **`< 62 KB gz`** (viewer), **`< 98 KB gz`** (`xr-live.min.js`), **`< 352 KB gz`** (`xr-live-full.min.js`) |
  348. <!-- mdformat on -->
  349. ### HTML attribute compatibility with `<model-viewer>`
  350. On the web, `<three-live>` supports the core HTML attributes used by
  351. [`<model-viewer>`](https://github.com/google/model-viewer) (`src`, `poster`,
  352. `camera-controls`, `camera-orbit`, `camera-target`, `min-camera-orbit`,
  353. `max-camera-orbit`, `field-of-view`, `auto-rotate`, `auto-rotate-delay`,
  354. `rotation-per-second`, `ar`, `ar-modes`, `ar-scale`, `ar-placement`, `exposure`,
  355. `shadow-intensity`, `shadow-softness`, `shadow-maps`, `tone-mapping`,
  356. `environment-image`, `skybox-image`, `autoplay`, `animation-name`,
  357. `variant-name`, and `slot="hotspot-*"`). It also accepts a CAD `section-plane`
  358. cut (`"y:2.8"`, `"-z:0.5"`, `"none"`) that clips the color and shadow passes on
  359. WebGL2 and WebGPU without requiring `<xr-live>`.
  360. If you have existing `<model-viewer>` HTML markup and want to add procedural
  361. Three.js scripts, native Android/iOS runtime targets, or CLI/MCP scene
  362. validation without renaming tags, call `ThreeLiveElement.defineModelViewer()`
  363. (or `defineModelViewer()`) to register `<three-live>` under the `<model-viewer>`
  364. custom element name when `@google/model-viewer` is not loaded.
  365. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  366. | Dimension | [`<model-viewer>`](https://github.com/google/model-viewer) | `<three-live>` / `<xr-live>` |
  367. | :--- | :--- | :--- |
  368. | **Primary focus** | Displaying pre-authored `.glb` and `.gltf` 3D assets on the web and launching mobile AR (`Scene Viewer`, `WebXR`, `Quick Look`). | Compiling and running procedural Three.js scripts, parametric CAD/CSG, and `.glb` / `.usdz` / `.spz` scenes across **Android, iOS/visionOS, and Web**. |
  369. | **Scene inputs** | Static `.glb` and `.gltf` files. | Static `.glb`, `.usdz`, and `.spz` files, plus inline or external `THREE.Scene` scripts (`type="text/three"` or `.js`) compiled in a worker/iframe sandbox or Rust VM. |
  370. | **Target platforms** | Web Custom Element (`<model-viewer>`). | Native **Android** SDK (`ThreeCompiler` JNI + Google Filament / Jetpack XR), native **iOS / visionOS** SDK (`ThreeCompiler` XCFramework + RealityKit), **Rust CLI / MCP server** (`three-live-cli`), and **Web** Custom Elements (`<three-live>`, `<xr-live>`). |
  371. | **Post-processing & effects** | Provided via the companion `@google/model-viewer-effects` package (`<effect-composer>`, `<bloom-effect>`, `<outline-effect>`). | Built-in HTML attributes (`bloom`, `bloom-threshold`, `bloom-radius`, `outline`, `outline-selected`, `outline-color`, `tone-mapping`, `shadow-maps`) with no external effect dependencies. |
  372. | **Interactivity & simulation** | Camera orbit/pan/zoom, animation playback, material variants, hotspots, and scene-graph material API. | Includes the above plus glTF `KHR_interactivity` behavior graphs, declarative `userData.xr` spatial traits (`grab`, `scale`, `anchor`, `snapTo`), and 60 Hz deterministic simulation plugins (`rigid-body`, `character-controller`, `navigation`, `objectives`). |
  373. | **Web bundle size (gzipped)** | Full Three.js renderer + glTF pipeline (~250 KB gz). | Modular tiers: `< 35 KB gz` (`three-live-viewer`), `< 86 KB gz` (`three-live`), `< 242 KB gz` (`three-live-full`), `< 352 KB gz` (`xr-live-full`). |
  374. <!-- mdformat on -->
  375. ### Modular plugins across Android, iOS, and Web
  376. Every capability works on both prebuilt `.glb`, `.usdz`, and `.spz` assets and
  377. live Three.js scenes:
  378. * **Compact core (`< 35 KB` to `< 98 KB gz` on Web):** The 3D viewer
  379. (`three-live-viewer.min.js`) is `< 35 KB gz` (`< 86 KB gz` with the live
  380. Three.js compiler in `three-live.min.js`), and the WebXR viewer
  381. (`xr-live-viewer.min.js`) is `< 62 KB gz` (`< 98 KB gz` with the live
  382. Three.js compiler in `xr-live.min.js`).
  383. * **Core 3D, CAD, procedural, animation, and WebGPU plugins (`three-live`, 20
  384. plugins):** Optional domain bundles (`three-live-studio.min.js` at
  385. `< 36 KB gz`, `three-live-cad.min.js` at `< 20 KB gz`,
  386. `three-live-procedural.min.js` at `< 30 KB gz`,
  387. `three-live-animation.min.js` at `< 11 KB gz`, `three-live-ai.min.js` at
  388. `< 35 KB gz`, `three-live-webgpu.min.js` at `< 23 KB gz`, and
  389. `three-live-tsl.min.js` at `< 19 KB gz`, or `< 242 KB gz` combined in
  390. `three-live-full.min.js`) add `KHR_interactivity` behavior graphs, PBR Next
  391. materials, `KHR_materials_variants`, `EXT_meshopt_compression`, HDRI and
  392. spherical-harmonics lighting, contact shadows, multi-light depth shadow maps
  393. (`shadow-maps` / `shadowMapsPlugin`), 3D hotspots, post-processing (`bloom`
  394. and `outline`), automatic multi-tier Level-of-Detail (`lod` / `THREE.LOD` /
  395. `MSFT_lod`), 2D `Shape`/`ExtrudeGeometry`, 3D `SweepGeometry`,
  396. `HelixGeometry`, multi-profile `LoftGeometry`, declarative
  397. `PatternInstancer` arrays, 3D `CSG` Booleans, 3D vector `TextGeometry`,
  398. 64-joint GPU skeletal skinning, morph targets, keyframe cross-fading,
  399. two-bone / FABRIK inverse kinematics (`ik`), loop-free `THREE.TSL`
  400. procedural node materials (`tslPlugin` / `extras.tsl`), LLM scene editing,
  401. and `GPURenderBundle` WebGPU scene acceleration
  402. (`renderer="auto | webgpu | webgl2"`). Five optional a la carte **domain
  403. kits**
  404. (`three-live-kit-{mechanical,architecture,industrial,science,electronics}.min.js`,
  405. `12–30 KB gz` each, or the all-in-one `three-live-kits.min.js`,
  406. `< 82 KB gz`, intentionally excluded from `three-live-full.min.js`) add 57
  407. watertight 2-manifold parametric parts across `THREE.Mechanical`,
  408. `THREE.Architecture`, `THREE.Industrial`, `THREE.Science`, and
  409. `THREE.Electronics` (see [`docs/kits-gallery.md`](docs/kits-gallery.md)).
  410. * **Hardware XR sensors (`xr-live-sensors.min.js`, `< 10 KB gz`):** Adds
  411. hardware XR depth occlusion (`XRDepthManager`), analytical heightfield
  412. physics (`XRHeightfieldPhysics`), 25-joint hand gesture classification
  413. (`XRHandGestureClassifier`), the desktop 6DoF keyboard/mouse simulator
  414. (`XRDesktopSimulator`), HRTF spatial audio earcons, and WebMCP agent tools.
  415. * **Spatial computing plugins (`xr-live-spatial.min.js`, 15 plugins,
  416. `< 65 KB gz`):** Each advanced spatial capability in
  417. `xr-live-spatial.min.js` is a standalone, zero-dependency plugin
  418. (`~2 to 5 KB gz` each) with a matching native implementation in the Android
  419. and iOS SDKs.
  420. * **Simulation and scenario plugins (`xr-live-sim.min.js`, 6 plugins,
  421. `< 30 KB gz`):** Six plugins for games, training drills, and safety
  422. walkthroughs add a controllable character, autonomous steering agents,
  423. deterministic 60 Hz rigid-body physics and mechanical joints (`rigid-body` /
  424. `joint`: `hinge`, `slider`, `spring`, `ball`), integrity and trigger zones,
  425. checklist objectives with scoring and timers, and procedural audio cues
  426. across Android, iOS, and Web.
  427. * **Opt-in WebGPU Gaussian Splatting accelerator (`xr-live-webgpu.min.js`,
  428. `< 13 KB gz`):** Offloads `.splat` / `.spz` depth sorting (deterministic
  429. 2-pass 8-bit tiled radix sort) and Degree 1–3 fp16 Spherical Harmonics to
  430. WGSL `@compute` shaders, rendering oriented anisotropic eigenvector quads
  431. via `drawIndirect` (`splat-renderer="auto | webgpu | hybrid | webgl2"`) and
  432. automatically switching to a double-buffered `mapAsync` WebGL2 coprocessor
  433. during WebXR stereo sessions or mixed glTF + splat Z-occluded scenes.
  434. #### Core 3D, CAD, TSL, and animation plugins (`three-live`)
  435. The following table lists the modular 3D, CAD, TSL, AI, WebGPU, and animation
  436. plugins:
  437. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  438. | Plugin | Attribute or Three.js API | What it adds |
  439. | :--- | :--- | :--- |
  440. | **`interactivity`** | `userData.interactivity`, `KHR_interactivity` | Compiles and executes glTF `KHR_interactivity` behavior graphs (`onSelect`, `onHoverIn`, `onStart`, `toggleTransform`, `interpolate`, `cycleMaterialColor`, and `sendEvent`) with step and tween budgets. |
  441. | **`materials`** | `MeshPhysicalMaterial`, `variant-name` | PBR Next material properties (`clearcoat`, `transmission`, `ior`, `thickness`, `attenuationColor`, `sheen`, `iridescence`, and `anisotropy`). |
  442. | **`variants`** | `variant-name`, `userData.variants` | `KHR_materials_variants` multi-colorway configurators and USDZ `VariantSet` export. |
  443. | **`meshopt`** | `EXT_meshopt_compression` | Zero-WASM decoder and encoder for `EXT_meshopt_compression` vertex, index, and animation buffers (`OCTAHEDRAL`, `QUATERNION`, `EXPONENTIAL`). |
  444. | **`envmap`** | `environment-image`, `skybox-image`, `exposure` | Procedural studio environment lighting, HDRI skyboxes, and 9-band spherical-harmonics diffuse irradiance. |
  445. | **`shadows`** | `shadow-intensity`, `shadow-softness` | Soft ground-plane contact shadows and dynamic shadow-map updates matching scene bounds. |
  446. | **`shadow-maps`** | `shadow-maps`, `light.castShadow`, `mesh.castShadow`, `mesh.receiveShadow` | Real-time multi-light depth shadow maps (up to 4 directional, spot, and point lights in a `DEPTH_COMPONENT24` / `depth24plus` 2D array with rotated Vogel-disk PCF, scale-invariant normal-offset bias, and static-orbit digest caching) across WebGL2, WebGPU, Android Filament, iOS/visionOS RealityKit, and `.usdz` (`UsdLuxShadowAPI`). |
  447. | **`hotspots`** | `slot="hotspot-*"`, `data-position`, `data-normal` | 3D surface-anchored annotations with normal-facing visibility culling and SVG leader lines. |
  448. | **`webxr`** | `ar`, `ar-modes`, `ar-scale`, `ar-placement` | Zero-server runtime `.glb` and `.usdz` packaging for 1-tap mobile AR handoff across Android Scene Viewer, iOS Quick Look, and WebXR. |
  449. | **`postprocessing`** | `bloom`, `outline`, `tone-mapping`, `xr.bloom`, `xr.outline` | Dual-Kawase mipmap bloom, selection/hover silhouette outlines, and `neutral`, `aces`, `agx`, `reinhard`, and `none` tone mapping. |
  450. | **`lod`** | `THREE.LOD`, `xr.lod`, `MSFT_lod` | Distance-based multi-tier Level-of-Detail switching with hysteresis, far-distance culling, automatic vertex-clustering mesh decimation (`decimateGeometry`), and `MSFT_lod` / `KHR_node_visibility` export. |
  451. | **`cad`** | `THREE.Shape`, `THREE.ExtrudeGeometry`, `THREE.SweepGeometry`, `THREE.HelixGeometry`, `THREE.LoftGeometry`, `THREE.PatternInstancer`, `THREE.CSG`, `THREE.TextGeometry` | 2D `Path`/`Shape` with ear-clipping hole triangulation, `ExtrudeGeometry` with beveling and `extrudePath`, twist-free Bishop-frame `SweepGeometry`, cylindrical/conical `HelixGeometry` (`HelixCurve3`), multi-profile `LoftGeometry` (axial & spline spine with hollow-vessel `wallThickness`), `PatternInstancer` linear/grid/circular/along-curve `InstancedMesh` arrays (`toGeometry` bakes them for `CSG`), 3D BSP `CSG` Booleans (`union`, `subtract`, `intersect`), and stroke-font `TextGeometry`. |
  452. | **`kit-mechanical`** | `THREE.Mechanical.*`, `SpurGearGeometry`, `BevelGearGeometry`, `BoltGeometry`, `PillowBlockGeometry`, `metricFastener` | A la carte domain kit (`three-live-kit-mechanical.min.js` / `three-live-kits.min.js`): 15 watertight 2-manifold parametric mechanical CAD parts (`SpurGearGeometry`, `BevelGearGeometry`, `InternalRingGearGeometry`, `RackGeometry`, `PulleyGeometry` (`v-belt`/`flat`/`timing`), ISO metric `BoltGeometry`, `NutGeometry`, `WasherGeometry`, `ShaftGeometry`, `ShaftCouplerGeometry`, `BearingGeometry`, `PillowBlockGeometry`, `HelicalSpringGeometry`, `FlangePlateGeometry`, `ProfileExtrusionGeometry`, `metricFastener('M8x25')`, `gearMeshDistance(g1, g2)`). |
  453. | **`kit-architecture`** | `THREE.Architecture.*`, `WallGeometry`, `SlabGeometry`, `StaircaseGeometry`, `DoorGeometry`, `WindowGeometry`, `codeStairSpec` | A la carte domain kit (`three-live-kit-architecture.min.js` / `three-live-kits.min.js`): 9 watertight 2-manifold building & AEC elements (`WallGeometry` with rectangular/semicircular/segmental/Gothic `openings`, `SlabGeometry` with stairwell/skylight openings, `StaircaseGeometry` in `straight`, `l-shape`, `u-shape`, and `spiral` modes, `RoofGeometry` in 6 roof styles, 10-style `DoorGeometry` across 5 operations, 10-style `WindowGeometry`, `RailingGeometry`, `ColumnGeometry`, `ArchwayGeometry`, `codeStairSpec`). |
  454. | **`kit-industrial`** | `THREE.Industrial.*`, `PipeRunGeometry`, `ValveGeometry`, `CentrifugalPumpGeometry`, `PalletRackGeometry`, `nominalPipeSpec` | A la carte domain kit (`three-live-kit-industrial.min.js` / `three-live-kits.min.js`): 10 watertight 2-manifold process plant, factory & warehouse assets (`PipeRunGeometry` with 3D Bishop-frame routing & weld-neck flanges, `PipeFittingGeometry`, `ValveGeometry`, `CentrifugalPumpGeometry`, `PalletRackGeometry`, `ConveyorGeometry`, `IndustrialLadderGeometry` with OSHA safety cage, `CatwalkPlatformGeometry`, `SafetyBarrierGeometry`, `StorageTankGeometry`, `nominalPipeSpec('DN100')`). |
  455. | **`kit-science`** | `THREE.Science.*`, `MoleculeGeometry`, `RibbonGeometry`, `CrystalLatticeGeometry`, `IsoSurfaceGeometry`, `StreamlineGeometry`, `DashedLineGeometry`, `AngleArcGeometry`, `sampleColormap`, `elementSpec`, `ribbonColorMap` | A la carte domain kit (`three-live-kit-science.min.js` / `three-live-kits.min.js`): 14 watertight 2-manifold chemistry, structural biology, physics, optics & math primitives (`MoleculeGeometry` with presets, covalent auto-bonding & CPK vertex colors, `RibbonGeometry` continuous polypeptide/biopolymer cartoon lofts across `'coil'`, `'helix'`, and arrow-tipped `'sheet'` spans + `ribbonColorMap`, `CrystalLatticeGeometry` for `sc`/`bcc`/`fcc`/`hcp`/`diamond`/`graphene`/`nacl`/`perovskite` + custom Bravais `vectors`/`basis`/`vacancies`/`millerPlanes`, `AtomicOrbitalGeometry`, `OpticalElementGeometry`, `SurfacePlotGeometry`, `ParametricSurfaceGeometry`, `VectorFieldGeometry`, `IsoSurfaceGeometry` Marching Tetrahedra scalar fields, `StreamlineGeometry` RK4 field curves, `Axes3DGeometry`, `DoubleHelixGeometry`, `DashedLineGeometry`, `AngleArcGeometry`, scientific colormaps `sampleColormap`/`colormapTexture`/`applyVertexColormap`, 44-element `elementSpec`). |
  456. | **`kit-electronics`** | `THREE.Electronics.*`, `PcbBoardGeometry`, `EnclosureGeometry`, `IcPackageGeometry`, `DiscreteComponentGeometry`, `jedecPackageSpec` | A la carte domain kit (`three-live-kit-electronics.min.js` / `three-live-kits.min.js`): 9 watertight 2-manifold ECAD & hardware parts (`PcbBoardGeometry`, `EnclosureGeometry` with bosses/vents/flanges/`panelCutouts`, `HeatsinkGeometry`, `DinRailGeometry`, `IcPackageGeometry` for `dip`/`soic`/`qfp`/`qfn`/`bga`/`to220`/`sot23`/`d2pak`, `PinHeaderGeometry`, `ConnectorGeometry`, `StandoffSpacerGeometry`, `DiscreteComponentGeometry`, `jedecPackageSpec`). |
  457. | **`procedural`** | `THREE.Box3`, `THREE.Sphere`, `THREE.CanvasTexture`, `THREE.ProceduralTexture`, `THREE.SimplexNoise`, `THREE.ImprovedNoise`, `THREE.Sprite`, `THREE.SplineCurve`, `THREE.GridHelper` | Extended 3D bounding-volume helpers (`Box3`, `Sphere`, `setFromObject`, `expandByObject`, `InstancedMesh` bounds), `CanvasTexture` with a zero-DOM headless 2D `<canvas>` rasterizer (`document.createElement('canvas').getContext('2d')`), deterministic `ImprovedNoise` and `SimplexNoise` heightmap/field generators, camera-facing `Sprite` / `SpriteMaterial` billboards, 2D curves (`LineCurve`, `QuadraticBezierCurve`, `CubicBezierCurve`, `SplineCurve`, `EllipseCurve`, `ArcCurve`, `CurvePath`), and exportable scene helpers (`GridHelper`, `AxesHelper`, `ArrowHelper`, `BoxHelper`, `Box3Helper`). |
  458. | **`skinning`** | `animation-name`, `autoplay` | 64-joint GPU vertex skinning and skeletal hierarchy evaluation. |
  459. | **`morph`** | `morphTargetInfluences` | GPU morph-target vertex displacement and weight blending. |
  460. | **`keyframes`** | `animationCrossfadeDuration` | Linear, step, and cubic-spline (`CUBICSPLINE`) TRS keyframe interpolation with smooth clip cross-fading. |
  461. | **`ik`** | `THREE.IKSolver`, `xr.ik` | Analytic two-bone (arm/leg with pole vector) and multi-joint FABRIK inverse kinematics chains. |
  462. | **`tsl`** | `THREE.TSL`, `THREE.MeshStandardNodeMaterial`, `el.setMaterialUniform()`, `extras.tsl` | Loop-free procedural node materials (`<= 128` SSA nodes, `<= 16` 60 Hz uniforms, 45 math/noise/Fresnel/triplanar/Voronoi/bump ops, `TL501`–`TL504` validator) compiled natively to WebGL2 GLSL ES 300, WebGPU WGSL `GPURenderBundle`s, Apple RealityKit USDZ `UsdShade` / MaterialX `NodeGraph`s, Android Filament (`filamat-android` + CPU fallback), and the Rust headless PBR rasterizer. |
  463. | **`ai`** | `el.editScene()`, `el.compileFromImage()`, `el.connectVoice()`, `xr.material.prompt` | Bring-your-own-LLM sandboxed scene editing, image-to-scene reconstruction with spatial priors, Tap & Speak / Talk-to-Select, and content-addressed AI PBR texture packs. |
  464. | **`webgpu`** | `renderer="auto\|webgpu\|webgl2"` | `GPURenderBundle` + storage-buffer WebGPU scene accelerator with `depth24plus` shadow maps, custom TSL WGSL pipelines, and 1×1-scissor GPU picking. |
  465. <!-- mdformat on -->
  466. #### Spatial perception, splat, audio, and multimodal AI plugins (`xr-live`)
  467. The following table lists the eight perception, rendering, audio, and AI plugins
  468. across Android Filament, iOS RealityKit, and WebXR:
  469. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  470. | Plugin | Attribute or `userData.xr` trait | What it adds across Android Filament, iOS RealityKit, and WebXR |
  471. | :--- | :--- | :--- |
  472. | **`head-follow`** | `xr.follow`, `xr.orbit` | Lazy HUD head or hand follow with an angular deadzone and critically damped spring, plus 3D satellite orbits. |
  473. | **`manipulation-handles`** | `xr.handles` | Four top-corner uniform scale handles and a bottom pedestal yaw-rotation bar that emit `xr-handles-change` events. |
  474. | **`world-understanding`** | `world-understanding="planes reticle"` | Real-world plane and mesh tracking, surface-normal gaze reticle, `XRTapeMeasure`, and 2D-to-3D bounding-box unprojection (`detectObjects`). |
  475. | **`gemini-live`** | `connectGeminiLive()`, `xr.holdToAsk` | Real-time bidirectional WebSocket vision and 16/24 kHz PCM voice streaming, barge-in cancellation, live transcription, and press-and-hold mesh queries. |
  476. | **`spatial-paint`** | `spatial-paint="#38bdf8"` | Pinch-to-paint 3D Catmull-Rom spline strokes extruded as twist-free parallel-transport tubes with `undo()` and `clear()`. |
  477. | **`depth-particles`** | `xr.particles` | GPU-friendly `rain`, `snow`, `sparks`, and `confetti` emitters (up to 2,000 particles per emitter) that collide with floors and real-world depth maps. |
  478. | **`splat-loader`** | `xr.splatUrl`, `allow-remote-splats` | Streams `.splat` and `.spz` (v2 and v3) 3D Gaussian Splats (up to 1,000,000 splats) with per-frame 16-bit counting sort. |
  479. | **`spatial-audio`** | `xr.audioEmitter`, `xr.audio`, `KHR_audio_emitter` | 3D positional and directional spatial audio emitters with 8 zero-asset ambient loop presets (`hum`, `reactor`, `wind`, `beacon`, `geiger`, `chimeLoop`, `machinery`, `water`), `inverse`/`linear`/`exponential` distance falloff, directional cones, and `KHR_audio_emitter` / USDZ `SpatialAudio` export. |
  480. <!-- mdformat on -->
  481. #### CAD review, spatial layout, locomotion, and co-presence plugins (`xr-live`)
  482. The following table lists the seven CAD, layout, locomotion, and multi-user
  483. plugins across Android Filament, iOS RealityKit, and WebXR:
  484. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  485. | Plugin | Attribute or `userData.xr` trait | What it adds across Android Filament, iOS RealityKit, and WebXR |
  486. | :--- | :--- | :--- |
  487. | **`spatial-measure`** | `spatial-measure="bounds\|tape\|all"`, `xr.dimensions` | Live `W × H × D` bounding-box dimension callout bars with 3D vector-glyph labels (`m`, `cm`, `mm`, `in`, and `ft-in`) and point-to-point AR tape measure. |
  488. | **`magnetic-snap`** | `magnetic-snap`, `xr.snapTo`, `xr.snapSocket` | Magnetic socket snapping with `1.25×` breakaway hysteresis and pulsing preview rings, plus Cartesian grid, yaw angle, and surface snapping. |
  489. | **`gaze-dwell`** | `gaze-dwell`, `xr.gaze` | Hands-free eye and head gaze raycasting with EMA smoothing, `1.5°` micro-saccade grace cone, and radial dwell progress ring (`select` or `ask`). |
  490. | **`exploded-view`** | `explode="0..1"`, `section-plane`, `xr.explode` | Multi-part CAD assembly explosion with staggered layers, dashed leader lines, two-hand spread gesture, and GPU cross-section slicer. |
  491. | **`persistent-anchors`** | `persistent-anchors`, `persist-url-hash`, `xr.anchor.persist` | Three-tier pose persistence across reloads and sessions via shareable `#xr-state=<base64url>` URLs, `localStorage`, and native anchors. |
  492. | **`spatial-locomotion`** | `locomotion="teleport snap-turn"`, `xr.navigable` | Ballistic parabolic teleport arc with walkable and blocked surface validation, thumbstick snap-turn or smooth glide, and a `120ms` FOV comfort vignette. |
  493. | **`shared-room`** | `shared-room="<id>\|wss://..."`, `xr.sync` | Zero-dependency multi-user co-presence (`20 Hz` quantized avatars and laser rays, optimistic grab locks with deterministic tie-breaking, and synced explode and paint). |
  494. <!-- mdformat on -->
  495. #### Interactive simulation, agent, and scenario plugins (`xr-live-sim`)
  496. The following table lists the six simulation plugins across Android Filament,
  497. iOS RealityKit, and Web:
  498. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  499. | Plugin | Attribute or `userData.xr` trait | What it adds across Android Filament, iOS RealityKit, and Web |
  500. | :--- | :--- | :--- |
  501. | **`character-controller`** | `character-controller`, `xr.character` | Capsule kinematics with floor and slope stepping, jump with coyote time, keyboard, gamepad, and touch-joystick input, and `third-person`, `first-person`, `top-down`, or `fixed-camera` rig follow. |
  502. | **`steering-agents`** | `steering-agents`, `xr.agent` | Autonomous kinematic agents (`patrol`, `chase`, `flee`, `follow`, and `wander`) with vision-cone target acquisition, obstacle avoidance, and `agentstatechange` and `agentreach` events. |
  503. | **`rigid-body`** | `xr.physics`, `xr.rigidBody`, `xr.joint` | Deterministic 60 Hz Sequential Impulse rigid-body solver (`dynamic`, `static`, `kinematic`; `box`, `sphere`, `cylinder`, `auto`; `mass`, `restitution`, `friction`, damping, sleeping, and `xrcollision` / `xrsleep` events), mechanical joint constraints (`hinge`, `slider`, `spring`, `ball` with limits, motors, and damped springs), and USDZ `PhysicsRigidBodyAPI` / `PhysicsMassAPI` / `Physics*Joint` export. |
  504. | **`hit-zones`** | `hit-zones`, `xr.integrity`, `xr.zone`, `xr.spawner` | Part and target `integrity` with world-space bars, hit flashes, `projectile`, `hitscan`, and `contact` interactions, burst fragments, colored trigger `zone` volumes, and timed template `spawner` pooling. |
  505. | **`objectives`** | `objectives`, `scenario-timer`, `target-score`, `attempts`, `xr.objective` | Ordered or unordered checklist objectives (`reach`, `clear`, `collect`, `activate`, and `hold`), score, attempt counter, countdown timer, HUD overlay (`sim-hud`), and `scenario-reset-key` resets. |
  506. | **`synth-audio`** | `synth-audio`, `synth-volume`, `xr.audioCues` | Zero-asset procedural audio synthesis (`beep`, `chime`, `buzz`, `thud`, `sweep`, `click`, `alarm`, and `whoosh`) bound to simulation events via Android `AudioTrack`, iOS `AVAudioEngine`, and Web Audio. |
  507. <!-- mdformat on -->
  508. ### JavaScript bundles and enforced size budgets (Web)
  509. Every web bundle targets `es2020`, strips full license blocks
  510. (`--legal-comments=none`), and emits a single four-line SPDX header:
  511. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  512. | Family | Bundle file | Enforced budget (`.min.js.gz`) | Included capabilities |
  513. | :--------------- | :-------------------------------- | :------------: | :-------------------------- |
  514. | **`three-live`** | **`three-live-viewer.min.js`** | **`< 35 KB gz`** | Lean `.glb` and `.usdz` WebGL2 PBR viewer, TRS animations, orbit controls, and AR packager. |
  515. | | **`three-live.min.js`** | **`< 86 KB gz`** | Standard `<three-live>` + **`three-author`** (live Three.js compiler, `InstancedMesh` GPU instancing, `KHR_interactivity` compiler, 5 tone-mapping modes, contact shadows) + AR packager. |
  516. | | **`three-live-studio.min.js`** | **`< 36 KB gz`** | Add-on plugin: PBR Next extensions, HDRI and SH irradiance, multi-light depth shadow maps (`shadow-maps` / `shadowMapsPlugin`), `bloom`/`outline` post-processing, `KHR_materials_variants`, `EXT_meshopt_compression`, `KHR_interactivity` VM, `lod` (`THREE.LOD` / `MSFT_lod`), 3D hotspots, and WebXR AR. |
  517. | | **`three-live-cad.min.js`** | **`< 20 KB gz`** | Add-on plugin: 2D `Path`/`Shape` with ear-clipping hole triangulation, `ExtrudeGeometry` with beveling and `extrudePath`, 3D Bishop-frame `SweepGeometry`, `HelixGeometry` (`HelixCurve3`), multi-profile `LoftGeometry`, `PatternInstancer` (`linear`, `grid`, `circular`, `alongCurve`, `toGeometry`), 3D `CSG` BSP Booleans (`union`, `subtract`, `intersect`), and 3D stroke-font `TextGeometry`. |
  518. | | **`three-live-kit-mechanical.min.js`** | **`< 18 KB gz`** | A la carte domain kit (`THREE.Mechanical`, NOT included in `three-live-full`): 15 watertight 2-manifold parametric mechanical machine parts (`SpurGearGeometry`, `BevelGearGeometry`, `InternalRingGearGeometry`, `RackGeometry`, `PulleyGeometry`, `BoltGeometry`, `NutGeometry`, `WasherGeometry`, `ShaftGeometry`, `ShaftCouplerGeometry`, `BearingGeometry`, `PillowBlockGeometry`, `HelicalSpringGeometry`, `FlangePlateGeometry`, `ProfileExtrusionGeometry`) plus `metricFastener` and `gearMeshDistance`. |
  519. | | **`three-live-kit-architecture.min.js`** | **`< 16 KB gz`** | A la carte domain kit (`THREE.Architecture`, NOT included in `three-live-full`): 9 watertight 2-manifold building & AEC parts (`WallGeometry`, `SlabGeometry`, `StaircaseGeometry`, `RoofGeometry`, `DoorGeometry`, `WindowGeometry`, `RailingGeometry`, `ColumnGeometry`, `ArchwayGeometry`) plus IBC `codeStairSpec`. |
  520. | | **`three-live-kit-industrial.min.js`** | **`< 14 KB gz`** | A la carte domain kit (`THREE.Industrial`, NOT included in `three-live-full`): 10 watertight 2-manifold process, factory & warehouse parts (`PipeRunGeometry`, `PipeFittingGeometry`, `ValveGeometry`, `CentrifugalPumpGeometry`, `PalletRackGeometry`, `ConveyorGeometry`, `IndustrialLadderGeometry`, `CatwalkPlatformGeometry`, `SafetyBarrierGeometry`, `StorageTankGeometry`) plus ASME `nominalPipeSpec`. |
  521. | | **`three-live-kit-science.min.js`** | **`< 31 KB gz`** | A la carte domain kit (`THREE.Science`, NOT included in `three-live-full`): 14 watertight 2-manifold chemistry, structural biology, physics, optics & math primitives (`MoleculeGeometry`, `RibbonGeometry`, `CrystalLatticeGeometry`, `AtomicOrbitalGeometry`, `OpticalElementGeometry`, `SurfacePlotGeometry`, `ParametricSurfaceGeometry`, `VectorFieldGeometry`, `IsoSurfaceGeometry`, `StreamlineGeometry`, `Axes3DGeometry`, `DoubleHelixGeometry`, `DashedLineGeometry`, `AngleArcGeometry`) plus `sampleColormap`, `colormapTexture`, `applyVertexColormap`, `ribbonColorMap`, and 44-element IUPAC `elementSpec`. |
  522. | | **`three-live-kit-electronics.min.js`** | **`< 14 KB gz`** | A la carte domain kit (`THREE.Electronics`, NOT included in `three-live-full`): 9 watertight 2-manifold ECAD & hardware parts (`PcbBoardGeometry`, `EnclosureGeometry`, `HeatsinkGeometry`, `DinRailGeometry`, `IcPackageGeometry`, `PinHeaderGeometry`, `ConnectorGeometry`, `StandoffSpacerGeometry`, `DiscreteComponentGeometry`) plus `jedecPackageSpec`. |
  523. | | **`three-live-kits.min.js`** | **`< 82 KB gz`** | All-in-one domain kits roll-up bundle registering all 5 domain kits (`mechanical`, `architecture`, `industrial`, `science`, `electronics`; 57 manifold geometries; a la carte, NOT included in `three-live-full`). |
  524. | | **`three-live-procedural.min.js`** | **`< 30 KB gz`** | Add-on plugin: `Box3` & `Sphere` bounding-volume helpers, `CanvasTexture` + headless 2D `<canvas>` rasterizer, `ImprovedNoise`, `SimplexNoise`, `MathUtils.seededRandom`, `ProceduralTexture` PBR material presets (`wood`, `marble`, `brick`, `rust`, …), `Sprite` billboards, 2D curves (`SplineCurve`, `EllipseCurve`, `CurvePath`), and exportable scene helpers (`GridHelper`, `AxesHelper`, `ArrowHelper`, `BoxHelper`, `Box3Helper`). |
  525. | | **`three-live-ai.min.js`** | **`< 35 KB gz`** | Opt-in bring-your-own-LLM scene editing & image-to-scene synthesis: `el.editScene(instruction)` and `el.compileFromImage(image, {prompt, priors})` with sandbox validation, spatial lint checks, one-turn auto-repair, hot-swap, and `el.undoEdit()`; `ai-chat` (Chat Completions-compatible) or custom providers. Tap & Speak and Talk-to-Select voice editing: tap/voice selection, push-to-talk, and `ai-realtime` / `gemini-live` voice sessions. AI textures (`userData.xr.material.prompt`) from texture packs or an OpenAI-compatible Images endpoint. Also included in the full bundles. |
  526. | | **`three-live-animation.min.js`** | **`< 11 KB gz`** | Add-on plugin: 64-joint GPU skeletal skinning, morph targets, animation cross-fading, and two-bone / FABRIK inverse kinematics (`ik` / `THREE.IKSolver`). |
  527. | | **`three-live-webgpu.min.js`** | **`< 23 KB gz`** | Opt-in WebGPU `GPURenderBundle` scene accelerator (`renderer="auto\|webgpu\|webgl2"`): compiles multi-thousand-part CAD and glTF assemblies into pre-recorded render bundles backed by storage buffers, with `depth24plus` 2D-array shadow depth passes + 16-tap Vogel-disk PCF, 1×1-scissor `pickMeshGPU`, Loop-Free TSL `GPURenderBundle` WGSL compilation, and automatic WebGL2 fallback for WebXR, `bloom`/`outline`, transmission, and custom shaders. |
  528. | | **`three-live-tsl.min.js`** | **`< 19 KB gz`** | Opt-in Loop-Free `THREE.TSL` & `MeshStandardNodeMaterial` shader graph compiler (`extras.tsl`): compiles bounded 45-op node materials across WebGL2 GLSL ES 300, WebGPU WGSL `GPURenderBundle`s, and `.usdz` `MaterialX` / `UsdShade` with 60 Hz `setMaterialUniform` updates and `TSL.time` animation. |
  529. | | **`three-live-full.min.js`** | **`< 242 KB gz`** | All-in-one 3D engine bundle (`three-live` + `studio` + `cad` + `procedural` + `animation` + `ai` + `webgpu` + `tsl`, all 20 engine plugins auto-registered; domain kits are loaded separately via `three-live-kits.min.js`). |
  530. | | **`three-live-compiler-bundle.min.js`** | **`< 260 KB gz`** | Self-contained headless host-JS compiler bundle (`ThreeEngine.{compileToGLB, compileToUSDZ, glbToUSDZ, aiCall, installSandboxHardening}` + optional `__three_live_host__` v1 native kernel acceleration) for apps embedding their own JS engine (`dist/engine-requirements.json`). |
  531. | **`xr-live`** | **`xr-live-viewer.min.js`** | **`< 62 KB gz`** | Lean `.glb` and `.usdz` WebXR viewer + spatial traits (`grab`, `scale`, `billboard`, `anchor`), `<div slot="spatial">`, and mobile AR bridge. |
  532. | | **`xr-live.min.js`** | **`< 98 KB gz`** | Standard `<xr-live>` + **`three-author`** (live Three.js compiler) + runtime USDZ and GLB compiler. |
  533. | | **`xr-live-sensors.min.js`** | **`< 10 KB gz`** | Add-on plugin: Hardware XR sensors (`XRDepthManager`, `XRHeightfieldPhysics`, 25-joint `XRHandGestureClassifier`), `XRDesktopSimulator`, Spatial Audio, Skybox, and WebMCP tools. |
  534. | | **`xr-live-spatial.min.js`** | **`< 65 KB gz`** | Add-on plugin bundle registering all 15 spatial plugins (`head-follow`, `manipulation-handles`, `world-understanding`, `gemini-live`, `spatial-paint`, `depth-particles`, `splat-loader`, `spatial-measure`, `magnetic-snap`, `gaze-dwell`, `exploded-view`, `persistent-anchors`, `spatial-locomotion`, `shared-room`, `spatial-audio`). |
  535. | | **`xr-live-sim.min.js`** | **`< 30 KB gz`** | Add-on simulation plugin bundle registering all six simulation plugins (`character-controller`, `steering-agents`, `rigid-body` + mechanical `joint` constraints, `hit-zones`, `objectives`, `synth-audio`). |
  536. | | **`xr-live-webgpu.min.js`** | **`< 13 KB gz`** | Opt-in WebGPU Gaussian Splatting compute and render accelerator (`splat-renderer="auto\|webgpu\|hybrid\|webgl2"`): WGSL 2-pass tiled radix sort, fp16 SH degrees 1–3, `drawIndirect` anisotropic quads, and WebXR / mixed-scene `mapAsync` coprocessor fallback. |
  537. | | **`xr-live-full.min.js`** | **`< 352 KB gz`** | All-in-one 3D, XR, simulation, TSL, and WebGPU bundle (`three-live-full` + `xr-live` + `xr-live-sensors` + all 15 spatial plugins + all 6 simulation plugins + `xr-live-webgpu`). |
  538. <!-- mdformat on -->
  539. ### Safe execution & capability-based security for live, AI-generated Three.js
  540. Because LLMs already know Three.js, an agent or backend can generate a complete
  541. interactive 3D or XR scene in 15 to 30 lines of JavaScript without external
  542. binary assets. Three-Live executes Three.js scripts inside a sandboxed Rust
  543. `Boa`/QuickJS VM on Android and iOS, and inside a dedicated Web Worker or
  544. opaque-origin `<iframe sandbox="allow-scripts">` (`connect-src 'none'`) on the
  545. web—with network and storage globals removed, `Object.prototype` frozen, CPU
  546. instruction fuel limits, and scene geometry memory quotas.
  547. In addition, **all sensitive host capabilities default to off**: embedders opt
  548. in explicitly via `capabilities="..."` on `<three-live>` / `<xr-live>` and
  549. `ThreeLiveCapabilities` on Android / iOS (`scripts`, `network`,
  550. `remote_content`, `camera`, `microphone`, `sensors`, `storage`, `ai`, and
  551. `external_handoff`, plus presets `viewer` and `all` and origin allowlists like
  552. `network:https,wss@https://cdn.example.com`). Author-controlled `userData.xr`
  553. traits cannot escalate host privileges, and `three-live-cli validate` statically
  554. checks HTML files for undeclared capabilities (`TL401` / `TL403`).
  555. ---
  556. ## Project status
  557. Three-Live is in **Beta**. Its core 3D, mobile AR/XR, and spatial computing
  558. runtime, versioned `userData.xr` trait schema (`schemaVersion: 1`), sandboxed
  559. JIT compiler, and three-target parity across Android XR, Apple RealityKit, and
  560. Web are feature-complete and ready for integration and evaluation.
  561. * **Prebuilt distributions:** The Android release AAR
  562. (`three-live-compiler-release.aar`), the Apple XCFramework
  563. (`ThreeLiveCompiler.xcframework.zip`), native `three-live-cli` binaries for
  564. macOS, Linux, and Windows, and standalone web JavaScript bundles
  565. (`three-live-web-dist.zip`) are published on
  566. **[GitHub Releases](https://github.com/google/three-live/releases)**.
  567. * **Package registries:** Published on **JitPack / GitHub Packages Maven**,
  568. **Swift Package Manager**,
  569. **[Crates.io (`three-live-compiler`)](https://crates.io/crates/three-live-compiler)**,
  570. **[npm (`three-live`)](https://www.npmjs.com/package/three-live)**,
  571. **[npm (`xr-live`)](https://www.npmjs.com/package/xr-live)**, **GitHub
  572. Releases**, and the **jsDelivr / GitHub Pages CDNs** (see
  573. [Install packages and bundles](#install-packages-and-bundles)).
  574. * **Release notes:** See [`CHANGELOG.md`](CHANGELOG.md) for release history
  575. and architectural notes.
  576. --------------------------------------------------------------------------------
  577. ## Documentation guide
  578. The following guides cover the native mobile SDKs, spatial plugins, web
  579. components, and LLM authoring workflows:
  580. <!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
  581. | Guide | Audience | Contents |
  582. | :--------------------------------------------- | :------- | :------- |
  583. | **[`docs/why-three-live.md`](docs/why-three-live.md)** | All developers & evaluators | Architectural rationale, technical capabilities specific to Three-Live, comparison across 3D/XR approaches, and trade-offs. |
  584. | **[`docs/xr-live.md`](docs/xr-live.md)** | Android, iOS, and XR developers | Complete spatial and native SDK guide: Android (`Filament` + Jetpack XR `SceneCore`), iOS/visionOS (`RealityKit`), canonical `userData.xr` traits, all 15 spatial plugins, the six `xr-live-sim` simulation plugins, depth and physics, 25-joint hands, and WebMCP. |
  585. | **[`docs/three-live.md`](docs/three-live.md)** | Mobile and web developers | Complete 3D reference: Three.js authoring, `KHR_interactivity`, PBR Next and HDRI, CAD/CSG/Text, animations, 3D hotspots, and sandboxing. |
  586. | **[`docs/kits-gallery.md`](docs/kits-gallery.md)** | All developers & designers | Visual thumbnail catalog of all 57 watertight parametric constructors across `THREE.Mechanical`, `THREE.Architecture`, `THREE.Industrial`, `THREE.Science`, and `THREE.Electronics` (plus [interactive 3D inspector](https://google.github.io/three-live/kits/)). |
  587. | **[`docs/cookbook.md`](docs/cookbook.md)** | All developers | Copy-pasteable Three.js recipes for e-commerce configurators, precision manipulation handles, Gemini Live spatial assistants, 3D spatial paint, CAD exploded views and measurements, magnetic snapping and persistent anchors, multi-user co-presence, and interactive training and simulation drills (`xr-live-sim`). |
  588. | **[`docs/llm-guide.md`](docs/llm-guide.md)** | LLMs and agents | Copy-paste system prompt snippet, canonical `userData.xr` and `userData.interactivity` schemas, strict `THREE.*` allowlist, scene quotas, and few-shot templates. |
  589. | **[`AGENTS.md`](AGENTS.md)** | Coding agents | Repository rules, three-target cross-platform parity contract, build and test commands, bundle budgets, and security invariants. |
  590. | **[`skills/`](skills/)** | Agent skills | Progressive-disclosure `SKILL.md` skills for authoring scenes ([`three-live-authoring`](skills/three-live-authoring/SKILL.md)) and developing plugins ([`xr-live-plugin-dev`](skills/xr-live-plugin-dev/SKILL.md)). |
  591. | **[`llms.txt`](llms.txt) and [`llms-full.txt`](llms-full.txt)** | LLM context feeds | Single-file concise index (`llms.txt`) and complete concatenated reference (`llms-full.txt`) for LLM context windows. |
  592. | **[`CHANGELOG.md`](CHANGELOG.md)** | All users | Release notes and architectural summary for Three-Live releases. |
  593. <!-- mdformat on -->
  594. ---
  595. ## Build and run demos
  596. Run `make` (or `make help`) from the repository root to build packages, run tests, or open the interactive studio demos:
  597. ```bash
  598. $ make doctor # Check installed toolchains (Android NDK, Xcode, Rust, Node)
  599. $ make android-demo # Build JNI .so slices and debug Compose APK, and open Android Studio
  600. $ make ios-demo # Build XCFramework, generate .xcodeproj, and open in Xcode (macOS)
  601. $ make test # Run full Android, iOS, Rust compiler, and Web parity test suites
  602. $ make web # Compile all <three-live> and <xr-live> JS bundles and embedded engine
  603. $ make web-demo # Launch web playgrounds at http://localhost:8888/three/ and /xr/
  604. ```
  605. ---
  606. ## Security
  607. Untrusted client Three.js script execution is disabled by default on the web
  608. (`allow-client-scripts` required) and always runs inside an isolated QuickJS/Boa
  609. VM on Android and iOS or a sandboxed Worker / opaque-origin `<iframe>`
  610. (`connect-src 'none'`) on Web—with network and storage globals stripped,
  611. `Object.prototype` frozen, CPU instruction fuel limits, and geometry memory
  612. quotas.
  613. To report a vulnerability, please follow the instructions in
  614. [`SECURITY.md`](SECURITY.md).
  615. ## Contributing
  616. Contributions are welcome! Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) and
  617. [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) before submitting a pull request.
  618. ## License
  619. Licensed under the [Apache License, Version 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.