three-live 1.2.0 → 1.2.2

package/README.md

@@ -41,11 +41,16 @@ display existing models only, use the viewer-only build:
 
 ## Bundles
 
+<!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
 | File | Contents |
 | :--- | :--- |
 | `dist/three-live-viewer.min.js` | Viewer only: `.glb` display, PBR, orbit controls, animation |
 | `dist/three-live.min.js` | Standard: viewer + sandboxed `<script type="text/three">` + AR handoff |
-| `dist/three-live-full.min.js` | Standard + all plugins (extras, animation) |
+| `dist/three-live-studio.min.js` | Add-on: PBR Next, HDRI/SH, `bloom`/`outline`, `KHR_materials_variants`, `EXT_meshopt_compression`, `KHR_interactivity` VM, hotspots |
+| `dist/three-live-cad.min.js` | Add-on: 2D `Path`/`Shape`, `ExtrudeGeometry`, 3D `CSG` Booleans, Hershey `TextGeometry` |
+| `dist/three-live-animation.min.js` | Add-on: 64-joint skinning, morph targets, keyframe cross-fading, 2-bone/FABRIK `IKSolver` |
+| `dist/three-live-full.min.js` | Standard + all plugins (`studio`, `cad`, `animation`) |
+<!-- mdformat on -->
 
 ES module and CommonJS builds are available through the package `exports`.
 

package/dist/index.d.ts

@@ -30,12 +30,12 @@ import type {
 } from './three-live/src/three-view';
 import type {ARLaunchResult, ARMode} from './three-live/src/three-xr';
 import type {
+  Detection3D,
   DimensionUnit,
   ExplodeMode,
   RemotePeerState,
   SnapSurfaceMode,
   TranscriptEvent,
-  Detection3D,
 } from './xr-live/src/plugins/index';
 import type {
   XRAnchorElement,
@@ -48,6 +48,29 @@ import type {
 } from './xr-live/src/xr-live-element';
 
 export * from './three-live/src/core';
+export {
+  cadPlugin,
+  installCadExtension,
+  MAX_BSP_DEPTH,
+  MAX_CSG_TRIANGLES,
+  MAX_TEXT_GEOMETRY_CHARS,
+  type ExtrudeGeometryOptions,
+  type TextGeometryOptions,
+} from './three-live/src/plugins/cad';
+export {
+  ikPlugin,
+  IKSolver,
+  quatFromUnitVectors,
+  solveFABRIK,
+  solveTwoBoneIK,
+  type FABRIKSolution,
+  type IKQuat,
+  type TwoBoneIKSolution,
+} from './three-live/src/plugins/ik';
+export {
+  extractNodeInstancing,
+  instancingPlugin,
+} from './three-live/src/plugins/instancing';
 export {
   getInteractivityVM,
   interactivityPlugin,
@@ -63,6 +86,30 @@ export {
   type InteractivityValueSocket,
   type InteractivityVariableDef,
 } from './three-live/src/plugins/interactivity';
+export {
+  applyMeshoptFilter,
+  decodeMeshoptBuffer,
+  decodeMeshoptGLB,
+  encodeMeshoptBuffer,
+  meshoptDecoder,
+  meshoptPlugin,
+  type MeshoptFilter,
+  type MeshoptMode,
+} from './three-live/src/plugins/meshopt';
+export {
+  computeOutlineClipOffset,
+  evaluateKawaseBloom,
+  parseHexRgb,
+  postprocessingPlugin,
+  resolveViewerBloom,
+} from './three-live/src/plugins/postprocessing';
+export {
+  extractMaterialVariants,
+  extractPrimitiveVariantMappings,
+  selectMaterialVariant,
+  variantsPlugin,
+  type VariantMapping,
+} from './three-live/src/plugins/variants';
 export {
   ThreeLiveElement,
   type ARLaunchOptions,
@@ -80,7 +127,7 @@ export {
   type XRProfile,
   type XRSimulatorRoom,
 } from './xr-live/src/xr-live-element';
-/** Optional spatial plugins (`xr-live/plugins`, `xr-live-plugins.min.js`). */
+/** Optional spatial plugins (`xr-live/spatial`, `xr-live-spatial.min.js`). */
 export * from './xr-live/src/plugins/index';
 
 /**
@@ -119,7 +166,7 @@ export interface ThreeLiveAttributes {
   'shadow-intensity'?: number | string;
   /** Radial Gaussian blur falloff of contact shadow (0.0 to 1.0). */
   'shadow-softness'?: number | string;
-  /** Tone mapping mode ("neutral", "reinhard", "none"). */
+  /** Tone mapping mode ("neutral", "aces", "agx", "reinhard", "none"). */
   'tone-mapping'?: string;
   /** Enable or disable interactive camera orbit/pan/zoom controls (default: true). */
   'camera-controls'?: boolean | string;
@@ -127,6 +174,8 @@ export interface ThreeLiveAttributes {
   'autoplay'?: boolean | string;
   /** Name of specific glTF animation clip to play. */
   'animation-name'?: string;
+  /** Name of the active KHR_materials_variants material variant. */
+  'variant-name'?: string;
   /** Automatically rotate scene around the Y-axis when user is idle. */
   'auto-rotate'?: boolean | string;
   /** Delay in milliseconds before auto-rotation resumes after user interaction (default: 3000). */
@@ -162,6 +211,7 @@ export interface ThreeLiveAttributes {
   onerror?: (e: CustomEvent<{error: any}>) => void;
   onmeshclick?: (e: CustomEvent<HitDetail>) => void;
   'oncamera-change'?: (e: CustomEvent<CameraDetail>) => void;
+  'onvariant-applied'?: (e: CustomEvent<{variantName: string | null}>) => void;
   'onar-status'?: (
     e: CustomEvent<{
       status: 'session-started' | 'not-presenting' | 'failed';
@@ -193,7 +243,7 @@ export interface XRLiveAttributes extends ThreeLiveAttributes {
   'xr-depth'?: XRDepthMode;
   /** 25-joint hand tracking and gesture recognition mode ("gestures", "joints", "pinch", "none"). */
   'xr-hands'?: XRHandsMode;
-  /** Desktop room simulator environment ("living-room", "office", "tabletop", "none"). */
+  /** Desktop 3D room preview environment, unrelated to `xr-live-sim` ("living-room", "office", "tabletop", "none"). */
   'xr-simulator'?: XRSimulatorRoom;
   /** Spatial UI profile ("quest3", "android-xr", "visionos", "auto"). */
   'xr-profile'?: XRProfile;
@@ -208,7 +258,14 @@ export interface XRLiveAttributes extends ThreeLiveAttributes {
   /** Default display unit for `spatial-measure` ("auto", "m", "cm", "mm", "in", "ft-in"). */
   'measure-unit'?: DimensionUnit;
   /** Spatial plugin: socket, grid, surface, and angle snapping ("grid", "surface", "sockets", "all", "none"). */
-  'magnetic-snap'?: boolean | 'grid' | 'surface' | 'sockets' | 'all' | 'none' | string;
+  'magnetic-snap'?:
+    | boolean
+    | 'grid'
+    | 'surface'
+    | 'sockets'
+    | 'all'
+    | 'none'
+    | string;
   /** Cartesian snap grid step in meters ("0.05" or "0.05 0.05 0.05"). */
   'snap-grid'?: number | string;
   /** Rotational yaw snap increment in degrees (0 to 180). */
@@ -241,6 +298,47 @@ export interface XRLiveAttributes extends ThreeLiveAttributes {
   'peer-name'?: string;
   /** Local avatar visor & laser color (`#rrggbb`) in `shared-room`. */
   'peer-color'?: string;
+  /** Opt-in WebRTC spatial voice chat signaling and HRTF distance attenuation in `shared-room`. */
+  'shared-room-voice'?: boolean | string;
+  /** xr-live-sim: character camera mode, or `none` to disable the character. */
+  'character-controller'?:
+    | 'third-person'
+    | 'first-person'
+    | 'top-down'
+    | 'fixed-camera'
+    | 'none';
+  /** xr-live-sim: character speed override (m/s). */
+  'character-speed'?: number | string;
+  /** xr-live-sim: character jump velocity override (m/s). */
+  'character-jump'?: number | string;
+  /** xr-live-sim: on-screen joystick (`auto` shows it on touch screens). */
+  'touch-joystick'?: 'auto' | 'always' | 'none';
+  /** xr-live-sim: `false` or `none` pauses steering agents. */
+  'steering-agents'?: boolean | string;
+  /** xr-live-sim: firing mode (empty means `projectile`). */
+  'hit-zones'?: '' | 'projectile' | 'hitscan' | 'contact' | 'off';
+  /** xr-live-sim: shots per second (default: 4). */
+  'fire-rate'?: number | string;
+  /** xr-live-sim: projectile speed in m/s (default: 14). */
+  'projectile-speed'?: number | string;
+  /** xr-live-sim: projectile gravity in m/s² (default: 0). */
+  'projectile-gravity'?: number | string;
+  /** xr-live-sim: integrity removed per hit (default: 25). */
+  'hit-amount'?: number | string;
+  /** xr-live-sim: enables objectives and scoring (`none` disables). */
+  'objectives'?: boolean | string;
+  /** xr-live-sim: scenario countdown in seconds. */
+  'scenario-timer'?: number | string;
+  /** xr-live-sim: score that passes the scenario. */
+  'target-score'?: number | string;
+  /** xr-live-sim: attempts before the scenario fails. */
+  'attempts'?: number | string;
+  /** xr-live-sim: score HUD style. */
+  'sim-hud'?: 'auto' | 'minimal' | 'none';
+  /** xr-live-sim: plays procedural audio cues (`muted` disables). */
+  'synth-audio'?: boolean | string;
+  /** xr-live-sim: cue volume from 0 to 1 (default: 0.7). */
+  'synth-volume'?: number | string;
   /** Register WebMCP browser AI tools on `navigator.modelContext`. */
   'webmcp'?: boolean | string;
   /** Opt-in gate allowing WebMCP `capture_xr_view` to include the 8x8 depth grid. */
@@ -314,7 +412,85 @@ export interface XRLiveAttributes extends ThreeLiveAttributes {
     e: CustomEvent<Pick<RemotePeerState, 'peerId' | 'name' | 'color'>>,
   ) => void;
   onpeersync?: (e: CustomEvent<{peerId: string; nodeId: string}>) => void;
-  onpeergrabconflict?: (e: CustomEvent<{peerId: string; nodeId: string}>) => void;
+  onpeergrabconflict?: (
+    e: CustomEvent<{peerId: string; nodeId: string}>,
+  ) => void;
+  onpeerrtcsignal?: (
+    e: CustomEvent<{
+      peerId: string;
+      targetPeerId: string;
+      signalType: 'offer' | 'answer' | 'ice';
+      sdp: string | null;
+      candidate: string | null;
+      sdpMid: string | null;
+      sdpMLineIndex: number | null;
+    }>,
+  ) => void;
+  /** xr-live-sim events. */
+  oncharacterjump?: (
+    e: CustomEvent<{nodeId: string; position: [number, number, number]}>,
+  ) => void;
+  oncharacterland?: (
+    e: CustomEvent<{nodeId: string; fallSpeed: number}>,
+  ) => void;
+  onagentstatechange?: (
+    e: CustomEvent<{nodeId: string; state: string; targetId: string | null}>,
+  ) => void;
+  onagentreach?: (
+    e: CustomEvent<{
+      agentId: string;
+      targetId: string;
+      position: [number, number, number];
+    }>,
+  ) => void;
+  onxrhit?: (
+    e: CustomEvent<{
+      targetId: string;
+      /** Shooter node name, or `'user'`. */
+      sourceId: string;
+      amount: number;
+      remaining: number;
+      point: [number, number, number];
+    }>,
+  ) => void;
+  onxrdepleted?: (
+    e: CustomEvent<{targetId: string; group: string; scoreValue: number}>,
+  ) => void;
+  onxrzoneenter?: (
+    e: CustomEvent<{zoneId: string; nodeId: string; group: string}>,
+  ) => void;
+  onxrzoneexit?: (
+    e: CustomEvent<{zoneId: string; nodeId: string; group: string}>,
+  ) => void;
+  onxrspawn?: (
+    e: CustomEvent<{spawnerId: string; instanceId: string; index: number}>,
+  ) => void;
+  onxrobjective?: (
+    e: CustomEvent<{
+      nodeId: string;
+      tag: string;
+      type: string;
+      amount: number;
+      totalScore: number;
+      remainingRequired: number;
+      outOfOrder: boolean;
+    }>,
+  ) => void;
+  onxrscorechange?: (
+    e: CustomEvent<{
+      score: number;
+      delta: number;
+      attemptsLeft: number | null;
+      timeRemaining: number | null;
+    }>,
+  ) => void;
+  onxrscenarioend?: (
+    e: CustomEvent<{
+      outcome: 'pass' | 'fail' | 'timeout';
+      finalScore: number;
+      elapsedSec: number;
+    }>,
+  ) => void;
 }
 
 declare global {