@webspatial/core-sdk 1.0.4 → 1.1.0

package/src/SpatialObject.ts

@@ -0,0 +1,46 @@
+import { DestroyCommand, InspectCommand } from './JSBCommand'
+
+/**
+ * @hidden
+ * Parent class of spatial objects, should not be used directly
+ */
+export class SpatialObject {
+  /** @hidden */
+  constructor(
+    /** @hidden */
+    public readonly id: string,
+  ) {}
+
+  name?: string
+
+  isDestroyed = false
+
+  async inspect() {
+    const ret = await new InspectCommand(this.id).execute()
+    if (ret.success) {
+      return ret.data
+    }
+    throw new Error(ret.errorMessage)
+  }
+
+  async destroy() {
+    if (this.isDestroyed) {
+      return
+    }
+
+    const ret = await new DestroyCommand(this.id).execute()
+    if (ret.success) {
+      this.onDestroy()
+      this.isDestroyed = true
+      return ret.data
+    } else if (this.isDestroyed) {
+      // already destroyed
+      return
+    }
+
+    throw new Error(ret.errorMessage)
+  }
+
+  // override this method to do some cleanup
+  protected onDestroy() {}
+}

package/src/SpatialScene.ts

@@ -0,0 +1,75 @@
+import {
+  SpatialSceneCreationOptions,
+  SpatialSceneProperties,
+} from './types/types'
+import { SpatialSceneCreationOptionsInternal } from "./types/internal"
+import {
+  AddSpatializedElementToSpatialScene,
+  GetSpatialSceneState,
+  UpdateSceneConfig,
+  UpdateSpatialSceneProperties,
+} from './JSBCommand'
+
+import { SpatializedElement } from './SpatializedElement'
+import { SpatialObject } from './SpatialObject'
+import { SpatialSceneState } from './types/internal'
+
+let instance: SpatialScene
+
+/**
+ * Represents the spatial scene that contains all spatialized elements.
+ * This class follows the singleton pattern - only one instance exists per application.
+ * The scene manages the overall spatial environment properties and contains all spatial elements.
+ */
+export class SpatialScene extends SpatialObject {
+  /**
+   * Gets the singleton instance of the SpatialScene.
+   * Creates a new instance if one doesn't exist yet.
+   * @returns The singleton SpatialScene instance
+   */
+  static getInstance(): SpatialScene {
+    if (!instance) {
+      instance = new SpatialScene('')
+    }
+    return instance
+  }
+
+  /**
+   * Updates the properties of the spatial scene.
+   * This can include background settings, lighting, and other scene-wide properties.
+   * @param properties Partial set of properties to update
+   * @returns Promise resolving when the update is complete
+   */
+  async updateSpatialProperties(properties: Partial<SpatialSceneProperties>) {
+    return new UpdateSpatialSceneProperties(properties).execute()
+  }
+
+  /**
+   * Adds a spatialized element to the scene.
+   * This makes the element visible and interactive in the spatial environment.
+   * @param element The SpatializedElement to add to the scene
+   * @returns Promise resolving when the element is added
+   */
+  async addSpatializedElement(element: SpatializedElement) {
+    return new AddSpatializedElementToSpatialScene(element).execute()
+  }
+
+  /**
+   * Updates the scene creation configuration.
+   * This allows changing scene parameters after initial creation.
+   * @param config The new scene creation configuration
+   * @returns Promise resolving when the update is complete
+   */
+  async updateSceneCreationConfig(config: SpatialSceneCreationOptionsInternal) {
+    return new UpdateSceneConfig(config).execute()
+  }
+
+  /**
+   * Gets the current state of the spatial scene.
+   * This includes information about active elements and scene configuration.
+   * @returns Promise resolving to the current SpatialSceneState
+   */
+  async getState(): Promise<SpatialSceneState> {
+    return (await new GetSpatialSceneState().execute()).data.name
+  }
+}

package/src/SpatialSession.ts

@@ -0,0 +1,187 @@
+import { initScene } from './scene-polyfill'
+import { SpatialScene } from './SpatialScene'
+import { Spatialized2DElement } from './Spatialized2DElement'
+import {
+  createSpatialized2DElement,
+  createSpatializedDynamic3DElement,
+} from './SpatializedElementCreator'
+import { createSpatializedStatic3DElement } from './SpatializedElementCreator'
+import { SpatializedStatic3DElement } from './SpatializedStatic3DElement'
+import {
+  ModelComponentOptions,
+  ModelAssetOptions,
+  SpatialBoxGeometryOptions,
+  SpatialConeGeometryOptions,
+  SpatialCylinderGeometryOptions,
+  SpatialGeometryOptions,
+  SpatialModelEntityCreationOptions,
+  SpatialPlaneGeometryOptions,
+  SpatialSceneCreationOptions,
+  SpatialSphereGeometryOptions,
+  SpatialUnlitMaterialOptions,
+  SpatialEntityUserData,
+} from './types/types'
+import { SpatializedDynamic3DElement } from './SpatializedDynamic3DElement'
+import { SpatialEntity } from './reality/entity/SpatialEntity'
+import {
+  createModelAsset,
+  createModelComponent,
+  createSpatialEntity,
+  createSpatialGeometry,
+  createSpatialModelEntity,
+  createSpatialUnlitMaterial,
+} from './reality/realityCreator'
+import {
+  SpatialBoxGeometry,
+  SpatialPlaneGeometry,
+  SpatialSphereGeometry,
+  SpatialConeGeometry,
+  SpatialCylinderGeometry,
+} from './reality'
+
+/**
+ * Session used to establish a connection to the spatial renderer of the system.
+ * All spatial resources must be created through this session object.
+ * This class serves as the main factory for creating spatial elements and geometries.
+ */
+export class SpatialSession {
+  /**
+   * Gets the singleton instance of the spatial scene.
+   * The spatial scene is the root container for all spatial elements.
+   * @returns The SpatialScene singleton instance
+   */
+  getSpatialScene(): SpatialScene {
+    return SpatialScene.getInstance()
+  }
+
+  /**
+   * Creates a new 2D element that can be spatialized in the 3D environment.
+   * 2D elements represent HTML content that can be positioned in 3D space.
+   * @returns Promise resolving to a new Spatialized2DElement instance
+   */
+  createSpatialized2DElement(): Promise<Spatialized2DElement> {
+    return createSpatialized2DElement()
+  }
+
+  /**
+   * Creates a new static 3D element with an optional model URL.
+   * Static 3D elements represent pre-built 3D models that can be loaded from a URL.
+   * @param modelURL Optional URL to the 3D model to load
+   * @returns Promise resolving to a new SpatializedStatic3DElement instance
+   */
+  createSpatializedStatic3DElement(
+    modelURL: string = '',
+  ): Promise<SpatializedStatic3DElement> {
+    return createSpatializedStatic3DElement(modelURL)
+  }
+
+  /**
+   * Initializes the spatial scene with custom configuration.
+   * This is a reference to the initScene function from scene-polyfill.
+   */
+  initScene = initScene
+  
+  /**
+   * Creates a new dynamic 3D element that can be manipulated at runtime.
+   * Dynamic 3D elements allow for programmatic creation and modification of 3D content.
+   * @returns Promise resolving to a new SpatializedDynamic3DElement instance
+   */
+  createSpatializedDynamic3DElement(): Promise<SpatializedDynamic3DElement> {
+    return createSpatializedDynamic3DElement()
+  }
+
+  /**
+   * Creates a new spatial entity with an optional name.
+   * Entities are the basic building blocks for creating custom 3D content.
+   * @param name Optional name for the entity
+   * @returns Promise resolving to a new SpatialEntity instance
+   */
+  createEntity(userData?: SpatialEntityUserData,): Promise<SpatialEntity> {
+    return createSpatialEntity(userData)
+  }
+
+  /**
+   * Creates a box geometry with optional configuration.
+   * @param options Configuration options for the box geometry
+   * @returns Promise resolving to a new SpatialBoxGeometry instance
+   */
+  createBoxGeometry(options: SpatialBoxGeometryOptions = {}) {
+    return createSpatialGeometry(SpatialBoxGeometry, options)
+  }
+
+  /**
+   * Creates a plane geometry with optional configuration.
+   * @param options Configuration options for the plane geometry
+   * @returns Promise resolving to a new SpatialPlaneGeometry instance
+   */
+  createPlaneGeometry(options: SpatialPlaneGeometryOptions = {}) {
+    return createSpatialGeometry(SpatialPlaneGeometry, options)
+  }
+
+  /**
+   * Creates a sphere geometry with optional configuration.
+   * @param options Configuration options for the sphere geometry
+   * @returns Promise resolving to a new SpatialSphereGeometry instance
+   */
+  createSphereGeometry(options: SpatialSphereGeometryOptions = {}) {
+    return createSpatialGeometry(SpatialSphereGeometry, options)
+  }
+
+  /**
+   * Creates a cone geometry with the specified configuration.
+   * @param options Configuration options for the cone geometry
+   * @returns Promise resolving to a new SpatialConeGeometry instance
+   */
+  createConeGeometry(options: SpatialConeGeometryOptions) {
+    return createSpatialGeometry(SpatialConeGeometry, options)
+  }
+
+  /**
+   * Creates a cylinder geometry with the specified configuration.
+   * @param options Configuration options for the cylinder geometry
+   * @returns Promise resolving to a new SpatialCylinderGeometry instance
+   */
+  createCylinderGeometry(options: SpatialCylinderGeometryOptions) {
+    return createSpatialGeometry(SpatialCylinderGeometry, options)
+  }
+
+  /**
+   * Creates a model component with the specified configuration.
+   * Model components are used to add 3D model rendering capabilities to entities.
+   * @param options Configuration options for the model component
+   * @returns Promise resolving to a new ModelComponent instance
+   */
+  createModelComponent(options: ModelComponentOptions) {
+    return createModelComponent(options)
+  }
+
+  /**
+   * Creates an unlit material with the specified configuration.
+   * Unlit materials don't respond to lighting in the scene.
+   * @param options Configuration options for the unlit material
+   * @returns Promise resolving to a new SpatialUnlitMaterial instance
+   */
+  createUnlitMaterial(options: SpatialUnlitMaterialOptions) {
+    return createSpatialUnlitMaterial(options)
+  }
+  
+  /**
+   * Creates a model asset with the specified configuration.
+   * Model assets represent 3D model resources that can be used by entities.
+   * @param options Configuration options for the model asset
+   * @returns Promise resolving to a new SpatialModelAsset instance
+   */
+  createModelAsset(options: ModelAssetOptions) {
+    return createModelAsset(options)
+  }
+
+  /**
+   * Creates a spatial model entity with the specified configuration.
+   * This is a convenience method for creating an entity with a model component.
+   * @param options Configuration options for the spatial model entity
+   * @returns Promise resolving to a new SpatialModelEntity instance
+   */
+  createSpatialModelEntity(options: SpatialModelEntityCreationOptions, userData?: SpatialEntityUserData) {
+    return createSpatialModelEntity(options, userData)
+  }
+}

package/src/SpatialWebEvent.ts

@@ -0,0 +1,23 @@
+interface SpatialWebEventData {
+  id: string
+  data: any
+}
+
+export class SpatialWebEvent {
+  static eventReceiver: Record<string, (data: any) => void> = {}
+  static init() {
+    // inject __SpatialWebEvent
+    window.__SpatialWebEvent = ({ id, data }: SpatialWebEventData) => {
+      // console.log('__SpatialWebEvent', id, data)
+      SpatialWebEvent.eventReceiver[id]?.(data)
+    }
+  }
+
+  static addEventReceiver(id: string, callback: (data: any) => void) {
+    SpatialWebEvent.eventReceiver[id] = callback
+  }
+
+  static removeEventReceiver(id: string) {
+    delete SpatialWebEvent.eventReceiver[id]
+  }
+}

package/src/SpatialWebEventCreator.ts

@@ -0,0 +1,12 @@
+import { SpatialWebMsgType } from './WebMsgCommand'
+
+export function createSpatialEvent<T>(
+  type: SpatialWebMsgType,
+  detail: T,
+): CustomEvent<T> {
+  return new CustomEvent<T>(type, {
+    bubbles: true,
+    cancelable: false,
+    detail,
+  })
+}

package/src/Spatialized2DElement.ts

@@ -0,0 +1,51 @@
+import {
+  AddSpatializedElementToSpatialized2DElement,
+  UpdateSpatialized2DElementProperties,
+} from './JSBCommand'
+import { hijackWindowATag } from './scene-polyfill'
+import { SpatializedElement } from './SpatializedElement'
+import { Spatialized2DElementProperties } from './types/types'
+
+/**
+ * Represents a 2D HTML element that has been spatialized in 3D space.
+ * This class handles the integration between 2D web content and the 3D spatial environment,
+ * allowing HTML elements to be positioned and interacted with in spatial applications.
+ */
+export class Spatialized2DElement extends SpatializedElement {
+  /**
+   * Creates a new spatialized 2D element.
+   * @param id Unique identifier for this element
+   * @param windowProxy Reference to the window object containing the 2D content
+   */
+  constructor(
+    id: string,
+    readonly windowProxy: WindowProxy,
+  ) {
+    super(id)
+    // Hijack anchor tag events to handle navigation within the spatial context
+    hijackWindowATag(windowProxy)
+  }
+
+  /**
+   * Updates the properties of this 2D element.
+   * This can include size, position, background, and other visual properties.
+   * @param properties Partial set of properties to update
+   * @returns Promise resolving when the update is complete
+   */
+  async updateProperties(properties: Partial<Spatialized2DElementProperties>) {
+    return new UpdateSpatialized2DElementProperties(this, properties).execute()
+  }
+
+  /**
+   * Adds a child spatialized element to this 2D element.
+   * This allows for creating hierarchical structures of spatial elements.
+   * @param element The child element to add
+   * @returns Promise resolving when the element is added
+   */
+  async addSpatializedElement(element: SpatializedElement) {
+    return new AddSpatializedElementToSpatialized2DElement(
+      this,
+      element,
+    ).execute()
+  }
+}

package/src/SpatializedDynamic3DElement.ts

@@ -0,0 +1,30 @@
+import {
+  AddEntityToDynamic3DCommand,
+  SetParentForEntityCommand,
+  UpdateSpatializedDynamic3DElementProperties,
+} from './JSBCommand'
+import { SpatialEntity } from './reality'
+import { SpatializedElement } from './SpatializedElement'
+import {
+  SpatialEntityOrReality,
+  SpatializedElementProperties,
+} from './types/types'
+export class SpatializedDynamic3DElement extends SpatializedElement {
+  children: SpatialEntityOrReality[] = []
+  constructor(id: string) {
+    super(id)
+  }
+
+  async addEntity(entity: SpatialEntity) {
+    const ans = new SetParentForEntityCommand(entity.id, this.id).execute()
+    this.children.push(entity)
+    entity.parent = this
+    return ans
+  }
+  async updateProperties(properties: Partial<SpatializedElementProperties>) {
+    return new UpdateSpatializedDynamic3DElementProperties(
+      this,
+      properties,
+    ).execute()
+  }
+}