⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

three-live-authoring

@google⭐ 375 stars

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 375 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Disclaimer: This is not an officially supported Google product.

Three-Live

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.

CI Release License

🧭 Why Three-Live? • ⚡ Quickstarts (Android • iOS • CLI • Web) • 📦 Install (JitPack • SwiftPM • Cargo • npm) • ▶ Live 3D Studio • 🧩 Domain Kits Catalog • 🥽 Live Spatial XR Studio • 📚 Docs

iOS & visionOS · RealityKitAndroid XR · Google Filament
iOS RealityKit DemoAndroid XR Demo

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 & MCP server)

Render a 4-up orthographic/camera contact sheet (zero GPU required), run the spatial linter for JSON frustum/overlap telemetry, compile scene.js to .glb / .usdz, generate a scene from a reference image (from-image), or attach three-live-cli mcp as a zero-dependency Model Context Protocol (MCP) stdio server (three_live_validate, three_live_render, three_live_convert, three_live_from_image, three_live_bake_textures, three_live_sim, three_live_link, and the three_live_gym_reset / three_live_gym_step / three_live_gym_close agent gym) in Gemini CLI, Google Antigravity, Claude Code, or any MCP client. The agent gym lets an agent play a scene step by step (act, observe, react) to check a level is winnable; "gym" is the reinforcement-learning term for such a reset/step environment, and no ML is involved. Not using MCP? three-live-cli gym reset level.js --session ep.json and three-live-cli gym step --session ep.json --actions '[...]' do the same, one command per step. three-live-cli link scene.js --qr prints a playground link (and a terminal QR code) that opens the scene on a phone, one tap from AR. Building from a photo, mockup, sketch, or blueprint? Pass --reference (or reference in MCP) to get a side-by-side + aligned-overlay + silhouette-diff sheet with IoU and proportion guidance, or run from-image to synthesize and verify a procedural Three.js scene directly from an image:

$ npx three-live-cli render scene.js --view=quad --grid --annotations -o contact_sheet.png
$ npx three-live-cli render scene.js --reference=blueprint.png --view=front -o compare.png
$ npx three-live-cli from-image photo.jpg -o scene.js --visual-turns 2 --render compare.png
$ npx three-live-cli validate scene.js --json
$ npx three-live-cli link scene.js --qr
$ npx three-live-cli convert scene.js -o model.usdz
$ npx three-live-cli textures bake scene.js -o scene.textures.json   # AI textures (needs THREE_LIVE_AI_IMAGE_ENDPOINT)
$ npx three-live-cli convert scene.js --texture-pack scene.textures.json -o model.glb

# Or register the built-in MCP server for closed-loop visual + spatial AI verification:
$ claude mcp add three-live -- npx -y -p three-live three-live-cli mcp

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

On the web, <three-live> (< 31 KB gz viewer, < 78 KB gz with the live Three.js compiler) and <xr-live> (< 90 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);

Add three-live-ai.min.js (< 33 KB gz; built into the full bundles) to let users reshape a scene with any LLM: every edit is compiled in the sandbox first, auto-repaired once on failure, and only then hot-swapped, so a bad generation never breaks the live scene.

<three-live allow-client-scripts
    ai-endpo

// HOW IT'S BUILT

// FILES

5 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/three-live-authoring/SKILL.md26 KB36f125e6e1ddupstream ↗
    ---
    name: three-live-authoring
    description: >-
      Builds interactive 3D viewers, procedural Three.js scenes, AR product
      configurators, and 6DoF WebXR, Android XR, and iOS/visionOS spatial computing
      apps using <three-live> and <xr-live>. Use when creating or editing
      <three-live> or <xr-live> HTML elements, writing <script type="text/three">
      procedural scenes, configuring userData.xr spatial traits or
      userData.interactivity behavior graphs, building <div slot="spatial"> 3D HTML
      cards, or integrating native Android (Filament / Jetpack XR SceneCore) and
      iOS/visionOS (RealityKit) spatial views.
    ---
    
    # Authoring 3D & Spatial Apps with `<three-live>` and `<xr-live>`
    
    `<three-live>` and `<xr-live>` compile declarative HTML and sandboxed Three.js scripts (`<script type="text/three">`) into WebGL2/WebXR on the web, Google Filament & Jetpack XR SceneCore on Android, and Apple RealityKit & Quick Look on iOS/visionOS.
    
    ## 1. Choose the Right Component & Bundle
    
    - **Use `<three-live>` (`three-live.min.js` or `three-live-full.min.js`)** when you need:
        -   A 3D `.glb` / `.usdz` model viewer (`<model-viewer>` drop-in
            replacement) with built-in `EXT_meshopt_compression` decoding and
            `KHR_materials_variants` (`variant-name`)
        -   A procedural Three.js scene (including 2D `Shape`/`ExtrudeGeometry`,
            3D `SweepGeometry`/`HelixGeometry`/`LoftGeometry` sweeps, coils, and
            lofted vessels, `THREE.CSG` Booleans, 3D `TextGeometry`, optional a la
            carte domain kits
            `THREE.Mechanical`, `THREE.Architecture`, `THREE.Industrial`,
            `THREE.Science`, and `THREE.Electronics` via `three-live-kits.min.js` or
            `three-live-kit-<domain>.min.js`, and `THREE.InstancedMesh` GPU
            instancing) with
            orbit controls and 1-tap mobile AR handoff (`ar`)
        -   PBR Next materials (clearcoat, transmission, dispersion, iridescence,
            sheen, volume), 5 filmic/commerce tone-mapping modes
            (`tone-mapping="neutral|aces|agx|reinhard|none"`), HDR emissive `bloom`,
            silhouette `outline`, `.hdr` environment lighting, ground contact
            shadows, multi-light depth shadow maps (`shadow-maps="auto|pcf|off"`,
            `light.castShadow`, `mesh.castShadow`, `mesh.receiveShadow`), loop-free
            `THREE.TSL` procedural node materials (`three-live-tsl.min.js` /
            `MeshStandardNodeMaterial` + `el.setMaterialUniform()`), skeletal
            animations & 2-bone/FABRIK `ik`, or 2D screen-space hotspots
            (`slot="hotspot-*"`)
    - **Use `<xr-live>` (`xr-live-full.min.js`)** when you need:
        - 6DoF WebXR (`xr-mode="ar"` / `"vr"` / `"auto"`) or desktop 6DoF simulation (`xr-simulator="living-room"`)
        -   Declarative spatial manipulation traits (`grab`, `scale`, `billboard`,
            `follow`, `anchor`, `physics`, `orbit`, `handles`, `dimensions`,
            `snapTo`, `snapSocket`, `gaze`, `explode`, `navigable`, `sync`, `bloom`,
            `outline`, `ik`, `text`, `splat`, `audioEmitter`)
        - True 3D raycastable HTML/CSS spatial cards (`<div slot="spatial">`)
        -   Real-world depth occlusion & heightfield physics
            (`xr-depth="occlusion-physics"`), 25-joint hand gesture recognition
            (`xr-hands="gestures"`), spatial 3D painting (`spatial-paint`),
            depth-colliding particles (`particles`), 3D Gaussian Splats with 3D
            covariance & SH degree 1–3 (`splatUrl` / `splat`), world plane/reticle
            understanding (`world-understanding`), multimodal Gemini Live
            (`connectGeminiLive()` / `holdToAsk`), 3D CAD dimension callouts & tape
            measure (`spatial-measure`), magnetic socket/grid snapping
            (`magnetic-snap`), hands-free eye/head gaze dwell (`gaze-dwell`),
            multi-part exploded views & section clipping (`explode` /
            `section-plane`), `#xr-state` & `XRAnchor` persistence
            (`persistent-anchors`), parabolic XR locomotion (`locomotion`), or
            multi-user co-presence & WebRTC voice signaling (`shared-room` +
            `shared-room-voice`; your app owns the `RTCPeerConnection`).
    -   **Add `xr-live-sim.min.js` (included in `xr-live-full.min.js`)** when the
        scene is an interactive simulation: a game, training drill, or safety
        walkthrough with a controllable character (`character`), steering agents
        (`agent`), integrity and hits (`integrity`, `hit-zones`), trigger zones
        (`zone`), spawners (`spawner`), objectives and scoring (`objective`,
        `scenario-timer`, `target-score`, `attempts`), or procedural audio cues
        (`audioCues`, `synth-audio`). Use neutral names: `integrity` (not health),
        `group` (not team).
    
    ---
    
    ## 2. Critical Rules That Prevent Broken Scenes
    
    1. **Include `allow-client-scripts` whenever using inline `<script type="text/three">` or `executeScript()`:**
       - `<three-live>` and `<xr-live>` reject inline client scripts unless `allow-client-scripts` is present on the host element.
       - Server-hosted scripts loaded via `script-src="/path/to/scene.js"` do not require `allow-client-scripts`.
    2. **Use the pre-defined `THREE` and `scene` globals inside `<script type="text/three">`:**
       - Do **not** `import * as THREE from 'three'`, do **not** create a `new THREE.WebGLRenderer()`, and do **not** call `document.body.appendChild(...)` inside `<script type="text/three">`. The script runs inside an isolated Web Worker (or Rust Boa sandbox) with zero DOM access and populates the global `scene` directly (`scene.add(mesh)`).
    3. **Never use `GLTFLoader` or `TextureLoader` inside `<script type="text/three">`:**
       - Network APIs (`fetch`, `XMLHttpRequest`) are revoked inside the procedural sandbox. Load `.glb` assets declaratively via `<three-live src="model.glb">` or `<xr-anchor src="model.glb">`.
    4. **Prefer `mesh.userData.xr = { ... }` over legacy `userData.xrTraits`:**
       - The structured `userData.xr` object supports all core and extended spatial traits and exports cleanly to `.glb` (`extras.xr` + `ANDROID_xr_scenecore`) and `.usdz` (`customData.xr`).
    5. **Always name interactive meshes (`mesh.name = '...'`):**
       - `meshclick` events, `selected-mesh`, `userData.xr.orbit.target`, `userData.interactivity` target references, `holdToAsk` prompts, and WebMCP `place_xr_object_at_gaze` all identify nodes by `mesh.name`.
    6.  **Use loop-free `THREE.MeshStandardNodeMaterial` + `THREE.TSL` for
        procedural shaders (never `ShaderMaterial` or `TSL.Loop`):**
        -   Load `three-live-tsl.min.js` (or `three-live-full.min.js` /
            `xr-live-full.min.js`) and assign `colorNode`, `opacityNode`,
            `emissiveNode`, `roughnessNode`, `metalnessNode`, `normalScaleNode`,
            `bumpNode`, or `positionNode` using `THREE.TSL` (`uv`, `time`,
            `positionLocal`, `positionWorld`, `normalLocal`, `normalWorld`,
            `viewDirection`, `uniform(val, name)`, `fresnel`, `simplexNoise2D/3D`,
            `voronoi2D`, `checker`, `triplanar`, `hueShift`, `bumpFromHeight`,
            `remap`). Keep graphs acyclic (`<= 128` nodes, `<= 16` uniforms) and
            avoid fragment-only ops (`viewDirection`, `fresnel`, `bumpFromHeight`)
            inside `positionNode` (`TL501`–`TL504`).
    
    ---
    
    ## 3. Canonical `userData.xr` Trait Quick Reference
    
    Attach `userData.xr` to any `THREE.Mesh` or `THREE.Group` inside `<script type="text/three">`:
    
    Trait Key                | Accepted Values                                                                                                                                                                                                                                                                                                       | Behavior
    :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------
    `grab`                   | `'1-hand' \| '2-hand' \| true`                                                                                                                                                                                                                                                                                        | Enables 6DoF pinch / controller trigger grabbing (`true` defaults to `'2-hand'`).
    `scale`                  | `{ min?: number, max?: number } \| true`                                                                                                                                                                                                                                                                              | Two-hand pinch-to-scale clamped to `[min, max]` (default `0.05`–`5.0`).
    `billboard`              | `'capsule' \| 'cylindrical' \| 'spherical' \| true`                                                                                                                                                                                                                                                                   | Faces the active viewer camera (`'capsule'` / `'cylindrical'` yaw-only; `'spherical'` full 3D).
    `follow`                 | `'head' \| 'hand-left' \| 'hand-right'` **or** `{ mode, lazy, distance, deadzoneDeg, stiffness, height, faceUser, snapOnStart }`                                                                                                                                                                                      | String values use eager spring follow; object values activate lazy follow with angular deadzone + critically damped spring.
    `anchor`                 | `'floor' \| 'wall' \| 'ceiling' \| 'table' \| 'horizontal' \| 'vertical'` **or** `{ target?, id?, persist? }`                                                                                                                                                                                                         | Snaps node to detected real-world planes or simulated surfaces; `persist: true` saves user-moved transforms across reloads and `#xr-state` URLs.
    `physics` / `rigidBody`  | `'dynamic' \| 'static' \| 'kinematic' \| true` **or** `{ body?, shape?: 'auto' \| 'box' \| 'sphere' \| 'cylinder', mass?, restitution?, friction?, linearDamping?, angularDamping?, gravityScale?, velocity?, angularVelocity?, lockRotation? }`                                                                      | Steps 60 Hz deterministic Sequential Impulse rigid-body physics (gravity, restitution bounce, friction, stacking, sleeping, character push, projectile knockback, and depth heightfield collisions); emits `xrcollision` and `xrsleep`.
    `orbit`                  | `{ target: [x,y,z] \| 'nodeName', radius, speed, height, phase, faceCenter }`                                                                                                                                                                                                                                         | Orbits around a 3D point or named target mesh at `speed` rad/s.
    `handles`                | `{ rotateAxis?: 'y' \| 'none', minScale?: number, maxScale?: number } \| true`                                                                                                                                                                                                                                        | Spawns 4 top-corner uniform-scale handles and a bottom pedestal yaw-rotation bar; emits `xr-handles-change`.
    `dimensions`             | `{ unit?: 'auto' \| 'm' \| 'cm' \| 'mm' \| 'in' \| 'ft-in', axes?: Array<'x' \| 'y' \| 'z'>, color?: string, showOnSelect?: boolean } \| true`                                                                                                                                                                        | Renders live `W × H × D` bounding-box dimension guide bars and 3D vector-glyph labels (`spatial-measure`).
    `snapTo`                 | `{ grid?: number \| [x,y,z], angleDeg?: number, surface?: 'none' \| 'floor' \| 'wall' \| 'ceiling' \| 'any', socketTag?: string, radius?: number } \| true`                                                                                                                                                           | Snaps grabbed meshes to matching `snapSocket` anchors (`1.25×` breakaway hysteresis), grids, surfaces, and yaw angles (`magnetic-snap`).
    `snapSocket`             | `string` **or** `{ tag: string, radius?: number, alignRotation?: boolean, highlightColor?: string }`                                                                                                                                                                                                                  | Marks a node as a magnetic snap target socket with a pulsing proximity ring (`magnetic-snap`).
    `gaze`                   | `{ dwellMs?: number, action?: 'select' \| 'ask', repeat?: boolean } \| true`                                                                                                                                                                                                                                          | Opts mesh into hands-free eye/head gaze dwell (`250..10000ms`, default `1200ms`), routing to `meshclick` or `gemini-live` (`gaze-dwell`).
    `explode`                | `{ direction?: [x,y,z], distance?: number, layer?: number, leaderLine?: boolean } \| boolean`                                                                                                                                                                                                                         | Configures per-part explosion vector, distance, staggered `layer` (`1..10`), and dashed leader lines (`exploded-view`); `false` pins base parts.
    `navigable`              | `boolean \| 'walkable' \| 'blocked'`                                                                                                                                                                                                                                                                                  | Marks floor/deck meshes as valid (`'walkable'`) or blocked landing surfaces for parabolic XR teleportation (`spatial-locomotion`).
    `sync`                   | `boolean`                                                                                                                                                                                                                                                                                                             | Controls whether user manipulations sync across peers in `shared-room` (defaults to `true` on grabbable nodes).
    `particles`              | `{ preset: 'rain' \| 'snow' \| 'sparks' \| 'confetti', count?: number, area?: [x,y,z], speed?: number }`                                                                                                                                                                                                              | Emits up to `2,000` depth-colliding particles inside `area`.
    `holdToAsk`              | `{ prompt?: string, holdMs?: number } \| true`                                                                                                                                                                                                                                                                        | Press-and-hold on the mesh starts speech recognition and queries Gemini Live; emits `xr-hold-to-ask`.
    `worldUnderstanding`     | `{ planes?: boolean, meshes?: boolean, reticle?: boolean, objects?: boolean }`                                                                                                                                                                                                                                        | Enables WebXR plane/mesh detection and gaze surface reticle (`__xr_reticle__`).
    `splatUrl`               | `'https://.../scene.splat'` or `'.spz'`                                                                                                                                                                                                                                                                               | Streams and depth-sorts 3D Gaussian Splats (`.splat` or Niantic `.spz` v2/v3 with 3D covariance + SH degree 1–3).
    `splat`                  | `{ url: string, shDegree?: 0 \| 1 \| 2 \| 3, maxSplats?: number }`                                                                                                                                                                                                                                                    | Structured 3D Gaussian Splat trait controlling Spherical Harmonics degree (`0..3`) and splat cap.
    `bloom`                  | `{ strength?: number, threshold?: number, radius?: number } \| boolean \| number`                                                                                                                                                                                                                                     | Enables HDR emissive bloom on the scene/node (`strength` in `[0, 5]`, `threshold` in `[0, 2]`, `radius` in `[0, 1]`).
    `outline`                | `{ color?: string, thickness?: number } \| boolean \| string`                                                                                                                                                                                                                                                         | Renders an inverted-hull or screen-space silhouette outline (`thickness` in `[0.002, 0.25]`) around the node.
    `ik`                     | `{ root: string, mid?: string, effector: string, target: string \| [x, y, z], pole?: string \| [x, y, z], solver?: 'two-bone' \| 'fabrik', iterations?: number, tolerance?: number, weight?: number }`                                                                                                                | Solves analytical 2-bone (`root` → `mid` → `effector`) or FABRIK inverse kinematics toward `target` (and optional `pole`, alias `poleTarget`).
    `lod`                    | `boolean \| number[] \| { distances?: number[], ratios?: number[], levels?: Array<{ distance: number, ratio?: number, node?: string }>, cullDistance?: number, hysteresis?: number }`                                                                                                                                 | Distance-based Level-of-Detail switching with hysteresis, far-distance culling, and automatic vertex-clustering decimation (also `new THREE.LOD()`).
    `text`                   | `{ text: string, size?: number, depth?: number, bevelEnabled?: boolean, bevelThickness?: number, bevelSize?: number }`                                                                                                                                                                                                | Extruded 3D vector text metadata exported to glTF `extras.xr.text` and USDZ `customData.xr`.
    `audioEmitter` / `audio` | `'hum' \| 'reactor' \| 'wind' \| 'beacon' \| 'geiger' \| 'chimeLoop' \| 'machinery' \| 'water'` or `'https://.../sound.mp3'` or `{ preset?, src?, volume?, loop?, autoplay?, playOnSelect?, distanceModel?, refDistance?, maxDistance?, rolloffFactor?, coneInnerAngle?, coneOuterAngle?, coneOuterGain?, pitchHz? }` | Attaches a 3D positional and directional spatial audio emitter (`spatial-audio`), exporting `KHR_audio_emitter` and USDZ `SpatialAudio`.
    `character`              | `true \| 'third-person' \| 'first-person' \| 'top-down' \| 'fixed'` **or** `{ speed, jumpVelocity, radius, height, cameraMode, clips }`                                                                                                                                                                               | (`xr-live-sim`) Keyboard, gamepad, or touch-joystick character that slides along `collidable` nodes.
    `agent`                  | `'patrol' \| 'chase' \| 'flee' \| 'follow' \| 'wander'` **or** `{ mode, target, speed, sightRadius, waypoints }`                                                                                                                                                                                                      | (`xr-live-sim`) Steering agent; `target: 'user'` means the character, else the viewer.
    `integrity`              | `number` **or** `{ max, group, showBar, scoreValue, contactAmount, hideOnDepleted }`                                                                                                                                                                                                                                  | (`xr-live-sim`) Takes hits from other groups; emits `xrhit` and `xrdepleted`.
    `zone`                   | `'box' \| 'sphere'` **or** `{ shape, size, radius, watchGroups, color }`                                                                                                                                                                                                                                              | (`xr-live-sim`) Emits `xrzoneenter` / `xrzoneexit` for characters, agents, and integrity nodes.
    `spawner`                | `'TemplateName'` **or** `{ template, intervalSec, maxActive, totalCount, spawnRadius }`                                                                                                                                                                                                                               | (`xr-live-sim`) Clones a hidden template node; emits `xrspawn`.
    `objective`              | `'pickup' \| 'checkpoint' \| 'key' \| 'time-bonus' \| 'restore'` **or** `{ type, amount, order, required, radius, respawnSec }`                                                                                                                                                                                       | (`xr-live-sim`) Completed by proximity to the character, or by tap without one; `order > 0` enforces sequence.
    `audioCues`              | `{ onTap?, onObjective?, onHit?, onDepleted?, onZoneEnter?, onZoneExit?, onSpawn?, onJump?, onLand? }` (cue names such as `'confirm'`, `'alarm'`)                                                                                                                                                                     | (`xr-live-sim`) Procedural cues with `synth-audio`; separate from the file-based `audio` trait.
    `collidable`             | `true`                                                                                                                                                                                                                                                                                                                | (`xr-live-sim`) Wall or floor for characters and agents.
    `pointerEvents`          | `'none'`                                                                                                                                                                                                                                                                                                              | Excludes the mesh from raycast picking so rays pass through to objects behind it.
    
    ---
    
    ## 4. Progressive Disclosure References
    
    Read these reference files when you need detailed schemas, copy-pasteable recipes, or debugging steps:
    
    -   **[`references/xr-traits-and-plugins.md`](references/xr-traits-and-plugins.md)**:
        Complete attribute tables, clamping ranges, DOM events,
        `userData.interactivity` (`KHR_interactivity`) actions, all 15 spatial
        plugin controllers, the 6 `xr-live-sim` simulation plugins, Gemini Live API,
        and WebMCP tool schemas.
    -   **[`references/recipes.md`](references/recipes.md)**: 10 production-ready,
        copy-pasteable code templates (E-commerce configurator, Physics ballpit &
        spatial HTML UI, manipulation handles & lazy HUD, Gemini Live + World
        Understanding, Spatial Paint + Particles + Gaussian Splats, Native
        Android/iOS integration, CAD Exploded View + Measure + Gaze Dwell, Magnetic
        Snapping + Persistent `#xr-state` + Locomotion, Multi-User `shared-room`
        Co-Presence, and an `xr-live-sim` training drill).
    -   **[`references/debugging-and-csp.md`](references/debugging-and-csp.md)**:
        Diagnosing blank scenes, inspecting `THREE.getAuthorWarnings()`, running
        closed-loop `three-live-cli validate --json` / `render --view=quad` /
        `sim --json` checks (`TL100–TL402`), configuring Worker/iframe sandboxes &
        `connect-src wss:` under strict CSP / Trusted Types, and verifying bundle
        budgets.
    
    --------------------------------------------------------------------------------
    
    ## 5. Closed-Loop CLI Verification (`three-live-cli`)
    
    Always verify authored `.js`, `.html`, or `.glb` scenes headlessly using
    `three-live-cli`:
    
    1.  **Validate & Spatial Lint:** `three-live-cli validate scene.js --json` — fix
        all `TL100–TL402` errors and spatial warnings (`inFrustum`,
        `screenCoveragePct`, `grounded`, broken target references) before rendering.
    2.  **Render 4-Up Quad Contact Sheet:** `three-live-cli render scene.js -o
        preview.png --view=quad --grid --annotations` — inspect perspective camera
        framing (`CAMERA`), front/right elevation (`FRONT`, `RIGHT`), and top-down
        layout (`TOP`) with `1 m` gridlines and AABB labels.
    3.  **Match a Reference (when given a photo, mockup, sketch, or blueprint):**
        `three-live-cli render scene.js -o compare.png --reference=ref.jpg
        --view=camera` (or `--view=front|right|top` for blueprints) — iterate until
        `silhouetteIou >= 0.85` and `|aspectError| < 0.05` when `silhouetteReliable`
        is true, otherwise compare the aligned OVERLAY panel.
    4.  **Simulate Interactivity & Temporal Motion:** `three-live-cli render
        scene.js -o anim.png --frames=4 --duration=2.0 --trigger-select=<node>` or
        `three-live-cli sim scene.js --duration=5.0 --actions='[...]' --json`. For
        games, play the level closed-loop with
        `three-live-cli gym reset scene.js --session ep.json` and
        `three-live-cli gym step --session ep.json --actions='[...]'` (or the
        `three_live_gym_*` MCP tools) to check it is winnable.
    
  • skills/three-live-authoring/references/debugging-and-csp.md8.7 KBe329d7ccebaaupstream ↗
    # Debugging, Sandboxing & CSP Guide (`<three-live>` & `<xr-live>`)
    
    ## 1. Why Nothing Renders (Top 4 Causes)
    
    1. **Missing `allow-client-scripts` attribute:**
       - **Symptom:** `<three-live>` or `<xr-live>` with an inline `<script type="text/three">` stays blank and dispatches an `error` event with `CLIENT_SCRIPTS_DISABLED_ERROR`.
       - **Fix:** Add `allow-client-scripts` to the element (`<three-live allow-client-scripts ...>`) or set `ThreeLiveElement.allowClientScripts = true` before connecting.
    2. **Bundler moved the Worker engine asset (`sandboxEngineSrc`):**
       - **Symptom:** When bundling with Vite, Webpack, or Rollup instead of loading `/dist/three-live.min.js` via `<script>`, the sandbox Worker cannot auto-detect the IIFE bundle URL and fails closed.
       - **Fix:** Explicitly point `ThreeLiveElement.sandboxEngineSrc` at the IIFE `.min.js` bundle:
         
         ```js
         import { ThreeLiveElement } from 'three-live';
         ThreeLiveElement.sandboxEngineSrc =
           new URL('three-live/dist/three-live.min.js', import.meta.url).href;
         ```
    3. **Strict Host CSP (`require-trusted-types-for 'script'` or blocked `blob:` Workers):**
       - **Symptom:** The host page's Content Security Policy blocks Worker creation or script evaluation.
       - **Fix:** Set `sandbox="iframe"` on the element and configure `ThreeLiveElement.sandboxIframeSrc` to point at `three-live-sandbox.html`, which runs inside an opaque-origin `<iframe sandbox="allow-scripts">`.
    4. **Calling `new THREE.GLTFLoader()` or `fetch()` inside `<script type="text/three">`:**
       - **Symptom:** External model does not appear because `fetch` and `XMLHttpRequest` are permanently revoked inside the sandbox Worker.
       - **Fix:** Use `<three-live src="/path/to/model.glb">` or `<xr-anchor src="/path/to/model.glb">`.
    
    ---
    
    ## 2. Inspecting Permissive Fallback Warnings (`THREE.getAuthorWarnings()`)
    
    When an LLM-generated `<script type="text/three">` uses unsupported Three.js classes (`ShaderMaterial`, `SpotLight`, `IcosahedronGeometry`, `CapsuleGeometry`, or unknown `THREE.*` constructors), `three-author` downgrades them gracefully instead of crashing.
    
    To inspect which fallbacks were triggered during a scene compilation:
    
    ```js
    // Inside <script type="text/three"> or unit tests:
    const warnings = THREE.getAuthorWarnings();
    console.log('Author warnings:', warnings);
    THREE.clearAuthorWarnings();
    ```
    
    ---
    
    ## 3. Enforced Sandbox Quotas
    
    Every procedural compilation (`toCanvas3D()`, `toGLB()`, `toUSDZ()`) runs `SceneQuotaValidator` with these defaults:
    
    - **Max Script Size:** `1,048,576` bytes (`1 MiB`)
    - **Max Meshes:** `1,000`
    - **Max Vertices:** `100,000`
    - **Max Indices:** `300,000`
    - **Max Textures:** `16` (max dimension `2048×2048`)
    - **Execution Watchdog:** `3,000 ms` wall-clock timeout (`250 ms` CPU ceiling inside Rust Boa compiler)
    - **Max Concurrent Sandbox Workers:** `32`
    
    --------------------------------------------------------------------------------
    
    ## 4. Network CSP & Plugin Security Quotas (`gemini-live`, `shared-room`, `persistent-anchors`)
    
    -   **Host `connect-src` for Live Relays:** The procedural
        `<script type="text/three">` Worker always runs with network access revoked
        (`connect-src 'none'`). Host-level plugins (`connectGeminiLive()` and
        `shared-room="wss://..."`) connect from the main thread and enforce `wss://`
        (or loopback `ws://localhost` / `ws://127.0.0.1` / `ws://[::1]`). If your
        page serves a strict Content Security Policy and uses remote WebSocket
        relays, allow your relay origin in `connect-src` (e.g.
        `connect-src 'self' wss://your-relay.example.com`). Same-origin
        `shared-room="room-id"` uses `BroadcastChannel` and needs no `connect-src`
        allowance.
    -   **Persistence & Co-Presence Caps:**
        -   `persistent-anchors`: `MAX_PERSISTED_NODES = 128`,
            `MAX_HASH_BYTES = 8192` (`#xr-state` tokens larger than `8 KB` or
            containing prototype-pollution keys are rejected).
        -   `shared-room`: `MAX_PEERS = 16`, `MAX_PAYLOAD_BYTES = 16384` (`16 KB`),
            `MAX_REMOTE_STROKES = 64`, `POSE_TICK_INTERVAL_MS = 50` (`20 Hz`),
            `SOFT_LOCK_TTL_MS = 2000`.
    
    --------------------------------------------------------------------------------
    
    ## 5. Closed-Loop CLI Diagnostics (`TL100–TL402`), Headless Contact Sheets & Scenario Simulation
    
    Use `three-live-cli` to verify `.js`, `.html`, and `.glb` scenes without a
    browser:
    
    ```bash
    # 1. Validate syntax, schema, HTML attributes, and 3D spatial layout
    three-live-cli validate scene.js --json
    
    # 2. Render a 2x2 quad contact sheet (Camera, Front, Right, Top) with 1m grid & AABB labels
    three-live-cli render scene.js -o preview.png --view=quad --grid --annotations
    
    # 3. Render a 4-frame temporal filmstrip or animated GIF with KHR_interactivity onSelect trigger
    three-live-cli render scene.js -o anim.png --frames=4 --duration=2.0 --trigger-select=crystal
    
    # 4. Run a 60Hz deterministic scenario simulation
    three-live-cli sim scene.js --duration=5.0 \
      --actions='[{"at":0.2,"type":"select","target":"crystal"},{"at":0.5,"type":"moveCharacter","direction":[0,0,-1],"duration":1.5}]' \
      --json
    ```
    
    ### Diagnostic Code Table (`TL100–TL402`)
    
    Code    | Severity  | Condition                                                          | Actionable Fix
    :------ | :-------- | :----------------------------------------------------------------- | :-------------
    `TL100` | `error`   | Syntax error, runtime exception, or quota exceeded                 | Check `line`/`column` in JSON output and fix JS syntax or reduce vertex/mesh count.
    `TL101` | `warning` | `ShaderMaterial` / `RawShaderMaterial` fallback                    | Replace with `THREE.MeshStandardMaterial` or `THREE.MeshPhysicalMaterial`.
    `TL102` | `warning` | Polyhedron/Tube geometry fallback                                  | Use `SphereGeometry`, `CylinderGeometry`, `ExtrudeGeometry`, `LatheGeometry`, or `THREE.CSG`.
    `TL103` | `warning` | `THREE.GLTFLoader` / `TextureLoader` / `fetch`                     | Load external `.glb` via `<three-live src="model.glb">` or `<xr-anchor src="model.glb">`.
    `TL104` | `info`    | `requestAnimationFrame` in static export                           | Use `userData.xr.orbit` or `userData.interactivity` so motion survives `.glb`/`.usdz` export.
    `TL105` | `warning` | Unknown `THREE.*` constructor/method                               | Remove unsupported Three.js helper call.
    `TL201` | `warning` | Unknown `userData.xr` or `userData.interactivity` key              | Apply the Levenshtein suggestion in `suggestion` (e.g. `grabbable` -> `grab`).
    `TL202` | `warning` | Out-of-range numeric trait clamped                                 | Keep `gaze.dwellMs` in `[200, 10000]`, `bloom.strength` in `[0, 5]`, `outline.thickness` in `[0.002, 0.25]`.
    `TL203` | `error`   | Unsafe media/live/room URL or anchor ID                            | Use `https://` (or clean relative paths) for media, `wss://` for relays, and alphanumeric anchor IDs.
    `TL204` | `error`   | Broken target node reference                                       | Ensure `orbit.target`, `ik.*`, `spawner.template`, and `interactivity.*.target` match an existing `mesh.name`.
    `TL205` | `warning` | Unnamed interactive/spatial mesh                                   | Set a unique `mesh.name = "..."` before attaching `userData.xr` or `userData.interactivity`.
    `TL301` | `error`   | Empty scene (`meshCount == 0`)                                     | Call `scene.add(mesh)` with at least one non-empty geometry.
    `TL302` | `warning` | Camera inside mesh AABB                                            | Move camera outside `summary.worldBounds` or shrink the enclosing mesh.
    `TL303` | `warning` | Mesh outside camera frustum or extreme framing                     | Reposition the mesh or adjust camera `position` / `lookAt` so `screenCoveragePct` is between `5%` and `85%`.
    `TL304` | `warning` | Extreme scene scale (`< 0.01 m` or `> 200 m`)                      | Author dimensions in meters (`1 unit = 1 meter`); scale millimeter meshes by `0.001`.
    `TL305` | `warning` | Unlit metallic PBR material                                        | Add a `DirectionalLight` / `AmbientLight` or set `environment` on `<three-live>`.
    `TL306` | `warning` | Co-located sibling meshes (`> 80%` overlap)                        | Offset sibling positions or use `THREE.CSG.subtract(a, b)` for boolean cutouts.
    `TL307` | `info`    | Floating or buried scene / character                               | Align `min.y` to `0.0` (`mesh.position.y = height / 2`) so AR/VR placement sits on the floor.
    `TL401` | `error`   | Inline `<script type="text/three">` without `allow-client-scripts` | Add `allow-client-scripts` to `<three-live>` or `<xr-live>`.
    `TL402` | `warning` | `<xr-live>` feature used on `<three-live>`                         | Upgrade the tag from `<three-live>` to `<xr-live>` and load `xr-live.min.js`.
    
  • skills/three-live-authoring/references/recipes.md20 KB84af27c9f71bupstream ↗
    # Copy-Paste Recipes for `<three-live>` and `<xr-live>`
    
    All 9 recipes below use features available in the repository today and work
    without external build steps.
    
    ---
    
    ## Recipe 1: Interactive 3D Product Configurator (`<three-live>` + `KHR_interactivity` + Hotspots)
    
    ```html
    <script type="module" src="/dist/three-live-full.min.js"></script>
    
    <three-live
      allow-client-scripts
      camera-controls
      auto-rotate
      ar
      shadow-intensity="0.8"
      shadow-softness="0.6"
      tone-mapping="neutral"
      style="width: 100%; height: 520px; display: block;">
    
      <script type="text/three">
        const pedestal = new THREE.Mesh(
          new THREE.CylinderGeometry(0.55, 0.65, 0.14, 48),
          new THREE.MeshStandardMaterial({ color: 0x1e293b, metalness: 0.7, roughness: 0.25 })
        );
        pedestal.name = 'pedestal';
        pedestal.position.set(0, -0.35, 0);
        scene.add(pedestal);
    
        const watchCase = new THREE.Mesh(
          new THREE.TorusGeometry(0.32, 0.09, 32, 64),
          new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.85, roughness: 0.15 })
        );
        watchCase.name = 'watch-case';
        watchCase.position.set(0, 0.15, 0);
        // Compile-to-GLB KHR_interactivity behavior on click/tap:
        watchCase.userData.interactivity = {
          onSelect: [
            {
              action: 'cycleMaterialColor',
              colors: [
                [0.22, 0.74, 0.97, 1.0],
                [0.96, 0.62, 0.04, 1.0],
                [0.66, 0.33, 0.97, 1.0]
              ],
              duration: 0.3
            },
            {
              action: 'toggleTransform',
              property: 'scale',
              from: [1, 1, 1],
              to: [1.18, 1.18, 1.18],
              duration: 0.25
            }
          ]
        };
        scene.add(watchCase);
    
        const keyLight = new THREE.DirectionalLight(0xffffff, 2.2);
        keyLight.position.set(2, 4, 3);
        scene.add(keyLight);
        scene.add(new THREE.AmbientLight(0xffffff, 0.6));
      </script>
    
      <button slot="hotspot-case" data-position="0 0.45 0.1" data-normal="0 1 0">
        Tap Ring to Cycle Finish
      </button>
    </three-live>
    ```
    
    ---
    
    ## Recipe 2: Spatial UI Card & Depth-Physics Ballpit (`<xr-live>`)
    
    ```html
    <script type="module" src="/dist/xr-live-full.min.js"></script>
    
    <xr-live
      allow-client-scripts
      xr-mode="ar"
      xr-depth="occlusion-physics"
      xr-hands="gestures"
      xr-simulator="living-room"
      sound-feedback
      camera-controls
      style="width: 100%; height: 600px; display: block;">
    
      <script type="text/three">
        const palette = [0x38bdf8, 0xf43f5e, 0x22c55e, 0xeab308, 0xa855f7];
        for (let i = 0; i < 12; i++) {
          const ball = new THREE.Mesh(
            new THREE.SphereGeometry(0.08, 24, 24),
            new THREE.MeshStandardMaterial({
              color: palette[i % palette.length],
              metalness: 0.2,
              roughness: 0.25
            })
          );
          ball.name = `ball-${i}`;
          ball.position.set((i % 4 - 1.5) * 0.22, 1.3 + Math.floor(i / 4) * 0.22, -1.1);
          ball.userData.xr = {
            grab: '1-hand',
            physics: 'dynamic',
            restitution: 0.78
          };
          scene.add(ball);
        }
    
        const light = new THREE.DirectionalLight(0xffffff, 2.0);
        light.position.set(1, 3, 2);
        scene.add(light);
      </script>
    
      <div slot="spatial" data-position="0.55 1.25 -1.1" data-xr-traits="grab billboard">
        <div style="padding: 16px; background: #0f172a; color: #f8fafc; border-radius: 14px; width: 220px;">
          <h4 style="margin: 0 0 8px;">Physics Controls</h4>
          <p style="margin: 0 0 12px; font-size: 13px;">Grab spheres or bounce them off real-world surfaces.</p>
          <button onclick="document.querySelector('xr-live').transitionToVR({ durationMs: 400 })">
            Toggle VR Environment
          </button>
        </div>
      </div>
    </xr-live>
    ```
    
    ---
    
    ## Recipe 3: Precision Manipulation Handles, Lazy Head-Follow HUD & Orbiting Satellites
    
    ```html
    <script type="module" src="/dist/xr-live-full.min.js"></script>
    
    <xr-live
      allow-client-scripts
      xr-simulator="office"
      camera-controls
      style="width: 100%; height: 560px; display: block;">
    
      <script type="text/three">
        // Centerpiece with 4 corner scale handles + pedestal yaw rotation bar
        const sculpture = new THREE.Mesh(
          new THREE.TorusKnotGeometry(0.22, 0.07, 64, 16),
          new THREE.MeshStandardMaterial({ color: 0x6366f1, metalness: 0.7, roughness: 0.2 })
        );
        sculpture.name = 'sculpture';
        sculpture.position.set(0, 0.9, -1.2);
        sculpture.userData.xr = {
          grab: '2-hand',
          handles: { rotateAxis: 'y', minScale: 0.4, maxScale: 2.5 }
        };
        scene.add(sculpture);
    
        // Satellite orbiting the named 'sculpture' node
        const orbiter = new THREE.Mesh(
          new THREE.SphereGeometry(0.05, 24, 24),
          new THREE.MeshStandardMaterial({ color: 0x38bdf8, emissive: 0x0284c7 })
        );
        orbiter.name = 'orbiter';
        orbiter.userData.xr = {
          orbit: { target: 'sculpture', radius: 0.45, speed: 1.2, height: 0.08, faceCenter: true }
        };
        scene.add(orbiter);
    
        // Lazy head-follow status pill with 18-degree angular deadzone
        const hudPill = new THREE.Mesh(
          new THREE.BoxGeometry(0.28, 0.08, 0.02),
          new THREE.MeshStandardMaterial({ color: 0x0f172a, roughness: 0.4 })
        );
        hudPill.name = 'hud-pill';
        hudPill.userData.xr = {
          follow: {
            mode: 'head',
            lazy: true,
            distance: 1.1,
            deadzoneDeg: 18,
            stiffness: 6,
            height: -0.22,
            faceUser: true
          }
        };
        scene.add(hudPill);
      </script>
    </xr-live>
    ```
    
    ---
    
    ## Recipe 4: Multimodal Gemini Live Assistant + Hold-to-Ask + World Understanding
    
    ```html
    <script type="module">
      import '/dist/xr-live-full.min.js';
      import { connectGeminiLive } from '/dist/xr-live-spatial.min.js';
    
      const xr = document.getElementById('gemini-xr');
    
      xr.addEventListener('xr-transcription', (e) => {
        console.log(`[${e.detail.speaker}] ${e.detail.text}`);
      });
    
      xr.addEventListener('xr-object-detected', (e) => {
        console.log(`Located ${e.detail.label} at`, e.detail.position);
      });
    
      // Connect only after user gesture (never on page load):
      document.getElementById('connect-btn').addEventListener('click', () => {
        connectGeminiLive(xr, {
          url: 'wss://your-proxy.example.com/gemini-live',
          frameIntervalMs: 1000,
          streamAudio: true,
          playAudio: true,
          detectObjects: true
        });
      });
    </script>
    
    <button id="connect-btn">Start Gemini Live Session</button>
    
    <xr-live
      id="gemini-xr"
      allow-client-scripts
      world-understanding="planes reticle"
      xr-depth="occlusion"
      camera-controls
      style="width: 100%; height: 560px; display: block;">
      <script type="text/three">
        const artifact = new THREE.Mesh(
          new THREE.CylinderGeometry(0.18, 0.22, 0.4, 32),
          new THREE.MeshStandardMaterial({ color: 0xf59e0b, metalness: 0.6, roughness: 0.3 })
        );
        artifact.name = 'turbine-core';
        artifact.position.set(0, 1.0, -1.0);
        artifact.userData.xr = {
          grab: '1-hand',
          holdToAsk: {
            prompt: 'Explain the role of this turbine core and inspect its orientation.',
            holdMs: 600
          }
        };
        scene.add(artifact);
      </script>
    </xr-live>
    ```
    
    ---
    
    ## Recipe 5: 3D Spatial Paint, Depth Particles & Gaussian Splats
    
    ```html
    <script type="module" src="/dist/xr-live-full.min.js"></script>
    
    <xr-live
      allow-client-scripts
      spatial-paint="#38bdf8"
      xr-depth="occlusion"
      xr-simulator="tabletop"
      camera-controls
      style="width: 100%; height: 560px; display: block;">
    
      <script type="text/three">
        // Depth-colliding snow emitter volume
        const snowVolume = new THREE.Mesh(
          new THREE.BoxGeometry(0.01, 0.01, 0.01),
          new THREE.MeshBasicMaterial({ color: 0xffffff })
        );
        snowVolume.name = 'snow-emitter';
        snowVolume.position.set(0, 1.4, -1.2);
        snowVolume.userData.xr = {
          particles: { preset: 'snow', count: 500, area: [2.5, 2.0, 2.5], speed: 0.9 }
        };
        scene.add(snowVolume);
    
        // 3D Gaussian Splat node (.splat or .spz)
        const splatAnchor = new THREE.Group();
        splatAnchor.name = 'garden-splat';
        splatAnchor.position.set(0, 0.8, -1.2);
        splatAnchor.userData.xr = {
          grab: '2-hand',
          splatUrl: 'https://example.com/assets/bonsai.spz'
        };
        scene.add(splatAnchor);
      </script>
    </xr-live>
    ```
    
    ---
    
    ## Recipe 6: Native Android (Kotlin) & iOS/visionOS (Swift) Integration
    
    ### Android (Google Filament + Jetpack XR SceneCore)
    
    ```kotlin
    import com.google.threelive.ThreeLiveRuntimeSession
    import com.google.threelive.XRLiveSceneCoreHelper
    import com.google.threelive.filament.ThreeLiveFilament
    
    // 1. Install the Filament renderer once at startup
    ThreeLiveFilament.install()
    
    // 2. Compile procedural Three.js and step XR traits / handles / particles natively
    val session = ThreeLiveRuntimeSession.fromScript(scriptSource)
    session.stepFrame(dtSeconds = 1f / 60f)
    
    // 3. Or attach traits directly to an Android XR SceneCore entity from GLB bytes
    XRLiveSceneCoreHelper.attachTraitsFromGlb(xrSession, rootEntity, glbByteBuffer)
    ```
    
    ### iOS & visionOS (Apple RealityKit)
    
    ```swift
    import ThreeLiveCompiler
    import RealityKit
    
    @MainActor
    func mountSpatialScene(script: String, in arView: ARView) async throws {
        let entity = try await RealityKitHelper.loadEntity(from: script)
        XRLiveRealityKit.installTraits(on: entity, in: arView)
    }
    ```
    
    --------------------------------------------------------------------------------
    
    ## Recipe 7: CAD Exploded View, Cross-Section Slicer, 3D Dimensions & Gaze Dwell
    
    ```html
    <script type="module" src="/dist/xr-live-full.min.js"></script>
    
    <xr-live
      allow-client-scripts
      explode="0.55"
      explode-mode="axial-y"
      section-plane="interactive"
      spatial-measure="all"
      measure-unit="mm"
      gaze-dwell="auto"
      dwell-time="950"
      camera-controls
      style="width: 100%; height: 560px; display: block;">
      <script type="text/three">
        const base = new THREE.Mesh(
          new THREE.CylinderGeometry(0.26, 0.3, 0.14, 36),
          new THREE.MeshStandardMaterial({ color: 0x334155, metalness: 0.8, roughness: 0.25 })
        );
        base.name = 'housing-base';
        base.position.set(0, 0.75, -1.1);
        base.userData.xr = {
          explode: false,
          dimensions: { unit: 'mm', axes: ['x', 'y', 'z'], color: '#38bdf8' }
        };
        scene.add(base);
    
        const shroud = new THREE.Mesh(
          new THREE.CylinderGeometry(0.24, 0.26, 0.14, 36),
          new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.65, roughness: 0.2 })
        );
        shroud.name = 'upper-shroud';
        shroud.position.set(0, 0.92, -1.1);
        shroud.userData.xr = {
          explode: { direction: [0, 1, 0], distance: 0.38, layer: 2, leaderLine: true },
          gaze: { dwellMs: 900, action: 'select' }
        };
        scene.add(shroud);
    
        scene.add(new THREE.DirectionalLight(0xffffff, 2.2));
      </script>
    </xr-live>
    ```
    
    --------------------------------------------------------------------------------
    
    ## Recipe 8: Magnetic Socket Snapping, `#xr-state` URL Persistence & XR Locomotion
    
    ```html
    <script type="module" src="/dist/xr-live-full.min.js"></script>
    
    <xr-live
      allow-client-scripts
      magnetic-snap="all"
      snap-grid="0.05"
      snap-angle="15"
      persistent-anchors="workbench"
      persist-url-hash
      locomotion="teleport snap-turn"
      snap-turn-deg="30"
      xr-simulator="office"
      camera-controls
      style="width: 100%; height: 560px; display: block;">
      <script type="text/three">
        const floor = new THREE.Mesh(
          new THREE.PlaneGeometry(4, 4),
          new THREE.MeshStandardMaterial({ color: 0x0f172a, roughness: 0.9 })
        );
        floor.name = 'walkable-floor';
        floor.rotation.x = -Math.PI / 2;
        floor.userData.xr = { navigable: 'walkable' };
        scene.add(floor);
    
        const socketPedestal = new THREE.Mesh(
          new THREE.CylinderGeometry(0.16, 0.18, 0.04, 32),
          new THREE.MeshStandardMaterial({ color: 0x1e293b })
        );
        socketPedestal.name = 'dock-socket';
        socketPedestal.position.set(0, 0.8, -1.1);
        socketPedestal.userData.xr = {
          snapSocket: { tag: 'bay-a', radius: 0.18, alignRotation: true, highlightColor: '#22c55e' }
        };
        scene.add(socketPedestal);
    
        const moduleCube = new THREE.Mesh(
          new THREE.BoxGeometry(0.18, 0.18, 0.18),
          new THREE.MeshStandardMaterial({ color: 0x6366f1, metalness: 0.5, roughness: 0.25 })
        );
        moduleCube.name = 'snap-module';
        moduleCube.position.set(0.35, 0.9, -1.1);
        moduleCube.userData.xr = {
          grab: '1-hand',
          snapTo: { socketTag: 'bay-a', radius: 0.18, grid: 0.05, angleDeg: 15 },
          anchor: { id: 'snap-module', persist: true }
        };
        scene.add(moduleCube);
    
        scene.add(new THREE.DirectionalLight(0xffffff, 2.0));
      </script>
    </xr-live>
    ```
    
    --------------------------------------------------------------------------------
    
    ## Recipe 9: Zero-Backend Multi-User Co-Presence & Shared Spatial Paint (`shared-room`)
    
    ```html
    <script type="module" src="/dist/xr-live-full.min.js"></script>
    
    <xr-live
      allow-client-scripts
      shared-room="studio-room-1"
      peer-name="Designer"
      peer-color="#38bdf8"
      spatial-paint="#38bdf8"
      camera-controls
      style="width: 100%; height: 560px; display: block;">
      <script type="text/three">
        const artifact = new THREE.Mesh(
          new THREE.TorusKnotGeometry(0.18, 0.055, 64, 16),
          new THREE.MeshStandardMaterial({ color: 0xa855f7, metalness: 0.65, roughness: 0.2 })
        );
        artifact.name = 'shared-artifact';
        artifact.position.set(0, 1.0, -1.1);
        artifact.userData.xr = {
          grab: '2-hand',
          handles: { rotateAxis: 'y', minScale: 0.4, maxScale: 2.5 },
          sync: true
        };
        scene.add(artifact);
    
        scene.add(new THREE.DirectionalLight(0xffffff, 2.2));
      </script>
    </xr-live>
    ```
    
    --------------------------------------------------------------------------------
    
    ## Recipe 10: Timed Training Drill with a Safety Zone (`xr-live-sim`)
    
    Ordered task steps, a countdown, and an alarm zone around a robot cell. Load
    `xr-live-sim.min.js` (or use `xr-live-full.min.js`). Taps complete steps in
    order; out-of-order taps play an `error` cue.
    
    ```html
    <!-- Load after xr-live.min.js; xr-live-full.min.js already includes it. -->
    <script src="/dist/xr-live-sim.min.js"></script>
    
    <xr-live
      id="drill"
      allow-client-scripts
      objectives
      scenario-timer="60"
      synth-audio
      style="width: 100%; height: 520px; display: block;">
      <script type="text/three">
        const mat = (color) => new THREE.MeshStandardMaterial({ color, roughness: 0.4 });
    
        // Ordered, required task steps (tap them in sequence)
        ['Step_1_Valve', 'Step_2_Filter', 'Step_3_Cap'].forEach((name, i) => {
          const part = new THREE.Mesh(new THREE.BoxGeometry(0.2, 0.2, 0.2), mat(0x38bdf8));
          part.name = name;
          part.position.set(i * 0.4 - 0.4, 1.0, -1.0);
          part.userData.xr = {
            objective: { type: 'checkpoint', order: i + 1, required: true, amount: 10 },
            audioCues: { onObjective: 'confirm' }
          };
          scene.add(part);
        });
    
        // Robot cell: alarm while the AGV is inside
        const cell = new THREE.Mesh(
          new THREE.BoxGeometry(1.2, 1, 1.2),
          new THREE.MeshStandardMaterial({ color: 0xef4444, transparent: true, opacity: 0.15 })
        );
        cell.name = 'Robot_Cell';
        cell.position.set(1.4, 0.5, -2);
        cell.userData.xr = {
          zone: { shape: 'box', size: [1.2, 1, 1.2], color: '#ef4444', watchGroups: ['agent'] },
          audioCues: { onZoneEnter: 'alarm' }
        };
        scene.add(cell);
    
        // AGV patrolling through the cell
        const agv = new THREE.Mesh(new THREE.BoxGeometry(0.4, 0.2, 0.6), mat(0xf59e0b));
        agv.name = 'AGV';
        agv.position.set(-1.5, 0.1, -2);
        agv.userData.xr = {
          agent: { mode: 'patrol', speed: 0.8, waypoints: [[-1.5, 0.1, -2], [2.5, 0.1, -2]] }
        };
        scene.add(agv);
    
        scene.add(new THREE.DirectionalLight(0xffffff, 2.2));
        scene.add(new THREE.AmbientLight(0xffffff, 0.6));
      </script>
    </xr-live>
    
    <script>
      const drill = document.getElementById('drill');
      drill.addEventListener('xrobjective', (e) => {
        if (e.detail.outOfOrder) console.warn('Out of order:', e.detail.nodeId);
      });
      drill.addEventListener('xrzoneenter', (e) => {
        console.log(e.detail.nodeId, 'entered', e.detail.zoneId);
      });
      drill.addEventListener('xrscenarioend', (e) => {
        console.log('Outcome:', e.detail.outcome, 'in', e.detail.elapsedSec, 's');
      });
    </script>
    ```
    
    --------------------------------------------------------------------------------
    
    ## Recipe 11: Procedural CAD Extrusion, CSG Booleans, 3D Text & GPU Instancing (`<three-live>`)
    
    ```html
    <script type="module" src="/dist/three-live.min.js"></script>
    
    <three-live
      allow-client-scripts
      camera-controls
      auto-rotate
      ar
      tone-mapping="aces"
      bloom="1.2"
      outline="#38bdf8 0.025"
      style="width: 100%; height: 520px; display: block;">
      <script type="text/three">
        const profile = new THREE.Shape();
        profile.absarc(0, 0, 0.55, 0, Math.PI * 2, false);
        const hole = new THREE.Path();
        hole.absarc(0, 0, 0.22, 0, Math.PI * 2, true);
        profile.holes.push(hole);
    
        const steel = new THREE.MeshStandardMaterial({ color: 0x94a3b8, metalness: 0.78, roughness: 0.24 });
        const rawFlange = new THREE.Mesh(
          new THREE.ExtrudeGeometry(profile, { depth: 0.16, bevelEnabled: true, bevelThickness: 0.02, bevelSize: 0.015 }),
          steel
        );
        rawFlange.rotation.x = -Math.PI / 2;
    
        const slotCutter = new THREE.Mesh(new THREE.BoxGeometry(1.3, 0.14, 0.16), steel);
        slotCutter.position.set(0, 0.12, 0);
        const machined = THREE.CSG.subtract(rawFlange, slotCutter);
        machined.name = 'machined-flange';
        machined.userData.xr = { outline: { color: '#38bdf8', thickness: 0.02 } };
        scene.add(machined);
    
        const label = new THREE.Mesh(
          new THREE.TextGeometry('CAD R1', { size: 0.14, depth: 0.035, bevelEnabled: true }),
          new THREE.MeshStandardMaterial({ color: 0xf8fafc, emissive: 0x0ea5e9, emissiveIntensity: 0.45 })
        );
        label.position.set(-0.32, 0.28, 0);
        scene.add(label);
    
        const bolts = new THREE.InstancedMesh(
          new THREE.CylinderGeometry(0.035, 0.035, 0.22, 16),
          new THREE.MeshStandardMaterial({ color: 0xf59e0b, metalness: 0.9, roughness: 0.15 }),
          12
        );
        const m = new THREE.Matrix4();
        const p = new THREE.Vector3();
        const q = new THREE.Quaternion();
        const s = new THREE.Vector3(1, 1, 1);
        for (let i = 0; i < 12; i++) {
          const a = (i / 12) * Math.PI * 2;
          p.set(Math.cos(a) * 0.39, 0.09, Math.sin(a) * 0.39);
          m.compose(p, q, s);
          bolts.setMatrixAt(i, m);
        }
        scene.add(bolts);
    
        scene.add(new THREE.DirectionalLight(0xffffff, 2.4));
        scene.add(new THREE.AmbientLight(0xffffff, 0.6));
      </script>
    </three-live>
    ```
    
    --------------------------------------------------------------------------------
    
    ## Recipe 12: Articulated Robotic Arm with 2-Bone / FABRIK IK & Voice Signaling (`<xr-live>`)
    
    ```html
    <script type="module" src="/dist/xr-live-full.min.js"></script>
    
    <xr-live
      allow-client-scripts
      bloom="1.3"
      outline="#38bdf8 0.025"
      tone-mapping="agx"
      shared-room="robotics-cell"
      shared-room-voice
      camera-controls
      style="width: 100%; height: 540px; display: block;">
      <script type="text/three">
        const armMat = new THREE.MeshStandardMaterial({ color: 0x64748b, metalness: 0.8, roughness: 0.25 });
        const shoulder = new THREE.Group();
        shoulder.name = 'Shoulder';
        shoulder.position.set(0, 0.75, -1.1);
        const upper = new THREE.Mesh(new THREE.BoxGeometry(0.08, 0.08, 0.32), armMat);
        upper.position.set(0, 0, 0.16);
        shoulder.add(upper);
    
        const forearm = new THREE.Group();
        forearm.name = 'Forearm';
        forearm.position.set(0, 0, 0.32);
        const lower = new THREE.Mesh(new THREE.BoxGeometry(0.065, 0.065, 0.28), armMat);
        lower.position.set(0, 0, 0.14);
        forearm.add(lower);
        shoulder.add(forearm);
    
        const wrist = new THREE.Mesh(
          new THREE.SphereGeometry(0.055, 20, 20),
          new THREE.MeshStandardMaterial({ color: 0x38bdf8, emissive: 0x0284c7, emissiveIntensity: 0.6 })
        );
        wrist.name = 'WristEffector';
        wrist.position.set(0, 0, 0.28);
        wrist.userData.xr = {
          ik: { root: 'Shoulder', mid: 'Forearm', effector: 'WristEffector', target: 'GripperTarget', pole: 'ElbowPole' }
        };
        forearm.add(wrist);
        scene.add(shoulder);
    
        const pole = new THREE.Group();
        pole.name = 'ElbowPole';
        pole.position.set(0, 1.35, -0.95);
        scene.add(pole);
    
        const target = new THREE.Mesh(
          new THREE.SphereGeometry(0.065, 24, 24),
          new THREE.MeshStandardMaterial({ color: 0x22c55e, emissive: 0x16a34a, emissiveIntensity: 0.8 })
        );
        target.name = 'GripperTarget';
        target.position.set(0.22, 1.02, -0.78);
        target.userData.xr = { grab: '1-hand', outline: { color: '#22c55e', thickness: 0.025 } };
        scene.add(target);
    
        scene.add(new THREE.DirectionalLight(0xffffff, 2.2));
      </script>
    </xr-live>
    ```
    
  • skills/three-live-authoring/references/xr-traits-and-plugins.md26 KB21dff42ec00aupstream ↗
    # `<three-live>` & `<xr-live>` Complete Traits, Plugins & Events Reference
    
    ## 1. `<xr-live>` Host Attributes
    
    `<xr-live>` inherits every `<three-live>` attribute (`src`, `ios-src`, `poster`, `scale`, `camera-orbit`, `camera-target`, `min-camera-orbit`, `max-camera-orbit`, `field-of-view`, `selected-mesh`, `camera-controls`, `ar`, `ar-modes`, `ar-scale`, `ar-placement`, `script-src`, `sandbox`, `allow-client-scripts`, `exposure`, `environment-image`, `skybox-image`, `shadow-intensity`, `shadow-softness`, `tone-mapping`, `autoplay`, `animation-name`, `auto-rotate`) and adds:
    
    Attribute             | Values                                                                                         | Default     | Description
    :-------------------- | :--------------------------------------------------------------------------------------------- | :---------- | :----------
    `xr-mode`             | `'ar' \| 'vr' \| 'inline' \| 'auto'`                                                           | `'auto'`    | Target WebXR session mode.
    `xr-depth`            | `'occlusion' \| 'occlusion-physics' \| 'mesh' \| 'none'`                                       | `'none'`    | Hardware depth occlusion and analytical heightfield physics collision.
    `xr-hands`            | `'gestures' \| 'joints' \| 'pinch' \| 'none'`                                                  | `'none'`    | 25-joint `XRHand` tracking and gesture classification (`pinch`, `grab`, `point`, `palm-up`).
    `xr-simulator`        | `'living-room' \| 'office' \| 'tabletop' \| 'none'`                                            | `'none'`    | Enables the desktop 6DoF keyboard/mouse simulator with room floor/table planes.
    `xr-profile`          | `'quest3' \| 'android-xr' \| 'visionos' \| 'auto'`                                             | `'auto'`    | Target hardware profile hint.
    `sound-feedback`      | boolean attribute                                                                              | `false`     | Plays procedural Web Audio earcons (`grab`, `release`, `bounce`, `hover`) on interaction.
    `world-understanding` | `'' \| 'planes' \| 'planes reticle' \| 'false'`                                                | —           | Activates `xr-live-world-understanding` plane/mesh tracking and optional gaze reticle.
    `spatial-paint`       | `'' \| '#rrggbb' \| 'false'`                                                                   | —           | Activates `xr-live-spatial-paint`; pinching in empty space extrudes Catmull-Rom 3D tube strokes.
    `spatial-measure`     | `'' \| 'bounds' \| 'tape' \| 'all' \| 'none'`                                                  | —           | Activates `xr-live-spatial-measure` 3D dimension callouts and/or interactive AR tape measure.
    `measure-unit`        | `'auto' \| 'm' \| 'cm' \| 'mm' \| 'in' \| 'ft-in'`                                             | `'auto'`    | Default display unit for `spatial-measure`.
    `magnetic-snap`       | `'' \| 'grid' \| 'surface' \| 'sockets' \| 'all' \| 'none'`                                    | —           | Activates `xr-live-magnetic-snap` socket, grid, surface, and yaw snapping.
    `snap-grid`           | `number` or `'gx gy gz'` (meters)                                                              | —           | Default Cartesian snap grid spacing in meters.
    `snap-angle`          | `number` (`0..180` degrees)                                                                    | `0`         | Default rotational yaw snap increment in degrees.
    `gaze-dwell`          | `'' \| 'auto' \| 'false' \| 'none'`                                                            | —           | Activates `xr-live-gaze-dwell` hands-free eye/head gaze reticle and radial dwell selection.
    `dwell-time`          | `number` (`250..10000` ms)                                                                     | `1200`      | Default dwell duration in milliseconds for `gaze-dwell`.
    `explode`             | `number` (`0..1`)                                                                              | `0`         | Normalized multi-part assembly explosion factor (`xr-live-exploded-view`).
    `explode-mode`        | `'radial' \| 'axial-x' \| 'axial-y' \| 'axial-z' \| 'hierarchical'`                            | `'radial'`  | Automatic explosion vector strategy when parts omit `userData.xr.explode.direction`.
    `explode-scale`       | `number`                                                                                       | `1.0`       | Multiplier applied to per-part explosion distances.
    `section-plane`       | `'none' \| 'x:<d>' \| 'y:<d>' \| 'z:<d>' \| '-x:<d>' \| '-y:<d>' \| '-z:<d>' \| 'interactive'` | `'none'`    | Real-time GPU cross-section clipping plane in scene (model) space (`d` in meters; the cut follows the model through AR placement and turntable rotation) with optional draggable gizmo frame.
    `persistent-anchors`  | `''` or `string` (namespace)                                                                   | —           | Activates `xr-live-persistent-anchors` cross-session transform persistence (`xr-live:anchors:<ns>`).
    `persist-url-hash`    | boolean attribute                                                                              | `false`     | Encodes persisted node poses into `#xr-state=<base64url>` (`<= 8192` bytes) for link sharing.
    `locomotion`          | `'' \| 'teleport' \| 'snap-turn' \| 'smooth' \| 'teleport snap-turn' \| 'none'`                | —           | Activates `xr-live-spatial-locomotion` parabolic teleportation, snap-turns, or smooth glide.
    `snap-turn-deg`       | `number` (degrees)                                                                             | `30`        | Horizontal thumbstick snap-turn increment in degrees.
    `comfort-vignette`    | boolean attribute                                                                              | `true`      | Shows a `120ms` peripheral FOV comfort vignette during teleports and snap-turns.
    `shared-room`         | `'<room-id>'` or `'wss://...'`                                                                 | —           | Joins a multi-user room via `BroadcastChannel("xr-live:room:<id>")` or a `wss://` relay (`xr-live-shared-room`).
    `shared-room-voice`   | boolean attribute                                                                              | `false`     | Opts in to voice **signaling** in `shared-room`: relays WebRTC offer/answer/ICE messages (`peerrtcsignal` event, `broadcastRtcSignal()`) and computes per-peer `voiceGain` (`computeSpatialVoiceGain`). Your app owns `getUserMedia`, `RTCPeerConnection`, and audio playback.
    `peer-name`           | `string` (max `32` chars)                                                                      | —           | Local peer display name broadcast in `shared-room`.
    `peer-color`          | `'#rrggbb'`                                                                                    | `'#38bdf8'` | Local peer 3D visor & laser ray tint color in `shared-room`.
    `bloom`               | `boolean \| string`                                                                            | —           | Enables HDR emissive bloom (`bloom`, `bloom="1.4"`, or `bloom="strength:1.2 threshold:0.75 radius:0.5"`).
    `outline`             | `boolean \| string`                                                                            | —           | Enables silhouette outlines on `selected-mesh` or nodes with `userData.xr.outline` (`outline="#38bdf8 0.03"`).
    `variant-name`        | `string`                                                                                       | —           | Selects active `KHR_materials_variants` colorway name (`viewer.variantName` / `viewer.availableVariants`).
    `webmcp`              | boolean attribute                                                                              | `false`     | Registers `inspect_xr_scene`, `place_xr_object_at_gaze`, and `capture_xr_view` on `navigator.modelContext`.
    `webmcp-allow-depth`  | boolean attribute                                                                              | `false`     | Opt-in gate allowing `capture_xr_view` to include the 8×8 metric `depthGridMeters` array.
    `webmcp-omit-pose`    | boolean attribute                                                                              | `false`     | When present, `inspect_xr_scene` omits `headPosition` entirely.
    
    ---
    
    ## 2. Canonical `userData.xr` Normalization & Clamping Rules
    
    Defined in `three-live/src/xr-trait-schema.ts`:
    
    ### `follow` (`LazyFollowOptions`)
    
    ```ts
    mesh.userData.xr = {
      follow: {
        mode: 'head',        // 'head' | 'hand-left' | 'hand-right' (default: 'head')
        lazy: true,          // false uses eager spring; true uses angular deadzone + critically damped spring
        distance: 1.0,       // [0.1, 10.0] meters (default: 1.0 for 'head', 0.15 for hands)
        deadzoneDeg: 15,     // [0, 90] degrees (default: 15 for 'head', 0 for hands)
        stiffness: 6,        // [0.5, 40] angular frequency omega (default: 6)
        height: -0.1,        // [-2.0, 2.0] vertical offset in meters (default: -0.1 for 'head', 0.12 for hands)
        faceUser: true,      // boolean (default: true)
        snapOnStart: true,   // boolean (default: true)
      },
    };
    ```
    
    ### `orbit` (`OrbitOptions`)
    
    ```ts
    mesh.userData.xr = {
      orbit: {
        target: 'sun',       // [x, y, z] finite tuple OR target mesh name (max 256 chars; default: [0, 0, 0])
        radius: 0.5,         // [0.01, 50] meters (default: 0.5)
        speed: 0.5,          // [-20, 20] radians/sec (default: 0.5)
        height: 0.0,         // [-10, 10] meters vertical offset from target (default: 0)
        phase: 0.0,          // [-1e6, 1e6] initial angle in radians (default: 0)
        faceCenter: false,   // boolean (default: false)
      },
    };
    ```
    
    ### `handles` (`HandlesOptions`)
    
    ```ts
    mesh.userData.xr = {
      handles: {
        rotateAxis: 'y',     // 'y' | 'none' (default: 'y')
        minScale: 0.1,       // [0.001, 1000] (default: 0.1)
        maxScale: 10.0,      // [minScale, 1000] (default: max(minScale, 10))
      },
    };
    ```
    
    ### `particles` (`ParticleOptions`)
    
    ```ts
    mesh.userData.xr = {
      particles: {
        preset: 'rain',      // 'rain' | 'snow' | 'sparks' | 'confetti' (default: 'rain')
        count: 600,          // [1, 2000] (defaults: rain=600, snow=400, sparks=300, confetti=300)
        area: [2, 2, 2],     // number or [x, y, z], each axis clamped to [0.05, 50] meters (default: [2, 2, 2])
        speed: 1.0,          // [0.05, 10] speed multiplier (default: 1.0)
      },
    };
    ```
    
    ### `holdToAsk` (`HoldToAskOptions`)
    
    ```ts
    mesh.userData.xr = {
      holdToAsk: {
        prompt: 'What is this?', // max 4000 chars (default: 'What is this?')
        holdMs: 600,             // [100, 5000] ms press-and-hold threshold (default: 600)
      },
    };
    ```
    
    ### `dimensions` (`DimensionsOptions`)
    
    ```ts
    mesh.userData.xr = {
      dimensions: {
        enabled: true,           // false disables (default: true)
        unit: 'auto',            // 'auto' | 'm' | 'cm' | 'mm' | 'in' | 'ft-in' (default: 'auto')
        axes: ['x', 'y', 'z'],   // subset of ['x', 'y', 'z'] or string 'xyz' (default: ['x', 'y', 'z'])
        color: '#38bdf8',        // sanitized #rgb / #rrggbb hex color (default: '#38bdf8')
        showOnSelect: false,     // when true, only displays callouts while selected (default: false)
      },
    };
    ```
    
    ### `snapTo` & `snapSocket` (`SnapToOptions` / `SnapSocketOptions`)
    
    ```ts
    // On the movable / grabbable part:
    part.userData.xr = {
      grab: '1-hand',
      snapTo: {
        grid: [0.05, 0.05, 0.05], // number or [gx, gy, gz] clamped to [0.001, 100] m (default: null)
        angleDeg: 15,             // [0, 180] yaw snap increment in degrees (default: 0)
        surface: 'floor',         // 'none' | 'floor' | 'wall' | 'ceiling' | 'any' (default: 'none')
        socketTag: 'module-bay',  // max 128 chars matching a snapSocket.tag (default: '')
        radius: 0.15,             // [0.01, 2.0] m capture radius; 1.25x breakaway hysteresis (default: 0.15)
      },
    };
    
    // On the stationary target socket:
    dock.userData.xr = {
      snapSocket: {
        tag: 'module-bay',        // required non-empty tag (max 128 chars)
        radius: 0.15,             // [0.01, 2.0] m capture radius; 1.5x pulsing preview ring (default: 0.15)
        alignRotation: true,      // slerps snapped part to socket orientation (default: true)
        highlightColor: '#22c55e',// sanitized hex color for preview ring (default: '#22c55e')
      },
    };
    ```
    
    ### `gaze` (`GazeOptions`)
    
    ```ts
    mesh.userData.xr = {
      gaze: {
        enabled: true,           // false disables (default: true)
        dwellMs: 1200,           // [250, 10000] ms after 150ms grace delay (default: 1200)
        repeat: false,           // when true, re-arms continuously while gazing (default: false)
        action: 'select',        // 'select' (fires meshclick + KHR_interactivity) | 'ask' (queries Gemini Live)
      },
    };
    ```
    
    ### `explode` (`ExplodeOptions`)
    
    ```ts
    mesh.userData.xr = {
      explode: {
        enabled: true,           // false pins a base/chassis mesh at rest (default: true)
        direction: [0, 1, 0],    // normalized [x, y, z] unit vector, or null to use explode-mode
        distance: 0.35,          // [0, 10] meters at explode="1" (default: 0.35)
        layer: 2,                // integer [1, 10] — outer layers separate earlier in staggered mode (default: 1)
        leaderLine: true,        // renders dashed 3D leader line back to rest position (default: true)
      },
    };
    ```
    
    ### `anchor` Persistence (`AnchorPersistOptions`), `navigable`, & `sync`
    
    ```ts
    mesh.userData.xr = {
      anchor: {
        target: 'table',         // optional: 'floor' | 'wall' | 'ceiling' | 'table' | 'horizontal' | 'vertical'
        id: 'turntable-1',       // sanitized key (max 128 chars; rejects __proto__/constructor/prototype)
        persist: true,           // persists across #xr-state URL hash, localStorage, and WebXR XRAnchor
      },
      navigable: 'walkable',     // true | 'walkable' | false | 'blocked' (spatial-locomotion)
      sync: true,                // boolean (shared-room; defaults to true on grabbable nodes)
    };
    ```
    
    ### `bloom`, `outline`, `ik`, `splat`, & `text` (`BloomTraitOptions` / `OutlineTraitOptions` / `IKTraitOptions` / `SplatTraitOptions` / `TextTraitOptions`)
    
    ```ts
    mesh.userData.xr = {
      bloom: {
        strength: 1.2,           // [0, 5] HDR bloom intensity (default: 1.0)
        threshold: 0.8,          // [0, 2] luminance threshold (default: 0.8)
        radius: 0.5,             // [0, 1] blur radius (default: 0.5)
      },
      outline: {
        color: '#38bdf8',        // sanitized #rgb / #rrggbb hex color (default: '#38bdf8')
        thickness: 0.03,         // [0.002, 0.25] outline width (default: 0.03)
      },
      ik: {
        root: 'Shoulder',        // required chain root node name
        mid: 'Forearm',          // optional middle joint (enables the two-bone solver)
        effector: 'WristEffector', // required end-effector node name
        target: 'GripperTarget', // required node name, 'head' / 'hand-left' / 'hand-right', or [x, y, z]
        pole: 'ElbowPole',       // optional pole node name or [x, y, z] (alias: poleTarget)
        solver: 'two-bone',      // 'two-bone' | 'fabrik' (default: 'two-bone' with mid, else 'fabrik')
        iterations: 8,           // integer [1, 32] for FABRIK (default: 8)
        tolerance: 0.001,        // [1e-5, 0.1] convergence tolerance in meters (default: 0.001)
        weight: 1,               // [0, 1] blend toward the solved pose (default: 1)
      },
      splat: {
        url: '/assets/room.spz', // safe https:// or clean relative .splat/.spz URL
        shDegree: 3,             // 0 | 1 | 2 | 3 Spherical Harmonics degree (default: 3)
        maxSplats: 500000,       // [1, 1000000] splat cap
      },
      text: {
        text: 'STAGE 1',         // max 256 chars
        size: 0.2,               // [0.01, 20] glyph height in meters (default: 0.2)
        depth: 0.04,             // [0.001, 10] extrusion depth in meters (default: 0.04)
        bevelEnabled: true,
        bevelThickness: 0.008,
        bevelSize: 0.006,
      },
    };
    ```
    
    ---
    
    ## 3. Declarative `KHR_interactivity` Authoring (`userData.interactivity`)
    
    Any mesh or group inside `<script type="text/three">` can declare interactive state machines compiled into standard Khronos `KHR_interactivity` graphs (`three-live/src/interactivity-compiler.ts`):
    
    - **Triggers:**
      - `onSelect`: Fired when clicked/tapped or pinched in XR (`pointer/onSelect`).
      - `onHoverIn` / `onHoverOut`: Fired on pointer/ray hover enter and exit.
      - `onStart`: Fired automatically when the scene loads (`event/onStart`).
      - `onReceive`: `{ [eventName: string]: Action | Action[] }` — reacts to custom events sent by `sendEvent`.
    - **Actions (single object or array executed in sequence):**
      - `{ action: 'toggleTransform', property: 'translation' | 'rotation' | 'scale', to: number[], from?: number[], duration?: number }`
      - `{ action: 'interpolate', target?: string, property: 'translation' | 'rotation' | 'scale' | 'baseColorFactor' | 'metallicFactor' | 'roughnessFactor' | 'emissiveFactor', to: number | number[], duration?: number }`
      - `{ action: 'setProperty', target?: string, property: string, value: any }`
      - `{ action: 'toggleVisibility', target?: string }`
      - `{ action: 'cycleMaterialColor', colors: Array<[number, number, number, number?]>, duration?: number }`
      - `{ action: 'playAnimation', animation?: number }` / `{ action: 'stopAnimation' }`
      - `{ action: 'sendEvent', event: string, values?: Record<string, any> }`
    
    ---
    
    ## 4. Programmatic Plugin Controllers (`xr-live/spatial`)
    
    When importing from `xr-live/spatial` (or using `xr-live-spatial.min.js` /
    `xr-live-full.min.js`):
    
    - **Gemini Live (`gemini-live.ts`):**
    
        ```ts
        import { connectGeminiLive } from 'xr-live/spatial';
    
        const live = connectGeminiLive(xrElement, {
          url: 'wss://your-backend.example.com/gemini-live', // wss:// required (or ws://localhost)
          model: 'models/gemini-2.0-flash-exp',
          systemInstruction: 'You are a spatial assistant.',
          frameIntervalMs: 1000,   // clamped to [250, 60000] ms
          streamAudio: true,       // streams 16 kHz PCM mic chunks
          playAudio: true,         // plays streamed 24 kHz PCM model audio
          speakReplies: false,     // SpeechSynthesis fallback
          detectObjects: true,     // auto-registers report_objects tool -> xr-object-detected events
        });
        ```
    - **Spatial Paint (`spatial-paint.ts`):**
    
        ```ts
        import { getSpatialPaintController } from 'xr-live/spatial';
    
        const paint = getSpatialPaintController(xrElement);
        paint.color = [0.22, 0.74, 0.97, 1.0];
        paint.radius = 0.008;
        paint.undo(xrElement.viewer);
        paint.clear(xrElement.viewer);
        ```
    - **World Understanding (`world-understanding.ts`):**
    
        ```ts
        import { detectObjects, parseDetections, XRTapeMeasure } from 'xr-live/spatial';
    
        const detections = parseDetections('[{"label":"chair","box":[200,300,800,700]}]');
        const located3D = detectObjects(xrElement, detections);
        ```
    -   **Spatial Measure, Exploded View, Persistent Anchors, Locomotion & Shared
        Room:**
    
        ```ts
        import {
          getSpatialMeasureController,
          getMagneticSnapController,
          getGazeDwellController,
          getExplodedViewController,
          getPersistentAnchorsController,
          getSpatialLocomotionController,
          getSharedRoomController,
        } from 'xr-live/spatial';
    
        xrElement.setExplode(0.65);                     // Smoothly animate exploded-view [0..1]
        xrElement.clearMeasurements();                  // Clear locked 3D tape-measure segments
        const token = xrElement.exportAnchorState();    // Base64url layout snapshot (<= 8 KB)
        xrElement.importAnchorState(token);             // Restore layout snapshot programmatically
        xrElement.teleportTo([0, 0, -1.5]);             // Teleport viewer rig + emit xrteleport
        const peers = xrElement.getSharedPeers();       // Active RemotePeerState[] in shared-room
        ```
    
    ---
    
    ## 5. DOM Events Summary
    
    Event Name                         | Dispatched By                | `event.detail` Payload
    :--------------------------------- | :--------------------------- | :---------------------
    `load`                             | `<three-live>` / `<xr-live>` | `{ model: GLBData }`
    `error`                            | `<three-live>` / `<xr-live>` | `{ error: Error }`
    `meshclick`                        | `<three-live>` / `<xr-live>` | `{ meshName, hitPoint, normal, distance }`
    `camera-change`                    | `<three-live>` / `<xr-live>` | `{ theta, phi, distance }`
    `ar-status`                        | `<three-live>` / `<xr-live>` | `{ status: 'session-started' \| 'not-presenting' \| 'failed', error? }`
    `interactivityEvent`               | `KHR_interactivity` VM       | `{ id: string, values: Record<string, any> }`
    `xr-select-start` / `move` / `end` | `XRInputManager`             | `{ hand: 'left' \| 'right' \| 'screen', pivotPosition, quaternion, rayOrigin, rayDirection, hit }`
    `xr-handles-change`                | `manipulation-handles`       | `{ mesh, scale: number, yawDeg: number }`
    `xr-object-detected`               | `world-understanding`        | `{ label: string, position: [number, number, number], distanceMeters: number, source: 'plane' \| 'depth' \| 'fallback' }`
    `xr-transcription`                 | `gemini-live`                | `{ speaker: 'user' \| 'model', text: string, isFinal: boolean }`
    `xr-hold-to-ask-listening`         | `gemini-live`                | `{ mesh: string }`
    `xr-hold-to-ask`                   | `gemini-live`                | `{ mesh: string, transcript: string, prompt: string }`
    `xr-gemini-interrupted`            | `gemini-live`                | `{}`
    `xr-paint-stroke`                  | `spatial-paint`              | `{ index: number, points: number, lengthMeters: number }`
    `measurecomplete`                  | `spatial-measure`            | `{ start: [x,y,z], end: [x,y,z], distanceMeters: number, formatted: string }`
    `xrsnap`                           | `magnetic-snap`              | `{ node, socket, position: [x,y,z], quaternion: [x,y,z,w], mode: 'socket' \| 'grid' \| 'surface' \| 'angle' }`
    `xrunsnap`                         | `magnetic-snap`              | `{ node, socket }`
    `gazeenter` / `gazeleave`          | `gaze-dwell`                 | `{ node, point: [x,y,z] }` / `{ node }`
    `gazedwell`                        | `gaze-dwell`                 | `{ node, point: [x,y,z], action: 'select' \| 'ask' }`
    `explodechange`                    | `exploded-view`              | `{ factor: number, source: 'attribute' \| 'gesture' \| 'api' \| 'peer' }`
    `anchorsrestored`                  | `persistent-anchors`         | `{ count: number, source: 'xr-anchor' \| 'storage' \| 'url-hash' }`
    `xrteleport`                       | `spatial-locomotion`         | `{ from: [x,y,z], to: [x,y,z], yawDeg: number }`
    `peerjoin` / `peerleave`           | `shared-room`                | `{ peerId: string, name: string, color: string }`
    `peergrabconflict`                 | `shared-room`                | `{ peerId: string, nodeId: string }`
    `peersync`                         | `shared-room`                | `{ peerId: string, nodeId: string }`
    `characterjump` / `characterland`  | `xr-live-sim`                | `{ nodeId, position }` / `{ nodeId, fallSpeed }`
    `agentstatechange` / `agentreach`  | `xr-live-sim`                | `{ nodeId, state, targetId }` / `{ agentId, targetId, position }`
    `xrhit` / `xrdepleted`             | `xr-live-sim`                | `{ targetId, sourceId, amount, remaining, point }` / `{ targetId, group, scoreValue }`
    `xrzoneenter` / `xrzoneexit`       | `xr-live-sim`                | `{ zoneId, nodeId, group }`
    `xrspawn`                          | `xr-live-sim`                | `{ spawnerId, instanceId, index }`
    `xrobjective`                      | `xr-live-sim`                | `{ nodeId, tag, type, amount, totalScore, remainingRequired, outOfOrder }`
    `xrscorechange`                    | `xr-live-sim`                | `{ score, delta, attemptsLeft, timeRemaining }`
    `xrscenarioend`                    | `xr-live-sim`                | `{ outcome: 'pass' \| 'fail' \| 'timeout', finalScore, elapsedSec }`
    `xr-webmcp-capture`                | `xr-extras` (WebMCP)         | Fired when `capture_xr_view` captures a frame (`data-xr-webmcp-indicator="active"`).
    
    --------------------------------------------------------------------------------
    
    ## 6. Simulation Plugins (`xr-live-sim`)
    
    Load `xr-live-sim.min.js` (global `XRSim`, included in `xr-live-full.min.js`) or
    import `xr-live/sim`. Systems step at a fixed 60 Hz (at most 5 steps per frame);
    at most 128 spawned instances exist per scene.
    
    Trait clamping (defaults in parentheses):
    
    -   **`character`:** `speed` 0.1–20 (4), `runMultiplier` 1–4 (1.6),
        `jumpVelocity` 0–30 (5.5), `gravity` 0–50 (15), `radius` 0.05–5 (0.35),
        `height` ≥ 2 × radius (1.4), `cameraMode` (`third-person`), `cameraDistance`
        0.5–50 (3.5), `cameraHeight` −10–50 (1.8).
    -   **`agent`:** `mode` (`wander`), `speed` 0.1–20 (2), `turnSpeed` 0.1–50 (6),
        `sightRadius` 0–100 (6), `stopDistance` 0.01–10 (0.6), `separationRadius`
        0–10 (0.8), up to 32 `waypoints`. `chase`, `flee`, and `follow` default
        `target` to `'user'`.
    -   **`integrity`:** `max` 1–1e6 (100), `group` (`neutral`), `cooldownMs`
        0–10000 (250), `hideOnDepleted` (true), `scoreValue`, `contactAmount` (0).
    -   **`zone`:** `shape` (`box`), `size` 0.01–1000 (1), `radius` (0.5), up to 16
        `watchGroups` (empty watches every tracked node).
    -   **`spawner`:** `intervalSec` 0.05–3600 (3), `maxActive` 1–32 (8),
        `totalCount` (0 = unlimited), `spawnRadius` 0–100 (0).
    -   **`objective`:** `type` (`pickup`), `amount` (10), `radius` 0.05–50 (0.65),
        `order` 0–1000 (0), `respawnSec` 0–3600 (0). Only pickups spin and bob by
        default.
    -   **`audioCues`:** event-to-cue map, `pitchJitter` 0–0.5 (0.08), `volume` 0–1
        (1), `spatial` (true).
    
    Host attributes: `character-controller`, `character-speed`, `character-jump`,
    `touch-joystick`, `steering-agents`, `hit-zones`, `fire-rate`,
    `projectile-speed`, `projectile-gravity`, `hit-amount`, `objectives`,
    `scenario-timer`, `target-score`, `attempts`, `sim-hud`, `synth-audio`, and
    `synth-volume`. `XRSim.resetSimScenario(element)` restarts the scenario.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/google-three-live-skills-three-live-authoring.md

// REPO STATS

375 stars