@relu-interactives/spatial-ecs 0.3.6 → 0.3.7

package/dist/index.d.cts

@@ -3,8 +3,8 @@ export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFac
 import * as THREE from 'three';
 import { O as Object3DRef, af as XrHandPreset } from './XRInteractor-I2q6TKtF.cjs';
 export { an as AnimationStateCallbacks, ao as AnimationStateMachine, ap as AnimationStateManager, aq as StateMachine } from './XRInteractor-I2q6TKtF.cjs';
-import { X as XrCapabilities, a as XrInputState } from './index-C5FrDt3z.cjs';
-export { A as AnimationSystem, b as AudioSystem, C as CameraSyncSystem, E as EnvironmentSyncSystem, I as InstancedMeshSystem, L as LightSyncSystem, M as MaterialSyncSystem, c as MeshGeometrySystem, d as ModuleLoader, N as NO_XR_CAPABILITIES, O as ObjectVisibilitySystem, P as PhysicsSyncSystem, e as PostprocessingSyncSystem, S as SCRIPT_OBJECT_ROOT_FLAG, f as ScriptBehaviourSystem, g as ScriptObjectSystem, h as SelectionContext, V as VRTeleportAreaSystem, i as VideoSystem, j as XRControllerVisualSystem, k as XRInputSystem, l as XRInteractionSystem, m as XRLocomotionSystem, n as XRSessionSystem, o as XRTeleportVisualSystem, p as XrHandedness, q as XrInputKind, r as readXrCapabilities } from './index-C5FrDt3z.cjs';
+import { X as XrCapabilities, a as XrInputState } from './index-B9nwRDf9.cjs';
+export { A as AnimationSystem, b as AudioSystem, C as CameraSyncSystem, E as EnvironmentSyncSystem, I as InstancedMeshSystem, L as LightSyncSystem, M as MaterialSyncSystem, c as MeshGeometrySystem, d as ModuleLoader, N as NO_XR_CAPABILITIES, O as ObjectVisibilitySystem, P as PhysicsSyncSystem, e as PostprocessingSyncSystem, S as SCRIPT_OBJECT_ROOT_FLAG, f as ScriptBehaviourSystem, g as ScriptObjectSystem, h as SelectionContext, V as VRTeleportAreaSystem, i as VideoSystem, j as XRControllerVisualSystem, k as XRInputSystem, l as XRInteractionSystem, m as XRLocomotionSystem, n as XRSessionSystem, o as XRTeleportVisualSystem, p as XrHandedness, q as XrInputKind, r as readXrCapabilities } from './index-B9nwRDf9.cjs';
 export { i as CoreComponents } from './index-BltjPEhg.cjs';
 export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.cjs';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export { A as AssetInput, t as CheckboxInput, u as ColorInput, v as ComponentFac
 import * as THREE from 'three';
 import { O as Object3DRef, af as XrHandPreset } from './XRInteractor-CCUzSqg9.js';
 export { an as AnimationStateCallbacks, ao as AnimationStateMachine, ap as AnimationStateManager, aq as StateMachine } from './XRInteractor-CCUzSqg9.js';
-import { X as XrCapabilities, a as XrInputState } from './index-BpbmZuOz.js';
-export { A as AnimationSystem, b as AudioSystem, C as CameraSyncSystem, E as EnvironmentSyncSystem, I as InstancedMeshSystem, L as LightSyncSystem, M as MaterialSyncSystem, c as MeshGeometrySystem, d as ModuleLoader, N as NO_XR_CAPABILITIES, O as ObjectVisibilitySystem, P as PhysicsSyncSystem, e as PostprocessingSyncSystem, S as SCRIPT_OBJECT_ROOT_FLAG, f as ScriptBehaviourSystem, g as ScriptObjectSystem, h as SelectionContext, V as VRTeleportAreaSystem, i as VideoSystem, j as XRControllerVisualSystem, k as XRInputSystem, l as XRInteractionSystem, m as XRLocomotionSystem, n as XRSessionSystem, o as XRTeleportVisualSystem, p as XrHandedness, q as XrInputKind, r as readXrCapabilities } from './index-BpbmZuOz.js';
+import { X as XrCapabilities, a as XrInputState } from './index-_q9TVDI5.js';
+export { A as AnimationSystem, b as AudioSystem, C as CameraSyncSystem, E as EnvironmentSyncSystem, I as InstancedMeshSystem, L as LightSyncSystem, M as MaterialSyncSystem, c as MeshGeometrySystem, d as ModuleLoader, N as NO_XR_CAPABILITIES, O as ObjectVisibilitySystem, P as PhysicsSyncSystem, e as PostprocessingSyncSystem, S as SCRIPT_OBJECT_ROOT_FLAG, f as ScriptBehaviourSystem, g as ScriptObjectSystem, h as SelectionContext, V as VRTeleportAreaSystem, i as VideoSystem, j as XRControllerVisualSystem, k as XRInputSystem, l as XRInteractionSystem, m as XRLocomotionSystem, n as XRSessionSystem, o as XRTeleportVisualSystem, p as XrHandedness, q as XrInputKind, r as readXrCapabilities } from './index-_q9TVDI5.js';
 export { i as CoreComponents } from './index-W8pUajCW.js';
 export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './factories/index.js';
 import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';

package/dist/index.js

@@ -1,5 +1,5 @@
-import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, VRTeleportAreaSystem, PhysicsSyncSystem, AnimationSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem, spawnPrefab, despawnPrefab, buildNodeKeyMapsFromSnapshot, indexSnapshotByEntity, findTopLevelNestedRegions, collectSnapshotSubtreeIds, groupOverridePaths, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, canonicalizeComponentValue, mergeComponentValue, decanonicalizeComponentValue, computeInstanceOverrides, collectEntitySubtree, ADDED_NODE_MARKER_COMPONENT } from './chunk-WRJ2K3LZ.js';
-export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, NO_XR_CAPABILITIES, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObject, ScriptObjectSystem, TransformSyncSystem, VRTeleportAreaSystem, VideoSystem, XRControllerVisualSystem, XRInputSystem, XRInteractionSystem, XRLocomotionSystem, XRSessionSystem, XRTeleportVisualSystem, applyHandMaterial, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, createHandMaterial, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, readXrCapabilities, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-WRJ2K3LZ.js';
+import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, VRTeleportAreaSystem, PhysicsSyncSystem, AnimationSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem, spawnPrefab, despawnPrefab, buildNodeKeyMapsFromSnapshot, indexSnapshotByEntity, findTopLevelNestedRegions, collectSnapshotSubtreeIds, groupOverridePaths, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, canonicalizeComponentValue, mergeComponentValue, decanonicalizeComponentValue, computeInstanceOverrides, collectEntitySubtree, ADDED_NODE_MARKER_COMPONENT } from './chunk-O6FJA4XW.js';
+export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, AnimationSystem, AudioSystem, Behaviour, CameraSyncSystem, EnvironmentSyncSystem, HYDRATABLE_ENTITY_KINDS, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, NO_XR_CAPABILITIES, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, SCRIPT_OBJECT_ROOT_FLAG, ScriptBehaviourSystem, ScriptObject, ScriptObjectSystem, TransformSyncSystem, VRTeleportAreaSystem, VideoSystem, XRControllerVisualSystem, XRInputSystem, XRInteractionSystem, XRLocomotionSystem, XRSessionSystem, XRTeleportVisualSystem, applyHandMaterial, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, createHandMaterial, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, readXrCapabilities, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-O6FJA4XW.js';
 import { registerDefaultFactories } from './chunk-FQTOC7HK.js';
 export { createAnimationComponent, createAudioComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createVRTeleportAreaComponent, createVideoComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-FQTOC7HK.js';
 import { ObjectManagementSystem } from './chunk-JRJ3CL5H.js';

package/dist/systems/index.cjs

@@ -8023,6 +8023,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;
@@ -8030,6 +8034,7 @@ var _XRLocomotionSystem = class _XRLocomotionSystem {
   update(world, deltaTime) {
     this.aimCurve = [];
     this.landingPoint = null;
+    this.aimValid = false;
     if (!world.isXrPresenting()) {
       this.parentingChecked = false;
       return;
@@ -8037,6 +8042,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;
@@ -8054,6 +8060,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.
    *
@@ -8121,29 +8147,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];
@@ -8174,6 +8231,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;
@@ -8620,6 +8681,7 @@ __name(_XRControllerVisualSystem, "XRControllerVisualSystem");
 var XRControllerVisualSystem = _XRControllerVisualSystem;
 var MARKER_RADIUS = 0.28;
 var ACCENT = new THREE14__namespace.Color("#4da3ff");
+var BLOCKED = new THREE14__namespace.Color("#ff5a5a");
 var _XRTeleportVisualSystem = class _XRTeleportVisualSystem {
   constructor(locomotionSystem) {
     this.group = new THREE14__namespace.Group();
@@ -8650,16 +8712,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);
@@ -8670,9 +8738,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",