@webspatial/core-sdk 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspatial/core-sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "this is the core js API for webspatial",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/JSBCommand.ts

@@ -24,6 +24,7 @@ import {
   Vec3,
   AttachmentEntityOptions,
   AttachmentEntityUpdateOptions,
+  ModelSource,
 } from './types/types'
 import { SpatialSceneCreationOptionsInternal } from './types/internal'
 import { composeSRT } from './utils'
@@ -289,13 +290,17 @@ export class AddSpatializedElementToSpatialScene extends JSBCommand {
 export class CreateSpatializedStatic3DElementCommand extends JSBCommand {
   commandType = 'CreateSpatializedStatic3DElement'
 
-  constructor(readonly modelURL: string) {
+  constructor(
+    readonly modelURL?: string,
+    readonly sources?: ModelSource[],
+  ) {
     super()
     this.modelURL = modelURL
+    this.sources = sources
   }
 
   protected getParams() {
-    return { modelURL: this.modelURL }
+    return { modelURL: this.modelURL, sources: this.sources }
   }
 }
 

package/src/Spatial.ts

@@ -29,7 +29,7 @@ export class Spatial {
    * @returns True if running in a spatial web environment, false otherwise
    */
   runInSpatialWeb() {
-    if (navigator.userAgent.indexOf('WebSpatial/') > 0) {
+    if (navigator.userAgent.indexOf('WebSpatial/') >= 0) {
       return true
     }
     return false

package/src/SpatialSession.ts

@@ -22,6 +22,7 @@ import {
   SpatialUnlitMaterialOptions,
   SpatialEntityUserData,
   AttachmentEntityOptions,
+  ModelSource,
 } from './types/types'
 import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
 import { SpatialEntity } from './reality/entity/SpatialEntity'
@@ -72,9 +73,10 @@ export class SpatialSession {
    * @returns Promise resolving to a new SpatializedStatic3DElement instance
    */
   createSpatializedStatic3DElement(
-    modelURL: string,
+    modelURL?: string,
+    sources?: ModelSource[],
   ): Promise<SpatializedStatic3DElement> {
-    return createSpatializedStatic3DElement(modelURL)
+    return createSpatializedStatic3DElement(modelURL, sources)
   }
 
   /**

package/src/SpatializedElement.ts

@@ -111,16 +111,7 @@ export abstract class SpatializedElement extends SpatialObject {
    * Handles various spatial events like transforms, gestures, and interactions.
    * @param data The event data received from the WebSpatial system
    */
-  protected onReceiveEvent(
-    data:
-      | SpatialTapMsg
-      | SpatialDragStartMsg
-      | SpatialDragMsg
-      | SpatialDragEndMsg
-      | SpatialRotateMsg
-      | SpatialRotateEndMsg
-      | ObjectDestroyMsg,
-  ) {
+  protected onReceiveEvent(data: ReceiveEventData) {
     const { type } = data
     if (type === SpatialWebMsgType.objectdestroy) {
       this.isDestroyed = true
@@ -260,3 +251,12 @@ export abstract class SpatializedElement extends SpatialObject {
     SpatialWebEvent.removeEventReceiver(this.id)
   }
 }
+
+export type ReceiveEventData =
+  | SpatialTapMsg
+  | SpatialDragStartMsg
+  | SpatialDragMsg
+  | SpatialDragEndMsg
+  | SpatialRotateMsg
+  | SpatialRotateEndMsg
+  | ObjectDestroyMsg

package/src/SpatializedElementCreator.ts

@@ -6,6 +6,7 @@ import {
 import { Spatialized2DElement } from './Spatialized2DElement'
 import { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
 import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
+import { ModelSource } from './types/types'
 
 export async function createSpatialized2DElement(): Promise<Spatialized2DElement> {
   const result = await new createSpatialized2DElementCommand().execute()
@@ -21,16 +22,18 @@ export async function createSpatialized2DElement(): Promise<Spatialized2DElement
 }
 
 export async function createSpatializedStatic3DElement(
-  modelURL: string,
+  modelURL?: string,
+  sources?: ModelSource[],
 ): Promise<SpatializedStatic3DElement> {
   const result = await new CreateSpatializedStatic3DElementCommand(
     modelURL,
+    sources,
   ).execute()
   if (!result.success) {
     throw new Error('createSpatializedStatic3DElement failed')
   } else {
     const { id } = result.data
-    return new SpatializedStatic3DElement(id, modelURL)
+    return new SpatializedStatic3DElement(id, modelURL, sources)
   }
 }
 

package/src/SpatializedStatic3DElement.test.ts

@@ -32,10 +32,24 @@ describe('SpatializedStatic3DElement', () => {
     const el = new SpatializedStatic3DElement('s2', 'model.glb')
     const p = el.ready
 
-    el.onReceiveEvent({ type: SpatialWebMsgType.modelloaded })
+    el.onReceiveEvent({
+      type: SpatialWebMsgType.modelloaded,
+      detail: { src: 'https://example.com/model.glb' },
+    })
     await expect(p).resolves.toBe(true)
   })
 
+  it('sets currentSrc from modelloaded detail data', () => {
+    const el = new SpatializedStatic3DElement('s2b', 'model.glb')
+
+    el.onReceiveEvent({
+      type: SpatialWebMsgType.modelloaded,
+      detail: { src: 'https://cdn.example.com/fallback.usdz' },
+    })
+
+    expect(el.currentSrc).toBe('https://cdn.example.com/fallback.usdz')
+  })
+
   it('ready resolves to false on modelloadfailed event', async () => {
     const el = new SpatializedStatic3DElement('s3', 'model.glb')
     const p = el.ready

package/src/SpatializedStatic3DElement.ts

@@ -1,7 +1,16 @@
 import { UpdateSpatializedStatic3DElementProperties } from './JSBCommand'
-import { SpatializedElement } from './SpatializedElement'
-import { SpatializedStatic3DElementProperties } from './types/types'
-import { SpatialWebMsgType } from './WebMsgCommand'
+import { ReceiveEventData, SpatializedElement } from './SpatializedElement'
+import {
+  ModelSource,
+  SpatializedStatic3DElementProperties,
+} from './types/types'
+import {
+  ModelLoadSuccess,
+  ModelLoadFailure,
+  SpatialWebMsgType,
+  AnimationStateChangeDetail,
+  AnimationStateChangeMsg,
+} from './WebMsgCommand'
 
 /**
  * Represents a static 3D model element in the spatial environment.
@@ -14,10 +23,12 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * 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
    */
-  constructor(id: string, modelURL: string) {
+  constructor(id: string, modelURL?: string, sources?: ModelSource[]) {
     super(id)
     this.modelURL = modelURL
+    this.sources = sources
   }
 
   /**
@@ -30,7 +41,21 @@ export class SpatializedStatic3DElement extends SpatializedElement {
    * Caches the last model URL to detect changes.
    * Used to reset the ready promise when the model URL changes.
    */
-  private modelURL: string
+  private modelURL?: string
+
+  /**
+   * Caches the last sources array to detect changes.
+   */
+  private sources?: ModelSource[]
+
+  /**
+   * The model URL that was successfully loaded by the native runtime.
+   */
+  private _currentSrc: string = ''
+
+  get currentSrc(): string {
+    return this._currentSrc
+  }
 
   /**
    * Creates a new promise for tracking the ready state of the model.
@@ -59,25 +84,125 @@ export class SpatializedStatic3DElement extends SpatializedElement {
   async updateProperties(
     properties: Partial<SpatializedStatic3DElementProperties>,
   ) {
+    let needsReadyReset = false
     if (properties.modelURL !== undefined) {
       if (this.modelURL !== properties.modelURL) {
         this.modelURL = properties.modelURL
-        this.ready = this.createReadyPromise()
+        needsReadyReset = true
+      }
+    }
+    if (properties.sources !== undefined) {
+      const prevJson = JSON.stringify(this.sources)
+      const nextJson = JSON.stringify(properties.sources)
+      if (prevJson !== nextJson) {
+        this.sources = properties.sources
+        needsReadyReset = true
       }
     }
+    if (needsReadyReset) {
+      this.ready = this.createReadyPromise()
+    }
+    if (properties.autoplay !== undefined) {
+      this._autoplay = properties.autoplay
+    }
+    if (properties.loop !== undefined) {
+      this._loop = properties.loop
+    }
+    if (properties.playbackRate !== undefined) {
+      this._playbackRate = properties.playbackRate
+    }
     return new UpdateSpatializedStatic3DElementProperties(
       this,
       properties,
     ).execute()
   }
 
+  /**
+   * Total animation duration in seconds, synced from native.
+   */
+  private _duration: number = 0
+
+  /**
+   * Returns the total animation duration in seconds.
+   */
+  get duration(): number {
+    return this._duration
+  }
+
+  /**
+   * Playback speed multiplier.
+   */
+  private _playbackRate: number = 1
+
+  /**
+   * Returns the current playback rate.
+   */
+  get playbackRate(): number {
+    return this._playbackRate
+  }
+
+  /**
+   * Sets the playback rate and sends it to native.
+   */
+  set playbackRate(value: number) {
+    this.updateProperties({ playbackRate: value })
+  }
+
+  /**
+   * Whether the animation is currently paused.
+   */
+  private _paused: boolean = true
+
+  /**
+   * Returns whether the animation is currently paused.
+   */
+  get paused(): boolean {
+    return this._paused
+  }
+
+  /**
+   * Callback for animation state changes.
+   */
+  private _onAnimationStateChangeCallback?: (
+    detail: AnimationStateChangeDetail,
+  ) => void
+
+  /**
+   * Sets the callback for animation state changes.
+   */
+  set onAnimationStateChangeCallback(
+    callback: undefined | ((detail: AnimationStateChangeDetail) => void),
+  ) {
+    this._onAnimationStateChangeCallback = callback
+  }
+
+  /**
+   * Starts or resumes animation playback.
+   * @returns Promise resolving when the command is sent
+   */
+  async play(): Promise<void> {
+    this._paused = false
+    await this.updateProperties({ animationPaused: false })
+  }
+
+  /**
+   * Pauses animation playback.
+   * @returns Promise resolving when the command is sent
+   */
+  async pause(): Promise<void> {
+    this._paused = true
+    await this.updateProperties({ animationPaused: true })
+  }
+
   /**
    * Processes events received from the WebSpatial environment.
    * Handles model loading events in addition to base spatial events.
    * @param data The event data received from the WebSpatial system
    */
-  override onReceiveEvent(data: { type: SpatialWebMsgType }) {
+  override onReceiveEvent(data: Static3DReceiveEventData) {
     if (data.type === SpatialWebMsgType.modelloaded) {
+      // On old runtimes (<⍺2.1) detail is not returned so fallback to modelURL
+      this._currentSrc = data.detail?.src ?? this.modelURL ?? ''
       // Handle successful model loading
       this._onLoadCallback?.()
       this._readyResolve?.(true)
@@ -85,12 +210,40 @@ export class SpatializedStatic3DElement extends SpatializedElement {
       // Handle model loading failure
       this._onLoadFailureCallback?.()
       this._readyResolve?.(false)
+    } else if (data.type === SpatialWebMsgType.animationstatechange) {
+      this._paused = data.detail.paused
+      this._duration = data.detail.duration
+      this._onAnimationStateChangeCallback?.(data.detail)
     } else {
       // Handle other spatial events using the base class implementation
-      super.onReceiveEvent(data as any)
+      super.onReceiveEvent(data)
     }
   }
 
+  /**
+   * Whether the model should automatically play its first animation on load.
+   */
+  private _autoplay: boolean = false
+
+  /**
+   * Returns whether autoplay is enabled for this element.
+   */
+  get autoplay(): boolean {
+    return this._autoplay
+  }
+
+  /**
+   * Whether the model animation should loop continuously.
+   */
+  private _loop: boolean = false
+
+  /**
+   * Returns whether loop is enabled for this element.
+   */
+  get loop(): boolean {
+    return this._loop
+  }
+
   /**
    * Callback function for successful model loading.
    */
@@ -122,3 +275,9 @@ export class SpatializedStatic3DElement extends SpatializedElement {
     this.updateProperties({ modelTransform })
   }
 }
+
+type Static3DReceiveEventData =
+  | ModelLoadSuccess
+  | ModelLoadFailure
+  | ReceiveEventData
+  | AnimationStateChangeMsg

package/src/WebMsgCommand.ts

@@ -19,6 +19,8 @@ export enum SpatialWebMsgType {
   spatialmagnify = 'spatialmagnify',
   spatialmagnifyend = 'spatialmagnifyend',
 
+  animationstatechange = 'animationstatechange',
+
   objectdestroy = 'objectdestroy',
 }
 
@@ -65,3 +67,23 @@ export interface SpatialMagnifyEndMsg {
   type: SpatialWebMsgType.spatialmagnifyend
   detail: SpatialMagnifyEventDetail
 }
+
+export interface ModelLoadSuccess {
+  type: SpatialWebMsgType.modelloaded
+  // detail object is undefined in old native runtimes
+  detail?: { src: string }
+}
+
+export interface ModelLoadFailure {
+  type: SpatialWebMsgType.modelloadfailed
+}
+
+export interface AnimationStateChangeDetail {
+  paused: boolean
+  duration: number
+}
+
+export interface AnimationStateChangeMsg {
+  type: SpatialWebMsgType.animationstatechange
+  detail: AnimationStateChangeDetail
+}