@webspatial/core-sdk 0.0.1-alpha

package/src/core/SpatialSession.ts

@@ -0,0 +1,434 @@
+import { SpatialEntity } from './SpatialEntity'
+import { SpatialWindowContainer } from './SpatialWindowContainer'
+import {
+  WebSpatial,
+  WebSpatialResource,
+  WindowContainer,
+} from './private/WebSpatial'
+import {
+  LoadingMethodKind,
+  sceneDataShape,
+  WindowContainerOptions,
+  WindowStyle,
+} from './types'
+
+import {
+  SpatialMeshResource,
+  SpatialPhysicallyBasedMaterialResource,
+} from './resource'
+import {
+  SpatialModelComponent,
+  SpatialInputComponent,
+  SpatialWindowComponent,
+  SpatialViewComponent,
+  SpatialModel3DComponent,
+} from './component'
+import { RemoteCommand } from './private/remote-command'
+
+/**
+ * Animation callback with timestamp
+ */
+type animCallback = (time: DOMHighResTimeStamp) => Promise<any>
+
+/**
+ * Parses the resource owners of the created object. If unedfined, will use the current window container and web panel. If null the created resource will not be destroyed unless explicitly destroyed.
+ * @param options
+ * @returns parsed results
+ */
+function _parseParentResources(options?: {
+  windowContainer?: SpatialWindowContainer | null
+  windowComponent?: SpatialWindowComponent | null
+}): [WindowContainer | null, WebSpatialResource | null] {
+  var parentWindowContainer: WindowContainer | null = null
+  if (options?.windowContainer !== null) {
+    parentWindowContainer = options?.windowContainer
+      ? options?.windowContainer._wg
+      : WebSpatial.getCurrentWindowContainer()
+  }
+
+  var parentWindow: WebSpatialResource | null = null
+  if (options?.windowComponent !== null) {
+    parentWindow = options?.windowComponent
+      ? options?.windowComponent._resource
+      : WebSpatial.getCurrentWebPanel()
+  }
+
+  return [parentWindowContainer, parentWindow]
+}
+
+/**
+ * Session use to establish a connection to the spatial renderer of the system. All resources must be created by the session
+ */
+export class SpatialSession {
+  /** @hidden */
+  _engineUpdateListeners = Array<animCallback>()
+  /** @hidden */
+  _frameLoopStarted = false
+
+  /**
+   * Add event listener callback to be called each frame
+   * @param callback callback to be called each update
+   */
+  addOnEngineUpdateEventListener(callback: animCallback) {
+    this._engineUpdateListeners.push(callback)
+
+    if (!this._frameLoopStarted) {
+      this._frameLoopStarted = true
+      WebSpatial.onFrame(async (time: number) => {
+        await Promise.all(
+          this._engineUpdateListeners.map(cb => {
+            return cb(time)
+          }),
+        )
+      })
+    }
+  }
+
+  /**
+   * Creates a Entity
+   * @returns Entity
+   */
+  async createEntity() {
+    let entity = await WebSpatial.createResource(
+      'Entity',
+      WebSpatial.getCurrentWindowContainer(),
+      WebSpatial.getCurrentWebPanel(),
+    )
+    return new SpatialEntity(entity)
+  }
+
+  /**
+   * Creates a WindowComponent
+   * [TODO] should creation of components be moved to entity? and these made private?
+   * @returns WindowComponent
+   */
+  async createWindowComponent(options?: {
+    windowContainer?: SpatialWindowContainer
+  }) {
+    let entity = await WebSpatial.createResource(
+      'SpatialWebView',
+      options?.windowContainer
+        ? options?.windowContainer._wg
+        : WebSpatial.getCurrentWindowContainer(),
+      WebSpatial.getCurrentWebPanel(),
+    )
+    return new SpatialWindowComponent(entity)
+  }
+
+  /**
+   * Creates a ViewComponent used to display 3D content within the entity
+   * @returns SpatialViewComponent
+   */
+  async createViewComponent(options?: {
+    windowContainer?: SpatialWindowContainer
+  }) {
+    let entity = await WebSpatial.createResource(
+      'SpatialView',
+      options?.windowContainer
+        ? options?.windowContainer._wg
+        : WebSpatial.getCurrentWindowContainer(),
+      WebSpatial.getCurrentWebPanel(),
+    )
+    return new SpatialViewComponent(entity)
+  }
+
+  /**
+   * Creates a ModelComponent used to display geometry + material of a 3D model
+   * @returns ModelComponent
+   */
+  async createModelComponent(options?: { url: string }) {
+    var opts = undefined
+    if (options) {
+      opts = { modelURL: options.url }
+    }
+    let entity = await WebSpatial.createResource(
+      'ModelComponent',
+      WebSpatial.getCurrentWindowContainer(),
+      WebSpatial.getCurrentWebPanel(),
+      opts,
+    )
+    return new SpatialModelComponent(entity)
+  }
+
+  /**
+   * Creates a Model3DComponent
+   * @returns Model3DComponent
+   */
+  async createModel3DComponent(options?: { url: string }) {
+    var opts = undefined
+    if (options) {
+      opts = { modelURL: options.url }
+    }
+    let entity = await WebSpatial.createResource(
+      'Model3DComponent',
+      WebSpatial.getCurrentWindowContainer(),
+      WebSpatial.getCurrentWebPanel(),
+      opts,
+    )
+    return new SpatialModel3DComponent(entity)
+  }
+
+  /**
+   * Creates a InputComponent
+   * [Experimental] Creates a InputComponent used to handle click and drag events of the entity containing a model
+   * @returns InputComponent
+   */
+  async createInputComponent() {
+    let entity = await WebSpatial.createResource(
+      'InputComponent',
+      WebSpatial.getCurrentWindowContainer(),
+      WebSpatial.getCurrentWebPanel(),
+    )
+    return new SpatialInputComponent(entity)
+  }
+
+  /**
+   * Creates a MeshResource containing geometry data
+   * @returns MeshResource
+   */
+  async createMeshResource(options?: { shape?: string }) {
+    let entity = await WebSpatial.createResource(
+      'MeshResource',
+      WebSpatial.getCurrentWindowContainer(),
+      WebSpatial.getCurrentWebPanel(),
+      options,
+    )
+    return new SpatialMeshResource(entity)
+  }
+
+  /**
+   * Creates a PhysicallyBasedMaterial containing PBR material data
+   * @returns PhysicallyBasedMaterial
+   */
+  async createPhysicallyBasedMaterialResource(options?: {}) {
+    let entity = await WebSpatial.createResource(
+      'PhysicallyBasedMaterial',
+      WebSpatial.getCurrentWindowContainer(),
+      WebSpatial.getCurrentWebPanel(),
+      options,
+    )
+    return new SpatialPhysicallyBasedMaterialResource(entity)
+  }
+  /**
+   * Creates a WindowContainer
+   * @returns SpatialWindowContainer
+   * */
+  async createWindowContainer(options?: {
+    style: WindowStyle
+    windowContainer?: SpatialWindowContainer | null
+    windowComponent?: SpatialWindowComponent | null
+  }) {
+    var style = options?.style ? options?.style : 'Plain'
+    var [parentWindowContainer, parentWindow] = _parseParentResources(options)
+    return new SpatialWindowContainer(
+      await WebSpatial.createWindowContainer(
+        style,
+        parentWindowContainer,
+        parentWindow,
+      ),
+    )
+  }
+
+  /**
+   * Creates a Scene to display content within an anchored area managed by the OS
+   * @hidden
+   * @param {WindowStyle} [style='Plain'] - The style of the Scene container to be created with. Defaults to 'Plain'.
+   * @param {Object} [cfg={}] - Configuration object for the Scene.
+   * @returns Boolean
+   */
+  async _createScene(
+    style: WindowStyle = 'Plain',
+    cfg: {
+      sceneData: sceneDataShape
+    },
+  ) {
+    return await WebSpatial.createScene(style, cfg)
+  }
+
+  /**
+   * Retrieves the window for this page
+   * @returns the window component corresponding to the js running on this page
+   * [TODO] discuss implications of this not being async
+   */
+  getCurrentWindowComponent() {
+    return new SpatialWindowComponent(WebSpatial.getCurrentWebPanel())
+  }
+
+  /**
+   * Retrieves the parent window for this page or null if this is the root page
+   * @returns the window component or null
+   */
+  async getParentWindowComponent() {
+    let parentResp: any = await WebSpatial.updateResource(
+      WebSpatial.getCurrentWebPanel(),
+      { getParentID: '' },
+    )
+    if (parentResp.data.parentID === '') {
+      return new Promise<SpatialWindowComponent | null>((res, rej) => {
+        res(null)
+      })
+    } else {
+      var res = new WebSpatialResource()
+      res.id = parentResp.data.parentID
+      return new SpatialWindowComponent(res)
+    }
+  }
+
+  /**
+   * Logs a message to the native apps console
+   * @param msg mesage to log
+   */
+  async log(...msg: any[]) {
+    await WebSpatial.sendCommand(new RemoteCommand('log', { logString: msg }))
+  }
+
+  /**
+   * @hidden
+   * Debugging only, used to ping the native renderer
+   */
+  async _ping(msg: string) {
+    return await WebSpatial.ping(msg)
+  }
+
+  /**
+   * @hidden
+   * Debugging to get internal state from native code
+   * @returns data as a js object
+   */
+  async _getStats() {
+    return (await WebSpatial.getStats()) as { objects: any; refObjects: any }
+  }
+
+  /**
+   * @hidden
+   */
+  async _inspect(spatialObjectId: string = WebSpatial.getCurrentWebPanel().id) {
+    return WebSpatial.inspect(spatialObjectId)
+  }
+
+  /**
+   * @hidden
+   */
+  async _inspectRootWindowContainer() {
+    return WebSpatial.inspectRootWindowContainer()
+  }
+
+  /** Opens the immersive space */
+  async openImmersiveSpace() {
+    return await WebSpatial.openImmersiveSpace()
+  }
+
+  /** Closes the immersive space */
+  async dismissImmersiveSpace() {
+    return await WebSpatial.dismissImmersiveSpace()
+  }
+
+  private static _immersiveWindowContainer =
+    null as null | SpatialWindowContainer
+  /**
+   * Retreives the window container corresponding to the Immersive space
+   * @returns the immersive window container
+   */
+  async getImmersiveWindowContainer() {
+    if (SpatialSession._immersiveWindowContainer) {
+      return SpatialSession._immersiveWindowContainer
+    } else {
+      SpatialSession._immersiveWindowContainer = new SpatialWindowContainer(
+        WebSpatial.getImmersiveWindowContainer(),
+      )
+      return SpatialSession._immersiveWindowContainer
+    }
+  }
+
+  // Retreives the window container that is the parent to this spatial web page
+  private static _currentWindowContainer = null as null | SpatialWindowContainer
+
+  /**
+   * Gets the current window container for the window
+   * [TODO] discuss what happens if it doesnt yet have a window container
+   * @returns the current window container for the window
+   */
+  getCurrentWindowContainer() {
+    if (SpatialSession._currentWindowContainer) {
+      return SpatialSession._currentWindowContainer
+    } else {
+      SpatialSession._currentWindowContainer = new SpatialWindowContainer(
+        WebSpatial.getCurrentWindowContainer(),
+      )
+      return SpatialSession._currentWindowContainer
+    }
+  }
+
+  /**
+   * Start a transaction that queues up commands to submit them all at once to reduce ipc overhead
+   * @param fn function to be run, within this function, promises will not resolve
+   * @returns promise for the entire transaction completion
+   */
+  transaction(fn: Function) {
+    WebSpatial.startTransaction()
+    fn()
+    return WebSpatial.sendTransaction()
+  }
+
+  /**
+   * Creates a window context object that is compatable with SpatialWindowComponent's setFromWindow API
+   * @returns window context
+   */
+  async createWindowContext() {
+    let openedWindow = window.open('webspatial://createWindowContext')
+    if (WebSpatial.getBackend() != 'AVP') {
+      // Currently there is a bug with webview which requires us to trigger a navigation before native code can interact with created webview
+      var counter = 0
+      while ((openedWindow!.window as any).testAPI == null) {
+        if (counter > 15) {
+          openedWindow?.close()
+          openedWindow = window.open('about:blank')
+          counter = 0
+          this.log('unexpected error when trying to open new window, retrying.')
+        }
+        var locName = 'about:blank?x' + counter
+        openedWindow!!.location.href = locName
+        counter++
+
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      ;(openedWindow! as any)._webSpatialID = (
+        openedWindow!.window as any
+      ).testAPI.getWindowID()
+    } else {
+      while ((openedWindow!.window as any)._webSpatialID == undefined) {
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+    }
+    openedWindow!.document.head.innerHTML =
+      '<meta name="viewport" content="width=device-width, initial-scale=1">'
+    return openedWindow
+  }
+
+  // Get Entity by id. Currently for debugging only.
+  /** @hidden */
+  async _getEntity(id: string) {
+    const entityInfo = await WebSpatial.inspect(id)
+    const [_, x, y, z] = entityInfo.position.match(/(\d+\.?\d*)/g)
+    const [__, sx, sy, sz] = entityInfo.scale.match(/(\d+\.?\d*)/g)
+
+    var res = new WebSpatialResource()
+    res.id = id
+    res.windowContainerId = WebSpatial.getCurrentWindowContainer().id
+    const entity = new SpatialEntity(res)
+    entity.transform.position.x = parseFloat(x)
+    entity.transform.position.y = parseFloat(y)
+    entity.transform.position.z = parseFloat(z)
+
+    entity.transform.scale.x = parseFloat(sx)
+    entity.transform.scale.y = parseFloat(sy)
+    entity.transform.scale.z = parseFloat(sz)
+
+    return entity
+  }
+  // set loading view.
+  /** @hidden */
+  async setLoading(method: LoadingMethodKind, style?: string) {
+    return WebSpatial.setLoading(method, style)
+  }
+}

package/src/core/SpatialTransform.ts

@@ -0,0 +1,26 @@
+export class Vec3 {
+  constructor(
+    public x = 0,
+    public y = 0,
+    public z = 0,
+  ) {}
+}
+
+export class Vec4 {
+  constructor(
+    public x = 0,
+    public y = 0,
+    public z = 0,
+    public w = 1,
+  ) {}
+}
+
+/**
+ * Transform containing position, orientation and scale
+ */
+export class SpatialTransform {
+  position = new Vec3(0, 0, 0)
+  /** Quaternion value for x,y,z,w */
+  orientation = new Vec4(0, 0, 0, 1)
+  scale = new Vec3(1, 1, 1)
+}

package/src/core/SpatialWindowContainer.ts

@@ -0,0 +1,51 @@
+import {
+  WebSpatial,
+  WebSpatialResource,
+  WindowContainer,
+} from './private/WebSpatial'
+import { SpatialEntity } from './SpatialEntity'
+
+/**
+ * Anchored window managed by the OS
+ */
+export class SpatialWindowContainer {
+  /** @hidden */
+  constructor(
+    /** @hidden */
+    public _wg: WindowContainer,
+  ) {}
+  /**
+   * @hidden
+   * Sets sets the open configuration for opening new window containers
+   * @param options style options
+   */
+  async _setOpenSettings(options: { resolution: { width: number; height: number } }) {
+    await WebSpatial.updateWindowContainer(this._wg, {
+      nextOpenSettings: options,
+    })
+  }
+
+  /**
+   * Retrieves the root entity of the windowContainer
+   * @returns the root entity of the windowContainer if one exists
+   */
+  async getRootEntity() {
+    let reqResp: any = await WebSpatial.updateWindowContainer(this._wg, {
+      getRootEntityID: '',
+    })
+    if (reqResp.data.rootEntId === '') {
+      return null
+    } else {
+      var res = new WebSpatialResource()
+      res.id = reqResp.data.rootEntId
+      return new SpatialEntity(res)
+    }
+  }
+  /*
+   * Sets the root entity that this windowContainer will display (this does not effect resource ownership)
+   * @param entity to display
+   */
+  async setRootEntity(entity: SpatialEntity) {
+    await entity._setParentWindowContainer(this)
+  }
+}

package/src/core/component/EventSpatialComponent.ts

@@ -0,0 +1,32 @@
+import { WebSpatial, WebSpatialResource } from '../private/WebSpatial'
+import { SpatialComponent } from './SpatialComponent'
+
+/**
+ * @description
+ * Represents a spatial component that handles events related to spatial interactions.
+ * This class extends `SpatialComponent` and provides additional functionality for managing
+ * event-driven spatial behaviors.
+ *
+ * @hidden
+ * This class is intended for internal use and should not be exposed in the public API.
+ */
+export abstract class EventSpatialComponent extends SpatialComponent {
+  // Class implementation goes here
+  constructor(_resource: WebSpatialResource) {
+    super(_resource)
+    WebSpatial.registerEventReceiver(_resource.id, (data: any) => {
+      this.onRecvEvent(data)
+    })
+  }
+
+  /**
+   * @description
+   * Abstract method to be implemented by subclasses. Called when a spatial event is received.
+   * @param data The data associated with the received event.
+   */
+  protected abstract onRecvEvent(data: any): void
+
+  protected override async onDestroy() {
+    WebSpatial.unregisterEventReceiver(this._resource.id)
+  }
+}

package/src/core/component/SpatialComponent.ts

@@ -0,0 +1,26 @@
+import { WebSpatial, WebSpatialResource } from '../private/WebSpatial'
+import { SpatialEntity } from '../SpatialEntity'
+import { SpatialObject } from '../SpatialObject'
+
+/** @hidden */
+export class SpatialComponent extends SpatialObject {
+  /**
+   * Gets the entity this component is attached to
+   * @returns entity or null
+   */
+  async getEntity() {
+    let reqResp: any = await WebSpatial.updateResource(
+      WebSpatial.getCurrentWebPanel(),
+      { getEntityID: '' },
+    )
+    if (reqResp.data.parentID === '') {
+      return new Promise<SpatialEntity | null>((res, rej) => {
+        res(null)
+      })
+    } else {
+      var res = new WebSpatialResource()
+      res.id = reqResp.data.parentID
+      return new SpatialEntity(res)
+    }
+  }
+}

package/src/core/component/SpatialInputComponent.ts

@@ -0,0 +1,24 @@
+import { Vec3 } from '../SpatialTransform'
+import { EventSpatialComponent } from './EventSpatialComponent'
+
+/**
+ * Translate event, matching similar behavior to https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drag_event
+ */
+type TranslateEvent = {
+  eventType: 'dragstart' | 'dragend' | 'drag'
+  translate?: Vec3
+}
+/**
+ * Used to handle input events on an entity
+ */
+export class SpatialInputComponent extends EventSpatialComponent {
+  protected override onRecvEvent(data: any): void {
+    this.onTranslate(data)
+  }
+
+  /**
+   * Callback fired when a translate event occurs
+   * @param data translate event data
+   */
+  public onTranslate(data: TranslateEvent) {}
+}