@webspatial/core-sdk 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webspatial/core-sdk",
-  "version": "1.4.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

@@ -2,6 +2,7 @@ import { createPlatform } from './platform-adapter'
 import { WebSpatialProtocolResult } from './platform-adapter/interface'
 import { SpatialComponent } from './reality/component/SpatialComponent'
 import { SpatialEntity } from './reality/entity/SpatialEntity'
+import { SpatialMaterial } from './reality/material/SpatialMaterial'
 import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
 import { SpatializedElement } from './SpatializedElement'
 import { SpatialObject } from './SpatialObject'
@@ -23,6 +24,7 @@ import {
   Vec3,
   AttachmentEntityOptions,
   AttachmentEntityUpdateOptions,
+  ModelSource,
 } from './types/types'
 import { SpatialSceneCreationOptionsInternal } from './types/internal'
 import { composeSRT } from './utils'
@@ -288,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 }
   }
 }
 
@@ -386,6 +392,38 @@ export class AddComponentToEntityCommand extends JSBCommand {
   commandType = 'AddComponentToEntity'
 }
 
+export class RemoveComponentFromEntityCommand extends JSBCommand {
+  constructor(
+    public entity: SpatialEntity,
+    public comp: SpatialComponent,
+  ) {
+    super()
+  }
+  protected getParams(): Record<string, any> | undefined {
+    return {
+      entityId: this.entity.id,
+      componentId: this.comp.id,
+    }
+  }
+  commandType = 'RemoveComponentFromEntity'
+}
+
+export class SetMaterialsOnEntityCommand extends JSBCommand {
+  constructor(
+    public entityId: string,
+    public materials: SpatialMaterial[],
+  ) {
+    super()
+  }
+  protected getParams(): Record<string, any> | undefined {
+    return {
+      entityId: this.entityId,
+      materialIds: this.materials.map(m => m.id),
+    }
+  }
+  commandType = 'SetMaterialsOnEntity'
+}
+
 export class AddEntityToDynamic3DCommand extends JSBCommand {
   constructor(
     public d3dEle: SpatializedDynamic3DElement,

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
+}

package/src/platform-adapter/index.ts

@@ -40,8 +40,8 @@ export function createPlatform(): PlatformAbility {
     userAgent.includes('PicoWebApp') &&
     isVersionGreater(webSpatialVersion, [0, 0, 1])
   ) {
-    const XRPlatform = require('./xr/XRPlatform').XRPlatform
-    return new XRPlatform()
+    const PicoOSPlatform = require('./pico-os/PicoOSPlatform').PicoOSPlatform
+    return new PicoOSPlatform()
   } else if (userAgent.includes('Android') || userAgent.includes('Linux')) {
     const AndroidPlatform = require('./android/AndroidPlatform').AndroidPlatform
     return new AndroidPlatform()

package/src/platform-adapter/{xr/XRPlatform.ts → pico-os/PicoOSPlatform.ts}

@@ -23,9 +23,10 @@ function nextRequestId() {
   return `rId_${requestId}`
 }
 
-export class XRPlatform implements PlatformAbility {
+// Only supports Pico OS 6
+export class PicoOSPlatform implements PlatformAbility {
   async callJSB(cmd: string, msg: string): Promise<CommandResult> {
-    // android JS Bridge interface only support sync invoking
+    // swan JS Bridge interface only support sync invoking
     // in order to implement promise API, register every request by requestId and remove when resolve/reject.
     return new Promise((resolve, reject) => {
       try {
@@ -54,7 +55,7 @@ export class XRPlatform implements PlatformAbility {
           }
         }
       } catch (error: unknown) {
-        console.error(`XRPlatform cmd: ${cmd}, msg: ${msg} error: ${error}`)
+        console.error(`SwanPlatform cmd: ${cmd}, msg: ${msg} error: ${error}`)
         const { code, message } = error as JSBError
         resolve(CommandResultFailure(code, message))
       }
@@ -75,7 +76,6 @@ export class XRPlatform implements PlatformAbility {
         SpatialWebEvent.addEventReceiver(
           createdId,
           (result: { spatialId: string }) => {
-            console.log('createdId', createdId, result.spatialId)
             resolve(
               CommandResultSuccess({
                 windowProxy: windowProxy,
@@ -87,13 +87,11 @@ export class XRPlatform implements PlatformAbility {
         )
         windowProxy = this.openWindow(
           command,
-          query,
+          'rid=' + createdId,
           target,
           features,
         ).windowProxy
-        windowProxy?.open(`about:blank?rid=${createdId}`, '_self')
       } catch (error: unknown) {
-        console.error(`open window error: ${error}`)
         const { code, message } = error as JSBError
         SpatialWebEvent.removeEventReceiver(createdId)
         resolve(CommandResultFailure(code, message))

package/src/reality/entity/SpatialEntity.ts

@@ -13,6 +13,7 @@ import {
 import {
   AddComponentToEntityCommand,
   AddEntityToEntityCommand,
+  RemoveComponentFromEntityCommand,
   RemoveEntityFromParentCommand,
   UpdateEntityEventCommand,
   UpdateEntityPropertiesCommand,
@@ -79,6 +80,9 @@ export class SpatialEntity extends SpatialObject {
   async addComponent(component: SpatialComponent) {
     return new AddComponentToEntityCommand(this, component).execute()
   }
+  async removeComponent(component: SpatialComponent) {
+    return new RemoveComponentFromEntityCommand(this, component).execute()
+  }
   async setPosition(position: Vec3) {
     return this.updateTransform({ position })
   }

package/src/reality/entity/SpatialModelEntity.ts

@@ -2,6 +2,8 @@ import {
   SpatialEntityUserData,
   SpatialModelEntityCreationOptions,
 } from '../../types/types'
+import { SetMaterialsOnEntityCommand } from '../../JSBCommand'
+import { SpatialMaterial } from '../material/SpatialMaterial'
 import { SpatialEntity } from './SpatialEntity'
 
 export class SpatialModelEntity extends SpatialEntity {
@@ -12,4 +14,8 @@ export class SpatialModelEntity extends SpatialEntity {
   ) {
     super(id, userData)
   }
+
+  async setMaterials(materials: SpatialMaterial[]) {
+    return new SetMaterialsOnEntityCommand(this.id, materials).execute()
+  }
 }