@relu-interactives/spatial-ecs 0.5.3 → 0.9.0

package/dist/{XRHandPose-CU3vNFuS.d.ts → XRHandPose-CWSrsnYN.d.ts}

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import { C as Component, p as EcsEntityKind, F as EcsEntityEditorKind, r as EntityId } from './System-V_mv07le.js';
+import { d as Component, a3 as AudioBus, $ as EcsEntityKind, ae as EcsEntityEditorKind, M as EntityId } from './System-DPMAW30g.js';
 import * as RAPIER from '@dimforge/rapier3d-compat';
 import { a as XrFinger, c as XrHandPoseDirection, b as XrHandPoseOrientation, X as XrHandPoseDefinition } from './handPose-DlcTtqgx.js';
 
@@ -256,6 +256,7 @@ declare const DEFAULT_AUDIO_OPTIONS: {
     refDistance: number;
     distanceModel: string;
     rolloffFactor: number;
+    bus: AudioBus;
 };
 /**
  * Plays an audio clip from `path`. Supports both global stereo (`positional:
@@ -281,6 +282,7 @@ declare class AudioComponent extends Component {
      * | `refDistance` | `1` | Distance at which volume is unattenuated (positional only). |
      * | `distanceModel` | `"inverse"` | WebAudio distance model (`linear`, `inverse`, `exponential`). |
      * | `rolloffFactor` | `1` | How quickly volume falls off past `refDistance`. |
+     * | `bus` | `"sfx"` | The mixer group it plays through: `sfx`, `voice` or `music`. Music dips while a voice plays. |
      */
     options: typeof DEFAULT_AUDIO_OPTIONS;
     /** Live three.js object hosting the audio (a parented `Audio`/`PositionalAudio`). `null` until built. */
@@ -761,6 +763,32 @@ declare class ImageTargetAnchor extends Component {
     constructor(options?: ImageTargetAnchorOptions);
 }
 
+/**
+ * Optional shadow tuning for a shadow-casting light (directional, spot,
+ * point). Only the fields present are applied; a missing field keeps three's
+ * default, and a light without a `shadow` block is never touched.
+ */
+type LightShadowState = {
+    /** Shadow map resolution in texels (square). three's default is `512`. Clamped to `[16, 8192]`. */
+    mapSize?: number;
+    /** Depth bias to fight shadow acne. Small negatives such as `-0.0005` are typical. */
+    bias?: number;
+    /** Bias along the surface normal; `0.02`-`0.05` removes acne on large flat surfaces. */
+    normalBias?: number;
+    /** Blur radius of the shadow edge (PCF shadow maps). */
+    radius?: number;
+    /**
+     * Half-extent, in world units, of a DIRECTIONAL light's orthographic shadow
+     * camera (`left = bottom = -cameraSize`, `right = top = cameraSize`).
+     * three's default is `5`, which only covers a 10 m square. Ignored for spot
+     * and point lights.
+     */
+    cameraSize?: number;
+    /** Near plane of the shadow camera. */
+    near?: number;
+    /** Far plane of the shadow camera. Spot lights with a `distance` use that instead. */
+    far?: number;
+};
 /** Authoring state for {@link LightComponent}. Common fields apply to every light kind; the optional fields are only meaningful for specific kinds. */
 type LightValueState = {
     /** Light color as `#rrggbb` hex string. */
@@ -783,6 +811,8 @@ type LightValueState = {
     width?: number;
     /** Rectangle height in world units. (RectAreaLight) */
     height?: number;
+    /** Optional shadow tuning. Absent = three's shadow defaults. (DirectionalLight, SpotLight, PointLight) */
+    shadow?: LightShadowState;
 };
 /**
  * Light source attached to an entity. `type` selects the underlying three.js
@@ -922,11 +952,23 @@ declare class MeshComponent extends Component {
     constructor(mesh: THREE.Object3D);
 }
 
+/** Load progress of a {@link ModelComponent}'s asset. */
+type ModelLoadState = "loading" | "loaded" | "error";
+/** Message used when a model entity has no asset path to load. */
+declare const MODEL_NO_PATH_MESSAGE = "No model path set.";
+/**
+ * Write a model's load state as NON-ENUMERABLE own properties, so it never
+ * enters snapshots, undo history or saved projects. Always via defineProperty
+ * (the pattern `setPhysicsLiveRef` uses): plain assignment on a
+ * history-restored clone would create an ENUMERABLE property instead.
+ */
+declare function setModelLoadState(component: ModelComponent, state: ModelLoadState, error?: string): void;
 /**
  * References a GLTF/GLB asset loaded from `path`. The model loading system
  * resolves the asset asynchronously and populates {@link ModelComponent.object}
  * once available; loading is deferred-tolerant so the entity exists before
- * the model finishes loading.
+ * the model finishes loading. {@link ModelComponent.loadState} reports
+ * progress (`"loading"` → `"loaded"` or `"error"`).
  *
  * @category Components
  */
@@ -935,6 +977,15 @@ declare class ModelComponent extends Component {
     path: string;
     /** Loaded model object, populated asynchronously by the model loader. `null` until loaded. */
     object: THREE.Object3D | null;
+    /**
+     * `"loading"` while the asset is being fetched and parsed, `"loaded"` once
+     * it is attached to the entity, `"error"` when it failed (see
+     * {@link loadError}). A model with an empty `path` reports `"error"`.
+     * Runtime-only: never saved.
+     */
+    loadState: ModelLoadState;
+    /** Why the load failed, when {@link loadState} is `"error"`. Runtime-only. */
+    loadError?: string;
     constructor(path: string);
 }
 
@@ -1573,6 +1624,119 @@ declare class XRAnchorComponent extends Component {
     constructor(options?: XRAnchorOptions);
 }
 
+/** Optional initializer for {@link BoneAttachmentComponent}. */
+type BoneAttachmentOptions = {
+    /** The bone's node name in the parent's model (as three.js names it). */
+    bone?: string;
+    /** The bone's humanoid name (`rightHand`, `head` …), used when the node name isn't found (another rig). */
+    humanoid?: string | null;
+    /** Cancel the bone's world scale so offsets are in metres on any rig. Defaults to `true`. */
+    compensateScale?: boolean;
+    /** Turn the attachment off without removing it. Defaults to `true`. */
+    enabled?: boolean;
+};
+/**
+ * Fixes an entity to a bone of its PARENT's model — a sword in a hand, a hat
+ * on a head, a backpack on the chest — so it moves with every animation.
+ *
+ * The entity's `ParentId` stays the character; this names the bone. The
+ * `ObjectManagementSystem` then parents the entity's object under that bone
+ * (through a small socket that cancels the rig's scale), and the entity's
+ * Transform becomes its offset FROM the bone: position in metres, rotation
+ * relative to the bone. Until the model has loaded, or when the bone isn't
+ * found, the entity sits under the character as an ordinary child.
+ *
+ * Attach and detach with `ObjectManagementSystem.attachToBone` /
+ * `detachFromBone`, which can keep the entity where it is in the world.
+ *
+ * @category Components
+ */
+declare class BoneAttachmentComponent extends Component {
+    /** The bone's node name in the parent's model. */
+    bone: string;
+    /** The bone's humanoid name, the fallback when the node name isn't found. */
+    humanoid: string | null;
+    /** Cancel the bone's world scale (offsets in metres on a centimetre rig). */
+    compensateScale: boolean;
+    /** Whether the entity follows the bone. Off: an ordinary child of the character. */
+    enabled: boolean;
+    constructor(options?: BoneAttachmentOptions);
+}
+
+/**
+ * The style model for spatial UI.
+ *
+ * Every field here is optional and stays ABSENT until authored. A defaulted
+ * field would show up as a change on every instance of a prefab saved before
+ * it existed, pinning those instances against later prefab edits. Old flat
+ * fields (`backgroundColor`, `cornerRadius`…) stay as the fallback, so a scene
+ * saved before this model renders the same.
+ *
+ * Units are metres. Any colour or file string may be a token, `$name`, which
+ * resolves through `tokens` on the nearest panel above the widget. A theme
+ * therefore travels with a prefab, and editing one panel restyles a menu.
+ *
+ * Pure and free of three.js and the DOM.
+ */
+type UiColorStop = {
+    at: number;
+    color: string;
+};
+type UiPaint = {
+    kind: "solid";
+    color: string;
+}
+/** `angle` is in degrees and reads like CSS: 0 points up, 90 points right. */
+ | {
+    kind: "linear";
+    angle: number;
+    stops: UiColorStop[];
+} | {
+    kind: "radial";
+    stops: UiColorStop[];
+} | {
+    kind: "image";
+    src: string;
+    fit: "cover" | "contain" | "fill";
+    tint?: string;
+};
+type UiShadow = {
+    x: number;
+    y: number;
+    blur: number;
+    color: string;
+};
+type UiTextStyle = {
+    /** A font file in the project, such as one `add_font` bundled. */
+    font?: string;
+    weight?: number;
+    /** Letter spacing in metres. */
+    tracking?: number;
+    transform?: "upper" | "lower";
+    paint?: UiPaint;
+    maxLines?: number;
+    shadow?: UiShadow;
+};
+type UiStyle = {
+    fill?: UiPaint;
+    border?: {
+        width: number;
+        paint: UiPaint;
+    };
+    /** One radius, or top-left, top-right, bottom-right, bottom-left. */
+    radius?: number | [number, number, number, number];
+    shadows?: UiShadow[];
+    /** A thin highlight along the top inner edge. */
+    edge?: {
+        width: number;
+        color: string;
+    };
+    /** 0–1. Multiplies down the widget tree, so fading a panel fades its menu. */
+    opacity?: number;
+    text?: UiTextStyle;
+};
+type UiTokens = Record<string, string>;
+
 /** How a panel orients itself while the experience runs. */
 type UiFollowMode = "world" | "billboard";
 /** Optional initializer for {@link UIPanelComponent}. */
@@ -1586,6 +1750,8 @@ type UIPanelOptions = {
     borderColor?: string;
     pixelDensity?: number;
     follow?: UiFollowMode;
+    style?: UiStyle;
+    tokens?: UiTokens;
 };
 /**
  * A flat UI surface in the world — the backdrop menus and HUDs are built on.
@@ -1617,6 +1783,13 @@ declare class UIPanelComponent extends Component {
     /** Texture density in px/metre, clamped 256–2048 at render time. */
     pixelDensity: number;
     follow: UiFollowMode;
+    /** Modern styling; wins over the flat fields above. Absent until authored. */
+    style?: UiStyle;
+    /**
+     * Named values widgets under this panel use as `$name`. The nearest panel
+     * wins, so a theme travels with the panel and one edit restyles the menu.
+     */
+    tokens?: UiTokens;
     constructor(options?: UIPanelOptions);
 }
 
@@ -1634,6 +1807,8 @@ type UITextOptions = {
     valign?: UiTextVAlign;
     lineHeight?: number;
     padding?: number;
+    pixelDensity?: number;
+    style?: UiStyle;
 };
 /**
  * A block of text drawn onto a transparent canvas quad.
@@ -1662,9 +1837,18 @@ declare class UITextComponent extends Component {
     lineHeight: number;
     /** Inner padding in metres. */
     padding: number;
+    /**
+     * Texture density in px/metre, clamped 256–2048 at render time. Absent means
+     * the default: a defaulted field would count as a change on every instance
+     * of a prefab saved before it existed.
+     */
+    pixelDensity?: number;
+    /** Modern styling; wins over the flat fields above. Absent until authored. */
+    style?: UiStyle;
     constructor(options?: UITextOptions);
 }
 
+type UiIconPosition = "left" | "right";
 /** Optional initializer for {@link UIButtonComponent}. */
 type UIButtonOptions = {
     label?: string;
@@ -1679,6 +1863,10 @@ type UIButtonOptions = {
     cornerRadius?: number;
     borderWidth?: number;
     borderColor?: string;
+    pixelDensity?: number;
+    style?: UiStyle;
+    icon?: string;
+    iconPosition?: UiIconPosition;
 };
 /**
  * A pressable control.
@@ -1709,9 +1897,21 @@ declare class UIButtonComponent extends Component {
     cornerRadius: number;
     borderWidth: number;
     borderColor: string;
+    /**
+     * Texture density in px/metre, clamped 256–2048 at render time. Absent means
+     * the default: a defaulted field would count as a change on every instance
+     * of a prefab saved before it existed.
+     */
+    pixelDensity?: number;
+    /** Modern styling; wins over the flat fields above. Absent until authored. */
+    style?: UiStyle;
+    /** An image or SVG file drawn beside the label, tinted to the text colour. */
+    icon?: string;
+    iconPosition?: UiIconPosition;
     constructor(options?: UIButtonOptions);
 }
 
+type UiToggleVariant = "switch" | "checkbox" | "radio";
 /** Optional initializer for {@link UIToggleComponent}. */
 type UIToggleOptions = {
     value?: boolean;
@@ -1721,6 +1921,9 @@ type UIToggleOptions = {
     trackColor?: string;
     accentColor?: string;
     knobColor?: string;
+    pixelDensity?: number;
+    style?: UiStyle;
+    variant?: UiToggleVariant;
 };
 /**
  * An on/off switch.
@@ -1745,9 +1948,20 @@ declare class UIToggleComponent extends Component {
     /** Track colour while ON. */
     accentColor: string;
     knobColor: string;
+    /**
+     * Texture density in px/metre, clamped 256–2048 at render time. Absent means
+     * the default: a defaulted field would count as a change on every instance
+     * of a prefab saved before it existed.
+     */
+    pixelDensity?: number;
+    /** Modern styling; wins over the flat fields above. Absent until authored. */
+    style?: UiStyle;
+    /** How the control is drawn. Absent means `switch`. */
+    variant?: UiToggleVariant;
     constructor(options?: UIToggleOptions);
 }
 
+type UiSliderVariant = "slider" | "progress" | "ring";
 /** Optional initializer for {@link UISliderComponent}. */
 type UISliderOptions = {
     value?: number;
@@ -1759,6 +1973,11 @@ type UISliderOptions = {
     trackColor?: string;
     accentColor?: string;
     knobColor?: string;
+    pixelDensity?: number;
+    style?: UiStyle;
+    variant?: UiSliderVariant;
+    step?: number;
+    readOnly?: boolean;
 };
 /**
  * A draggable value control.
@@ -1786,6 +2005,20 @@ declare class UISliderComponent extends Component {
     /** Fill colour between min and the current value. */
     accentColor: string;
     knobColor: string;
+    /**
+     * Texture density in px/metre, clamped 256–2048 at render time. Absent means
+     * the default: a defaulted field would count as a change on every instance
+     * of a prefab saved before it existed.
+     */
+    pixelDensity?: number;
+    /** Modern styling; wins over the flat fields above. Absent until authored. */
+    style?: UiStyle;
+    /** How the value is drawn. `progress` and `ring` are read-only. */
+    variant?: UiSliderVariant;
+    /** Snap to multiples of this, measured from `min`. */
+    step?: number;
+    /** Shows the value but takes no input. */
+    readOnly?: boolean;
     constructor(options?: UISliderOptions);
 }
 
@@ -1953,4 +2186,4 @@ declare class XRHandPoseComponent extends Component {
     constructor(options?: XRHandPoseOptions);
 }
 
-export { Selectable as $, AnimationComponent as A, type MaterialValueState as B, CameraComponent as C, DEFAULT_COLLIDER_STATE as D, type EditableMeshObjectKind as E, MeshComponent as F, MeshGeometryComponent as G, type MeshGeometryParameters as H, ImageComponent as I, type MeshGeometryParametersByKind as J, ModelComponent as K, LightComponent as L, MaterialComponent as M, Name as N, Object3DRef as O, PhysicsComponent as P, type PhysicsState as Q, type PlaneMeshParameters as R, type RadiusHeightMeshParameters as S, type RadiusMeshParameters as T, type RigidbodyState as U, type RigidbodyType as V, ScriptComponent as W, type ScriptEntry as X, ScriptObjectComponent as Y, type ScriptObjectComponentInput as Z, type ScriptObjectRuntimeState as _, type AnimationComponentOptions as a, SelectionTransformState as a0, SpriteComponent as a1, type TextureFilteringValue as a2, type TransformModeValue as a3, type TransformSpaceValue as a4, UIButtonComponent as a5, type UIButtonOptions as a6, UIPanelComponent as a7, type UIPanelOptions as a8, UISliderComponent as a9, type XrGrabGesture as aA, type XrGrabHands as aB, type XrGrabReach as aC, type XrHandPoseEntry as aD, type XrHandPreset as aE, type XrInteractorSide as aF, type XrInteractorType as aG, type XrLocomotionMode as aH, type XrTrackingOrigin as aI, type XrTwoHandRotation as aJ, createAttachPoint as aK, createHandPoseEntry as aL, defaultMaterialValue as aM, handPoseDefinitionFor as aN, normalizePhysicsState as aO, setPhysicsLiveRef as aP, type AnimationStateCallbacks as aQ, AnimationStateMachine as aR, AnimationStateManager as aS, type StateMachine as aT, type UISliderOptions as aa, UITextComponent as ab, type UITextOptions as ac, UIToggleComponent as ad, type UIToggleOptions as ae, type UiFollowMode as af, type UiTextAlign as ag, type UiTextVAlign as ah, VRTeleportAreaComponent as ai, type VRTeleportAreaOptions as aj, VideoComponent as ak, type VrTeleportShape as al, XRAnchorComponent as am, type XRAnchorOptions as an, XRHandPoseComponent as ao, type XRHandPoseOptions as ap, XRInteractableComponent as aq, type XRInteractableOptions as ar, XRInteractorComponent as as, type XRInteractorOptions as at, XRInteractorSideComponent as au, XRRigComponent as av, type XRRigOptions as aw, type XrAttachPoint as ax, type XrDistanceGrabBehavior as ay, type XrEnvironmentPhysics as az, AudioComponent as b, type CameraComponentOptions as c, type CameraProjection as d, type CameraRuntimeType as e, type ColliderShape as f, type ColliderState as g, type CubeMeshParameters as h, DEFAULT_INSTANCED_MESH_PARAMETERS as i, DEFAULT_INSTANCE_TRANSFORM as j, DEFAULT_MESH_GEOMETRY_PARAMETERS as k, DEFAULT_PHYSICS_STATE as l, DEFAULT_POSE_CURLS as m, DEFAULT_POSE_DIRECTIONS as n, DEFAULT_RIGIDBODY_STATE as o, EntityType as p, ImageTarget as q, ImageTargetAnchor as r, type ImageTargetAnchorOptions as s, type ImageTargetReference as t, InstanceSlotComponent as u, type InstanceTransform as v, InstancedMeshComponent as w, type InstancedMeshKind as x, type LightValueState as y, type MaterialTypeValue as z };
+export { ScriptComponent as $, AnimationComponent as A, BoneAttachmentComponent as B, CameraComponent as C, DEFAULT_COLLIDER_STATE as D, type EditableMeshObjectKind as E, type LightValueState as F, MaterialComponent as G, type MaterialTypeValue as H, ImageComponent as I, type MaterialValueState as J, MeshComponent as K, LightComponent as L, MODEL_NO_PATH_MESSAGE as M, MeshGeometryComponent as N, type MeshGeometryParameters as O, type MeshGeometryParametersByKind as P, ModelComponent as Q, type ModelLoadState as R, Name as S, Object3DRef as T, PhysicsComponent as U, type PhysicsState as V, type PlaneMeshParameters as W, type RadiusHeightMeshParameters as X, type RadiusMeshParameters as Y, type RigidbodyState as Z, type RigidbodyType as _, type AnimationComponentOptions as a, AnimationStateManager as a$, type ScriptEntry as a0, ScriptObjectComponent as a1, type ScriptObjectComponentInput as a2, type ScriptObjectRuntimeState as a3, Selectable as a4, SelectionTransformState as a5, SpriteComponent as a6, type TextureFilteringValue as a7, type TransformModeValue as a8, type TransformSpaceValue as a9, XRInteractorComponent as aA, type XRInteractorOptions as aB, XRInteractorSideComponent as aC, XRRigComponent as aD, type XRRigOptions as aE, type XrAttachPoint as aF, type XrDistanceGrabBehavior as aG, type XrEnvironmentPhysics as aH, type XrGrabGesture as aI, type XrGrabHands as aJ, type XrGrabReach as aK, type XrHandPoseEntry as aL, type XrHandPreset as aM, type XrInteractorSide as aN, type XrInteractorType as aO, type XrLocomotionMode as aP, type XrTrackingOrigin as aQ, type XrTwoHandRotation as aR, createAttachPoint as aS, createHandPoseEntry as aT, defaultMaterialValue as aU, handPoseDefinitionFor as aV, normalizePhysicsState as aW, setModelLoadState as aX, setPhysicsLiveRef as aY, type AnimationStateCallbacks as aZ, AnimationStateMachine as a_, UIButtonComponent as aa, type UIButtonOptions as ab, UIPanelComponent as ac, type UIPanelOptions as ad, UISliderComponent as ae, type UISliderOptions as af, UITextComponent as ag, type UITextOptions as ah, UIToggleComponent as ai, type UIToggleOptions as aj, type UiFollowMode as ak, type UiIconPosition as al, type UiSliderVariant as am, type UiTextAlign as an, type UiTextVAlign as ao, type UiToggleVariant as ap, VRTeleportAreaComponent as aq, type VRTeleportAreaOptions as ar, VideoComponent as as, type VrTeleportShape as at, XRAnchorComponent as au, type XRAnchorOptions as av, XRHandPoseComponent as aw, type XRHandPoseOptions as ax, XRInteractableComponent as ay, type XRInteractableOptions as az, AudioComponent as b, type StateMachine as b0, type UiColorStop as b1, type UiPaint as b2, type UiShadow as b3, type UiStyle as b4, type UiTextStyle as b5, type UiTokens as b6, type BoneAttachmentOptions as c, type CameraComponentOptions as d, type CameraProjection as e, type CameraRuntimeType as f, type ColliderShape as g, type ColliderState as h, type CubeMeshParameters as i, DEFAULT_INSTANCED_MESH_PARAMETERS as j, DEFAULT_INSTANCE_TRANSFORM as k, DEFAULT_MESH_GEOMETRY_PARAMETERS as l, DEFAULT_PHYSICS_STATE as m, DEFAULT_POSE_CURLS as n, DEFAULT_POSE_DIRECTIONS as o, DEFAULT_RIGIDBODY_STATE as p, EntityType as q, ImageTarget as r, ImageTargetAnchor as s, type ImageTargetAnchorOptions as t, type ImageTargetReference as u, InstanceSlotComponent as v, type InstanceTransform as w, InstancedMeshComponent as x, type InstancedMeshKind as y, type LightShadowState as z };