@webspatial/core-sdk 1.0.4 → 1.1.0

package/src/SpatializedElement.ts

@@ -0,0 +1,331 @@
+import { UpdateSpatializedElementTransform } from './JSBCommand'
+import { WebSpatialProtocolResult } from './platform-adapter/interface'
+import { SpatialObject } from './SpatialObject'
+import { SpatialWebEvent } from './SpatialWebEvent'
+import { createSpatialEvent } from './SpatialWebEventCreator'
+import {
+  CubeInfo,
+  SpatialDragEndEvent,
+  SpatialDragEvent,
+  SpatializedElementProperties,
+  SpatialMagnifyEndEvent,
+  SpatialMagnifyEvent,
+  SpatialRotateEndEvent,
+  SpatialRotateEvent,
+  SpatialTapEvent,
+} from './types/types'
+import {
+  CubeInfoMsg,
+  ObjectDestroyMsg,
+  SpatialDragEndMsg,
+  SpatialDragMsg,
+  SpatialMagnifyEndMsg,
+  SpatialMagnifyMsg,
+  SpatialRotateEndMsg,
+  SpatialRotateMsg,
+  SpatialTapMsg,
+  SpatialWebMsgType,
+  TransformMsg,
+} from './WebMsgCommand'
+
+/**
+ * Abstract base class for all spatialized elements in the WebSpatial environment.
+ * Provides common functionality for elements that can exist in 3D space,
+ * including transformation handling and gesture event processing.
+ */
+export abstract class SpatializedElement extends SpatialObject {
+  /**
+   * Creates a new spatialized element with the specified ID.
+   * Registers the element to receive spatial events.
+   * @param id Unique identifier for this element
+   */
+  constructor(public readonly id: string) {
+    super(id)
+
+    SpatialWebEvent.addEventReceiver(id, this.onReceiveEvent.bind(this))
+  }
+
+  /**
+   * Updates the properties of this spatialized element.
+   * Must be implemented by derived classes to handle specific property updates.
+   * @param properties Partial set of properties to update
+   * @returns Promise resolving to the result of the update operation
+   */
+  abstract updateProperties(
+    properties: Partial<SpatializedElementProperties>,
+  ): Promise<WebSpatialProtocolResult>
+
+  /**
+   * Updates the transformation matrix of this element in 3D space.
+   * This affects the position, rotation, and scale of the element.
+   * @param matrix The new transformation matrix
+   * @returns Promise resolving when the transform is updated
+   */
+  async updateTransform(matrix: DOMMatrix) {
+    return new UpdateSpatializedElementTransform(this, matrix).execute()
+  }
+
+  /**
+   * Information about the element's bounding cube.
+   * Used for spatial calculations and hit testing.
+   */
+  private _cubeInfo?: CubeInfo
+
+  /**
+   * Gets the current cube information for this element.
+   * @returns The current CubeInfo or undefined if not set
+   */
+  get cubeInfo() {
+    return this._cubeInfo
+  }
+
+  /**
+   * The current transformation matrix of this element.
+   */
+  private _transform?: DOMMatrix
+
+  /**
+   * The inverse of the current transformation matrix.
+   * Used for converting world coordinates to local coordinates.
+   */
+  private _transformInv?: DOMMatrix
+
+  /**
+   * Gets the current transformation matrix.
+   * @returns The current transformation matrix or undefined if not set
+   */
+  get transform() {
+    return this._transform
+  }
+
+  /**
+   * Gets the inverse of the current transformation matrix.
+   * @returns The inverse transformation matrix or undefined if not set
+   */
+  get transformInv() {
+    return this._transformInv
+  }
+
+  /**
+   * Processes events received from the WebSpatial environment.
+   * Handles various spatial events like transforms, gestures, and interactions.
+   * @param data The event data received from the WebSpatial system
+   */
+  protected onReceiveEvent(
+    data:
+      | CubeInfoMsg
+      | TransformMsg
+      | SpatialTapMsg
+      | SpatialDragMsg
+      | SpatialDragEndMsg
+      | SpatialRotateMsg
+      | SpatialRotateEndMsg
+      | ObjectDestroyMsg,
+  ) {
+    const { type } = data
+    if (type === SpatialWebMsgType.objectdestroy) {
+      this.isDestroyed = true
+    } else if (type === SpatialWebMsgType.cubeInfo) {
+      // Handle cube info updates (bounding box information)
+      const cubeInfoMsg = data as CubeInfoMsg
+      this._cubeInfo = new CubeInfo(cubeInfoMsg.size, cubeInfoMsg.origin)
+    } else if (type === SpatialWebMsgType.transform) {
+      // Handle transformation matrix updates
+      this._transform = new DOMMatrix([
+        data.detail.column0[0],
+        data.detail.column0[1],
+        data.detail.column0[2],
+        0,
+        data.detail.column1[0],
+        data.detail.column1[1],
+        data.detail.column1[2],
+        0,
+        data.detail.column2[0],
+        data.detail.column2[1],
+        data.detail.column2[2],
+        0,
+        data.detail.column3[0],
+        data.detail.column3[1],
+        data.detail.column3[2],
+        1,
+      ])
+      this._transformInv = this._transform.inverse()
+    } else if (type === SpatialWebMsgType.spatialtap) {
+      // Handle tap gestures
+      const event = createSpatialEvent(
+        SpatialWebMsgType.spatialtap,
+        (data as SpatialTapMsg).detail,
+      )
+      this._onSpatialTap?.(event)
+    } else if (type === SpatialWebMsgType.spatialdrag) {
+      // Handle drag gestures, with special handling for drag start
+      if (!this._isDragging) {
+        const dragStartEvent = createSpatialEvent(
+          SpatialWebMsgType.spatialdragstart,
+          (data as SpatialDragMsg).detail,
+        )
+        this._onSpatialDragStart?.(dragStartEvent)
+      }
+      this._isDragging = true
+      const event = createSpatialEvent(
+        SpatialWebMsgType.spatialdrag,
+        (data as SpatialDragMsg).detail,
+      )
+      this._onSpatialDrag?.(event)
+    } else if (type === SpatialWebMsgType.spatialdragend) {
+      this._isDragging = false
+      const event = createSpatialEvent(
+        SpatialWebMsgType.spatialdragend,
+        (data as SpatialDragEndMsg).detail,
+      )
+      this._onSpatialDragEnd?.(event)
+    } else if (type === SpatialWebMsgType.spatialrotate) {
+      if (!this._isRotating) {
+        const rotationStartEvent = createSpatialEvent(
+          SpatialWebMsgType.spatialrotatestart,
+          (data as SpatialRotateMsg).detail,
+        )
+        this._onSpatialRotateStart?.(rotationStartEvent)
+      }
+      this._isRotating = true
+      const event = createSpatialEvent(
+        SpatialWebMsgType.spatialrotate,
+        (data as SpatialRotateMsg).detail,
+      )
+      this._onSpatialRotate?.(event)
+    } else if (type === SpatialWebMsgType.spatialrotateend) {
+      this._isRotating = false
+      const event = createSpatialEvent(
+        SpatialWebMsgType.spatialrotateend,
+        (data as SpatialRotateEndMsg).detail,
+      )
+      this._onSpatialRotateEnd?.(event)
+    } else if (type === SpatialWebMsgType.spatialmagnify) {
+      if (!this._isMagnify) {
+        const magnifyStartEvent = createSpatialEvent(
+          SpatialWebMsgType.spatialmagnifystart,
+          (data as SpatialMagnifyMsg).detail,
+        )
+        this._onSpatialMagnifyStart?.(magnifyStartEvent)
+      }
+      this._isMagnify = true
+      const event = createSpatialEvent(
+        SpatialWebMsgType.spatialmagnify,
+        (data as SpatialMagnifyMsg).detail,
+      )
+      this._onSpatialMagnify?.(event)
+    } else if (type === SpatialWebMsgType.spatialmagnifyend) {
+      this._isMagnify = false
+      const event = createSpatialEvent(
+        SpatialWebMsgType.spatialmagnifyend,
+        (data as SpatialMagnifyEndMsg).detail,
+      )
+      this._onSpatialMagnifyEnd?.(event)
+    }
+  }
+
+  private _onSpatialTap?: (event: SpatialTapEvent) => void
+  set onSpatialTap(value: (event: SpatialTapEvent) => void | undefined) {
+    this._onSpatialTap = value
+    this.updateProperties({
+      enableTapGesture: value !== undefined,
+    })
+  }
+
+  private _isDragging = false
+  private _onSpatialDragStart?: (event: SpatialDragEvent) => void
+  set onSpatialDragStart(value: (event: SpatialDragEvent) => void | undefined) {
+    this._onSpatialDragStart = value
+    this.updateProperties({
+      enableDragStartGesture: this._onSpatialDragStart !== undefined,
+    })
+  }
+
+  private _onSpatialDrag?: (event: SpatialDragEvent) => void
+  set onSpatialDrag(value: (event: SpatialDragEvent) => void | undefined) {
+    this._onSpatialDrag = value
+    this.updateProperties({
+      enableDragGesture: this._onSpatialDrag !== undefined,
+    })
+  }
+
+  private _onSpatialDragEnd?: (event: SpatialDragEndEvent) => void
+  set onSpatialDragEnd(
+    value: ((event: SpatialDragEndEvent) => void) | undefined,
+  ) {
+    this._onSpatialDragEnd = value
+    this.updateProperties({
+      enableDragEndGesture: value !== undefined,
+    })
+  }
+
+  private _isRotating = false
+  private _onSpatialRotateStart?: (event: SpatialRotateEvent) => void
+  set onSpatialRotateStart(
+    value: ((event: SpatialRotateEvent) => void) | undefined,
+  ) {
+    this._onSpatialRotateStart = value
+    this.updateProperties({
+      enableRotateStartGesture: this._onSpatialRotateStart !== undefined,
+    })
+  }
+
+  private _onSpatialRotate?: (event: SpatialRotateEvent) => void
+  set onSpatialRotate(
+    value: ((event: SpatialRotateEvent) => void) | undefined,
+  ) {
+    this._onSpatialRotate = value
+    this.updateProperties({
+      enableRotateGesture: this._onSpatialRotate !== undefined,
+    })
+  }
+
+  private _onSpatialRotateEnd?: (event: SpatialRotateEndEvent) => void
+  set onSpatialRotateEnd(
+    value: ((event: SpatialRotateEndEvent) => void) | undefined,
+  ) {
+    this._onSpatialRotateEnd = value
+    this.updateProperties({
+      enableRotateEndGesture: value !== undefined,
+    })
+  }
+
+  private _isMagnify = false
+  private _onSpatialMagnifyStart?: (event: SpatialMagnifyEvent) => void
+  set onSpatialMagnifyStart(
+    value: ((event: SpatialMagnifyEvent) => void) | undefined,
+  ) {
+    this._onSpatialMagnifyStart = value
+    this.updateProperties({
+      enableMagnifyStartGesture: value !== undefined,
+    })
+  }
+
+  private _onSpatialMagnify?: (event: SpatialMagnifyEvent) => void
+  set onSpatialMagnify(
+    value: ((event: SpatialMagnifyEvent) => void) | undefined,
+  ) {
+    this._onSpatialMagnify = value
+    this.updateProperties({
+      enableMagnifyGesture: value !== undefined,
+    })
+  }
+
+  private _onSpatialMagnifyEnd?: (event: SpatialMagnifyEndEvent) => void
+  set onSpatialMagnifyEnd(
+    value: ((event: SpatialMagnifyEndEvent) => void) | undefined,
+  ) {
+    this._onSpatialMagnifyEnd = value
+    this.updateProperties({
+      enableMagnifyEndGesture: value !== undefined,
+    })
+  }
+
+  /**
+   * Cleans up resources when this element is destroyed.
+   * Removes event receivers to prevent memory leaks.
+   */
+  override onDestroy() {
+    SpatialWebEvent.removeEventReceiver(this.id)
+  }
+}

package/src/SpatializedElementCreator.ts

@@ -0,0 +1,45 @@
+import {
+  createSpatialized2DElementCommand,
+  CreateSpatializedDynamic3DElementCommand,
+  CreateSpatializedStatic3DElementCommand,
+} from './JSBCommand'
+import { Spatialized2DElement } from './Spatialized2DElement'
+import { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
+import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
+
+export async function createSpatialized2DElement(): Promise<Spatialized2DElement> {
+  const result = await new createSpatialized2DElementCommand().execute()
+  if (!result.success) {
+    throw new Error('createSpatialized2DElement failed')
+  } else {
+    const { id, windowProxy } = result.data!
+    // set base href to make sure the relative url is correct
+    windowProxy.document.head.innerHTML = `<meta name="viewport" content="width=device-width, initial-scale=1">
+      <base href="${document.baseURI}">`
+    return new Spatialized2DElement(id, windowProxy)
+  }
+}
+
+export async function createSpatializedStatic3DElement(
+  modelURL: string,
+): Promise<SpatializedStatic3DElement> {
+  const result = await new CreateSpatializedStatic3DElementCommand(
+    modelURL,
+  ).execute()
+  if (!result.success) {
+    throw new Error('createSpatializedStatic3DElement failed')
+  } else {
+    const { id } = result.data
+    return new SpatializedStatic3DElement(id)
+  }
+}
+
+export async function createSpatializedDynamic3DElement(): Promise<SpatializedDynamic3DElement> {
+  const result = await new CreateSpatializedDynamic3DElementCommand().execute()
+  if (!result.success) {
+    throw new Error('createSpatializedDynamic3DElement failed')
+  } else {
+    const { id } = result.data
+    return new SpatializedDynamic3DElement(id)
+  }
+}

package/src/SpatializedStatic3DElement.ts

@@ -0,0 +1,111 @@
+import { UpdateSpatializedStatic3DElementProperties } from './JSBCommand'
+import { SpatializedElement } from './SpatializedElement'
+import { SpatializedStatic3DElementProperties } from './types/types'
+import { SpatialWebMsgType } from './WebMsgCommand'
+
+/**
+ * Represents a static 3D model element in the spatial environment.
+ * This class handles loading and displaying pre-built 3D models from URLs,
+ * and provides events for load success and failure.
+ */
+export class SpatializedStatic3DElement extends SpatializedElement {
+  /**
+   * Promise resolver for the ready state.
+   * Used to resolve the ready promise when the model is loaded.
+   */
+  private _readyResolve?: (success: boolean) => void
+
+  /**
+   * Caches the last model URL to detect changes.
+   * Used to reset the ready promise when the model URL changes.
+   */
+  private modelURL: string = ''
+
+  /**
+   * Creates a new promise for tracking the ready state of the model.
+   * @returns Promise that resolves when the model is loaded (true) or fails to load (false)
+   */
+  private createReadyPromise() {
+    return new Promise<boolean>(resolve => {
+      this._readyResolve = resolve
+    })
+  }
+
+  /**
+   * Promise that resolves when the model is loaded.
+   * Resolves to true on successful load, false on failure.
+   */
+  ready: Promise<boolean> = this.createReadyPromise()
+
+  /**
+   * Updates the properties of this static 3D element.
+   * Handles special case for modelURL changes by resetting the ready promise.
+   * @param properties Partial set of properties to update
+   * @returns Promise resolving when the update is complete
+   */
+  async updateProperties(
+    properties: Partial<SpatializedStatic3DElementProperties>,
+  ) {
+    if (properties.modelURL !== undefined) {
+      if (this.modelURL !== properties.modelURL) {
+        this.modelURL = properties.modelURL
+        this.ready = this.createReadyPromise()
+      }
+    }
+    return new UpdateSpatializedStatic3DElementProperties(
+      this,
+      properties,
+    ).execute()
+  }
+
+  /**
+   * 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 }) {
+    if (data.type === SpatialWebMsgType.modelloaded) {
+      // Handle successful model loading
+      this._onLoadCallback?.()
+      this._readyResolve?.(true)
+    } else if (data.type === SpatialWebMsgType.modelloadfailed) {
+      // Handle model loading failure
+      this._onLoadFailureCallback?.()
+      this._readyResolve?.(false)
+    } else {
+      // Handle other spatial events using the base class implementation
+      super.onReceiveEvent(data as any)
+    }
+  }
+
+  /**
+   * Callback function for successful model loading.
+   */
+  private _onLoadCallback?: () => void
+
+  /**
+   * Sets the callback function for successful model loading.
+   * @param callback Function to call when the model is loaded successfully
+   */
+  set onLoadCallback(callback: undefined | (() => void)) {
+    this._onLoadCallback = callback
+  }
+
+  /**
+   * Callback function for model loading failure.
+   */
+  private _onLoadFailureCallback?: undefined | (() => void)
+
+  /**
+   * Sets the callback function for model loading failure.
+   * @param callback Function to call when the model fails to load
+   */
+  set onLoadFailureCallback(callback: undefined | (() => void)) {
+    this._onLoadFailureCallback = callback
+  }
+
+  updateModelTransform(transform: DOMMatrix) {
+    const modelTransform = Array.from(transform.toFloat64Array())
+    this.updateProperties({ modelTransform })
+  }
+}

package/src/WebMsgCommand.ts

@@ -0,0 +1,88 @@
+import {
+  Vec3,
+  Size3D,
+  SpatialDragEventDetail,
+  SpatialTapEventDetail,
+  SpatialRotateEventDetail,
+  SpatialMagnifyEventDetail,
+} from './types/types'
+
+export enum SpatialWebMsgType {
+  cubeInfo = 'cubeInfo',
+  transform = 'transform',
+  modelloaded = 'modelloaded',
+  modelloadfailed = 'modelloadfailed',
+  spatialtap = 'spatialtap',
+  spatialdragstart = 'spatialdragstart',
+  spatialdrag = 'spatialdrag',
+  spatialdragend = 'spatialdragend',
+  spatialrotatestart = 'spatialrotatestart',
+  spatialrotate = 'spatialrotate',
+  spatialrotateend = 'spatialrotateend',
+  spatialmagnifystart = 'spatialmagnifystart',
+  spatialmagnify = 'spatialmagnify',
+  spatialmagnifyend = 'spatialmagnifyend',
+
+  objectdestroy = 'objectdestroy',
+}
+
+export interface ObjectDestroyMsg {
+  type: SpatialWebMsgType.objectdestroy
+}
+
+export interface CubeInfoMsg {
+  type: SpatialWebMsgType.cubeInfo
+  origin: Vec3
+  size: Size3D
+}
+
+export interface CubeInfoMsg {
+  type: SpatialWebMsgType.cubeInfo
+  origin: Vec3
+  size: Size3D
+}
+
+export interface TransformMsg {
+  type: SpatialWebMsgType.transform
+  detail: {
+    column0: [number, number, number]
+    column1: [number, number, number]
+    column2: [number, number, number]
+    column3: [number, number, number]
+  }
+}
+
+export interface SpatialTapMsg {
+  type: SpatialWebMsgType.spatialtap
+  detail: SpatialTapEventDetail
+}
+
+export interface SpatialDragMsg {
+  type: SpatialWebMsgType.spatialdrag
+  detail: SpatialDragEventDetail
+}
+
+export interface SpatialDragEndMsg {
+  type: SpatialWebMsgType.spatialdragend
+  detail: SpatialDragEventDetail
+}
+
+export interface SpatialRotateMsg {
+  type: SpatialWebMsgType.spatialrotate
+  detail: SpatialRotateEventDetail
+}
+
+export interface SpatialRotateEndMsg {
+  type: SpatialWebMsgType.spatialrotateend
+  detail: SpatialRotateEventDetail
+}
+
+export interface SpatialMagnifyMsg {
+  type: SpatialWebMsgType.spatialmagnify
+  detail: SpatialMagnifyEventDetail
+}
+
+export interface SpatialMagnifyEndMsg {
+  type: SpatialWebMsgType.spatialmagnifyend
+  detail: SpatialMagnifyEventDetail
+}

package/src/index.ts

@@ -1 +1,23 @@
-export * from './core/index'
+export { SpatialObject } from './SpatialObject'
+export { Spatial } from './Spatial'
+export { SpatialSession } from './SpatialSession'
+export { SpatialScene } from './SpatialScene'
+export { SpatializedElement } from './SpatializedElement'
+export { Spatialized2DElement } from './Spatialized2DElement'
+export { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
+export { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
+export * from './reality'
+export * from './types/types'
+export * from './types/global.d'
+
+// side effects
+import { injectSceneHook } from './scene-polyfill'
+import { isSSREnv } from './ssr-polyfill'
+import { spatialWindowPolyfill } from './spatial-window-polyfill'
+
+export { isSSREnv }
+
+if (!isSSREnv() && navigator.userAgent.indexOf('WebSpatial/') > 0) {
+  injectSceneHook()
+  spatialWindowPolyfill()
+}

package/src/platform-adapter/CommandResultUtils.ts

@@ -0,0 +1,22 @@
+import { CommandResult } from './interface'
+
+export function CommandResultSuccess(data: any): CommandResult {
+  return {
+    success: true,
+    data,
+    errorCode: '',
+    errorMessage: '',
+  }
+}
+
+export function CommandResultFailure(
+  errorCode: string,
+  errorMessage = '',
+): CommandResult {
+  return {
+    success: false,
+    data: undefined,
+    errorCode,
+    errorMessage,
+  }
+}