@relu-interactives/spatial-ecs 0.3.6 → 0.3.7

package/dist/{index-C5FrDt3z.d.cts → index-B9nwRDf9.d.cts}

@@ -434,10 +434,22 @@ declare class XRLocomotionSystem implements EcsSystem {
     /** Curve up to the landing point, for the visual system. Empty when not aiming. */
     private aimCurve;
     private landingPoint;
+    /** True when the current aim lands somewhere the player may actually stand. */
+    private aimValid;
+    /** Sources currently aiming via thumbstick (hysteresis, so it doesn't chatter). */
+    private readonly stickAiming;
     /** True once we've tried to self-heal camera parenting for this session. */
     private parentingChecked;
     constructor(inputSystem: XRInputSystem);
     update(world: World, deltaTime: number): void;
+    /**
+     * Name what is missing, once per session.
+     *
+     * Inside a headset there is no console and no inspector, so a scene that
+     * simply cannot move gives the author nothing to go on. These messages are
+     * visible over remote debugging and say exactly which entity to add.
+     */
+    private warnOnIncompleteSetup;
     /**
      * Guarantee the render camera is a CHILD of the rig.
      *
@@ -458,11 +470,21 @@ declare class XRLocomotionSystem implements EcsSystem {
     private applySnapTurn;
     private applySmoothMove;
     private applyTeleport;
+    /**
+     * Thumbstick-forward aiming with hysteresis.
+     *
+     * Engaging at 0.6 and releasing at 0.3 stops a stick resting near the
+     * threshold from flickering the arc on and off — and the release edge is what
+     * commits the teleport, so chatter there would teleport the player randomly.
+     */
+    private readStickAim;
     /** Walk the arc segment-by-segment, returning the first surface hit. */
     private raycastArc;
     private collectTeleportTargets;
     /** Arc points up to the landing spot this frame; empty when not aiming. */
     getAimCurve(): THREE.Vector3[];
+    /** True when the aim lands on a valid teleport area. */
+    isAimValid(): boolean;
     /** Where the arc currently lands, or null when not aiming at a valid area. */
     getLandingPoint(): THREE.Vector3 | null;
 }

package/dist/{index-BpbmZuOz.d.ts → index-_q9TVDI5.d.ts}

@@ -434,10 +434,22 @@ declare class XRLocomotionSystem implements EcsSystem {
     /** Curve up to the landing point, for the visual system. Empty when not aiming. */
     private aimCurve;
     private landingPoint;
+    /** True when the current aim lands somewhere the player may actually stand. */
+    private aimValid;
+    /** Sources currently aiming via thumbstick (hysteresis, so it doesn't chatter). */
+    private readonly stickAiming;
     /** True once we've tried to self-heal camera parenting for this session. */
     private parentingChecked;
     constructor(inputSystem: XRInputSystem);
     update(world: World, deltaTime: number): void;
+    /**
+     * Name what is missing, once per session.
+     *
+     * Inside a headset there is no console and no inspector, so a scene that
+     * simply cannot move gives the author nothing to go on. These messages are
+     * visible over remote debugging and say exactly which entity to add.
+     */
+    private warnOnIncompleteSetup;
     /**
      * Guarantee the render camera is a CHILD of the rig.
      *
@@ -458,11 +470,21 @@ declare class XRLocomotionSystem implements EcsSystem {
     private applySnapTurn;
     private applySmoothMove;
     private applyTeleport;
+    /**
+     * Thumbstick-forward aiming with hysteresis.
+     *
+     * Engaging at 0.6 and releasing at 0.3 stops a stick resting near the
+     * threshold from flickering the arc on and off — and the release edge is what
+     * commits the teleport, so chatter there would teleport the player randomly.
+     */
+    private readStickAim;
     /** Walk the arc segment-by-segment, returning the first surface hit. */
     private raycastArc;
     private collectTeleportTargets;
     /** Arc points up to the landing spot this frame; empty when not aiming. */
     getAimCurve(): THREE.Vector3[];
+    /** True when the aim lands on a valid teleport area. */
+    isAimValid(): boolean;
     /** Where the arc currently lands, or null when not aiming at a valid area. */
     getLandingPoint(): THREE.Vector3 | null;
 }

package/dist/index.cjs

@@ -10697,6 +10697,10 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     /** Curve up to the landing point, for the visual system. Empty when not aiming. */
     this.aimCurve = [];
     this.landingPoint = null;
+    /** True when the current aim lands somewhere the player may actually stand. */
+    this.aimValid = false;
+    /** Sources currently aiming via thumbstick (hysteresis, so it doesn't chatter). */
+    this.stickAiming = /* @__PURE__ */ new WeakSet();
     /** True once we've tried to self-heal camera parenting for this session. */
     this.parentingChecked = false;
     this.inputSystem = inputSystem;
@@ -10704,6 +10708,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
   update(world, deltaTime) {
     this.aimCurve = [];
     this.landingPoint = null;
+    this.aimValid = false;
     if (!world.isXrPresenting()) {
       this.parentingChecked = false;
       return;
@@ -10711,6 +10716,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
     if (!this.parentingChecked) {
       this.parentingChecked = true;
       this.ensureCameraUnderRig(world);
+      this.warnOnIncompleteSetup(world);
     }
     const rigEntityId = world.query(XRRigComponent, TransformComponent)[0];
     if (typeof rigEntityId !== "number") return;
@@ -10728,6 +10734,26 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
       this.applySmoothMove(world, rig, rigTransform, inputs, deltaTime);
     }
   }
+  /**
+   * Name what is missing, once per session.
+   *
+   * Inside a headset there is no console and no inspector, so a scene that
+   * simply cannot move gives the author nothing to go on. These messages are
+   * visible over remote debugging and say exactly which entity to add.
+   */
+  warnOnIncompleteSetup(world) {
+    if (typeof world.query(XRRigComponent)[0] !== "number") {
+      console.warn(
+        "[XRLocomotion] No XR Rig in this scene \u2014 the player cannot move. Add one via Add Object \u2192 VR \u2192 XR Rig (the scene camera is parented to it automatically)."
+      );
+      return;
+    }
+    if (world.query(VRTeleportAreaComponent).length === 0) {
+      console.warn(
+        "[XRLocomotion] No Teleport Area in this scene \u2014 teleport has nowhere to land. Add one via Add Object \u2192 VR \u2192 Teleport Area, or add a Teleport Area component to an existing floor."
+      );
+    }
+  }
   /**
    * Guarantee the render camera is a CHILD of the rig.
    *
@@ -10795,29 +10821,60 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
   }
   applyTeleport(world, transform, inputs) {
     const targets = this.collectTeleportTargets(world);
-    if (targets.length === 0) return;
     for (const input of inputs) {
-      if (!input.select && !input.selectEnd) continue;
+      const source = input;
+      const stick = this.readStickAim(input, source);
+      const aiming = input.select || stick.aiming;
+      const commit = input.selectEnd || stick.released;
+      if (!aiming && !commit) continue;
       const points = sampleTeleportArc(
         input.rayOrigin,
         input.rayDirection,
         this.arcPoints
       );
       const hit = this.raycastArc(points, targets);
-      if (!hit) continue;
-      this.landingPoint = hit.point;
-      this.aimCurve = points.slice(0, hit.segmentIndex + 1).concat(hit.point);
-      if (input.selectEnd) {
+      this.aimCurve = hit ? points.slice(0, hit.segmentIndex + 1).concat(hit.point) : points.slice();
+      this.landingPoint = hit ? hit.point : null;
+      this.aimValid = hit !== null;
+      if (commit && hit) {
         transform.position.x = hit.point.x;
         transform.position.y = hit.point.y;
         transform.position.z = hit.point.z;
         this.aimCurve = [];
         this.landingPoint = null;
+        this.aimValid = false;
+      } else if (commit) {
+        this.aimCurve = [];
+        this.aimValid = false;
       }
     }
   }
+  /**
+   * Thumbstick-forward aiming with hysteresis.
+   *
+   * Engaging at 0.6 and releasing at 0.3 stops a stick resting near the
+   * threshold from flickering the arc on and off — and the release edge is what
+   * commits the teleport, so chatter there would teleport the player randomly.
+   */
+  readStickAim(input, source) {
+    if (!input.hasAxes || input.axes.length < 4) {
+      return { aiming: false, released: false };
+    }
+    const forward = -(input.axes[3] ?? 0);
+    const wasAiming = this.stickAiming.has(source);
+    if (!wasAiming && forward > 0.6) {
+      this.stickAiming.add(source);
+      return { aiming: true, released: false };
+    }
+    if (wasAiming && forward < 0.3) {
+      this.stickAiming.delete(source);
+      return { aiming: false, released: true };
+    }
+    return { aiming: wasAiming, released: false };
+  }
   /** Walk the arc segment-by-segment, returning the first surface hit. */
   raycastArc(points, targets) {
+    if (targets.length === 0) return null;
     for (let i = 1; i < points.length; i += 1) {
       const from = points[i - 1];
       const to = points[i];
@@ -10848,6 +10905,10 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
   getAimCurve() {
     return this.aimCurve;
   }
+  /** True when the aim lands on a valid teleport area. */
+  isAimValid() {
+    return this.aimValid;
+  }
   /** Where the arc currently lands, or null when not aiming at a valid area. */
   getLandingPoint() {
     return this.landingPoint;
@@ -11294,6 +11355,7 @@ __name(_XRControllerVisualSystem, "XRControllerVisualSystem");
 var XRControllerVisualSystem = _XRControllerVisualSystem;
 var MARKER_RADIUS = 0.28;
 var ACCENT = new THREE39__namespace.Color("#4da3ff");
+var BLOCKED = new THREE39__namespace.Color("#ff5a5a");
 var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
   constructor(locomotionSystem) {
     this.group = new THREE39__namespace.Group();
@@ -11324,16 +11386,22 @@ var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
     }
     const curve = this.locomotionSystem.getAimCurve();
     const landing = this.locomotionSystem.getLandingPoint();
-    if (!landing || curve.length < 2) {
+    const valid = this.locomotionSystem.isAimValid();
+    if (curve.length < 2) {
       this.setVisible(false);
       return;
     }
-    this.updateArcGeometry(curve);
-    this.marker.position.copy(landing);
-    this.marker.position.y += 0.01;
+    this.updateArcGeometry(curve, valid ? ACCENT : BLOCKED);
+    if (valid && landing) {
+      this.marker.position.copy(landing);
+      this.marker.position.y += 0.01;
+      this.marker.visible = true;
+    } else {
+      this.marker.visible = false;
+    }
     this.setVisible(true);
   }
-  updateArcGeometry(curve) {
+  updateArcGeometry(curve, tint) {
     const count = curve.length;
     const positions = new Float32Array(count * 3);
     const colors = new Float32Array(count * 3);
@@ -11344,9 +11412,9 @@ var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
       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;
+      colors[i * 3] = tint.r * fade;
+      colors[i * 3 + 1] = tint.g * fade;
+      colors[i * 3 + 2] = tint.b * fade;
     }
     this.arcGeometry.setAttribute(
       "position",