@relu-interactives/spatial-ecs 0.2.11 → 0.2.13

package/dist/{System-KTHuWc-i.d.cts → System-CTTwEGn1.d.cts}

@@ -16,6 +16,253 @@ import * as RAPIER from '@dimforge/rapier3d-compat';
 declare class Component {
 }
 
+/** 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";
+/** 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"`. */
+    imageUrl?: string;
+    /** Gradient parameters used when {@link type} is `"gradient"`. */
+    gradient: {
+        /** Ordered list of color stops as `#rrggbb` strings. */
+        colors: string[];
+        /** Gradient distribution. */
+        effect: EnvironmentGradientEffect;
+    };
+};
+/** Fog configuration. Mirrors three.js `Fog` / `FogExp2`. */
+type EnvironmentFogState = {
+    /** Active fog model. */
+    type: EnvironmentFogType;
+    /** Fog color as `#rrggbb`. */
+    color: string;
+    /** Linear-fog parameters used when {@link type} is `"linear"`. */
+    linear: {
+        /** Distance at which fog begins to take effect. */
+        near: number;
+        /** Distance at which fog reaches full opacity. */
+        far: number;
+    };
+    /** Exponential-fog parameters used when {@link type} is `"exponential"`. */
+    exponential: {
+        /** Density coefficient. Higher values produce thicker fog. */
+        density: number;
+    };
+};
+/** World gravity vector applied by the physics system, in world units per second squared. */
+type EnvironmentGravityState = {
+    /** Gravity along world X. */
+    x: number;
+    /** Gravity along world Y (negative pulls objects down). */
+    y: number;
+    /** Gravity along world Z. */
+    z: number;
+};
+/** Aggregated authoring state owned by {@link Environment}. */
+type EnvironmentState = {
+    /** Skybox configuration. */
+    skybox: EnvironmentSkyboxState;
+    /** Fog configuration. */
+    fog: EnvironmentFogState;
+    /** World gravity. */
+    gravity: EnvironmentGravityState;
+    /**
+     * Fixed timestep (seconds) used by the physics accumulator loop.
+     * Physics is stepped in fixed increments of this size each frame.
+     * Default is `0.02` (50 Hz).
+     */
+    fixedTimeStep: number;
+};
+declare const DEFAULT_ENVIRONMENT_STATE: EnvironmentState;
+/**
+ * Scene environment settings: skybox (gradient/color/image), fog
+ * (linear/exponential), and gravity vector for the physics world.
+ * Singleton-style — attached to one environment entity per scene.
+ *
+ * Use `world.getEnvironmentComponent()` to access this component directly
+ * from a Behaviour script. Mutate `values` to change settings at runtime;
+ * `EnvironmentSyncSystem` applies the changes on the next frame.
+ *
+ * @category Components
+ */
+declare class Environment extends Component {
+    /** Aggregated environment authoring state (skybox, fog, gravity). Saved with the project. */
+    values: EnvironmentState;
+    constructor(values?: Partial<EnvironmentState>);
+}
+
+/** Aggregated post-processing effect chain authored on the scene environment. Each sub-effect has its own `enabled` flag plus per-effect parameters. */
+type PostprocessingState = {
+    /** Master toggle. When `false` no post-processing is applied even if individual effects are enabled. */
+    postEnabled: boolean;
+    /** Depth-of-field (bokeh) effect. */
+    dof: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Distance to the focal plane in world units. */
+        focusDistance: number;
+        /** Lens focal length controlling depth-of-field strength. */
+        focalLength: number;
+        /** Bokeh blur kernel scale. */
+        bokehScale: number;
+    };
+    /** Bloom (HDR glow) effect. */
+    bloom: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Strength of the bloom contribution. */
+        intensity: number;
+        /** Luminance threshold above which pixels bloom. */
+        threshold: number;
+        /** Blur radius applied to the bloom buffer. */
+        radius: number;
+    };
+    /** Vignette (corner darkening) effect. */
+    vignette: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Distance from screen center where the vignette begins. */
+        offset: number;
+        /** Maximum darkness applied at screen edges. */
+        darkness: number;
+    };
+    /** Chromatic aberration (RGB channel offset) effect. */
+    chromAberration: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Horizontal channel offset. */
+        offsetX: number;
+        /** Vertical channel offset. */
+        offsetY: number;
+    };
+    /** Film-noise overlay. */
+    noise: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Opacity of the noise layer in `[0, 1]`. */
+        opacity: number;
+    };
+    /** Pixelation (mosaic) effect. */
+    pixelation: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Pixel block size in screen pixels. */
+        granularity: number;
+    };
+    /** Tone-mapping exposure control. */
+    toneMapping: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Exposure multiplier applied before tone-mapping. */
+        exposure: number;
+    };
+    /** Hue/saturation color grading. */
+    hueSaturation: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Hue rotation in radians. */
+        hue: number;
+        /** Saturation offset (`0` = unchanged, `>0` = more saturated). */
+        saturation: number;
+    };
+    /** Sepia color grade. */
+    sepia: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Blend strength between original and sepia in `[0, 1]`. */
+        intensity: number;
+    };
+    /** SMAA antialiasing pass. */
+    smaa: {
+        /** Enable the effect. */
+        enabled: boolean;
+    };
+    /** Screen-space ambient occlusion. */
+    ssao: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Strength of the AO contribution. */
+        intensity: number;
+        /** Sampling radius in world units. */
+        radius: number;
+    };
+    /** Dot-screen (halftone) effect. */
+    dotScreen: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Pattern scale (legacy field; use {@link scale} where available). */
+        dotScreenScale: number;
+        /** Pattern rotation in radians (legacy field; use {@link angle} where available). */
+        dotScreenAngle: number;
+        /** Pattern rotation in radians. */
+        angle?: number;
+        /** Pattern scale. */
+        scale?: number;
+        /** Three.js blend function override. */
+        blendFunction?: number;
+        /** Effect opacity in `[0, 1]`. */
+        opacity?: number;
+    };
+    /** Glitch effect (digital corruption simulation). */
+    glitch: {
+        /** Enable the effect. */
+        enabled: boolean;
+        /** Three.js blend function override. */
+        blendFunction?: number;
+        /** RGB channel offset applied during a glitch burst. */
+        chromaticAberrationOffset?: {
+            x: number;
+            y: number;
+        } | [number, number];
+        /** `[min, max]` delay (seconds) between glitch bursts. */
+        delay?: [number, number];
+        /** `[min, max]` duration (seconds) of each glitch burst. */
+        duration?: [number, number];
+        /** Glitch displacement strength (scalar or per-axis). */
+        strength?: number | {
+            x: number;
+            y: number;
+        };
+        /** Size of the displacement texture sampled by the glitch shader. */
+        dtSize?: number;
+        /** Fraction of columns affected during a glitch burst. */
+        columns?: number;
+        /** Ratio between weak and strong glitch bursts. */
+        ratio?: number;
+        /** Glitch mode label (matches the postprocessing library's mode enum). */
+        mode?: string;
+        /** Force the glitch to remain active. */
+        active?: boolean;
+    };
+};
+declare const DEFAULT_POSTPROCESSING_STATE: PostprocessingState;
+/**
+ * Postprocessing stack settings (depth-of-field, bloom, vignette, chromatic
+ * aberration, noise, pixelation, tone mapping, hue/saturation, sepia, SMAA,
+ *
+ * Use `world.getPostprocessingComponent()` to access this component directly
+ * from a Behaviour script. Mutate `values` to toggle effects or adjust
+ * parameters at runtime; `PostprocessingSyncSystem` applies changes next frame.
+ * SSAO, dot-screen, glitch). The render system applies enabled effects in a
+ * `postprocessing`-library composer when `postEnabled` is `true`. Singleton-
+ * style — attached to one entity per scene.
+ *
+ * @category Components
+ */
+declare class Postprocessing extends Component {
+    /** Aggregated post-processing state. Saved with the project. */
+    values: PostprocessingState;
+    constructor(values?: Partial<PostprocessingState>);
+}
+
 /**
  * Records the parent entity id for hierarchical scene graphs. `null` means
  * the entity is at the world root. The `ObjectManagementSystem` reconciles
@@ -117,7 +364,10 @@ type DropdownInput = {
     options: DropdownOption[];
     value: string | any;
 };
-type CheckboxInput = boolean;
+type CheckboxInput = {
+    type: "checkbox";
+    value: boolean;
+};
 type ToggleInput = boolean;
 type AssetInput = {
     path: string;
@@ -253,7 +503,29 @@ declare class ObjectManagementSystem implements EcsSystem {
     createComponentNow(kind: EcsComponentFactoryKind, world: World, entityId: EntityId, ...args: any[]): unknown;
     requestCreate(kind: EcsEntityKind, payload?: CreatePayload, onCreated?: (entityId: EntityId) => void): void;
     createNow(kind: EcsEntityKind, world: World, payload?: CreatePayload): EntityId;
-    deleteEntity(world: World, entityId: EntityId): boolean;
+    /**
+     * Removes an entity from the ECS world and its associated `Object3D` from the
+     * THREE.js scene graph.
+     *
+     * @param world - The world the entity belongs to.
+     * @param entityId - The entity to remove.
+     * @param dispose - When `true`, traverses the entity's `Object3D` subtree and
+     *   calls `.dispose()` on every `BufferGeometry` and `Material` found. Pass
+     *   `true` when the entity will not be reused and you want to free GPU memory
+     *   immediately (e.g. dynamically spawned objects). Defaults to `false`.
+     * @returns `true` if the entity existed and was removed; `false` if the entity
+     *   was not found.
+     *
+     * @example
+     * ```ts
+     * // Remove from scene, keep GPU resources (safe if geometry is shared)
+     * objects.deleteEntity(world, entityId);
+     *
+     * // Remove from scene and free GPU memory (use for one-off spawned objects)
+     * objects.deleteEntity(world, entityId, true);
+     * ```
+     */
+    deleteEntity(world: World, entityId: EntityId, dispose?: boolean): boolean;
     setParent(world: World, entityId: EntityId, parentId: EntityId | null, options?: {
         preserveWorldTransform?: boolean;
     }): boolean;
@@ -465,6 +737,8 @@ declare class World {
     private components;
     private inputSystem;
     private objectManagementSystem;
+    private environmentSyncSystem;
+    private postprocessingSyncSystem;
     private rapierModule;
     private rapierModulePromise;
     private physicsWorld;
@@ -592,6 +866,41 @@ declare class World {
     getEntityByName(name: string): WorldEntityView | null;
     getEntityById(entityId: number): WorldEntityView | null;
     getObjectManagementSystem(): ObjectManagementSystem;
+    /**
+     * Returns the singleton {@link Environment} component for the scene, or
+     * `undefined` if no environment entity exists yet.
+     *
+     * Mutate `component.values` directly to change skybox, fog, or gravity at
+     * runtime — `EnvironmentSyncSystem` picks up the changes next frame.
+     *
+     * @example
+     * ```ts
+     * const env = this.world.getEnvironmentComponent();
+     * if (env) {
+     *   env.values.fog.type = "exponential";
+     *   env.values.fog.exponential.density = 0.01;
+     * }
+     * ```
+     */
+    getEnvironmentComponent(): Environment | undefined;
+    /**
+     * Returns the singleton {@link Postprocessing} component for the scene, or
+     * `undefined` if no postprocessing entity exists yet.
+     *
+     * Mutate `component.values` directly to enable/disable effects or tweak
+     * parameters at runtime — `PostprocessingSyncSystem` picks up the changes
+     * next frame.
+     *
+     * @example
+     * ```ts
+     * const pp = this.world.getPostprocessingComponent();
+     * if (pp) {
+     *   pp.values.bloom.enabled = true;
+     *   pp.values.bloom.intensity = 2.0;
+     * }
+     * ```
+     */
+    getPostprocessingComponent(): Postprocessing | undefined;
     /**
      * Cast a ray from `origin` along `direction` and return every intersected
      * entity-bound mesh, sorted by distance. Each result is a standard
@@ -658,4 +967,4 @@ interface EcsSystem {
     dispose?(world: World): void;
 }
 
-export { type AssetInput as A, type WorldHistorySnapshot as B, Component as C, type DropdownInput as D, type EcsSystem as E, type FloatInput as F, cloneHistoryValue as G, normalizeDebugValue as H, InputSystem as I, type KeyboardKey as K, type MouseButton as M, ObjectManagementSystem as O, ParentId as P, RenderSystem as R, type SelectionListener as S, TransformComponent as T, type Vec3$1 as V, type WorldEntityView$1 as W, type TransformData as a, World as b, type ComponentClass as c, type ParentLookup as d, type EcsEntityKind as e, type CheckboxInput as f, type ColorInput as g, type ComponentFactory as h, type ComponentInput as i, type ComponentKind as j, type DropdownOption as k, type EcsComponentFactoryKind as l, type EcsEntityEditorKind as m, type EntityId as n, type EntityInput as o, type IntersectionResult as p, KeyboardKeys as q, type SliderInput as r, type TextInput as s, type ToggleInput as t, TransformSyncSystem as u, type Vec3 as v, type Vector2Input as w, type Vector3Input as x, type AnyComponent as y, DEBUG_CHANGE_IGNORED_SYSTEMS as z };
+export { cloneHistoryValue as $, type AssetInput as A, type IntersectionResult as B, Component as C, DEFAULT_ENVIRONMENT_STATE as D, Environment as E, type FloatInput as F, KeyboardKeys as G, type SliderInput as H, InputSystem as I, type TextInput as J, type KeyboardKey as K, type ToggleInput as L, type MouseButton as M, TransformSyncSystem as N, ObjectManagementSystem as O, ParentId as P, type Vec3 as Q, RenderSystem as R, type SelectionListener as S, TransformComponent as T, type Vector2Input as U, type Vec3$1 as V, type WorldEntityView$1 as W, type Vector3Input as X, type AnyComponent as Y, DEBUG_CHANGE_IGNORED_SYSTEMS as Z, type WorldHistorySnapshot as _, DEFAULT_POSTPROCESSING_STATE as a, normalizeDebugValue as a0, 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 ComponentClass as m, type ParentLookup as n, type EcsEntityKind as o, type CheckboxInput as p, type ColorInput as q, type ComponentFactory as r, type ComponentInput as s, type ComponentKind as t, type DropdownInput as u, type DropdownOption as v, type EcsComponentFactoryKind as w, type EcsEntityEditorKind as x, type EntityId as y, type EntityInput as z };