@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/SpatializedStatic3DElement.ts

@@ -1,8 +1,10 @@
 import { UpdateSpatializedStatic3DElementProperties } from './JSBCommand'
 import { ReceiveEventData, SpatializedElement } from './SpatializedElement'
 import {
+  ModelLoadingMode,
   ModelSource,
   SpatializedStatic3DElementProperties,
+  StageMode,
 } from './types/types'
 import {
   ModelLoadSuccess,
@@ -10,6 +12,7 @@ import {
   SpatialWebMsgType,
   AnimationStateChangeDetail,
   AnimationStateChangeMsg,
+  EntityTransformChangeMsg,
 } from './WebMsgCommand'
 
 /**
@@ -18,17 +21,29 @@ import {
  * and provides events for load success and failure.
  */
 export class SpatializedStatic3DElement extends SpatializedElement {
+  /**
+   * Identifies the motion target kind supported by this element.
+   */
+  override readonly kind = 'static3d' as const
+
   /**
    * Creates a new spatialized static 3D element with the specified ID and URL.
    * Registers the element to receive spatial events.
    * @param id Unique identifier for this element
    * @param modelURL URL of the 3D model
    * @param sources Optional fallback model sources
+   * @param loading Initial loading mode (`'eager'` by default)
    */
-  constructor(id: string, modelURL?: string, sources?: ModelSource[]) {
+  constructor(
+    id: string,
+    modelURL?: string,
+    sources?: ModelSource[],
+    loading: ModelLoadingMode = 'eager',
+  ) {
     super(id)
     this.modelURL = modelURL
     this.sources = sources
+    this._loading = loading
   }
 
   /**
@@ -42,6 +57,10 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * Used to reset the ready promise when the model URL changes.
    */
   private modelURL?: string
+  // @TODO: Deprecate modelURL property from Web and Swift code
+  get modelUrl(): string | undefined {
+    return this.modelURL
+  }
 
   /**
    * Caches the last sources array to detect changes.
@@ -109,8 +128,26 @@ export class SpatializedStatic3DElement extends SpatializedElement {
       this._loop = properties.loop
     }
     if (properties.playbackRate !== undefined) {
+      // Re-anchor so extrapolation uses the new rate only for future elapsed
+      // time, not the window between the last sample and this change.
+      if (!this._paused) {
+        this._currentTime = this.currentTime
+        this._anchorTimestamp = Date.now()
+      }
       this._playbackRate = properties.playbackRate
     }
+    if (properties.currentTime !== undefined) {
+      // Optimistically update the local anchor so subsequent reads reflect
+      // the requested seek without waiting for the next native sample.
+      this._currentTime = properties.currentTime
+      this._anchorTimestamp = Date.now()
+    }
+    if (properties.loading !== undefined) {
+      this._loading = properties.loading
+    }
+    if (properties.stagemode !== undefined) {
+      this._stagemode = properties.stagemode
+    }
     return new UpdateSpatializedStatic3DElementProperties(
       this,
       properties,
@@ -148,6 +185,49 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     this.updateProperties({ playbackRate: value })
   }
 
+  /**
+   * Last playback position sampled from native (seconds).
+   */
+  private _currentTime: number = 0
+
+  /**
+   * Unix epoch time (ms) corresponding to `_currentTime`. Sourced from the
+   * native `timestamp` on samples, or `Date.now()` on local seeks/transitions.
+   */
+  private _anchorTimestamp: number = 0
+
+  private clampTime(time: number): number {
+    if (!Number.isFinite(time) || time < 0) return 0
+    // When looping the current time is modulo the duration
+    if (time > this._duration) {
+      return this.loop && this.duration > 0
+        ? time % this._duration
+        : this.duration
+    }
+    return time
+  }
+
+  /**
+   * Returns the current (un-scaled) playback position in seconds. While
+   * playing, the value is extrapolated from the last anchor using
+   * `playbackRate` and clamped to `[0, duration]`; while paused it returns
+   * the anchor directly.
+   */
+  get currentTime(): number {
+    if (this._paused) return this._currentTime
+    const elapsed = (Date.now() - this._anchorTimestamp) / 1000
+    return this.clampTime(this._currentTime + elapsed * this._playbackRate)
+  }
+
+  /**
+   * Seeks the animation to `value` seconds (clamped to `[0, duration]`) and
+   * forwards the request to native.
+   */
+  set currentTime(value: number) {
+    const time = Number.isNaN(value) ? 0 : clamp(value, 0, this.duration)
+    this.updateProperties({ currentTime: time })
+  }
+
   /**
    * Whether the animation is currently paused.
    */
@@ -181,6 +261,10 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * @returns Promise resolving when the command is sent
    */
   async play(): Promise<void> {
+    if (this._paused) {
+      // Start extrapolating from the last known position on resume.
+      this._anchorTimestamp = Date.now()
+    }
     this._paused = false
     await this.updateProperties({ animationPaused: false })
   }
@@ -190,6 +274,12 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * @returns Promise resolving when the command is sent
    */
   async pause(): Promise<void> {
+    if (!this._paused) {
+      // Freeze the extrapolated position so reads remain stable until the
+      // next native sample arrives.
+      this._currentTime = this.currentTime
+      this._anchorTimestamp = Date.now()
+    }
     this._paused = true
     await this.updateProperties({ animationPaused: true })
   }
@@ -213,7 +303,12 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     } else if (data.type === SpatialWebMsgType.animationstatechange) {
       this._paused = data.detail.paused
       this._duration = data.detail.duration
+      // In unsupported environments currentTime is invalid
+      this._currentTime = data.detail.currentTime ?? 0
+      this._anchorTimestamp = data.detail.timestamp ?? Date.now()
       this._onAnimationStateChangeCallback?.(data.detail)
+    } else if (data.type === SpatialWebMsgType.entitytransformchange) {
+      this._entityTransform = new DOMMatrixReadOnly(data.detail.transform)
     } else {
       // Handle other spatial events using the base class implementation
       super.onReceiveEvent(data)
@@ -232,6 +327,16 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     return this._autoplay
   }
 
+  /**
+   * Asset fetch policy. `'lazy'` defers fetching until the host signals the
+   * element is in view; `'eager'` fetches immediately.
+   */
+  private _loading: ModelLoadingMode = 'eager'
+
+  get loading(): ModelLoadingMode {
+    return this._loading
+  }
+
   /**
    * Whether the model animation should loop continuously.
    */
@@ -270,10 +375,41 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     this._onLoadFailureCallback = callback
   }
 
-  updateModelTransform(transform: DOMMatrixReadOnly) {
-    const modelTransform = Array.from(transform.toFloat64Array())
-    this.updateProperties({ modelTransform })
+  /**
+   * Built-in interaction mode. In `'orbit'` the native layer drives the
+   * transform and `entityTransform` is read-only.
+   */
+  private _stagemode: StageMode = 'none'
+
+  get stagemode(): StageMode {
+    return this._stagemode
+  }
+
+  /**
+   * Latest transform of the model, including native-driven manipulations such
+   * as orbit interaction.
+   */
+  private _entityTransform: DOMMatrixReadOnly = new DOMMatrixReadOnly()
+
+  get entityTransform(): DOMMatrixReadOnly {
+    return this._entityTransform
   }
+
+  set entityTransform(transform: DOMMatrixReadOnly) {
+    // In orbit mode the native layer owns the transform, so ignore writes.
+    if (this._stagemode === 'orbit') return
+    this._entityTransform = transform
+    // The public API is `entityTransform`, but the JSB property stays
+    // `modelTransform` so the native side remains backward compatible.
+    this.updateProperties({
+      modelTransform: Array.from(transform.toFloat64Array()),
+    })
+  }
+}
+
+// Equivalent of proposed Math.clamp
+function clamp(num: number, min: number, max: number) {
+  return num <= min ? min : num >= max ? max : num
 }
 
 type Static3DReceiveEventData =
@@ -281,3 +417,4 @@ type Static3DReceiveEventData =
   | ModelLoadFailure
   | ReceiveEventData
   | AnimationStateChangeMsg
+  | EntityTransformChangeMsg

package/src/WebMsgCommand.ts

@@ -21,6 +21,14 @@ export enum SpatialWebMsgType {
 
   animationstatechange = 'animationstatechange',
 
+  // Native-driven transform updates (e.g. while in `stagemode="orbit"`)
+  entitytransformchange = 'entitytransformchange',
+
+  // Animation terminal events (keyed by animationId, not by this enum)
+  animationcompleted = 'animationcompleted',
+  animationstopped = 'animationstopped',
+  animationfailed = 'animationfailed',
+
   objectdestroy = 'objectdestroy',
 }
 
@@ -81,9 +89,51 @@ export interface ModelLoadFailure {
 export interface AnimationStateChangeDetail {
   paused: boolean
   duration: number
+  /**
+   * Sampled animation playback position in seconds at `timestamp`.
+   * Optional for compatibility with older native runtimes.
+   */
+  currentTime?: number
+  /**
+   * Unix epoch time in milliseconds at which `currentTime` was sampled.
+   * Used to extrapolate `currentTime` between samples while playing.
+   */
+  timestamp?: number
 }
 
 export interface AnimationStateChangeMsg {
   type: SpatialWebMsgType.animationstatechange
   detail: AnimationStateChangeDetail
 }
+
+export interface EntityTransformChangeDetail {
+  /** Column-major 4x4 matrix (16 numbers) representing the manipulated transform. */
+  transform: number[]
+}
+
+export interface EntityTransformChangeMsg {
+  type: SpatialWebMsgType.entitytransformchange
+  detail: EntityTransformChangeDetail
+}
+
+// Animation terminal event payloads (delivered via SpatialWebEvent keyed by animationId)
+
+export interface AnimationCompletedEventPayload {
+  type: 'completed'
+  /** Column-major 4x4 matrix (16 numbers) representing the final native transform. */
+  transform: number[]
+}
+
+export interface AnimationCanceledEventPayload {
+  type: 'canceled'
+  /** Column-major 4x4 matrix (16 numbers) representing the restored transform after cancel. */
+  transform: number[]
+}
+
+export interface AnimationFailedEventPayload {
+  type: 'failed'
+  animationId: string
+  command: 'play' | 'pause' | 'resume' | 'cancel'
+  code?: string
+  reason: string
+}