@relu-interactives/spatial-ecs 0.5.2 → 0.8.0

package/dist/{System-V_mv07le.d.cts → System-8D-XBDKZ.d.cts}

@@ -1,6 +1,8 @@
 import * as THREE from 'three';
 import { Vector3, Euler, EulerOrder, Quaternion } from 'three';
 import * as RAPIER from '@dimforge/rapier3d-compat';
+import { HumanoidBone } from './animation/index.cjs';
+import { WebGPURenderer } from 'three/webgpu';
 
 /**
  * Marker base class for every ECS component. Subclass `Component` to declare
@@ -16,20 +18,150 @@ import * as RAPIER from '@dimforge/rapier3d-compat';
 declare class Component {
 }
 
+/** A value a networked prop can hold: anything that survives JSON. */
+type NetValue = string | number | boolean | null | NetValue[] | {
+    [key: string]: NetValue;
+};
+/**
+ * Marks an entity as shared between players. A scene object is simulated by
+ * the host (the first player in the room, then the longest connected); a
+ * spawned object belongs to the player who spawned it and leaves with them.
+ *
+ * @category Components
+ */
+declare class NetworkIdentityComponent extends Component {
+    /** The id every client knows this entity by. Set when connected, never saved. */
+    networkId: string;
+    /** The session that simulates this entity. Set when connected, never saved. */
+    owner: string;
+    constructor();
+}
+type NetworkTransformOptions = Partial<Pick<NetworkTransformComponent, "enabled" | "sendRate" | "interpolationMs" | "syncRotation" | "teleportDistance">>;
+/**
+ * Shares an entity's position and rotation. The owner moves it at once and
+ * sends updates; everyone else plays them back a little in the past, so
+ * movement is smooth however the packets arrive.
+ *
+ * @category Components
+ */
+declare class NetworkTransformComponent extends Component {
+    enabled: boolean;
+    /** Updates per second the owner sends. */
+    sendRate: number;
+    /** How far in the past others see it, in ms. More is smoother; less is more current. */
+    interpolationMs: number;
+    syncRotation: boolean;
+    /** A jump longer than this (m) snaps instead of sliding, for respawns and teleports. */
+    teleportDistance: number;
+    constructor(options?: NetworkTransformOptions);
+}
+/**
+ * Named values shared with everyone: a health bar, a score. Only the entity's
+ * owner can change them, with `this.network.setProp()`. `values` holds the
+ * starting values, and a Behaviour hears changes in `onNetworkProp`.
+ *
+ * @category Components
+ */
+declare class NetworkedPropsComponent extends Component {
+    values: Record<string, NetValue>;
+    constructor(values?: Record<string, NetValue>);
+}
+/**
+ * Gives each player an avatar: when a client connects it spawns `playerPrefab`
+ * as its own, placed around this entity.
+ *
+ * @category Components
+ */
+declare class NetworkSpawnerComponent extends Component {
+    /** The `.prefab` each player gets. */
+    playerPrefab: string;
+    /** How far from this entity players appear, in metres. */
+    spawnRadius: number;
+    constructor(playerPrefab?: string, spawnRadius?: number);
+}
+
+/** One recording of a slot. `file` is an asset path; `volume` multiplies the slot's. */
+interface SoundTake {
+    file: string;
+    volume?: number;
+}
+/** The mixer's groups. Music dips while a voice plays. */
+type AudioBus = "sfx" | "voice" | "music";
+/**
+ * A named sound the game asks for ("hit", "footstep"), played as a random take.
+ *
+ * | Field | Default | Description |
+ * |---|---|---|
+ * | `takes` | | The recordings to choose between. |
+ * | `bus` | `"sfx"` | Which volume group it plays through. |
+ * | `chance` | `1` | Probability it plays at all when asked, `0` to `1`. |
+ * | `cooldownMs` | `0` | Asks within this long of the last play are ignored. |
+ * | `volume` | `1` | Linear gain. |
+ * | `priority` | `0` | On the voice bus: lower priorities wait, higher ones cut in. |
+ */
+interface SoundSlot {
+    takes: SoundTake[];
+    bus?: AudioBus;
+    chance?: number;
+    cooldownMs?: number;
+    volume?: number;
+    priority?: number;
+}
+/** The contents of a `.soundbank.json` asset. */
+interface SoundBankAsset {
+    version: 1;
+    slots: Record<string, SoundSlot>;
+}
+/** Every recording a bank needs. */
+declare function soundBankFiles(bank: SoundBankAsset): string[];
+/**
+ * Decides whether a slot sounds and which take: chance, cooldown, and never the
+ * same take twice running when there's another. No audio here, so it's testable.
+ */
+declare class SlotChooser {
+    private readonly random;
+    private readonly lastPlay;
+    private readonly lastTake;
+    constructor(random?: () => number);
+    /** The take to play now, or `null` to stay silent. `now` is in milliseconds. */
+    choose(id: string, slot: SoundSlot, now: number): SoundTake | null;
+}
+
 /** Skybox rendering modes. `none` disables skybox rendering entirely. */
 type EnvironmentSkyboxType = "gradient" | "color" | "image" | "none";
 /** Gradient distribution applied when {@link EnvironmentSkyboxState.type} is `"gradient"`. */
 type EnvironmentGradientEffect = "radial" | "linear" | "angular";
 /** Fog distance models. `none` disables fog. */
 type EnvironmentFogType = "linear" | "exponential" | "none";
+/**
+ * How an `"image"` skybox is projected.
+ *
+ * - `"screen"` (the behaviour when the field is absent): the image is drawn as
+ *   a flat backdrop stretched over the viewport. It does not rotate with the
+ *   camera.
+ * - `"equirect"`: the image is an equirectangular panorama wrapped around the
+ *   scene, so it turns with the camera like a real sky. `.hdr` and `.exr`
+ *   files load in this mode.
+ */
+type EnvironmentSkyboxImageProjection = "screen" | "equirect";
+/**
+ * Tone-mapping operator applied by the renderer. `"none"` leaves colours
+ * linear-clamped (three's `NoToneMapping`).
+ */
+type EnvironmentToneMapping = "none" | "aces" | "agx" | "neutral";
 /** Skybox configuration. Only the fields relevant to {@link type} are read at render time. */
 type EnvironmentSkyboxState = {
     /** Active skybox mode. */
     type: EnvironmentSkyboxType;
     /** Solid color used when {@link type} is `"color"`. `#rrggbb`. */
     color: string;
-    /** URL or `localasset://` path of the equirectangular image used when {@link type} is `"image"`. */
+    /** URL or `localasset://` path of the image used when {@link type} is `"image"`. */
     imageUrl?: string;
+    /**
+     * Projection for an `"image"` skybox. Absent means `"screen"` (a flat
+     * backdrop, the original behaviour). Set `"equirect"` for a 360° panorama.
+     */
+    imageProjection?: EnvironmentSkyboxImageProjection;
     /** Gradient parameters used when {@link type} is `"gradient"`. */
     gradient: {
         /** Ordered list of color stops as `#rrggbb` strings. */
@@ -66,6 +198,37 @@ type EnvironmentGravityState = {
     /** Gravity along world Z. */
     z: number;
 };
+/**
+ * Image-based lighting and renderer colour settings. Every field is optional;
+ * the defaults below apply when a field is missing. When the whole block is
+ * absent the scene's environment map and the renderer's tone mapping are left
+ * untouched.
+ */
+type EnvironmentLightingState = {
+    /**
+     * URL or `localasset://` path of an equirectangular environment map used
+     * for image-based lighting (reflections and ambient light on PBR
+     * materials). `.hdr` and `.exr` load as HDR; any other extension loads as an
+     * sRGB image. Empty = no environment map.
+     */
+    envMapUrl?: string;
+    /** Strength of the environment lighting (`scene.environmentIntensity`). Default `1`. */
+    envIntensity?: number;
+    /** Rotation of the environment map around world Y, in radians. Default `0`. */
+    envRotationY?: number;
+    /** Also show the environment map as the background. Overrides the skybox. Default `false`. */
+    useAsBackground?: boolean;
+    /** Background blur in `[0, 1]` when {@link useAsBackground} is on. Default `0`. */
+    backgroundBlurriness?: number;
+    /** Background brightness multiplier when {@link useAsBackground} is on. Default `1`. */
+    backgroundIntensity?: number;
+    /** Renderer tone-mapping operator. Default `"none"`. */
+    toneMapping?: EnvironmentToneMapping;
+    /** Renderer exposure (`toneMappingExposure`). Only has an effect when tone mapping is on. Default `1`. */
+    exposure?: number;
+};
+/** Defaults for every {@link EnvironmentLightingState} field. */
+declare const DEFAULT_ENVIRONMENT_LIGHTING: Required<EnvironmentLightingState>;
 /** Aggregated authoring state owned by {@link Environment}. */
 type EnvironmentState = {
     /** Skybox configuration. */
@@ -80,11 +243,24 @@ type EnvironmentState = {
      * Default is `0.02` (50 Hz).
      */
     fixedTimeStep: number;
+    /**
+     * Image-based lighting, tone mapping and exposure. Optional: absent means
+     * the scene's environment map and the renderer's tone mapping stay
+     * untouched, which is how every scene saved before 0.5.4 renders.
+     */
+    lighting?: EnvironmentLightingState;
 };
 declare const DEFAULT_ENVIRONMENT_STATE: EnvironmentState;
+/**
+ * Normalize a lighting block to a complete {@link EnvironmentLightingState}.
+ * Returns `undefined` when `value` is not an object, so a scene without the
+ * block stays without it.
+ */
+declare function normalizeEnvironmentLighting(value: unknown): Required<EnvironmentLightingState> | undefined;
 /**
  * Scene environment settings: skybox (gradient/color/image), fog
- * (linear/exponential), and gravity vector for the physics world.
+ * (linear/exponential), gravity vector for the physics world, and optional
+ * image-based lighting / tone mapping (`values.lighting`).
  * Singleton-style — attached to one environment entity per scene.
  *
  * Use `world.getEnvironmentComponent()` to access this component directly
@@ -94,7 +270,7 @@ declare const DEFAULT_ENVIRONMENT_STATE: EnvironmentState;
  * @category Components
  */
 declare class Environment extends Component {
-    /** Aggregated environment authoring state (skybox, fog, gravity). Saved with the project. */
+    /** Aggregated environment authoring state (skybox, fog, gravity, lighting). Saved with the project. */
     values: EnvironmentState;
     constructor(values?: Partial<EnvironmentState>);
 }
@@ -323,6 +499,55 @@ declare class TransformComponent extends Component {
     setRotation(input: TransformInput, order?: EulerOrder): this;
 }
 
+/** The limb a chain moves: its end bone, by humanoid name. */
+type IKLimb = "leftHand" | "rightHand" | "leftFoot" | "rightFoot";
+/** One limb reaching for an entity. */
+type IKChain = {
+    /** The hand or foot that reaches. */
+    limb: IKLimb;
+    /** Entity whose world position the hand/foot reaches (a weapon's grip, a door handle, a step). */
+    target: EntityId | null;
+    /** Entity the elbow/knee bends toward; `null` keeps the animation's own bend. */
+    pole: EntityId | null;
+    /** 0 = the animation, 1 = the target; in between blends. */
+    weight: number;
+    /** Also turn the hand/foot to the target's rotation. */
+    matchRotation: boolean;
+    /** Whether this chain runs. */
+    enabled: boolean;
+};
+/** Optional initializer for {@link IKComponent}. */
+type IKOptions = {
+    chains?: Array<Partial<IKChain> & {
+        limb: IKLimb;
+    }>;
+    enabled?: boolean;
+};
+/** A chain with every field filled in. */
+declare function normalizeIKChain(chain: Partial<IKChain> & {
+    limb: IKLimb;
+}): IKChain;
+/**
+ * Inverse kinematics for a humanoid model: after the animation plays, each
+ * chain bends an arm or leg so its hand/foot reaches a target entity — the
+ * second hand on a rifle's grip, a hand on a door handle, a foot on a step.
+ * The elbow/knee keeps the animation's bend unless a pole entity says
+ * otherwise. Bones are found by humanoid name, so any rig the editor
+ * recognises works (Mixamo, auto-rigs, Unreal, VRM).
+ *
+ * The `IKSystem` runs it right after the `AnimationSystem`; objects attached
+ * to the moved bones follow.
+ *
+ * @category Components
+ */
+declare class IKComponent extends Component {
+    /** The limbs that reach. */
+    chains: IKChain[];
+    /** Turn every chain off at once. */
+    enabled: boolean;
+    constructor(options?: IKOptions);
+}
+
 /**
  * Numeric identifier for an entity. Entities are pure ids — all data lives in
  * components attached to the entity.
@@ -445,6 +670,99 @@ type IntersectionResult = {
     threeResult: THREE.Intersection;
 };
 
+/** One shared entity, as the room holds it. */
+type NetEntityView = {
+    id: string;
+    owner: string;
+    /** The prefab to spawn; empty for a scene object. */
+    prefab: string;
+    x: number;
+    y: number;
+    z: number;
+    qx: number;
+    qy: number;
+    qz: number;
+    qw: number;
+    /** JSON-encoded prop values. */
+    props: Record<string, string>;
+};
+type NetPose = Pick<NetEntityView, "x" | "y" | "z" | "qx" | "qy" | "qz" | "qw">;
+/** What a shared-world connection must do. `ColyseusTransport` is the real one. */
+interface NetworkTransport {
+    readonly sessionId: string;
+    /** The session that simulates scene objects. */
+    readonly host: string;
+    readonly players: string[];
+    onEntityAdd(cb: (entity: NetEntityView) => void): void;
+    onEntityChange(cb: (entity: NetEntityView) => void): void;
+    onEntityRemove(cb: (id: string) => void): void;
+    onPlayerJoin(cb: (id: string) => void): void;
+    onPlayerLeave(cb: (id: string) => void): void;
+    /** A message from the server or another player. */
+    onMessage(cb: (name: string, payload: unknown, from: string) => void): void;
+    /** The server overruled the owner's pose. */
+    onCorrect(cb: (id: string, pose: NetPose) => void): void;
+    onClose(cb: () => void): void;
+    /** Tell the room about the scene's shared objects; the first client's copy wins. */
+    registerScene(entities: (NetPose & {
+        id: string;
+        props: Record<string, string>;
+    })[]): void;
+    spawn(request: NetPose & {
+        prefab: string;
+        props: Record<string, string>;
+    }): void;
+    despawn(id: string): void;
+    sendPose(id: string, pose: NetPose): void;
+    setProp(id: string, key: string, json: string): void;
+    send(name: string, payload: unknown): void;
+    leave(): void;
+}
+/** Options for {@link NetworkHandle.spawn}. */
+type NetSpawnOptions = {
+    position?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Euler XYZ in radians. */
+    rotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    props?: Record<string, NetValue>;
+};
+/** A Behaviour's view of the shared world: `this.network`, `null` in a single-player run. */
+interface NetworkHandle {
+    readonly connected: boolean;
+    /** This client's id in the room. */
+    readonly sessionId: string;
+    /** Whether this client simulates the scene's shared objects. */
+    readonly isHost: boolean;
+    /** Whether this client simulates this entity. */
+    readonly isOwner: boolean;
+    /** Everyone in the room, by session id. */
+    readonly players: string[];
+    /** Send to the room. Others hear it in `onMessage`, unless a server hook keeps it. */
+    send(name: string, payload?: unknown): void;
+    /** Listen for a message. Returns the way to stop. */
+    onMessage(name: string, handler: (payload: unknown, from: string) => void): () => void;
+    /** Spawn a prefab everyone sees, owned by this client. */
+    spawn(prefab: string | {
+        path: string;
+    }, options?: NetSpawnOptions): void;
+    /** Remove a shared entity this client owns (this one by default). */
+    despawn(entityId?: EntityId): void;
+    /** Change a shared value on this entity. Only its owner can. */
+    setProp(key: string, value: NetValue): void;
+    getProp(key: string): NetValue | undefined;
+}
+/** What `world.getNetwork()` returns. Set by `NetworkSystem` once connected. */
+interface NetworkService {
+    handleFor(entityId: EntityId): NetworkHandle;
+}
+
 type ComponentClass<T extends Component> = new (...args: never[]) => T;
 type AnyComponent = Component;
 type WorldHistorySnapshot = {
@@ -468,6 +786,53 @@ type NormalizeContext = {
 declare function normalizeDebugValue(value: unknown, ctx: NormalizeContext): unknown;
 declare function cloneHistoryValue<T>(value: T, seen?: WeakMap<object, unknown>): T;
 
+/**
+ * Where in a script's life an error happened.
+ *
+ * - `"load"`: fetching/importing the module, or the named class is missing.
+ * - `"init"`: the constructor or a Behaviour's `init()` threw.
+ * - `"build"`: a ScriptObject's `build()` threw or did not return an Object3D.
+ * - `"update"`: a per-frame `update()` / `onUpdate()` threw.
+ * - Any other string is the name of the Behaviour hook that threw, e.g.
+ *   `"onSelect"`, `"onUiPress"`, `"onGrab"`, `"onXRSessionStart"`.
+ */
+type ScriptErrorPhase = "load" | "init" | "build" | "update" | (string & {});
+/** Which kind of script failed. */
+type ScriptErrorSource = "behaviour" | "scriptObject";
+/**
+ * Emitted by `world.onScriptError(...)` the first time a distinct script error
+ * occurs. "Distinct" is the combination of script URL, class name, phase and
+ * message: ten enemies running the same broken script report once.
+ */
+type ScriptErrorEvent = {
+    /** Entity the failing script is attached to. */
+    entityId: number;
+    /** That entity's name (`Name` component), or `"Entity <id>"`. */
+    entityName: string;
+    /** URL of the script module. Empty when unknown. */
+    scriptUrl: string;
+    /** Script class name. */
+    className: string;
+    /** Lifecycle phase or hook name. See {@link ScriptErrorPhase}. */
+    phase: ScriptErrorPhase;
+    /** Short error message, with local file paths removed. */
+    message: string;
+    /** Stack trace when the error carried one, with local file paths removed. */
+    stack?: string;
+    /** Behaviour or ScriptObject. */
+    source: ScriptErrorSource;
+};
+/** Listener registered with `world.onScriptError(...)`. */
+type ScriptErrorListener = (event: ScriptErrorEvent) => void;
+/** What a system knows when it reports a script error. */
+type ScriptErrorReport = {
+    entityId: number;
+    scriptUrl: string;
+    className: string;
+    phase: ScriptErrorPhase;
+    source: ScriptErrorSource;
+};
+
 /**
  * Snapshot-space entity-id walking/remapping.
  *
@@ -479,6 +844,7 @@ declare function cloneHistoryValue<T>(value: T, seen?: WeakMap<object, unknown>)
  *   - `ScriptObjectComponent.data` EntityInput/ComponentInput (same shapes)
  *   - `InstancedMeshComponent.instanceEntityIds[]`
  *   - `InstanceSlotComponent.groupEntityId`
+ *   - `IKComponent.chains[].target` / `.pole`
  *
  * Any new id-bearing component field must be added here — serialization,
  * instantiation and the override differ all route through this walker.
@@ -595,6 +961,29 @@ declare function spawnPrefab(world: World, source: SpawnPrefabSource, options?:
  */
 declare function despawnPrefab(world: World, rootId: EntityId, dispose?: boolean): number;
 
+/** A bone of a loaded model, for bone pickers and attachment. */
+type ModelBoneInfo = {
+    /** Node name as three.js has it (glTF names are sanitized: `mixamorig:Hips` → `mixamorigHips`). */
+    name: string;
+    /** Humanoid name when the rig is a recognisable humanoid, else `null`. */
+    humanoid: HumanoidBone | null;
+    /** Parent bone's name, or `null` for a root bone. */
+    parent: string | null;
+    /** Depth below the topmost bone (for indenting a tree). */
+    depth: number;
+};
+/** Every bone of a loaded model, parents before children. */
+declare function listModelBones(root: THREE.Object3D): ModelBoneInfo[];
+/**
+ * The bone an attachment names in `root`: by node name, then by its
+ * sanitized form (a name saved from a source file), then by humanoid name
+ * (the same body part on another rig). `null` when none matches.
+ */
+declare function findModelBone(root: THREE.Object3D, ref: {
+    bone?: string | null;
+    humanoid?: string | null;
+}): THREE.Object3D | null;
+
 type CreatePayload = {
     name?: string;
     transform?: TransformData;
@@ -619,7 +1008,7 @@ type CreateContext = {
     isEditor?: boolean;
 };
 type EntityFactory = (context: CreateContext) => EntityId;
-type EcsComponentFactoryKind = "animation" | "audio" | "camera" | "environment" | "entityType" | "image" | "imageTargetAnchor" | "imageTarget" | "light" | "material" | "mesh" | "meshGeometry" | "model" | "name" | "object3DRef" | "parentId" | "physics" | "postprocessing" | "script" | "scriptObject" | "selectable" | "selectionTransformState" | "sprite" | "transform" | "video" | "instancedMesh" | "xrRig" | "vrTeleportArea" | "xrHandPose" | "xrAnchor" | "uiPanel" | "uiText" | "uiButton" | "uiToggle" | "uiSlider" | "xrInteractable" | "xrInteractor" | "xrInteractorSide";
+type EcsComponentFactoryKind = "animation" | "audio" | "camera" | "environment" | "entityType" | "image" | "imageTargetAnchor" | "imageTarget" | "light" | "material" | "mesh" | "meshGeometry" | "model" | "name" | "object3DRef" | "parentId" | "physics" | "postprocessing" | "script" | "scriptObject" | "selectable" | "selectionTransformState" | "sprite" | "transform" | "video" | "instancedMesh" | "xrRig" | "vrTeleportArea" | "xrHandPose" | "xrAnchor" | "boneAttachment" | "ik" | "networkIdentity" | "networkTransform" | "networkedProps" | "networkSpawner" | "uiPanel" | "uiText" | "uiButton" | "uiToggle" | "uiSlider" | "xrInteractable" | "xrInteractor" | "xrInteractorSide";
 type ComponentFactory = (world: World, entityId: EntityId, ...args: any[]) => unknown;
 declare class ObjectManagementSystem implements EcsSystem {
     private readonly scene;
@@ -628,6 +1017,9 @@ declare class ObjectManagementSystem implements EcsSystem {
     private readonly registry;
     private readonly componentRegistry;
     private readonly createQueue;
+    private readonly boneSockets;
+    /** Attachments whose bone wasn't found in a given model (skip re-searching every frame). */
+    private readonly boneMisses;
     constructor(scene: THREE.Scene, camera: THREE.PerspectiveCamera, isEditor?: boolean);
     register(kind: EcsEntityKind, factory: EntityFactory): void;
     registerComponentFactory(kind: EcsComponentFactoryKind, factory: ComponentFactory): void;
@@ -665,9 +1057,144 @@ declare class ObjectManagementSystem implements EcsSystem {
     }): boolean;
     private syncTransformComponentFromObject;
     reconcileSceneFromWorld(world: World): void;
+    private dropBoneSocket;
+    /**
+     * The socket an attached entity hangs under, or `null` (not attached, the
+     * parent's model not loaded yet, or no such bone — the entity then sits
+     * under its parent as an ordinary child).
+     */
+    private resolveBoneSocket;
+    /**
+     * Cancel the rig's own scale between the character and the bone (a
+     * centimetre armature under a 0.01 node), so offsets are in the character's
+     * units and the object keeps its size; the character entity's own scale
+     * still applies, as it does to any child.
+     */
+    private fitSocketScale;
+    /**
+     * Load a model entity's file again and swap it in (the file was rewritten);
+     * the entity, its components and children stay, attachments re-home.
+     */
+    reloadModel(world: World, entityId: EntityId): boolean;
+    /** Reload every model entity whose path `matches` (returns how many). */
+    reloadModelsAt(world: World, matches: (path: string) => boolean): number;
+    /** The bones of an entity's loaded model (empty until it loads, or for a model without a skeleton). */
+    listModelBones(world: World, entityId: EntityId): ModelBoneInfo[];
+    /** The socket object an attached entity currently hangs under, if resolved. */
+    getBoneSocket(entityId: EntityId): THREE.Object3D | null;
+    /**
+     * Fix `entityId` to a bone of `parentEntityId`'s model (making it the
+     * parent if it isn't). With `preserveWorldTransform` (default) it stays
+     * where it is and its Transform becomes the offset from the bone; without,
+     * it snaps onto the bone (zero offset). Returns whether the bone was found
+     * (when the model is still loading, the attachment is stored and resolves
+     * once it loads, without preserving the pose).
+     */
+    attachToBone(world: World, entityId: EntityId, parentEntityId: EntityId, ref: {
+        bone?: string;
+        humanoid?: string | null;
+    }, options?: {
+        preserveWorldTransform?: boolean;
+        compensateScale?: boolean;
+    }): {
+        ok: boolean;
+        resolved: boolean;
+        bone: string | null;
+    };
+    /**
+     * Release a bone attachment. The entity stays a child of the character
+     * (or moves to the root with `toRoot`), and by default keeps its place in
+     * the world.
+     */
+    detachFromBone(world: World, entityId: EntityId, options?: {
+        preserveWorldTransform?: boolean;
+        toRoot?: boolean;
+    }): boolean;
     update(world: World): void;
 }
 
+/**
+ * A renderer a {@link World} can run on: three's classic `WebGLRenderer`, or
+ * `WebGPURenderer` from `three/webgpu` (which falls back to WebGL 2 on its own
+ * when the browser has no WebGPU).
+ */
+type EcsRenderer = THREE.WebGLRenderer | WebGPURenderer;
+/** Which renderer family a world is drawing with. */
+type RendererKind = "webgl" | "webgpu";
+/**
+ * A built post-processing chain. `RenderSystem` calls `render()` in place of
+ * `renderer.render()` while it is active.
+ *
+ * `setSize` / `setPixelRatio` are optional: a WebGL `EffectComposer` needs
+ * them, while a WebGPU `RenderPipeline` reads the renderer's size every frame.
+ */
+interface PostprocessingPipeline {
+    render(): void;
+    setSize?(width: number, height: number): void;
+    setPixelRatio?(pixelRatio: number): void;
+    dispose(): void;
+}
+/** Everything a backend needs to build a post-processing chain. */
+interface PostprocessingBuildContext {
+    renderer: EcsRenderer;
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    /** The scene's current `Postprocessing.values` (`postEnabled` is `true`). */
+    values: PostprocessingState;
+    /** The world being rendered, when known (used to scope one-time warnings). */
+    world?: World;
+}
+/** Green-screen settings, in the same units as `VideoComponent.options`. */
+interface ChromaKeyOptions {
+    /** Colour to key out (any three.js colour representation, e.g. `"#00ff00"`). */
+    keyColor: THREE.ColorRepresentation;
+    /** Colour distance below which a pixel is fully transparent. */
+    similarity: number;
+    /** Width of the soft edge above `similarity`. */
+    smoothness: number;
+    /** How far past the edge the key colour is desaturated (spill removal). */
+    spill: number;
+}
+/**
+ * Everything renderer-specific the engine does, behind one small interface so
+ * a {@link World} can run on WebGL or WebGPU.
+ *
+ * The default is `webglBackend` (exported from the package root). For a
+ * `WebGPURenderer`, pass `webgpuBackend` from
+ * `@relu-interactives/spatial-ecs/webgpu`.
+ */
+interface RenderBackend {
+    /** Renderer family this backend drives. */
+    readonly kind: RendererKind;
+    /** One-time renderer setup, called once from the `World` constructor. */
+    install?(world: World): void;
+    /**
+     * Called the first time an area light (`RectAreaLight`) is created, so the
+     * backend can load the lookup tables those lights need. Optional.
+     */
+    prepareAreaLights?(world: World): void;
+    /**
+     * Build the post-processing chain for `context.values`. Return `null` to
+     * render the scene directly (no chain).
+     */
+    createPostprocessing(context: PostprocessingBuildContext): PostprocessingPipeline | null;
+    /**
+     * Apply a values change to an existing chain without rebuilding it. Return
+     * `true` when the chain was updated in place, `false` when the change is
+     * structural (an effect switched on or off) and the caller must rebuild.
+     * When omitted, every change rebuilds.
+     */
+    updatePostprocessing?(pipeline: PostprocessingPipeline, previous: PostprocessingState, next: PostprocessingState): boolean;
+    /** Material that renders `texture` with `options.keyColor` keyed out. */
+    createChromaKeyMaterial(texture: THREE.Texture, options: ChromaKeyOptions): THREE.Material;
+    /**
+     * Push new options into a material made by {@link createChromaKeyMaterial}.
+     * Returns `false` when `material` is not one of this backend's chroma-key
+     * materials.
+     */
+    updateChromaKeyMaterial(material: THREE.Material, options: ChromaKeyOptions): boolean;
+}
+
 declare const KeyboardKeys: {
     readonly A: "a";
     readonly B: "b";
@@ -833,12 +1360,41 @@ declare class InputSystem implements EcsSystem {
     private clearAll;
 }
 
+/**
+ * Draws the frame: through the post-processing chain in
+ * `scene.userData.ecsPostprocessingComposer` while
+ * `scene.userData.ecsPostprocessingComposerActive` is `true`, otherwise with
+ * `renderer.render(scene, camera)`. Runs last in the default system list.
+ *
+ * Works with `WebGLRenderer` and `WebGPURenderer`. A `WebGPURenderer` must be
+ * initialised (`await renderer.init()`) first; until it is, frames are
+ * skipped with a single warning instead of throwing.
+ *
+ * @category Systems
+ */
 declare class RenderSystem implements EcsSystem {
     private readonly renderer;
     private readonly scene;
     private readonly camera;
     private readonly afterRender?;
-    constructor(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera, afterRender?: () => void);
+    /** Composer the last size was pushed to, plus that size. */
+    private sizedComposer;
+    private sizedWidth;
+    private sizedHeight;
+    private sizedPixelRatio;
+    private warnedUninitialized;
+    constructor(renderer: EcsRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera, afterRender?: () => void);
+    /**
+     * `WebGPURenderer.render()` throws until `await renderer.init()` resolved.
+     * Skip those frames (warning once) rather than throwing from the loop.
+     */
+    private isRendererReady;
+    /**
+     * Resize the composer only when the canvas size or pixel ratio changed, or
+     * when the composer itself was rebuilt. `setSize` resizes every render
+     * target in the chain, so calling it every frame wasted GPU work.
+     */
+    private syncComposerSize;
     update(_world: World): void;
 }
 
@@ -846,6 +1402,102 @@ declare class TransformSyncSystem implements EcsSystem {
     update(world: World): void;
 }
 
+/** Options for {@link AudioSystem.playSlot}. */
+type PlaySlotOptions = {
+    /** Multiplies the slot's volume. */
+    volume?: number;
+    /** Play from this point in the world instead of everywhere. */
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/**
+ * 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.
+ *
+ * **Mixing** — every sound plays through a bus (`sfx`, `voice`, `music`) with
+ * its own volume, and music dips while a voice plays.
+ *
+ * **Sound banks** — {@link loadSoundBank} and {@link playSlot} play named
+ * sounds from a `.soundbank.json` asset, as a random take.
+ *
+ * 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;
+    private world;
+    private mixer;
+    private readonly slots;
+    private readonly buffers;
+    private readonly chooser;
+    private voice;
+    constructor({ isEditor }?: {
+        isEditor?: boolean;
+    });
+    /** Scripts can load a bank in `init`, before this system's first update. */
+    attachWorld(world: World): void;
+    /** The mixer, made with the listener on first use. */
+    private getMixer;
+    /** Set a bus's volume (`0` silent, `1` as mixed). */
+    setBusVolume(bus: AudioBus, volume: number): void;
+    getBusVolume(bus: AudioBus): number;
+    /**
+     * Fetch a `.soundbank.json` and decode its recordings. Its slots add to any
+     * loaded before, and a slot id used twice takes the later one.
+     * @param source an asset path, or a script's `AssetInput` field
+     */
+    loadSoundBank(source: string | {
+        path: string;
+    }): Promise<void>;
+    /**
+     * Play a named sound from a loaded bank. Returns whether it sounded: a slot's
+     * chance, cooldown and priority can each keep it quiet, and that's normal.
+     */
+    playSlot(id: string, options?: PlaySlotOptions): 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;
+}
+
+/**
+ * Runs each {@link IKComponent}'s chains after the animation: hands and feet
+ * reach their target entities. Bones the animation doesn't drive would keep
+ * last frame's IK pose and drift, so every bone IK touched is put back to its
+ * pre-IK rotation first unless the animation already overwrote it.
+ *
+ * @category Systems
+ */
+declare class IKSystem implements EcsSystem {
+    private readonly runtimes;
+    private readonly reach;
+    /** How far a limb's end stayed from its target last frame, in metres (0 = reached). */
+    getReachError(entityId: EntityId, limb: IKLimb): number | null;
+    private restore;
+    update(world: World): void;
+    dispose(): void;
+}
+
 type StoreListener = () => void;
 type WorldFeatureFlags = {
     supportSkybox?: boolean;
@@ -864,13 +1516,21 @@ declare class World {
     private systems;
     private selectionListeners;
     private storeListeners;
+    private scriptErrorListeners;
+    /** Keys (`url|class|phase|message`) of script errors already reported. */
+    private reportedScriptErrors;
     private scene;
     private camera;
     private renderer;
+    private readonly rendererKind;
+    private readonly renderBackend;
     private readonly featureFlags;
     private components;
     private inputSystem;
     private objectManagementSystem;
+    private ikSystem;
+    private audioSystem;
+    private network;
     private environmentSyncSystem;
     private postprocessingSyncSystem;
     private rapierModule;
@@ -878,10 +1538,20 @@ declare class World {
     private physicsWorld;
     private isEditor;
     private paused;
+    /**
+     * @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: {
         scene: THREE.Scene;
         camera: THREE.PerspectiveCamera;
-        renderer: THREE.WebGLRenderer;
+        renderer: EcsRenderer;
+        backend?: RenderBackend;
         featureFlags?: WorldFeatureFlags;
     });
     createEntity(): EntityId;
@@ -1013,7 +1683,20 @@ declare class World {
     isPaused(): boolean;
     getScene(): THREE.Scene;
     getCamera(): THREE.PerspectiveCamera;
-    getRenderer(): THREE.WebGLRenderer;
+    /**
+     * 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(): EcsRenderer;
+    /** `"webgpu"` when the world renders with a `WebGPURenderer`, else `"webgl"`. */
+    getRendererKind(): RendererKind;
+    /**
+     * The renderer-specific backend in use (post-processing, green-screen
+     * video, area lights). See `RenderBackend`.
+     */
+    getRenderBackend(): RenderBackend;
     update(deltaTime: number): void;
     dispose(): void;
     setSelectedEntity(entityId: EntityId | null): void;
@@ -1037,6 +1720,14 @@ declare class World {
     spawnPrefab(source: SpawnPrefabSource, options?: SpawnPrefabOptions): Promise<EntityId>;
     /** Remove a spawned prefab instance (root + descendants). */
     despawnPrefab(rootEntityId: EntityId): number;
+    /** The shared-world connection, or `null` in a single-player run. */
+    getNetwork(): NetworkService | null;
+    /** Set by `NetworkSystem` when it connects and clears. */
+    setNetwork(network: NetworkService | null): void;
+    /** The audio system (mixer buses, sound banks), or `null` before `setup`. */
+    getAudioSystem(): AudioSystem | null;
+    /** The IK system (reach errors per limb), or `null` before `setup`. */
+    getIKSystem(): IKSystem | null;
     getObjectManagementSystem(): ObjectManagementSystem;
     /**
      * Returns the singleton {@link Environment} component for the scene, or
@@ -1127,6 +1818,41 @@ declare class World {
     getAllEntities(): WorldEntityView[];
     onSelectionChanged(listener: SelectionListener): () => void;
     subscribe(listener: StoreListener): () => void;
+    /**
+     * 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: ScriptErrorListener): () => void;
+    /**
+     * 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: ScriptErrorReport, error: unknown): boolean;
+    /**
+     * 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?: string): void;
     getDebugSnapshot(maxDepth?: number): unknown;
     getDebugSignature(maxDepth?: number): string;
     /**
@@ -1154,4 +1880,4 @@ interface EcsSystem {
     dispose?(world: World): void;
 }
 
-export { type ToggleInput as $, type AssetInput as A, type EcsComponentFactoryKind as B, Component as C, DEFAULT_ENVIRONMENT_STATE as D, Environment as E, type EcsEntityEditorKind as F, type EntityInput as G, type FloatInput as H, InputSystem as I, type IntersectionResult as J, type KeyboardKey as K, KeyboardKeys as L, type MouseButton as M, PREFAB_FILE_VERSION as N, ObjectManagementSystem as O, ParentId as P, PREFAB_FILE_VERSION_NESTED as Q, type PrefabAsset as R, type SpawnPrefabSource as S, TransformComponent as T, type RemapSnapshotOptions as U, type Vec3$1 as V, type WorldEntityView$1 as W, RenderSystem as X, type SelectionListener as Y, type SliderInput as Z, type TextInput as _, DEFAULT_POSTPROCESSING_STATE as a, TransformSyncSystem as a0, type Vec3 as a1, type Vector2Input as a2, type Vector3Input as a3, clearPrefabCache as a4, despawnPrefab as a5, loadPrefab as a6, parsePrefabAsset as a7, prefabFileVersionFor as a8, remapSnapshotEntityIds as a9, setPrefabAssetUrlResolver as aa, spawnPrefab as ab, type AnyComponent as ac, DEBUG_CHANGE_IGNORED_SYSTEMS as ad, type WorldHistorySnapshot as ae, cloneHistoryValue as af, normalizeDebugValue as ag, type EnvironmentFogState as b, type EnvironmentFogType as c, type EnvironmentGradientEffect as d, type EnvironmentSkyboxState as e, type EnvironmentSkyboxType as f, type EnvironmentState as g, Postprocessing as h, type PostprocessingState as i, type TransformData as j, type EcsSystem as k, World as l, type SpawnPrefabOptions as m, type ComponentClass as n, type ParentLookup as o, type EcsEntityKind as p, type SubtreeSnapshot as q, type EntityId as r, type ExternalRefWarning as s, type CheckboxInput as t, type ColorInput as u, type ComponentFactory as v, type ComponentInput as w, type ComponentKind as x, type DropdownInput as y, type DropdownOption as z };
+export { type AssetInput as $, type NetPose as A, type EcsSystem as B, Component as C, DEFAULT_ENVIRONMENT_LIGHTING as D, Environment as E, type NetworkService as F, type EntityId as G, type NetworkHandle as H, type IKChain as I, type NetSpawnOptions as J, type WorldEntityView$1 as K, type SpawnPrefabOptions as L, type PlaySlotOptions as M, type NetValue as N, type ComponentClass as O, ParentId as P, type ParentLookup as Q, type RenderBackend as R, type SpawnPrefabSource as S, TransformComponent as T, type EcsEntityKind as U, type Vec3$1 as V, World as W, ObjectManagementSystem as X, type SubtreeSnapshot as Y, type ExternalRefWarning as Z, type AudioBus as _, DEFAULT_ENVIRONMENT_STATE as a, AudioSystem as a0, type CheckboxInput as a1, type ChromaKeyOptions as a2, type ColorInput as a3, type ComponentFactory as a4, type ComponentInput as a5, type ComponentKind as a6, type DropdownInput as a7, type DropdownOption as a8, type EcsComponentFactoryKind as a9, SlotChooser as aA, type SoundBankAsset as aB, type SoundSlot as aC, type SoundTake as aD, type TextInput as aE, type ToggleInput as aF, TransformSyncSystem as aG, type Vec3 as aH, type Vector2Input as aI, type Vector3Input as aJ, clearPrefabCache as aK, despawnPrefab as aL, findModelBone as aM, listModelBones as aN, loadPrefab as aO, parsePrefabAsset as aP, prefabFileVersionFor as aQ, remapSnapshotEntityIds as aR, setPrefabAssetUrlResolver as aS, soundBankFiles as aT, spawnPrefab as aU, type AnyComponent as aV, DEBUG_CHANGE_IGNORED_SYSTEMS as aW, type WorldHistorySnapshot as aX, cloneHistoryValue as aY, normalizeDebugValue as aZ, type EcsEntityEditorKind as aa, type EcsRenderer as ab, type EntityInput as ac, type FloatInput as ad, IKSystem as ae, InputSystem as af, type IntersectionResult as ag, type KeyboardKey as ah, KeyboardKeys as ai, type ModelBoneInfo as aj, type MouseButton as ak, PREFAB_FILE_VERSION as al, PREFAB_FILE_VERSION_NESTED as am, type PostprocessingBuildContext as an, type PostprocessingPipeline as ao, type PrefabAsset as ap, type RemapSnapshotOptions as aq, RenderSystem as ar, type RendererKind as as, type ScriptErrorEvent as at, type ScriptErrorListener as au, type ScriptErrorPhase as av, type ScriptErrorReport as aw, type ScriptErrorSource as ax, type SelectionListener as ay, type SliderInput as az, DEFAULT_POSTPROCESSING_STATE as b, type EnvironmentFogState as c, type EnvironmentFogType as d, type EnvironmentGradientEffect as e, type EnvironmentLightingState as f, type EnvironmentSkyboxImageProjection as g, type EnvironmentSkyboxState as h, type EnvironmentSkyboxType as i, type EnvironmentState as j, type EnvironmentToneMapping as k, IKComponent as l, type IKLimb as m, type IKOptions as n, NetworkIdentityComponent as o, NetworkSpawnerComponent as p, NetworkTransformComponent as q, type NetworkTransformOptions as r, NetworkedPropsComponent as s, Postprocessing as t, type PostprocessingState as u, type TransformData as v, normalizeEnvironmentLighting as w, normalizeIKChain as x, type NetworkTransport as y, type NetEntityView as z };