@relu-interactives/spatial-ecs 0.3.2 → 0.3.5

package/dist/index.cjs

@@ -2593,7 +2593,8 @@ var _VRTeleportAreaComponent = class _VRTeleportAreaComponent extends Component
   constructor(options) {
     super();
     this.enabled = options?.enabled ?? true;
-    this.shape = options?.shape ?? "plane";
+    const shape = options?.shape;
+    this.shape = shape === "cylinder" ? "circle" : options?.shape ?? "plane";
     this.width = options?.width ?? 10;
     this.depth = options?.depth ?? 10;
   }
@@ -4340,6 +4341,15 @@ function buildComponentValueMaps(snapshot) {
       snapshot.components,
       "ScriptObjectComponent"
     ),
+    xrRigValues: readByComponent(snapshot.components, "XRRigComponent"),
+    vrTeleportAreaValues: readByComponent(
+      snapshot.components,
+      "VRTeleportAreaComponent"
+    ),
+    xrInteractableValues: readByComponent(
+      snapshot.components,
+      "XRInteractableComponent"
+    ),
     instancedMeshValues: readByComponent(snapshot.components, "InstancedMeshComponent"),
     instanceSlotValues: readByComponent(snapshot.components, "InstanceSlotComponent"),
     prefabNodeValues: readByComponent(snapshot.components, "PrefabNode"),
@@ -4465,6 +4475,67 @@ function restorePostCreateComponents(world, objectManagementSystem, targetEntity
       soc.data = remapEntityRefsInScriptData(data, idMap);
     }
   }
+  {
+    const sourceXrRig = asRecord3(values.xrRigValues.get(sourceEntityId));
+    const rig = world.getComponent(targetEntityId, XRRigComponent);
+    if (sourceXrRig && rig) {
+      if (typeof sourceXrRig.locomotion === "string") {
+        rig.locomotion = sourceXrRig.locomotion;
+      }
+      if (typeof sourceXrRig.moveSpeed === "number") {
+        rig.moveSpeed = sourceXrRig.moveSpeed;
+      }
+      if (typeof sourceXrRig.snapTurn === "boolean") {
+        rig.snapTurn = sourceXrRig.snapTurn;
+      }
+      if (typeof sourceXrRig.snapTurnDegrees === "number") {
+        rig.snapTurnDegrees = sourceXrRig.snapTurnDegrees;
+      }
+      if (typeof sourceXrRig.fallbackEyeHeight === "number") {
+        rig.fallbackEyeHeight = sourceXrRig.fallbackEyeHeight;
+      }
+    }
+  }
+  {
+    const sourceArea = asRecord3(values.vrTeleportAreaValues.get(sourceEntityId));
+    const area = world.getComponent(targetEntityId, VRTeleportAreaComponent);
+    if (sourceArea && area) {
+      if (typeof sourceArea.enabled === "boolean") {
+        area.enabled = sourceArea.enabled;
+      }
+      if (typeof sourceArea.shape === "string") {
+        area.shape = sourceArea.shape === "cylinder" ? "circle" : sourceArea.shape;
+      }
+      if (typeof sourceArea.width === "number") area.width = sourceArea.width;
+      if (typeof sourceArea.depth === "number") area.depth = sourceArea.depth;
+    }
+  }
+  {
+    const sourceInteractable = asRecord3(
+      values.xrInteractableValues.get(sourceEntityId)
+    );
+    const interactable = world.getComponent(
+      targetEntityId,
+      XRInteractableComponent
+    );
+    if (sourceInteractable && interactable) {
+      if (typeof sourceInteractable.enabled === "boolean") {
+        interactable.enabled = sourceInteractable.enabled;
+      }
+      if (typeof sourceInteractable.grabbable === "boolean") {
+        interactable.grabbable = sourceInteractable.grabbable;
+      }
+      if (typeof sourceInteractable.pointable === "boolean") {
+        interactable.pointable = sourceInteractable.pointable;
+      }
+      if (typeof sourceInteractable.grabMode === "string") {
+        interactable.grabMode = sourceInteractable.grabMode;
+      }
+      if (typeof sourceInteractable.highlightOnHover === "boolean") {
+        interactable.highlightOnHover = sourceInteractable.highlightOnHover;
+      }
+    }
+  }
   {
     const imComponent = world.getComponent(targetEntityId, InstancedMeshComponent);
     if (imComponent && imComponent.instanceEntityIds.length > 0) {
@@ -10436,6 +10507,45 @@ var _XRInteractionSystem = class _XRInteractionSystem {
 };
 __name(_XRInteractionSystem, "XRInteractionSystem");
 var XRInteractionSystem = _XRInteractionSystem;
+var ARC_GRAVITY = 9.8;
+var ARC_SPEED = 7;
+var ARC_STEPS = 24;
+var ARC_MAX_TIME = 2;
+function sampleTeleportArc(origin, direction, out = [], options) {
+  const speed = options?.speed ?? ARC_SPEED;
+  const gravity = options?.gravity ?? ARC_GRAVITY;
+  const steps = Math.max(2, options?.steps ?? ARC_STEPS);
+  const maxTime = options?.maxTime ?? ARC_MAX_TIME;
+  out.length = 0;
+  const velocity = direction.clone().normalize().multiplyScalar(speed);
+  for (let i = 0; i < steps; i += 1) {
+    const t = i / (steps - 1) * maxTime;
+    out.push(
+      new THREE38__namespace.Vector3(
+        origin.x + velocity.x * t,
+        origin.y + velocity.y * t - 0.5 * gravity * t * t,
+        origin.z + velocity.z * t
+      )
+    );
+  }
+  return out;
+}
+__name(sampleTeleportArc, "sampleTeleportArc");
+function arcGroundCrossing(points, groundY) {
+  for (let i = 1; i < points.length; i += 1) {
+    const previous = points[i - 1];
+    const current = points[i];
+    if (previous.y >= groundY && current.y <= groundY) {
+      const span = previous.y - current.y;
+      const alpha = span > 1e-6 ? (previous.y - groundY) / span : 0;
+      return new THREE38__namespace.Vector3().lerpVectors(previous, current, alpha);
+    }
+  }
+  return null;
+}
+__name(arcGroundCrossing, "arcGroundCrossing");
+
+// core/systems/XRLocomotionSystem.ts
 var UP = new THREE38__namespace.Vector3(0, 1, 0);
 var AXIS_DEADZONE = 0.5;
 var _XRLocomotionSystem = class _XRLocomotionSystem {
@@ -10443,13 +10553,26 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     this.raycaster = new THREE38__namespace.Raycaster();
     /** Per-source latch so one stick push yields exactly one snap turn. */
     this.turnLatched = /* @__PURE__ */ new WeakSet();
-    /** Where the pointer currently lands, for the consumer to draw a marker. */
-    this.teleportPoint = null;
+    /** Reused arc buffer — aiming runs every frame. */
+    this.arcPoints = [];
+    /** Curve up to the landing point, for the visual system. Empty when not aiming. */
+    this.aimCurve = [];
+    this.landingPoint = null;
+    /** True once we've tried to self-heal camera parenting for this session. */
+    this.parentingChecked = false;
     this.inputSystem = inputSystem;
   }
   update(world, deltaTime) {
-    this.teleportPoint = null;
-    if (!world.isXrPresenting()) return;
+    this.aimCurve = [];
+    this.landingPoint = null;
+    if (!world.isXrPresenting()) {
+      this.parentingChecked = false;
+      return;
+    }
+    if (!this.parentingChecked) {
+      this.parentingChecked = true;
+      this.ensureCameraUnderRig(world);
+    }
     const rigEntityId = world.query(XRRigComponent, TransformComponent)[0];
     if (typeof rigEntityId !== "number") return;
     const rig = world.getComponent(rigEntityId, XRRigComponent);
@@ -10466,9 +10589,37 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
       this.applySmoothMove(world, rig, rigTransform, inputs, deltaTime);
     }
   }
+  /**
+   * Guarantee the render camera is a CHILD of the rig.
+   *
+   * Locomotion moves the rig, and three composes the head pose against
+   * `camera.parent` — so if the camera sits at the scene root instead, moving
+   * the rig does nothing at all and the player is frozen in place. Scenes
+   * authored before the rig existed (or with the camera re-parented by hand)
+   * would otherwise silently fail to move, which is exactly the symptom that is
+   * hardest to diagnose from inside a headset. Repairing it via `ParentId` lets
+   * `ObjectManagementSystem` reconcile the scene graph normally.
+   */
+  ensureCameraUnderRig(world) {
+    const rigEntityId = world.query(XRRigComponent)[0];
+    if (typeof rigEntityId !== "number") return;
+    const activeCamera = world.getCamera();
+    for (const entityId of world.query(CameraComponent, Object3DRef)) {
+      if (world.getComponent(entityId, Object3DRef)?.object !== activeCamera) {
+        continue;
+      }
+      const parent = world.getComponent(entityId, ParentId);
+      if (parent) {
+        if (parent.value !== rigEntityId) parent.value = rigEntityId;
+      } else {
+        world.addComponent(entityId, new ParentId(rigEntityId));
+      }
+      return;
+    }
+  }
   /**
    * Snap turning, not smooth turning — rotating the view continuously is the
-   * single biggest cause of VR nausea, so the comfort-safe option is the one
+   * single biggest cause of VR nausea, so the comfort-safe option is what's
    * wired to the stick.
    */
   applySnapTurn(rig, transform, inputs) {
@@ -10482,8 +10633,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
       }
       if (this.turnLatched.has(source)) continue;
       this.turnLatched.add(source);
-      const step = THREE38__namespace.MathUtils.degToRad(rig.snapTurnDegrees);
-      transform.rotation.y -= Math.sign(x) * step;
+      transform.rotation.y -= Math.sign(x) * THREE38__namespace.MathUtils.degToRad(rig.snapTurnDegrees);
     }
   }
   applySmoothMove(world, rig, transform, inputs, deltaTime) {
@@ -10508,17 +10658,42 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     const targets = this.collectTeleportTargets(world);
     if (targets.length === 0) return;
     for (const input of inputs) {
-      this.raycaster.set(input.rayOrigin, input.rayDirection);
-      const hit = this.raycaster.intersectObjects(targets, true)[0];
+      if (!input.select && !input.selectEnd) continue;
+      const points = sampleTeleportArc(
+        input.rayOrigin,
+        input.rayDirection,
+        this.arcPoints
+      );
+      const hit = this.raycastArc(points, targets);
       if (!hit) continue;
-      this.teleportPoint = hit.point.clone();
+      this.landingPoint = hit.point;
+      this.aimCurve = points.slice(0, hit.segmentIndex + 1).concat(hit.point);
       if (input.selectEnd) {
         transform.position.x = hit.point.x;
         transform.position.y = hit.point.y;
         transform.position.z = hit.point.z;
+        this.aimCurve = [];
+        this.landingPoint = null;
       }
     }
   }
+  /** Walk the arc segment-by-segment, returning the first surface hit. */
+  raycastArc(points, targets) {
+    for (let i = 1; i < points.length; i += 1) {
+      const from = points[i - 1];
+      const to = points[i];
+      const delta = new THREE38__namespace.Vector3().subVectors(to, from);
+      const distance = delta.length();
+      if (distance < 1e-6) continue;
+      this.raycaster.set(from, delta.divideScalar(distance));
+      this.raycaster.far = distance;
+      const hit = this.raycaster.intersectObjects(targets, true)[0];
+      if (hit) {
+        return { point: hit.point.clone(), segmentIndex: i - 1 };
+      }
+    }
+    return null;
+  }
   collectTeleportTargets(world) {
     const objects = [];
     for (const entityId of world.query(VRTeleportAreaComponent, Object3DRef)) {
@@ -10530,12 +10705,13 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     }
     return objects;
   }
-  /**
-   * Where the teleport pointer currently lands this frame, or null.
-   * Consumers use this to render an aim marker.
-   */
-  getTeleportPoint() {
-    return this.teleportPoint;
+  /** Arc points up to the landing spot this frame; empty when not aiming. */
+  getAimCurve() {
+    return this.aimCurve;
+  }
+  /** Where the arc currently lands, or null when not aiming at a valid area. */
+  getLandingPoint() {
+    return this.landingPoint;
   }
 };
 __name(_XRLocomotionSystem, "XRLocomotionSystem");
@@ -10658,7 +10834,7 @@ var _XRSessionSystem = class _XRSessionSystem {
 __name(_XRSessionSystem, "XRSessionSystem");
 var XRSessionSystem = _XRSessionSystem;
 function buildGeometry2(area) {
-  if (area.shape === "cylinder") {
+  if (area.shape === "circle") {
     const radius = Math.max(5e-3, area.width / 2);
     return new THREE38__namespace.CircleGeometry(radius, 48);
   }
@@ -10697,7 +10873,7 @@ var _VRTeleportAreaSystem = class _VRTeleportAreaSystem {
 __name(_VRTeleportAreaSystem, "VRTeleportAreaSystem");
 var VRTeleportAreaSystem = _VRTeleportAreaSystem;
 var _XRControllerVisualSystem = class _XRControllerVisualSystem {
-  constructor(slots = 2) {
+  constructor(options) {
     this.controllerModelFactory = new XRControllerModelFactory_js.XRControllerModelFactory();
     this.handModelFactory = new XRHandModelFactory_js.XRHandModelFactory();
     this.group = new THREE38__namespace.Group();
@@ -10705,7 +10881,9 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
     this.attachedTo = null;
     /** Index → whether we've already attached visuals for that slot. */
     this.ready = /* @__PURE__ */ new Set();
-    this.slots = slots;
+    this.rays = [];
+    this.slots = options?.slots ?? 2;
+    this.interactionSystem = options?.interactionSystem ?? null;
     this.group.name = "XRControllerVisuals";
     this.group.userData.ecsPreviewHidden = true;
   }
@@ -10713,6 +10891,7 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
     const renderer = world.getRenderer();
     if (!renderer.xr?.enabled) return;
     this.ensureAttached(world);
+    this.updateRayVisibility();
     if (this.built) return;
     for (let index = 0; index < this.slots; index += 1) {
       if (this.ready.has(index)) continue;
@@ -10720,7 +10899,9 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
       const grip = renderer.xr.getControllerGrip(index);
       const hand = renderer.xr.getHand(index);
       if (!controller || !grip || !hand) continue;
-      controller.add(this.createRay());
+      const ray = this.createRay();
+      this.rays.push(ray);
+      controller.add(ray);
       this.group.add(controller);
       grip.add(this.controllerModelFactory.createControllerModel(grip));
       this.group.add(grip);
@@ -10732,6 +10913,17 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
       this.built = true;
     }
   }
+  /**
+   * Show the aim ray only when it is meaningful: hovering something
+   * interactive, or mid-grab. A permanently-drawn ray is visual noise, and it
+   * implies everything is clickable when most of the scene is not. Teleport
+   * aiming has its own arc, so the straight ray stays hidden for that.
+   */
+  updateRayVisibility() {
+    if (!this.interactionSystem) return;
+    const active = this.interactionSystem.getHoveredEntityId() !== null || this.interactionSystem.isGrabbing();
+    for (const ray of this.rays) ray.visible = active;
+  }
   /**
    * Parent the visuals to the XR rig when there is one, so locomotion moves the
    * hands with the player. Falls back to the scene root.
@@ -10757,6 +10949,7 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
     const line = new THREE38__namespace.Line(geometry, material);
     line.name = "XRPointerRay";
     line.renderOrder = 999;
+    line.visible = this.interactionSystem === null;
     return line;
   }
   dispose() {
@@ -10772,6 +10965,7 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
       }
     });
     this.group.clear();
+    this.rays.length = 0;
     this.ready.clear();
     this.built = false;
     this.attachedTo = null;
@@ -10779,6 +10973,121 @@ var _XRControllerVisualSystem = class _XRControllerVisualSystem {
 };
 __name(_XRControllerVisualSystem, "XRControllerVisualSystem");
 var XRControllerVisualSystem = _XRControllerVisualSystem;
+var MARKER_RADIUS = 0.28;
+var ACCENT = new THREE38__namespace.Color("#4da3ff");
+var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
+  constructor(locomotionSystem) {
+    this.group = new THREE38__namespace.Group();
+    this.arcGeometry = new THREE38__namespace.BufferGeometry();
+    this.marker = new THREE38__namespace.Group();
+    this.attached = false;
+    this.locomotionSystem = locomotionSystem;
+    this.group.name = "XRTeleportVisuals";
+    this.group.userData.ecsPreviewHidden = true;
+    const arcMaterial = new THREE38__namespace.LineBasicMaterial({
+      vertexColors: true,
+      transparent: true,
+      depthTest: false
+    });
+    this.arc = new THREE38__namespace.Line(this.arcGeometry, arcMaterial);
+    this.arc.frustumCulled = false;
+    this.arc.renderOrder = 998;
+    this.group.add(this.arc);
+    this.marker.add(this.createRing(), this.createDot());
+    this.marker.renderOrder = 999;
+    this.group.add(this.marker);
+    this.setVisible(false);
+  }
+  update(world) {
+    if (!this.attached) {
+      world.getScene().add(this.group);
+      this.attached = true;
+    }
+    const curve = this.locomotionSystem.getAimCurve();
+    const landing = this.locomotionSystem.getLandingPoint();
+    if (!landing || curve.length < 2) {
+      this.setVisible(false);
+      return;
+    }
+    this.updateArcGeometry(curve);
+    this.marker.position.copy(landing);
+    this.marker.position.y += 0.01;
+    this.setVisible(true);
+  }
+  updateArcGeometry(curve) {
+    const count = curve.length;
+    const positions = new Float32Array(count * 3);
+    const colors = new Float32Array(count * 3);
+    for (let i = 0; i < count; i += 1) {
+      const point = curve[i];
+      positions[i * 3] = point.x;
+      positions[i * 3 + 1] = point.y;
+      positions[i * 3 + 2] = point.z;
+      const t = count > 1 ? i / (count - 1) : 0;
+      const fade = 1 - t * 0.75;
+      colors[i * 3] = ACCENT.r * fade;
+      colors[i * 3 + 1] = ACCENT.g * fade;
+      colors[i * 3 + 2] = ACCENT.b * fade;
+    }
+    this.arcGeometry.setAttribute(
+      "position",
+      new THREE38__namespace.BufferAttribute(positions, 3)
+    );
+    this.arcGeometry.setAttribute("color", new THREE38__namespace.BufferAttribute(colors, 3));
+    this.arcGeometry.computeBoundingSphere();
+  }
+  createRing() {
+    const geometry = new THREE38__namespace.RingGeometry(
+      MARKER_RADIUS * 0.72,
+      MARKER_RADIUS,
+      48
+    );
+    geometry.rotateX(-Math.PI / 2);
+    return new THREE38__namespace.Mesh(
+      geometry,
+      new THREE38__namespace.MeshBasicMaterial({
+        color: ACCENT,
+        transparent: true,
+        opacity: 0.9,
+        side: THREE38__namespace.DoubleSide,
+        depthTest: false
+      })
+    );
+  }
+  createDot() {
+    const geometry = new THREE38__namespace.CircleGeometry(MARKER_RADIUS * 0.16, 24);
+    geometry.rotateX(-Math.PI / 2);
+    return new THREE38__namespace.Mesh(
+      geometry,
+      new THREE38__namespace.MeshBasicMaterial({
+        color: ACCENT,
+        transparent: true,
+        opacity: 0.55,
+        side: THREE38__namespace.DoubleSide,
+        depthTest: false
+      })
+    );
+  }
+  setVisible(visible) {
+    this.group.visible = visible;
+  }
+  dispose() {
+    this.group.removeFromParent();
+    this.group.traverse((child) => {
+      const mesh = child;
+      mesh.geometry?.dispose?.();
+      const material = mesh.material;
+      if (Array.isArray(material)) {
+        for (const entry of material) entry.dispose?.();
+      } else {
+        material?.dispose?.();
+      }
+    });
+    this.attached = false;
+  }
+};
+__name(_XRTeleportVisualSystem, "XRTeleportVisualSystem");
+var XRTeleportVisualSystem = _XRTeleportVisualSystem;
 
 // core/World.ts
 var _World = class _World {
@@ -12153,6 +12462,10 @@ function serializeEntitySubtree(world, rootId, options) {
 __name(serializeEntitySubtree, "serializeEntitySubtree");
 
 exports.ADDED_NODE_MARKER_COMPONENT = ADDED_NODE_MARKER_COMPONENT;
+exports.ARC_GRAVITY = ARC_GRAVITY;
+exports.ARC_MAX_TIME = ARC_MAX_TIME;
+exports.ARC_SPEED = ARC_SPEED;
+exports.ARC_STEPS = ARC_STEPS;
 exports.AnimationStateMachine = AnimationStateMachine;
 exports.AnimationStateManager = AnimationStateManager;
 exports.AnimationSystem = AnimationSystem;
@@ -12194,7 +12507,9 @@ exports.XRInputSystem = XRInputSystem;
 exports.XRInteractionSystem = XRInteractionSystem;
 exports.XRLocomotionSystem = XRLocomotionSystem;
 exports.XRSessionSystem = XRSessionSystem;
+exports.XRTeleportVisualSystem = XRTeleportVisualSystem;
 exports.applyPrefabToSnapshotInstances = applyPrefabToSnapshotInstances;
+exports.arcGroundCrossing = arcGroundCrossing;
 exports.buildComponentValueMaps = buildComponentValueMaps;
 exports.buildNodeKeyMapsFromSnapshot = buildNodeKeyMapsFromSnapshot;
 exports.buildNodeMapsFromSnapshot = buildNodeMapsFromSnapshot;
@@ -12259,6 +12574,7 @@ exports.remapSnapshotEntityIds = remapSnapshotEntityIds;
 exports.resolveDracoDecoderPath = resolveDracoDecoderPath;
 exports.restoreComponentState = restoreComponentState;
 exports.restorePostCreateComponents = restorePostCreateComponents;
+exports.sampleTeleportArc = sampleTeleportArc;
 exports.serializeEntitySubtree = serializeEntitySubtree;
 exports.setDracoDecoderPath = setDracoDecoderPath;
 exports.setPrefabAssetUrlResolver = setPrefabAssetUrlResolver;