@relu-interactives/spatial-ecs 0.5.2 → 0.8.0

package/dist/factories/index.d.cts

@@ -1,8 +1,10 @@
-import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, U as RigidbodyState, g as ColliderState, P as PhysicsComponent, p as EntityType, I as ImageComponent, r as ImageTargetAnchor, q as ImageTarget, L as LightComponent, M as MaterialComponent, F as MeshComponent, G as MeshGeometryComponent, K as ModelComponent, N as Name, O as Object3DRef, X as ScriptEntry, W as ScriptComponent, Z as ScriptObjectComponentInput, Y as ScriptObjectComponent, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, x as InstancedMeshKind, H as MeshGeometryParameters, w as InstancedMeshComponent, u as InstanceSlotComponent, ak as VideoComponent, av as XRRigComponent, ai as VRTeleportAreaComponent, ao as XRHandPoseComponent, am as XRAnchorComponent, aq as XRInteractableComponent, as as XRInteractorComponent, au as XRInteractorSideComponent, a5 as UIButtonComponent, a7 as UIPanelComponent, a9 as UISliderComponent, ab as UITextComponent, ad as UIToggleComponent } from '../XRHandPose-CQTLGxFC.cjs';
-import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-V_mv07le.cjs';
+import { A as AnimationComponent, b as AudioComponent, d as CameraComponentOptions, C as CameraComponent, Z as RigidbodyState, h as ColliderState, U as PhysicsComponent, q as EntityType, I as ImageComponent, s as ImageTargetAnchor, r as ImageTarget, L as LightComponent, G as MaterialComponent, K as MeshComponent, N as MeshGeometryComponent, Q as ModelComponent, S as Name, T as Object3DRef, a0 as ScriptEntry, $ as ScriptComponent, a2 as ScriptObjectComponentInput, a1 as ScriptObjectComponent, a4 as Selectable, a5 as SelectionTransformState, a6 as SpriteComponent, y as InstancedMeshKind, O as MeshGeometryParameters, x as InstancedMeshComponent, v as InstanceSlotComponent, ap as VideoComponent, aA as XRRigComponent, an as VRTeleportAreaComponent, at as XRHandPoseComponent, ar as XRAnchorComponent, B as BoneAttachmentComponent, av as XRInteractableComponent, ax as XRInteractorComponent, az as XRInteractorSideComponent, aa as UIButtonComponent, ac as UIPanelComponent, ae as UISliderComponent, ag as UITextComponent, ai as UIToggleComponent } from '../XRHandPose-VQMT1WXj.cjs';
+import { W as World, j as EnvironmentState, E as Environment, P as ParentId, u as PostprocessingState, t as Postprocessing, T as TransformComponent, l as IKComponent, o as NetworkIdentityComponent, p as NetworkSpawnerComponent, q as NetworkTransformComponent, s as NetworkedPropsComponent, X as ObjectManagementSystem } from '../System-8D-XBDKZ.cjs';
 import * as THREE from 'three';
 import '@dimforge/rapier3d-compat';
 import '../handPose-DlcTtqgx.cjs';
+import '../animation/index.cjs';
+import 'three/webgpu';
 
 declare function createAnimationComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof AnimationComponent>): AnimationComponent;
 
@@ -83,6 +85,15 @@ declare function createXRHandPoseComponent(world: World, entityId: number, ...ar
 
 declare function createXRAnchorComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRAnchorComponent>): XRAnchorComponent;
 
+declare function createBoneAttachmentComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof BoneAttachmentComponent>): BoneAttachmentComponent;
+
+declare function createIKComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof IKComponent>): IKComponent;
+
+declare function createNetworkIdentityComponent(world: World, entityId: number): NetworkIdentityComponent;
+declare function createNetworkTransformComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof NetworkTransformComponent>): NetworkTransformComponent;
+declare function createNetworkedPropsComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof NetworkedPropsComponent>): NetworkedPropsComponent;
+declare function createNetworkSpawnerComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof NetworkSpawnerComponent>): NetworkSpawnerComponent;
+
 declare function createXRInteractableComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRInteractableComponent>): XRInteractableComponent;
 
 declare function createXRInteractorComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRInteractorComponent>): XRInteractorComponent;
@@ -103,4 +114,4 @@ declare function registerDefaultComponentFactories(objectManagementSystem: Objec
 
 declare function registerDefaultFactories(objectManagementSystem: ObjectManagementSystem): void;
 
-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 };
+export { createAnimationComponent, createAudioComponent, createBoneAttachmentComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, 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, registerDefaultComponentFactories, registerDefaultFactories };

package/dist/factories/index.d.ts

@@ -1,8 +1,10 @@
-import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, U as RigidbodyState, g as ColliderState, P as PhysicsComponent, p as EntityType, I as ImageComponent, r as ImageTargetAnchor, q as ImageTarget, L as LightComponent, M as MaterialComponent, F as MeshComponent, G as MeshGeometryComponent, K as ModelComponent, N as Name, O as Object3DRef, X as ScriptEntry, W as ScriptComponent, Z as ScriptObjectComponentInput, Y as ScriptObjectComponent, $ as Selectable, a0 as SelectionTransformState, a1 as SpriteComponent, x as InstancedMeshKind, H as MeshGeometryParameters, w as InstancedMeshComponent, u as InstanceSlotComponent, ak as VideoComponent, av as XRRigComponent, ai as VRTeleportAreaComponent, ao as XRHandPoseComponent, am as XRAnchorComponent, aq as XRInteractableComponent, as as XRInteractorComponent, au as XRInteractorSideComponent, a5 as UIButtonComponent, a7 as UIPanelComponent, a9 as UISliderComponent, ab as UITextComponent, ad as UIToggleComponent } from '../XRHandPose-CU3vNFuS.js';
-import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-V_mv07le.js';
+import { A as AnimationComponent, b as AudioComponent, d as CameraComponentOptions, C as CameraComponent, Z as RigidbodyState, h as ColliderState, U as PhysicsComponent, q as EntityType, I as ImageComponent, s as ImageTargetAnchor, r as ImageTarget, L as LightComponent, G as MaterialComponent, K as MeshComponent, N as MeshGeometryComponent, Q as ModelComponent, S as Name, T as Object3DRef, a0 as ScriptEntry, $ as ScriptComponent, a2 as ScriptObjectComponentInput, a1 as ScriptObjectComponent, a4 as Selectable, a5 as SelectionTransformState, a6 as SpriteComponent, y as InstancedMeshKind, O as MeshGeometryParameters, x as InstancedMeshComponent, v as InstanceSlotComponent, ap as VideoComponent, aA as XRRigComponent, an as VRTeleportAreaComponent, at as XRHandPoseComponent, ar as XRAnchorComponent, B as BoneAttachmentComponent, av as XRInteractableComponent, ax as XRInteractorComponent, az as XRInteractorSideComponent, aa as UIButtonComponent, ac as UIPanelComponent, ae as UISliderComponent, ag as UITextComponent, ai as UIToggleComponent } from '../XRHandPose-G0Dl-F0w.js';
+import { W as World, o as EnvironmentState, g as Environment, y as ParentId, b as PostprocessingState, z as Postprocessing, T as TransformComponent, q as IKComponent, t as NetworkIdentityComponent, u as NetworkSpawnerComponent, v as NetworkTransformComponent, x as NetworkedPropsComponent, a0 as ObjectManagementSystem } from '../System-DPMAW30g.js';
 import * as THREE from 'three';
 import '@dimforge/rapier3d-compat';
 import '../handPose-DlcTtqgx.js';
+import '../animation/index.js';
+import 'three/webgpu';
 
 declare function createAnimationComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof AnimationComponent>): AnimationComponent;
 
@@ -83,6 +85,15 @@ declare function createXRHandPoseComponent(world: World, entityId: number, ...ar
 
 declare function createXRAnchorComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRAnchorComponent>): XRAnchorComponent;
 
+declare function createBoneAttachmentComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof BoneAttachmentComponent>): BoneAttachmentComponent;
+
+declare function createIKComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof IKComponent>): IKComponent;
+
+declare function createNetworkIdentityComponent(world: World, entityId: number): NetworkIdentityComponent;
+declare function createNetworkTransformComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof NetworkTransformComponent>): NetworkTransformComponent;
+declare function createNetworkedPropsComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof NetworkedPropsComponent>): NetworkedPropsComponent;
+declare function createNetworkSpawnerComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof NetworkSpawnerComponent>): NetworkSpawnerComponent;
+
 declare function createXRInteractableComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRInteractableComponent>): XRInteractableComponent;
 
 declare function createXRInteractorComponent(world: World, entityId: number, ...args: ConstructorParameters<typeof XRInteractorComponent>): XRInteractorComponent;
@@ -103,4 +114,4 @@ declare function registerDefaultComponentFactories(objectManagementSystem: Objec
 
 declare function registerDefaultFactories(objectManagementSystem: ObjectManagementSystem): void;
 
-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 };
+export { createAnimationComponent, createAudioComponent, createBoneAttachmentComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, 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, registerDefaultComponentFactories, registerDefaultFactories };

package/dist/factories/index.js

@@ -1,6 +1,9 @@
-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 '../chunk-WJD2VKEH.js';
-import '../chunk-BUEKOSR5.js';
-import '../chunk-OY7ZODZP.js';
+export { registerDefaultComponentFactories, registerDefaultFactories } from '../chunk-SGF73YTF.js';
+import '../chunk-OHCNPPMX.js';
+export { createAnimationComponent, createAudioComponent, createBoneAttachmentComponent, createCameraComponent, createEntityTypeComponent, createEnvironmentComponent, 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 } from '../chunk-G4XJ53LS.js';
+import '../chunk-NNDUOQ7O.js';
+import '../chunk-CKTHDXPS.js';
+import '../chunk-GSWC6LLD.js';
+import '../chunk-XE4OXN2W.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{index-D2Jt_JzH.d.ts → index-C61n65PE.d.ts}

@@ -1,4 +1,4 @@
-import { k as EcsSystem, l as World, I as InputSystem, r as EntityId } from './System-V_mv07le.js';
+import { K as EcsSystem, W as World, E as EcsRenderer, R as RenderBackend, ai as InputSystem, M as EntityId } from './System-DPMAW30g.js';
 import * as THREE from 'three';
 import { m as XrHandJoints, r as XrHandShape } from './handPose-DlcTtqgx.js';
 
@@ -22,33 +22,135 @@ declare class ObjectVisibilitySystem implements EcsSystem {
     update(world: World): void;
 }
 
+/**
+ * Applies the scene's {@link Environment} component to the three.js scene:
+ * skybox, fog, and (when `values.lighting` is present) image-based lighting,
+ * tone mapping and exposure.
+ *
+ * Each part is dirty-checked on its own, so animating `lighting.envIntensity`
+ * every frame does not rebuild the skybox texture.
+ *
+ * Runs in the editor and at runtime. While an XR session composites over the
+ * real world (`World.isXrPassthrough()`) the background is withheld; lighting
+ * and fog still apply.
+ *
+ * On WebGL the environment map is PMREM-prefiltered here. On WebGPU
+ * (`World.getRendererKind() === "webgpu"`) the equirect texture is assigned
+ * to `scene.environment` as is and the renderer prefilters it.
+ *
+ * @category Systems
+ */
 declare class EnvironmentSyncSystem implements EcsSystem {
     private readonly scene;
     private readonly textureLoader;
-    private signature;
+    /** `true` once an Environment entity has been seen (drives the reset path). */
+    private hasEnvironment;
+    private skyboxSignature;
+    private fogSignature;
+    private lightingSignature;
     private activeTexture;
+    /** Load key (`url`, or `equirect|url`) of the current/pending image skybox. */
     private pendingImageUrl;
+    /** What the skybox wants as the background, before passthrough/env overrides. */
+    private skyboxBackground;
     /** Whether the skybox is currently withheld because passthrough is on. */
     private passthroughSuppressed;
+    private renderer;
+    private lighting;
+    /** URL of the environment map currently loaded or loading. */
+    private envUrl;
+    /** Incremented per env-map load; a load whose token is stale is discarded. */
+    private envLoadToken;
+    /** Equirect source texture of the current environment map. */
+    private envSource;
+    /**
+     * PMREM render target built from {@link envSource} (WebGL only; on WebGPU
+     * the renderer prefilters `scene.environment` itself and this stays null).
+     */
+    private envTarget;
+    private sceneLightingBaseline;
+    private sceneBackgroundBaseline;
+    private disposed;
     constructor(scene: THREE.Scene);
     private disposeActiveTexture;
+    /** Write the background the current state calls for. */
+    private commitBackground;
+    private restoreBackgroundBaseline;
+    private setSkyboxBackground;
     private applySkybox;
     private applyFog;
+    private disposeEnvResources;
+    /** Drop the environment map (any in-flight load is abandoned). */
+    private clearEnvMap;
+    /**
+     * Undo everything the lighting block wrote to the scene and renderer.
+     * `commit` re-applies the background afterwards (off during teardown, which
+     * must not touch the background).
+     */
+    private clearLighting;
+    /**
+     * PMREM-filter an equirect texture. `null` when no usable renderer exists,
+     * or on WebGPU: there the WebGL `PMREMGenerator` would silently produce a
+     * black map, while `WebGPURenderer` prefilters an equirect
+     * `scene.environment` (and a blurred background) by itself.
+     */
+    private buildPmrem;
+    private loadEnvMap;
+    private applyEnvironmentParams;
+    private applyLighting;
+    private resetAll;
     update(world: World): void;
     dispose(): void;
 }
 
+/**
+ * Builds the post-processing chain from the scene's {@link Postprocessing}
+ * component and hands it to `RenderSystem` through `scene.userData`:
+ *
+ * - `ecsPostprocessingComposer` — the built chain (`render()`, `dispose()`,
+ *   optional `setSize()` / `setPixelRatio()`). On WebGL it is the
+ *   `EffectComposer` itself.
+ * - `ecsPostprocessingComposerActive` — `true` while `RenderSystem` should
+ *   render through it.
+ * - `ecsPostprocessing` — the values the chain was built from.
+ *
+ * The chain itself comes from the world's render backend: an
+ * `EffectComposer` on WebGL (pass order: scene render → depth of field →
+ * bloom → vignette → hue/saturation → sepia → film noise → dot screen →
+ * SSAO → glitch → chromatic aberration → pixelation → SMAA → output), a
+ * `RenderPipeline` of TSL nodes with `webgpuBackend`. A backend that can
+ * update a chain in place (the WebGPU one) skips the rebuild when only
+ * parameters changed.
+ *
+ * The `toneMapping` effect has no pass of its own: when active it asks the
+ * renderer for tone mapping, which the chain's output step then applies. See
+ * `Environment.values.lighting.toneMapping` for how the two combine.
+ *
+ * @category Systems
+ */
 declare class PostprocessingSyncSystem implements EcsSystem {
     private readonly renderer;
     private readonly scene;
     private readonly camera;
+    private readonly backend;
     private signature;
+    /** Deep copy of the values the current chain reflects. */
+    private appliedValues;
     private composer;
     private composerEnabled;
-    constructor(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera);
+    /**
+     * @param backend - Builds the chain. When omitted, the world's backend
+     *   (`world.getRenderBackend()`) is used.
+     */
+    constructor(renderer: EcsRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera, backend?: RenderBackend);
     private setComposerEnabled;
     private disposeComposer;
+    /** Ask the renderer for tone mapping while the effect is active. */
+    private applyToneMapping;
+    private resolveBackend;
     private buildComposer;
+    /** Update the existing chain in place; `false` when it must be rebuilt. */
+    private tryUpdateInPlace;
     update(world: World): void;
     dispose(): void;
 }
@@ -132,6 +234,20 @@ declare class InstancedMeshSystem implements EcsSystem {
 /** Resolves a script URL to its ES module namespace. */
 type ModuleLoader = (scriptUrl: string) => Promise<Record<string, unknown>>;
 
+/**
+ * Seconds a Behaviour waits after an error (load, `init()` or `update()`)
+ * before it is re-initialised. Without the wait a script that throws every
+ * frame was torn down and rebuilt every frame.
+ */
+declare const DEFAULT_SCRIPT_ERROR_RETRY_DELAY = 1;
+/** Options for {@link ScriptBehaviourSystem}. */
+type ScriptBehaviourSystemOptions = {
+    /**
+     * Seconds to wait after a script error before re-initialising the script.
+     * Default {@link DEFAULT_SCRIPT_ERROR_RETRY_DELAY}.
+     */
+    errorRetryDelay?: number;
+};
 /**
  * Optional context that enables raycast-based onSelect / onDeselect dispatch.
  * When provided, pointer/touch taps on the canvas fire a raycast against the
@@ -148,6 +264,11 @@ declare class ScriptBehaviourSystem implements EcsSystem {
     private instances;
     private loading;
     private readonly moduleLoader;
+    private readonly errorRetryDelay;
+    /** Seconds of world time this system has seen (sum of `deltaTime`). */
+    private clock;
+    /** Instance key → clock time before which a failed script is not retried. */
+    private retryAt;
     private readonly selectionCtx;
     private readonly raycaster;
     private readonly ndcPointer;
@@ -155,7 +276,7 @@ declare class ScriptBehaviourSystem implements EcsSystem {
     private pendingEntityId;
     private pointerDownPos;
     private static readonly CLICK_THRESHOLD;
-    constructor(moduleLoader?: ModuleLoader, selectionContext?: SelectionContext);
+    constructor(moduleLoader?: ModuleLoader, selectionContext?: SelectionContext, options?: ScriptBehaviourSystemOptions);
     /** Walk up the object hierarchy to find the nearest userData.entityId. */
     private resolveEntityId;
     /** Convert client (screen) coordinates to normalised device coordinates. */
@@ -170,6 +291,9 @@ declare class ScriptBehaviourSystem implements EcsSystem {
      * onSelect() on all behaviours of the newly selected entity.
      */
     private applySelection;
+    private reportRecordError;
+    /** Hold a failed script back for {@link errorRetryDelay} seconds. */
+    private scheduleRetry;
     update(world: World, deltaTime: number): void;
     dispose(world: World): void;
     private loadBehaviour;
@@ -195,6 +319,8 @@ declare class ScriptObjectSystem implements EcsSystem {
     private loading;
     /** Bumped by invalidate*() so in-flight loads that predate it are discarded. */
     private epoch;
+    /** World seen by the last update(), so invalidate*() can reset error dedupe. */
+    private lastWorld;
     constructor(moduleLoader?: ModuleLoader);
     update(world: World, deltaTime: number): void;
     private loadScriptObject;
@@ -208,41 +334,6 @@ declare class ScriptObjectSystem implements EcsSystem {
     dispose(world: World): void;
 }
 
-/**
- * Reconciles `AudioComponent` state with the underlying THREE.js audio objects
- * each frame.
- *
- * **Playback** — drives `play()`, `pause()`, and `stop()` on the THREE.js
- * audio node based on the `isPlaying` / `isPaused` flags set by
- * `AudioComponent.play()`, `.pause()`, and `.stop()`.
- *
- * **Option sync** — detects changes to `loop`, `pitch`, `volume`,
- * `refDistance`, `distanceModel`, and `rolloffFactor` and applies them live.
- * Changes take effect on the next frame, so scripts and inspector edits during
- * runtime are reflected without reloading the scene.
- *
- * Only active in **preview** mode (`isEditor: true` makes every update a
- * no-op so the editor is unaffected).
- *
- * @category Systems
- */
-declare class AudioSystem implements EcsSystem {
-    private readonly isEditor;
-    /** THREE.js `isPlaying` state captured at the end of the previous frame. */
-    private readonly prevPlayingState;
-    /** Snapshot of options applied in the previous frame, for change detection. */
-    private readonly prevOptions;
-    /** Tracks entities that were stopped due to invisibility. */
-    private readonly stoppedDueToInvisibility;
-    constructor({ isEditor }?: {
-        isEditor?: boolean;
-    });
-    update(world: World, _deltaTime: number): void;
-    /** Apply any changed options from the component to the THREE.js audio node. */
-    private _syncOptions;
-    dispose(_world: World): void;
-}
-
 /**
  * Reconciles `VideoComponent` state with the underlying HTML video element
  * and THREE.js mesh/material each frame.
@@ -252,8 +343,10 @@ declare class AudioSystem implements EcsSystem {
  * by `VideoComponent.play()`, `.pause()`, and `.stop()`.
  *
  * **Option sync** — detects changes to `loop`, `volume`, `width`, `height`,
- * and green-screen shader uniforms (`backgroundColor`, `similarity`,
- * `smoothness`, `spill`) and applies them live without a scene reload.
+ * and green-screen keying (`backgroundColor`, `similarity`, `smoothness`,
+ * `spill`) and applies them live without a scene reload. The keying material
+ * belongs to the world's render backend (GLSL on WebGL, TSL with
+ * `webgpuBackend`), which updates it.
  *
  * Only active in **preview** mode (`isEditor: true` makes every update a
  * no-op so the editor is unaffected).
@@ -1174,4 +1267,4 @@ declare class XRHoverVisualSystem implements EcsSystem {
     dispose(): void;
 }
 
-export { AnimationSystem as A, type XrInputKind as B, CameraSyncSystem as C, readXrCapabilities as D, EnvironmentSyncSystem as E, InstancedMeshSystem as I, LightSyncSystem as L, MaterialSyncSystem as M, NO_XR_CAPABILITIES as N, ObjectVisibilitySystem as O, PhysicsSyncSystem as P, SCRIPT_OBJECT_ROOT_FLAG as S, UIInteractionSystem as U, VRTeleportAreaSystem as V, type XrCapabilities as X, type XrInputState as a, type XrHandPoseEventDetail as b, AudioSystem as c, MeshGeometrySystem as d, type ModuleLoader as e, PostprocessingSyncSystem as f, ScriptBehaviourSystem as g, ScriptObjectSystem as h, type SelectionContext as i, UIPanelSystem as j, type UiCanvasLike as k, VideoSystem as l, XRAnchorSystem as m, XRControllerVisualSystem as n, XREnvironmentSystem as o, XRHandPoseSystem as p, XRHitTestSystem as q, XRHoverVisualSystem as r, XRInputSystem as s, XRInteractionSystem as t, XRLocomotionSystem as u, XRSessionSystem as v, XRTeleportVisualSystem as w, XR_HOVER_SHELL_FLAG as x, type XrHandedness as y, type XrHitResult as z };
+export { AnimationSystem as A, type XrInputKind as B, CameraSyncSystem as C, DEFAULT_SCRIPT_ERROR_RETRY_DELAY as D, EnvironmentSyncSystem as E, readXrCapabilities as F, InstancedMeshSystem as I, LightSyncSystem as L, MaterialSyncSystem as M, NO_XR_CAPABILITIES as N, ObjectVisibilitySystem as O, PhysicsSyncSystem as P, SCRIPT_OBJECT_ROOT_FLAG as S, UIInteractionSystem as U, VRTeleportAreaSystem as V, type XrCapabilities as X, type XrInputState as a, type XrHandPoseEventDetail as b, MeshGeometrySystem as c, type ModuleLoader as d, PostprocessingSyncSystem as e, ScriptBehaviourSystem as f, type ScriptBehaviourSystemOptions as g, ScriptObjectSystem as h, type SelectionContext as i, UIPanelSystem as j, type UiCanvasLike as k, VideoSystem as l, XRAnchorSystem as m, XRControllerVisualSystem as n, XREnvironmentSystem as o, XRHandPoseSystem as p, XRHitTestSystem as q, XRHoverVisualSystem as r, XRInputSystem as s, XRInteractionSystem as t, XRLocomotionSystem as u, XRSessionSystem as v, XRTeleportVisualSystem as w, XR_HOVER_SHELL_FLAG as x, type XrHandedness as y, type XrHitResult as z };

package/dist/{index-DaG03vyN.d.cts → index-C70N4BYG.d.cts}

@@ -1,4 +1,4 @@
-import { k as EcsSystem, l as World, I as InputSystem, r as EntityId } from './System-V_mv07le.cjs';
+import { B as EcsSystem, W as World, ab as EcsRenderer, R as RenderBackend, af as InputSystem, G as EntityId } from './System-8D-XBDKZ.cjs';
 import * as THREE from 'three';
 import { m as XrHandJoints, r as XrHandShape } from './handPose-DlcTtqgx.cjs';
 
@@ -22,33 +22,135 @@ declare class ObjectVisibilitySystem implements EcsSystem {
     update(world: World): void;
 }
 
+/**
+ * Applies the scene's {@link Environment} component to the three.js scene:
+ * skybox, fog, and (when `values.lighting` is present) image-based lighting,
+ * tone mapping and exposure.
+ *
+ * Each part is dirty-checked on its own, so animating `lighting.envIntensity`
+ * every frame does not rebuild the skybox texture.
+ *
+ * Runs in the editor and at runtime. While an XR session composites over the
+ * real world (`World.isXrPassthrough()`) the background is withheld; lighting
+ * and fog still apply.
+ *
+ * On WebGL the environment map is PMREM-prefiltered here. On WebGPU
+ * (`World.getRendererKind() === "webgpu"`) the equirect texture is assigned
+ * to `scene.environment` as is and the renderer prefilters it.
+ *
+ * @category Systems
+ */
 declare class EnvironmentSyncSystem implements EcsSystem {
     private readonly scene;
     private readonly textureLoader;
-    private signature;
+    /** `true` once an Environment entity has been seen (drives the reset path). */
+    private hasEnvironment;
+    private skyboxSignature;
+    private fogSignature;
+    private lightingSignature;
     private activeTexture;
+    /** Load key (`url`, or `equirect|url`) of the current/pending image skybox. */
     private pendingImageUrl;
+    /** What the skybox wants as the background, before passthrough/env overrides. */
+    private skyboxBackground;
     /** Whether the skybox is currently withheld because passthrough is on. */
     private passthroughSuppressed;
+    private renderer;
+    private lighting;
+    /** URL of the environment map currently loaded or loading. */
+    private envUrl;
+    /** Incremented per env-map load; a load whose token is stale is discarded. */
+    private envLoadToken;
+    /** Equirect source texture of the current environment map. */
+    private envSource;
+    /**
+     * PMREM render target built from {@link envSource} (WebGL only; on WebGPU
+     * the renderer prefilters `scene.environment` itself and this stays null).
+     */
+    private envTarget;
+    private sceneLightingBaseline;
+    private sceneBackgroundBaseline;
+    private disposed;
     constructor(scene: THREE.Scene);
     private disposeActiveTexture;
+    /** Write the background the current state calls for. */
+    private commitBackground;
+    private restoreBackgroundBaseline;
+    private setSkyboxBackground;
     private applySkybox;
     private applyFog;
+    private disposeEnvResources;
+    /** Drop the environment map (any in-flight load is abandoned). */
+    private clearEnvMap;
+    /**
+     * Undo everything the lighting block wrote to the scene and renderer.
+     * `commit` re-applies the background afterwards (off during teardown, which
+     * must not touch the background).
+     */
+    private clearLighting;
+    /**
+     * PMREM-filter an equirect texture. `null` when no usable renderer exists,
+     * or on WebGPU: there the WebGL `PMREMGenerator` would silently produce a
+     * black map, while `WebGPURenderer` prefilters an equirect
+     * `scene.environment` (and a blurred background) by itself.
+     */
+    private buildPmrem;
+    private loadEnvMap;
+    private applyEnvironmentParams;
+    private applyLighting;
+    private resetAll;
     update(world: World): void;
     dispose(): void;
 }
 
+/**
+ * Builds the post-processing chain from the scene's {@link Postprocessing}
+ * component and hands it to `RenderSystem` through `scene.userData`:
+ *
+ * - `ecsPostprocessingComposer` — the built chain (`render()`, `dispose()`,
+ *   optional `setSize()` / `setPixelRatio()`). On WebGL it is the
+ *   `EffectComposer` itself.
+ * - `ecsPostprocessingComposerActive` — `true` while `RenderSystem` should
+ *   render through it.
+ * - `ecsPostprocessing` — the values the chain was built from.
+ *
+ * The chain itself comes from the world's render backend: an
+ * `EffectComposer` on WebGL (pass order: scene render → depth of field →
+ * bloom → vignette → hue/saturation → sepia → film noise → dot screen →
+ * SSAO → glitch → chromatic aberration → pixelation → SMAA → output), a
+ * `RenderPipeline` of TSL nodes with `webgpuBackend`. A backend that can
+ * update a chain in place (the WebGPU one) skips the rebuild when only
+ * parameters changed.
+ *
+ * The `toneMapping` effect has no pass of its own: when active it asks the
+ * renderer for tone mapping, which the chain's output step then applies. See
+ * `Environment.values.lighting.toneMapping` for how the two combine.
+ *
+ * @category Systems
+ */
 declare class PostprocessingSyncSystem implements EcsSystem {
     private readonly renderer;
     private readonly scene;
     private readonly camera;
+    private readonly backend;
     private signature;
+    /** Deep copy of the values the current chain reflects. */
+    private appliedValues;
     private composer;
     private composerEnabled;
-    constructor(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera);
+    /**
+     * @param backend - Builds the chain. When omitted, the world's backend
+     *   (`world.getRenderBackend()`) is used.
+     */
+    constructor(renderer: EcsRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera, backend?: RenderBackend);
     private setComposerEnabled;
     private disposeComposer;
+    /** Ask the renderer for tone mapping while the effect is active. */
+    private applyToneMapping;
+    private resolveBackend;
     private buildComposer;
+    /** Update the existing chain in place; `false` when it must be rebuilt. */
+    private tryUpdateInPlace;
     update(world: World): void;
     dispose(): void;
 }
@@ -132,6 +234,20 @@ declare class InstancedMeshSystem implements EcsSystem {
 /** Resolves a script URL to its ES module namespace. */
 type ModuleLoader = (scriptUrl: string) => Promise<Record<string, unknown>>;
 
+/**
+ * Seconds a Behaviour waits after an error (load, `init()` or `update()`)
+ * before it is re-initialised. Without the wait a script that throws every
+ * frame was torn down and rebuilt every frame.
+ */
+declare const DEFAULT_SCRIPT_ERROR_RETRY_DELAY = 1;
+/** Options for {@link ScriptBehaviourSystem}. */
+type ScriptBehaviourSystemOptions = {
+    /**
+     * Seconds to wait after a script error before re-initialising the script.
+     * Default {@link DEFAULT_SCRIPT_ERROR_RETRY_DELAY}.
+     */
+    errorRetryDelay?: number;
+};
 /**
  * Optional context that enables raycast-based onSelect / onDeselect dispatch.
  * When provided, pointer/touch taps on the canvas fire a raycast against the
@@ -148,6 +264,11 @@ declare class ScriptBehaviourSystem implements EcsSystem {
     private instances;
     private loading;
     private readonly moduleLoader;
+    private readonly errorRetryDelay;
+    /** Seconds of world time this system has seen (sum of `deltaTime`). */
+    private clock;
+    /** Instance key → clock time before which a failed script is not retried. */
+    private retryAt;
     private readonly selectionCtx;
     private readonly raycaster;
     private readonly ndcPointer;
@@ -155,7 +276,7 @@ declare class ScriptBehaviourSystem implements EcsSystem {
     private pendingEntityId;
     private pointerDownPos;
     private static readonly CLICK_THRESHOLD;
-    constructor(moduleLoader?: ModuleLoader, selectionContext?: SelectionContext);
+    constructor(moduleLoader?: ModuleLoader, selectionContext?: SelectionContext, options?: ScriptBehaviourSystemOptions);
     /** Walk up the object hierarchy to find the nearest userData.entityId. */
     private resolveEntityId;
     /** Convert client (screen) coordinates to normalised device coordinates. */
@@ -170,6 +291,9 @@ declare class ScriptBehaviourSystem implements EcsSystem {
      * onSelect() on all behaviours of the newly selected entity.
      */
     private applySelection;
+    private reportRecordError;
+    /** Hold a failed script back for {@link errorRetryDelay} seconds. */
+    private scheduleRetry;
     update(world: World, deltaTime: number): void;
     dispose(world: World): void;
     private loadBehaviour;
@@ -195,6 +319,8 @@ declare class ScriptObjectSystem implements EcsSystem {
     private loading;
     /** Bumped by invalidate*() so in-flight loads that predate it are discarded. */
     private epoch;
+    /** World seen by the last update(), so invalidate*() can reset error dedupe. */
+    private lastWorld;
     constructor(moduleLoader?: ModuleLoader);
     update(world: World, deltaTime: number): void;
     private loadScriptObject;
@@ -208,41 +334,6 @@ declare class ScriptObjectSystem implements EcsSystem {
     dispose(world: World): void;
 }
 
-/**
- * Reconciles `AudioComponent` state with the underlying THREE.js audio objects
- * each frame.
- *
- * **Playback** — drives `play()`, `pause()`, and `stop()` on the THREE.js
- * audio node based on the `isPlaying` / `isPaused` flags set by
- * `AudioComponent.play()`, `.pause()`, and `.stop()`.
- *
- * **Option sync** — detects changes to `loop`, `pitch`, `volume`,
- * `refDistance`, `distanceModel`, and `rolloffFactor` and applies them live.
- * Changes take effect on the next frame, so scripts and inspector edits during
- * runtime are reflected without reloading the scene.
- *
- * Only active in **preview** mode (`isEditor: true` makes every update a
- * no-op so the editor is unaffected).
- *
- * @category Systems
- */
-declare class AudioSystem implements EcsSystem {
-    private readonly isEditor;
-    /** THREE.js `isPlaying` state captured at the end of the previous frame. */
-    private readonly prevPlayingState;
-    /** Snapshot of options applied in the previous frame, for change detection. */
-    private readonly prevOptions;
-    /** Tracks entities that were stopped due to invisibility. */
-    private readonly stoppedDueToInvisibility;
-    constructor({ isEditor }?: {
-        isEditor?: boolean;
-    });
-    update(world: World, _deltaTime: number): void;
-    /** Apply any changed options from the component to the THREE.js audio node. */
-    private _syncOptions;
-    dispose(_world: World): void;
-}
-
 /**
  * Reconciles `VideoComponent` state with the underlying HTML video element
  * and THREE.js mesh/material each frame.
@@ -252,8 +343,10 @@ declare class AudioSystem implements EcsSystem {
  * by `VideoComponent.play()`, `.pause()`, and `.stop()`.
  *
  * **Option sync** — detects changes to `loop`, `volume`, `width`, `height`,
- * and green-screen shader uniforms (`backgroundColor`, `similarity`,
- * `smoothness`, `spill`) and applies them live without a scene reload.
+ * and green-screen keying (`backgroundColor`, `similarity`, `smoothness`,
+ * `spill`) and applies them live without a scene reload. The keying material
+ * belongs to the world's render backend (GLSL on WebGL, TSL with
+ * `webgpuBackend`), which updates it.
  *
  * Only active in **preview** mode (`isEditor: true` makes every update a
  * no-op so the editor is unaffected).
@@ -1174,4 +1267,4 @@ declare class XRHoverVisualSystem implements EcsSystem {
     dispose(): void;
 }
 
-export { AnimationSystem as A, type XrInputKind as B, CameraSyncSystem as C, readXrCapabilities as D, EnvironmentSyncSystem as E, InstancedMeshSystem as I, LightSyncSystem as L, MaterialSyncSystem as M, NO_XR_CAPABILITIES as N, ObjectVisibilitySystem as O, PhysicsSyncSystem as P, SCRIPT_OBJECT_ROOT_FLAG as S, UIInteractionSystem as U, VRTeleportAreaSystem as V, type XrCapabilities as X, type XrInputState as a, type XrHandPoseEventDetail as b, AudioSystem as c, MeshGeometrySystem as d, type ModuleLoader as e, PostprocessingSyncSystem as f, ScriptBehaviourSystem as g, ScriptObjectSystem as h, type SelectionContext as i, UIPanelSystem as j, type UiCanvasLike as k, VideoSystem as l, XRAnchorSystem as m, XRControllerVisualSystem as n, XREnvironmentSystem as o, XRHandPoseSystem as p, XRHitTestSystem as q, XRHoverVisualSystem as r, XRInputSystem as s, XRInteractionSystem as t, XRLocomotionSystem as u, XRSessionSystem as v, XRTeleportVisualSystem as w, XR_HOVER_SHELL_FLAG as x, type XrHandedness as y, type XrHitResult as z };
+export { AnimationSystem as A, type XrInputKind as B, CameraSyncSystem as C, DEFAULT_SCRIPT_ERROR_RETRY_DELAY as D, EnvironmentSyncSystem as E, readXrCapabilities as F, InstancedMeshSystem as I, LightSyncSystem as L, MaterialSyncSystem as M, NO_XR_CAPABILITIES as N, ObjectVisibilitySystem as O, PhysicsSyncSystem as P, SCRIPT_OBJECT_ROOT_FLAG as S, UIInteractionSystem as U, VRTeleportAreaSystem as V, type XrCapabilities as X, type XrInputState as a, type XrHandPoseEventDetail as b, MeshGeometrySystem as c, type ModuleLoader as d, PostprocessingSyncSystem as e, ScriptBehaviourSystem as f, type ScriptBehaviourSystemOptions as g, ScriptObjectSystem as h, type SelectionContext as i, UIPanelSystem as j, type UiCanvasLike as k, VideoSystem as l, XRAnchorSystem as m, XRControllerVisualSystem as n, XREnvironmentSystem as o, XRHandPoseSystem as p, XRHitTestSystem as q, XRHoverVisualSystem as r, XRInputSystem as s, XRInteractionSystem as t, XRLocomotionSystem as u, XRSessionSystem as v, XRTeleportVisualSystem as w, XR_HOVER_SHELL_FLAG as x, type XrHandedness as y, type XrHitResult as z };