@webspatial/core-sdk 1.2.1 → 1.4.0

package/src/reality/Attachment.ts

@@ -0,0 +1,47 @@
+import { SpatialObject } from '../SpatialObject'
+import {
+  CreateAttachmentEntityCommand,
+  UpdateAttachmentEntityCommand,
+  InitializeAttachmentCommand,
+} from '../JSBCommand'
+import {
+  AttachmentEntityOptions,
+  AttachmentEntityUpdateOptions,
+} from '../types/types'
+
+export class Attachment extends SpatialObject {
+  constructor(
+    id: string,
+    private readonly windowProxy: WindowProxy,
+    private options: AttachmentEntityOptions,
+  ) {
+    super(id)
+  }
+
+  getContainer(): HTMLElement {
+    return (this.windowProxy as Window).document.body
+  }
+
+  getWindowProxy(): WindowProxy {
+    return this.windowProxy
+  }
+
+  async update(options: AttachmentEntityUpdateOptions) {
+    if (this.isDestroyed) return
+    if (options.position) this.options.position = options.position
+    if (options.size) this.options.size = options.size
+    return new UpdateAttachmentEntityCommand(this.id, options).execute()
+  }
+}
+
+export async function createAttachmentEntity(
+  options: AttachmentEntityOptions,
+): Promise<Attachment> {
+  const result = await new CreateAttachmentEntityCommand(options).execute()
+  if (!result.success) {
+    throw new Error('createAttachmentEntity failed: ' + result?.errorMessage)
+  }
+  const { id, windowProxy } = result.data!
+  await new InitializeAttachmentCommand(id, options).execute()
+  return new Attachment(id, windowProxy, options)
+}

package/src/reality/entity/SpatialEntity.ts

@@ -23,16 +23,16 @@ import { SpatialComponent } from '../component/SpatialComponent'
 import { SpatialWebEvent } from '../../SpatialWebEvent'
 import { createSpatialEvent } from '../../SpatialWebEventCreator'
 import {
-  CubeInfoMsg,
   ObjectDestroyMsg,
   SpatialDragEndMsg,
   SpatialDragMsg,
+  SpatialDragStartMsg,
+  SpatialMagnifyEndMsg,
   SpatialMagnifyMsg,
   SpatialRotateEndMsg,
   SpatialRotateMsg,
   SpatialTapMsg,
   SpatialWebMsgType,
-  TransformMsg,
 } from '../../WebMsgCommand'
 
 export class SpatialEntity extends SpatialObject {
@@ -43,6 +43,31 @@ export class SpatialEntity extends SpatialObject {
   events: Record<string, (data: any) => void> = {}
   children: SpatialEntity[] = []
   parent: SpatialEntityOrReality | null = null
+  private _enableInput: boolean = false
+
+  get enableInput(): boolean {
+    return this._enableInput
+  }
+
+  set enableInput(value: boolean) {
+    // Why enabling only 'spatialtap' makes the entity interactive:
+    // - On the native (Swift/RealityKit) side, SpatialEntity.updateGesture(type, isEnable)
+    //   toggles per-gesture flags. Then enableInteractive = enableTap || enableRotate || enableDrag || enableMagnify.
+    // - As soon as any gesture (e.g., 'spatialtap') is enabled, enableInteractive becomes true and
+    //   InputTargetComponent is attached, making the entity targetable by targetedToAnyEntity().
+    // - The view layer forwards hit gestures to the web, so enabling 'spatialtap' is sufficient to
+    //   make the entity targetable; enable additional gestures only when needed.
+    if (this._enableInput === value) return
+    this._enableInput = value
+    void this.updateEntityEvent('spatialtap', value).catch(err => {
+      console.error('enableInput updateEntityEvent failed', 'spatialtap', err)
+      // Roll back local flag if the native toggle fails to keep web/native states consistent.
+      // Otherwise, the web side would think the entity is interactive while RealityKit is not.
+      if (this._enableInput === value) {
+        this._enableInput = !value
+      }
+    })
+  }
   constructor(
     id: string,
     public userData?: SpatialEntityUserData,
@@ -123,13 +148,15 @@ export class SpatialEntity extends SpatialObject {
     return new UpdateEntityEventCommand(this, eventName, isEnable).execute()
   }
   private onReceiveEvent = (
-    data: // | CubeInfoMsg
-    // | TransformMsg
-    | SpatialTapMsg
-      // | SpatialDragMsg
-      // | SpatialDragEndMsg
-      // | SpatialRotateMsg
-      // | SpatialRotateEndMsg
+    data:
+      | SpatialTapMsg
+      | SpatialDragStartMsg
+      | SpatialDragMsg
+      | SpatialDragEndMsg
+      | SpatialMagnifyMsg
+      | SpatialMagnifyEndMsg
+      | SpatialRotateMsg
+      | SpatialRotateEndMsg
       | ObjectDestroyMsg,
   ) => {
     // console.log('SpatialEntityEvent', data)
@@ -139,27 +166,21 @@ export class SpatialEntity extends SpatialObject {
     }
     // tap
     else if (type === SpatialWebMsgType.spatialtap) {
-      const evt = createSpatialEvent(
-        SpatialWebMsgType.spatialtap,
-        (data as SpatialTapMsg).detail,
-      )
+      const evt = createSpatialEvent(SpatialWebMsgType.spatialtap, data.detail)
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialdragstart) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialdragstart,
-        (data as SpatialDragMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialdrag) {
-      const evt = createSpatialEvent(
-        SpatialWebMsgType.spatialdrag,
-        (data as SpatialDragMsg).detail,
-      )
+      const evt = createSpatialEvent(SpatialWebMsgType.spatialdrag, data.detail)
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialdragend) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialdragend,
-        (data as SpatialDragEndMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     }
@@ -167,13 +188,13 @@ export class SpatialEntity extends SpatialObject {
     else if (type === SpatialWebMsgType.spatialrotate) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialrotate,
-        (data as SpatialRotateMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialrotateend) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialrotateend,
-        (data as SpatialRotateEndMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     }
@@ -181,13 +202,13 @@ export class SpatialEntity extends SpatialObject {
     else if (type === SpatialWebMsgType.spatialmagnify) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialmagnify,
-        (data as SpatialMagnifyMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     } else if (type === SpatialWebMsgType.spatialmagnifyend) {
       const evt = createSpatialEvent(
         SpatialWebMsgType.spatialmagnifyend,
-        (data as SpatialMagnifyMsg).detail,
+        data.detail,
       )
       this.dispatchEvent(evt)
     }
@@ -200,7 +221,7 @@ export class SpatialEntity extends SpatialObject {
     }
     this.events[evt.type]?.(evt)
     if (evt.bubbles && !evt.cancelBubble) {
-      if (this.parent && this.parent instanceof SpatialEntity) {
+      if (this.parent) {
         this.parent.dispatchEvent(evt)
       }
     }

package/src/reality/index.ts

@@ -3,3 +3,4 @@ export * from './component'
 export * from './material'
 export * from './geometry'
 export * from './resource'
+export * from './Attachment'

package/src/types/global.d.ts

@@ -1,3 +1,5 @@
+import type { PhysicalMetricsValueShape } from '../physicalMetrics'
+
 declare global {
   declare const __WEBSPATIAL_CORE_SDK_VERSION__: string
 
@@ -28,16 +30,16 @@ declare global {
       'natvie-version'?: string
       'react-sdk-version'?: string
       'core-sdk-version'?: string
+      physicalMetrics?: PhysicalMetricsValueShape
     }
 
-    innerDepth: number
-    outerDepth: number
+    xrInnerDepth: number
+    xrOuterDepth: number
   }
 
   interface HTMLElement {
-    offsetBack: number
-    clientDepth: number
-    getBoundingClientCube: () => CubeInfo | undefined
+    xrOffsetBack: number
+    xrClientDepth: number
   }
 }
 

package/src/types/types.ts

@@ -80,6 +80,11 @@ export interface SpatializedElementProperties {
   enableRotateEndGesture: boolean
   enableMagnifyGesture: boolean
   enableMagnifyEndGesture: boolean
+  /**
+   * Optional world-space axis for spatial rotate gesture. Omitted or zero vector
+   * means unconstrained rotation (platform default).
+   */
+  rotateConstrainedToAxis?: Vec3
 }
 
 export interface Spatialized2DElementProperties
@@ -115,6 +120,16 @@ export interface SpatialSceneCreationOptions {
   baseplateVisibility?: BaseplateVisibilityType
 }
 
+export type SpatialEntityEventType =
+  | 'spatialtap'
+  | 'spatialdragstart'
+  | 'spatialdrag'
+  | 'spatialdragend'
+  | 'spatialrotate'
+  | 'spatialrotateend'
+  | 'spatialmagnify'
+  | 'spatialmagnifyend'
+
 export const BaseplateVisibilityValues = [
   'automatic',
   'visible',
@@ -186,8 +201,6 @@ export interface SpatialEntityProperties {
   scale: Vec3
 }
 
-export type SpatialEntityEventType = 'spatialtap' //| 'drag' | 'rotate' | 'scale'
-
 export type SpatialGeometryType =
   | 'BoxGeometry'
   | 'PlaneGeometry'
@@ -344,12 +357,14 @@ export class CubeInfo {
 
 export interface SpatialTapEventDetail {
   location3D: Point3D
+  globalLocation3D?: Point3D
 }
 
 export type SpatialTapEvent = CustomEvent<SpatialTapEventDetail>
 
 export interface SpatialDragStartEventDetail {
   startLocation3D: Point3D
+  globalLocation3D?: Point3D
 }
 
 export interface SpatialDragEventDetail {
@@ -384,3 +399,15 @@ export type SpatialMagnifyEvent = CustomEvent<SpatialMagnifyEventDetail>
 export type SpatialMagnifyEndEvent = CustomEvent<SpatialMagnifyEndEventDetail>
 
 export type SpatialEntityOrReality = SpatialEntity | SpatializedDynamic3DElement
+
+export interface AttachmentEntityOptions {
+  parentEntityId: string
+  position?: [number, number, number]
+  size: { width: number; height: number }
+  ownerViewId: string
+}
+
+export interface AttachmentEntityUpdateOptions {
+  position?: [number, number, number]
+  size?: { width: number; height: number }
+}