@relu-interactives/spatial-ecs 0.5.2 → 0.8.0

package/dist/index.js

@@ -1,27 +1,48 @@
-import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, VRTeleportAreaSystem, UIPanelSystem, 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-DF5SSRN6.js';
-export { ADDED_NODE_MARKER_COMPONENT, ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, AnimationSystem, AudioSystem, Behaviour, CURLED_COS, CameraSyncSystem, DEFAULT_DIRECTION_TOLERANCE, DEFAULT_ENTER_CONFIDENCE, DEFAULT_EXIT_CONFIDENCE, DEFAULT_LOST_GRACE_SECONDS, DEFAULT_MIN_HOLD_SECONDS, EnvironmentSyncSystem, FALLBACK_HAND_SCALE, HYDRATABLE_ENTITY_KINDS, HandPoseTracker, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MATCH_FALLOFF, MAX_PLAUSIBLE_SPEED, MAX_SAMPLE_AGE_SECONDS, MaterialSyncSystem, MeshGeometrySystem, NODE_KEY_SEPARATOR, NO_XR_CAPABILITIES, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, ObjectVisibilitySystem, PINCH_FINGERS, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, SCRIPT_OBJECT_ROOT_FLAG, STRAIGHT_COS, ScriptBehaviourSystem, ScriptObject, ScriptObjectSystem, TeleportAimGate, ThrowVelocityTracker, TransformSyncSystem, UIInteractionSystem, UIPanelSystem, VELOCITY_SAMPLES, VRTeleportAreaSystem, VideoSystem, XRAnchorSystem, XRControllerVisualSystem, XREnvironmentSystem, XRHandPoseSystem, XRHitTestSystem, XRHoverVisualSystem, XRInputSystem, XRInteractionSystem, XRLocomotionSystem, XRSessionSystem, XRTeleportVisualSystem, XR_FINGERS, XR_HOVER_SHELL_FLAG, angularVelocityFrom, applyHandMaterial, arcGroundCrossing, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeFingerCurl, computeHandShape, computeInstanceOverrides, computePalmPose, computePalmWidth, computePinch, computeSpread, createHandMaterial, decanonicalizeComponentValue, despawnPrefab, encodeOverride, estimateHandScale, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, matchHandPose, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, readXrCapabilities, restoreComponentState, restorePostCreateComponents, sampleTeleportArc, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-DF5SSRN6.js';
-import { registerDefaultFactories } from './chunk-RXBLOO5B.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, createUIButtonComponent, createUIPanelComponent, createUISliderComponent, createUITextComponent, createUIToggleComponent, createVRTeleportAreaComponent, createVideoComponent, createXRAnchorComponent, createXRHandPoseComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, registerDefaultComponentFactories, registerDefaultFactories } from './chunk-RXBLOO5B.js';
-import { ObjectManagementSystem } from './chunk-WJD2VKEH.js';
-export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-WJD2VKEH.js';
-import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-BUEKOSR5.js';
-export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents, HAND_POSE_PRESETS, HAND_POSE_PRESET_IDS, cloneHandPose, getHandPosePreset, handPoseFromCurls } from './chunk-BUEKOSR5.js';
+import { MeshGeometrySystem, InstancedMeshSystem, EnvironmentSyncSystem, PostprocessingSyncSystem, LightSyncSystem, MaterialSyncSystem, VRTeleportAreaSystem, UIPanelSystem, PhysicsSyncSystem, AnimationSystem, IKSystem, AudioSystem, VideoSystem, CameraSyncSystem, TransformSyncSystem, ObjectVisibilitySystem, RenderSystem } from './chunk-JIJQFW6P.js';
+export { ARC_GRAVITY, ARC_MAX_TIME, ARC_SPEED, ARC_STEPS, AnimationSystem, AudioMixer, AudioSystem, CURLED_COS, CameraSyncSystem, DEFAULT_DIRECTION_TOLERANCE, DEFAULT_ENTER_CONFIDENCE, DEFAULT_EXIT_CONFIDENCE, DEFAULT_LOST_GRACE_SECONDS, DEFAULT_MIN_HOLD_SECONDS, DEFAULT_SCRIPT_ERROR_RETRY_DELAY, EnvironmentSyncSystem, FALLBACK_HAND_SCALE, HandPoseTracker, IKSystem, InputSystem, InstancedMeshSystem, KeyboardKeys, LightSyncSystem, MATCH_FALLOFF, MAX_PLAUSIBLE_SPEED, MAX_SAMPLE_AGE_SECONDS, MaterialSyncSystem, MeshGeometrySystem, NO_XR_CAPABILITIES, ObjectVisibilitySystem, PINCH_FINGERS, PhysicsSyncSystem, PostprocessingSyncSystem, RenderSystem, SCRIPT_OBJECT_ROOT_FLAG, STRAIGHT_COS, ScriptBehaviourSystem, ScriptObject, ScriptObjectSystem, SlotChooser, TeleportAimGate, ThrowVelocityTracker, TransformSyncSystem, UIInteractionSystem, UIPanelSystem, VELOCITY_SAMPLES, VRTeleportAreaSystem, VideoSystem, XRAnchorSystem, XRControllerVisualSystem, XREnvironmentSystem, XRHandPoseSystem, XRHitTestSystem, XRHoverVisualSystem, XRInputSystem, XRInteractionSystem, XRLocomotionSystem, XRSessionSystem, XRTeleportVisualSystem, XR_FINGERS, XR_HOVER_SHELL_FLAG, angularVelocityFrom, applyHandMaterial, arcGroundCrossing, computeFingerCurl, computeHandShape, computePalmPose, computePalmWidth, computePinch, computeSpread, createHandMaterial, estimateHandScale, gripQuaternion, matchHandPose, readXrCapabilities, sampleTeleportArc, setWorldQuaternion, soundBankFiles, twoBoneIK } from './chunk-JIJQFW6P.js';
+import { registerDefaultFactories } from './chunk-SGF73YTF.js';
+export { registerDefaultComponentFactories, registerDefaultFactories } from './chunk-SGF73YTF.js';
+import { getRendererKindOf, resolveRenderBackend } from './chunk-OHCNPPMX.js';
+export { webglBackend } from './chunk-OHCNPPMX.js';
 import './chunk-QHILSPT4.js';
-import { normalizeDebugValue, DEBUG_CHANGE_IGNORED_SYSTEMS, cloneHistoryValue } from './chunk-OWQSESTO.js';
-import { __name } from './chunk-OY7ZODZP.js';
-export { Component } from './chunk-OY7ZODZP.js';
+import { normalizeDebugValue, DEBUG_CHANGE_IGNORED_SYSTEMS, cloneHistoryValue } from './chunk-XU2DVWCP.js';
+import { spawnPrefab, despawnPrefab, toErrorMessage, toErrorStack, buildNodeKeyMapsFromSnapshot, indexSnapshotByEntity, findTopLevelNestedRegions, collectSnapshotSubtreeIds, groupOverridePaths, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, canonicalizeComponentValue, mergeComponentValue, decanonicalizeComponentValue, computeInstanceOverrides, collectEntitySubtree, ADDED_NODE_MARKER_COMPONENT } from './chunk-U727NTWQ.js';
+export { ADDED_NODE_MARKER_COMPONENT, Behaviour, HYDRATABLE_ENTITY_KINDS, NODE_KEY_SEPARATOR, OVERRIDE_DIFF_EXCLUDED_COMPONENTS, OVERRIDE_ROOT_EXCLUDED_COMPONENTS, PREFAB_FILE_VERSION, PREFAB_FILE_VERSION_NESTED, buildComponentValueMaps, buildNodeKeyMapsFromSnapshot, buildNodeMapsFromSnapshot, canonicalizeComponentValue, clearPrefabCache, collectDiffPaths, collectEntitySubtree, collectSnapshotSubtreeIds, computeInstanceOverrides, decanonicalizeComponentValue, despawnPrefab, encodeOverride, findSnapshotRootEntityIds, findTopLevelNestedRegions, groupOverridePaths, hydrateWorldFromSnapshot, hydrateWorldFromSnapshotDetailed, indexSnapshotByEntity, instantiateSubtree, loadPrefab, mergeComponentValue, parseOverride, parsePrefabAsset, prefabFileVersionFor, restoreComponentState, restorePostCreateComponents, setPrefabAssetUrlResolver, spawnPrefab } from './chunk-U727NTWQ.js';
+import { ObjectManagementSystem } from './chunk-G4XJ53LS.js';
+export { ObjectManagementSystem, SHARED_MODEL_RESOURCE_FLAG, clearModelCache, createAnimationComponent, createAudioComponent, createBoneAttachmentComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, createGLTFLoader, createIKComponent, createImageComponent, createImageTargetAnchorComponent, createImageTargetComponent, createInstanceSlotComponent, createInstancedMeshComponent, createLightComponent, createMaterialComponent, createMeshComponent, createMeshGeometryComponent, createModelComponent, createNameComponent, createNetworkIdentityComponent, createNetworkSpawnerComponent, createNetworkTransformComponent, createNetworkedPropsComponent, createObject3DRefComponent, createParentIdComponent, createPhysicsComponent, createPostprocessingComponent, createScriptComponent, createScriptObjectComponent, createSelectableComponent, createSelectionTransformStateComponent, createSpriteComponent, createTransformComponent, createUIButtonComponent, createUIPanelComponent, createUISliderComponent, createUITextComponent, createUIToggleComponent, createVRTeleportAreaComponent, createVideoComponent, createXRAnchorComponent, createXRHandPoseComponent, createXRInteractableComponent, createXRInteractorComponent, createXRInteractorSideComponent, createXRRigComponent, findModelBone, listModelBones, loadSharedGltf, resolveDracoDecoderPath, setDracoDecoderPath } from './chunk-G4XJ53LS.js';
+import { SelectionTransformState, Object3DRef, Name, EntityType, ParentId, Environment, Postprocessing, ScriptComponent } from './chunk-NNDUOQ7O.js';
+export { AnimationStateMachine, AnimationStateManager, components_exports as CoreComponents, HAND_POSE_PRESETS, HAND_POSE_PRESET_IDS, cloneHandPose, getHandPosePreset, handPoseFromCurls } from './chunk-NNDUOQ7O.js';
+export { Component } from './chunk-CKTHDXPS.js';
+import './chunk-GSWC6LLD.js';
+import { __name } from './chunk-XE4OXN2W.js';
 import * as THREE from 'three';
 
+var MAX_REMEMBERED_SCRIPT_ERRORS = 500;
 var _World = class _World {
+  /**
+   * @param options.renderer - A `THREE.WebGLRenderer`, or a `WebGPURenderer`
+   *   from `three/webgpu`. A `WebGPURenderer` must be initialised
+   *   (`await renderer.init()`) before the first `update()`.
+   * @param options.backend - Renderer-specific behaviour (post-processing,
+   *   green-screen video, area lights). Defaults to the WebGL backend; pass
+   *   `webgpuBackend` from `@relu-interactives/spatial-ecs/webgpu` with a
+   *   `WebGPURenderer`.
+   */
   constructor(options) {
     this.nextEntityId = 1;
     this.entities = /* @__PURE__ */ new Set();
     this.systems = [];
     this.selectionListeners = /* @__PURE__ */ new Set();
     this.storeListeners = /* @__PURE__ */ new Set();
+    this.scriptErrorListeners = /* @__PURE__ */ new Set();
+    /** Keys (`url|class|phase|message`) of script errors already reported. */
+    this.reportedScriptErrors = /* @__PURE__ */ new Map();
     this.components = /* @__PURE__ */ new Map();
     this.inputSystem = null;
     this.objectManagementSystem = null;
+    this.ikSystem = null;
+    this.audioSystem = null;
+    this.network = null;
     this.environmentSyncSystem = null;
     this.postprocessingSyncSystem = null;
     this.rapierModule = null;
@@ -32,11 +53,14 @@ var _World = class _World {
     this.scene = options.scene;
     this.camera = options.camera;
     this.renderer = options.renderer;
+    this.rendererKind = getRendererKindOf(options.renderer);
+    this.renderBackend = resolveRenderBackend(options.renderer, options.backend);
     this.featureFlags = {
       supportSkybox: options.featureFlags?.supportSkybox ?? true,
       supportPostprocessing: options.featureFlags?.supportPostprocessing ?? true
     };
     this.renderer.shadowMap.enabled = true;
+    this.renderBackend.install?.(this);
   }
   createEntity() {
     const entityId = this.nextEntityId;
@@ -352,7 +376,12 @@ var _World = class _World {
     const meshGeometrySystem = new MeshGeometrySystem();
     const instancedMeshSystem = new InstancedMeshSystem();
     const environmentSyncSystem = this.featureFlags.supportSkybox ? new EnvironmentSyncSystem(this.scene) : null;
-    const postprocessingSyncSystem = this.featureFlags.supportPostprocessing ? new PostprocessingSyncSystem(this.renderer, this.scene, this.camera) : null;
+    const postprocessingSyncSystem = this.featureFlags.supportPostprocessing ? new PostprocessingSyncSystem(
+      this.renderer,
+      this.scene,
+      this.camera,
+      this.renderBackend
+    ) : null;
     const lightSyncSystem = new LightSyncSystem();
     const materialSyncSystem = new MaterialSyncSystem();
     const vrTeleportAreaSystem = new VRTeleportAreaSystem();
@@ -361,6 +390,7 @@ var _World = class _World {
       isEditor: isEditor ?? false
     });
     const animationSystem = new AnimationSystem();
+    const ikSystem = new IKSystem();
     const audioSystem = new AudioSystem({ isEditor: isEditor ?? false });
     const videoSystem = new VideoSystem({ isEditor: isEditor ?? false });
     const cameraSyncSystem = new CameraSyncSystem();
@@ -394,6 +424,7 @@ var _World = class _World {
       lightSyncSystem,
       materialSyncSystem,
       animationSystem,
+      ikSystem,
       audioSystem,
       videoSystem,
       cameraSyncSystem,
@@ -408,6 +439,9 @@ var _World = class _World {
     }
     this.isEditor = isEditor ?? false;
     this.objectManagementSystem = objectManagementSystem;
+    this.ikSystem = ikSystem;
+    this.audioSystem = audioSystem;
+    audioSystem.attachWorld(this);
     this.environmentSyncSystem = environmentSyncSystem;
     this.postprocessingSyncSystem = postprocessingSyncSystem;
     return {
@@ -489,9 +523,26 @@ var _World = class _World {
   getCamera() {
     return this.camera;
   }
+  /**
+   * The renderer this world draws with: a `THREE.WebGLRenderer`, or a
+   * `WebGPURenderer` from `three/webgpu`. Check {@link getRendererKind} before
+   * using an API only one of them has (for example `capabilities` exists on
+   * WebGL only).
+   */
   getRenderer() {
     return this.renderer;
   }
+  /** `"webgpu"` when the world renders with a `WebGPURenderer`, else `"webgl"`. */
+  getRendererKind() {
+    return this.rendererKind;
+  }
+  /**
+   * The renderer-specific backend in use (post-processing, green-screen
+   * video, area lights). See `RenderBackend`.
+   */
+  getRenderBackend() {
+    return this.renderBackend;
+  }
   update(deltaTime) {
     if (this.paused) return;
     for (const system of this.systems) {
@@ -504,6 +555,8 @@ var _World = class _World {
     }
     this.selectionListeners.clear();
     this.storeListeners.clear();
+    this.scriptErrorListeners.clear();
+    this.reportedScriptErrors.clear();
     this.physicsWorld = null;
     this.systems = [];
     this.paused = false;
@@ -624,6 +677,22 @@ var _World = class _World {
   despawnPrefab(rootEntityId) {
     return despawnPrefab(this, rootEntityId);
   }
+  /** The shared-world connection, or `null` in a single-player run. */
+  getNetwork() {
+    return this.network;
+  }
+  /** Set by `NetworkSystem` when it connects and clears. */
+  setNetwork(network) {
+    this.network = network;
+  }
+  /** The audio system (mixer buses, sound banks), or `null` before `setup`. */
+  getAudioSystem() {
+    return this.audioSystem;
+  }
+  /** The IK system (reach errors per limb), or `null` before `setup`. */
+  getIKSystem() {
+    return this.ikSystem;
+  }
   getObjectManagementSystem() {
     if (this.objectManagementSystem) return this.objectManagementSystem;
     const objectManagementSystem = this.systems.find(
@@ -854,6 +923,94 @@ var _World = class _World {
       this.storeListeners.delete(listener);
     };
   }
+  /**
+   * Listen for script errors from Behaviours and ScriptObjects: load
+   * failures, `init()` / `build()` / `update()` exceptions, and exceptions
+   * thrown inside Behaviour hooks such as `onSelect` or `onUiPress`.
+   *
+   * Each DISTINCT error (same script URL, class, phase and message) is
+   * delivered once, so a script that throws every frame does not flood the
+   * listener. Returns an unsubscribe function.
+   *
+   * @example
+   * ```ts
+   * const stop = world.onScriptError((event) => {
+   *   console.warn(`${event.className} failed in ${event.phase}: ${event.message}`);
+   * });
+   * // later
+   * stop();
+   * ```
+   */
+  onScriptError(listener) {
+    this.scriptErrorListeners.add(listener);
+    return () => {
+      this.scriptErrorListeners.delete(listener);
+    };
+  }
+  /**
+   * Report a script error. Used by the script systems and by any system that
+   * calls into Behaviour hooks; scripts themselves do not need to call it.
+   *
+   * The first occurrence of a distinct error (same script URL, class, phase
+   * and message) is logged with `console.error` and delivered to
+   * {@link onScriptError} listeners; repeats are dropped. Returns `true` when
+   * the error was new.
+   */
+  reportScriptError(report, error) {
+    const message = toErrorMessage(error);
+    const key = `${report.scriptUrl}|${report.className}|${report.phase}|${message}`;
+    if (this.reportedScriptErrors.has(key)) {
+      return false;
+    }
+    if (this.reportedScriptErrors.size >= MAX_REMEMBERED_SCRIPT_ERRORS) {
+      const oldest = this.reportedScriptErrors.keys().next().value;
+      if (oldest !== void 0) {
+        this.reportedScriptErrors.delete(oldest);
+      }
+    }
+    this.reportedScriptErrors.set(key, report.scriptUrl);
+    const entityName = this.hasEntity(report.entityId) ? this.getEntityName(report.entityId) : `Entity ${report.entityId}`;
+    const stack = toErrorStack(error);
+    const event = {
+      entityId: report.entityId,
+      entityName,
+      scriptUrl: report.scriptUrl,
+      className: report.className,
+      phase: report.phase,
+      message,
+      source: report.source,
+      ...stack ? { stack } : {}
+    };
+    const kind = report.source === "scriptObject" ? "ScriptObject" : "Behaviour";
+    console.error(
+      `[spatial-ecs] ${kind} "${report.className || "unknown"}" failed in ${report.phase} on entity "${entityName}" (#${report.entityId}): ${message}`,
+      ...error instanceof Error ? [error] : []
+    );
+    for (const listener of this.scriptErrorListeners) {
+      try {
+        listener(event);
+      } catch (listenerError) {
+        console.error("[spatial-ecs] onScriptError listener threw:", listenerError);
+      }
+    }
+    return true;
+  }
+  /**
+   * Forget which script errors were already reported, so their next
+   * occurrence is logged and delivered again. Pass a script URL to forget only
+   * that script's errors (for example after hot-reloading it).
+   */
+  clearScriptErrors(scriptUrl) {
+    if (scriptUrl === void 0) {
+      this.reportedScriptErrors.clear();
+      return;
+    }
+    for (const [key, url] of this.reportedScriptErrors) {
+      if (url === scriptUrl) {
+        this.reportedScriptErrors.delete(key);
+      }
+    }
+  }
   getDebugSnapshot(maxDepth = 3) {
     const components = [...this.components.entries()].map(([componentClass, store]) => {
       return {
@@ -1099,6 +1256,24 @@ function remapSnapshotEntityIds(snapshot, idMap, options) {
           });
           record.instanceEntityIds = remapped;
         }
+      } else if (block.component === "IKComponent" && record) {
+        if (Array.isArray(record.chains)) {
+          record.chains = record.chains.map((rawChain, index) => {
+            const chain = asRecord(rawChain);
+            if (!chain) return rawChain;
+            for (const key of ["target", "pole"]) {
+              const id = chain[key];
+              if (typeof id !== "number") continue;
+              const mapped = idMap.get(id);
+              if (mapped !== void 0) chain[key] = mapped;
+              else {
+                warn(`chains/${index}/${key}`, id);
+                if (nullExternal) chain[key] = null;
+              }
+            }
+            return chain;
+          });
+        }
       } else if (block.component === "InstanceSlotComponent" && record) {
         if (typeof record.groupEntityId === "number" && record.groupEntityId !== -1) {
           const mapped = idMap.get(record.groupEntityId);