illutions 0.21.6 → 0.21.8

package/dist/main.d.ts

@@ -23,7 +23,8 @@ import type * as THREE_TYPE from 'three';
 import type * as THREE_WEBGPU_TYPE from 'three/webgpu';
 import type * as THREE_WEBTSL_TYPE from 'three/tsl';
 
-/** Defines the shared anti-aliasing settings.
+/**
+ * Defines the shared anti-aliasing settings.
  * @category Cfg
  */
 export declare interface aaCfg {
@@ -39,7 +40,8 @@ export declare interface aaCfg {
     mode: 'none' | 'fxaa' | 'smaa';
 }
 
-/** Defines the ambient light settings controlling global scene illumination.
+/**
+ * Defines the ambient light settings controlling global scene illumination.
  * @category Cfg
  */
 export declare interface AmbientlightCfg {
@@ -90,7 +92,7 @@ export declare interface AnimFadeEvent {
  * @category Core
  */
 export declare class App<TClasses extends Classes = {}> {
-    readonly audio: Audio_2;
+    readonly audio: Audio_2 | null;
     readonly cfgCtrl: CfgCtrl;
     readonly engine: Engine;
     readonly envCtrls: EnvCtrls;
@@ -100,7 +102,7 @@ export declare class App<TClasses extends Classes = {}> {
     readonly raycast: Raycast;
     readonly stateMachine: StateMachine;
     private cam3D;
-    private readonly gui;
+    private readonly inspector;
     readonly comps: CompInsts<NonNullable<TClasses['comps']>>;
     readonly objs3D: Obj3DInsts<NonNullable<TClasses['objs3D']>>;
     /* Excluded from this release type: __constructor */
@@ -210,10 +212,16 @@ declare class Audio_2 {
 }
 export { Audio_2 as Audio }
 
-/** Defines the audio settings used for playback timing and distance-based spatial attenuation.
+/**
+ * Defines the audio settings used for playback timing and distance-based spatial attenuation.
  * @category Cfg
  */
 export declare interface AudioCfg {
+    /**
+     * Whether audio support is initialized when the application starts.
+     * @default false
+     */
+    enable: boolean;
     /**
      * Whether the GUI audio dropdown is open.
      * @default false
@@ -294,7 +302,8 @@ export declare class Cam3D extends Obj3D {
     /* Excluded from this release type: updateCanvasResize */
 }
 
-/** Defines the shared camera settings used to position, orient and clip the scene view.
+/**
+ * Defines the shared camera settings used to position, orient and clip the scene view.
  * @category Cfg
  */
 export declare interface CamBaseCfg {
@@ -330,7 +339,8 @@ export declare interface CamBaseCfg {
 
 export declare type CamCfg = CamPerspectiveCfg | CamOrthographicCfg;
 
-/** Defines the orthographic camera settings used to render the scene without perspective distortion.
+/**
+ * Defines the orthographic camera settings used to render the scene without perspective distortion.
  * @category Cfg
  */
 export declare interface CamOrthographicCfg extends CamBaseCfg {
@@ -365,7 +375,8 @@ export declare interface CamOrthographicCfg extends CamBaseCfg {
     aspect?: never;
 }
 
-/** Defines the perspective camera settings used to render the scene with depth perception.
+/**
+ * Defines the perspective camera settings used to render the scene with depth perception.
  * @category Cfg
  */
 export declare interface CamPerspectiveCfg extends CamBaseCfg {
@@ -405,7 +416,8 @@ export declare interface CanvasPointerEvent {
     event: PointerEvent;
 }
 
-/** Defines the full configuration structure used to initialize the application.
+/**
+ * Defines the full configuration structure used to initialize the application.
  * @category Cfg
  */
 export declare interface Cfg {
@@ -417,10 +429,10 @@ export declare interface Cfg {
     debug: DebugCfg;
     /** Environment controls settings. */
     envCtrls: EnvCtrlsCfg;
+    /** Default GUI settings. */
+    gui: GuiCfg;
     /** Light and shadow settings. */
     light: LightCfg;
-    /** Menu bar settings. */
-    menuBar: MenuBarCfg;
     /** Default mesh settings. */
     mesh: MeshCfg;
     /** GLTF/GLB model settings. */
@@ -439,8 +451,6 @@ export declare interface Cfg {
     scene: SceneCfg;
     /** State machine settings. */
     stateMachine: StateMachineCfg;
-    /** Runtime statistics settings. */
-    stats: StatsCfg;
 }
 
 /** Defines the static configuration that is applied at compile-time. For runtime updates use {@link CfgCtrl}. */
@@ -465,7 +475,7 @@ export declare class CfgCtrl {
      * @param params.coneOuterAngle - {@link AudioCfg.coneOuterAngle}.
      * @param params.coneOuterGain - {@link AudioCfg.coneOuterGain}.
      */
-    setAudio(params: Partial<AudioCfg>): void;
+    setAudio(params: Partial<Omit<AudioCfg, 'enable'>>): void;
     /**
      * Applies runtime updates to `RenderCfg`.
      *
@@ -546,7 +556,7 @@ export declare class Comp extends HTMLElement {
      * @public
      *
      * **Example**
-     * {@includeCode ../../examples/comp-onready.ts}
+     * {@includeCode ../../examples/ilu-onready.ts}
      */
     protected onReady(): void;
     /**
@@ -570,7 +580,8 @@ export declare type CompInsts<T extends Record<string, CompClass>> = {
     [K in keyof T]: InstanceType<T[K]>[];
 };
 
-/** Defines the debugging settings that can be toggled during development.
+/**
+ * Defines the debugging settings that can be toggled during development.
  * @category Cfg
  */
 export declare interface DebugCfg {
@@ -599,7 +610,7 @@ export declare class Engine {
     private readonly comps;
     private readonly objs3D;
     private readonly cfg;
-    private readonly stats;
+    private readonly infoBox;
     private actionObserver;
     private gltf;
     private mixer;
@@ -624,7 +635,7 @@ export declare class Engine {
     private ambientLight;
     private hemisphereLight;
     private powerMode;
-    private postAuto;
+    private postNoise;
     private dTs;
     private dT;
     private dTFrameMax;
@@ -637,7 +648,6 @@ export declare class Engine {
     /* Excluded from this release type: __constructor */
     /* Excluded from this release type: init */
     private initWebGpuRenderer;
-    private isPostEnabled;
     /**
      * Registers a callback that is executed on every requestAnimationFrame update.
      * @param {(deltaTime: number) => void} cb - Callback executed once per frame with `deltaTime`.
@@ -756,7 +766,9 @@ export declare class Engine {
      * @param enable - Whether SSR should be enabled.
      */
     enableSsr(enable: boolean): Promise<void>;
-    private getPostAuto;
+    private isPostCfg;
+    /* Excluded from this release type: isPostEnabled */
+    private isPostGpu;
     private loadModel;
     private pauseObjActions;
     /**
@@ -997,7 +1009,8 @@ export declare class EnvCtrls {
     private update;
 }
 
-/** Defines the environment controls settings for `THREE.Scene.environment` and `THREE.Scene.background`.
+/**
+ * Defines the environment controls settings for `THREE.Scene.environment` and `THREE.Scene.background`.
  * @category Cfg
  */
 export declare interface EnvCtrlsCfg {
@@ -1079,7 +1092,8 @@ export declare class Events {
     /* Excluded from this release type: windowResize */
 }
 
-/** Defines the fog settings controlling scene depth-based color attenuation.
+/**
+ * Defines the fog settings controlling scene depth-based color attenuation.
  * @category Cfg
  */
 export declare interface FogCfg {
@@ -1186,7 +1200,8 @@ export declare class FpvCtrls {
     use(extension: (fpvctrls: FpvCtrls) => void): void;
 }
 
-/** Defines the First Person View Controls settings used to move and rotate the camera inside a scene.
+/**
+ * Defines the First Person View Controls settings used to move and rotate the camera inside a scene.
  * @category Cfg
  */
 export declare interface FpvCtrlsCfg {
@@ -1253,7 +1268,8 @@ export declare interface FpvCtrlsEvent {
     type: 'FPVCTRLS_DISABLED' | 'FPVCTRLS_ENABLED' | 'FPVCTRLS_LOCK' | 'FPVCTRLS_UNLOCK' | 'FPVCTRLS_DISABLED';
 }
 
-/** Defines the FXAA anti-aliasing settings used to smooth jagged edges in the rendered image.
+/**
+ * Defines the FXAA anti-aliasing settings used to smooth jagged edges in the rendered image.
  * @category Cfg
  */
 export declare interface FxaaCfg {
@@ -1264,7 +1280,27 @@ export declare interface FxaaCfg {
     sharpness: number;
 }
 
-/** Defines the hemisphere light settings controlling ambient sky and ground illumination.
+/**
+ * Defines the GUI elements for runtime information, controls and inspection.
+ * @category Cfg
+ */
+export declare interface GuiCfg {
+    /** The infobox for runtime statistics and renderer information. */
+    infoBox: InfoBoxCfg;
+    /** The inspector for runtime properties. */
+    inspector: {
+        /**
+         * Activates the inspector for runtime property control via lazy loading.
+         * @default true
+         */
+        enable: boolean;
+    };
+    /** The menubar at the bottom. */
+    menuBar: MenuBarCfg;
+}
+
+/**
+ * Defines the hemisphere light settings controlling ambient sky and ground illumination.
  * @category Cfg
  */
 export declare interface HemisphereCfg {
@@ -1290,6 +1326,73 @@ export declare interface HemisphereCfg {
     intensity: number;
 }
 
+/**
+ * Defines the built-in engine infobox settings used to display FPS, CPU/frame timing and renderer.info values.
+ * @category Cfg
+ */
+export declare interface InfoBoxCfg {
+    /**
+     * Enables or disables infobox data collection.
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Shows the FPS value.
+     * @default true
+     */
+    fps: boolean;
+    /**
+     * Shows the measured CPU/update time in milliseconds.
+     * @default true
+     */
+    cpu: boolean;
+    /**
+     * Shows the frame time in milliseconds.
+     * @default true
+     */
+    frame: boolean;
+    /**
+     * Shows renderer.info.render.calls.
+     * @default true
+     */
+    calls: boolean;
+    /**
+     * Shows renderer.info.render.triangles.
+     * @default true
+     */
+    triangles: boolean;
+    /**
+     * Shows renderer.info.render.lines.
+     * @default true
+     */
+    lines: boolean;
+    /**
+     * Shows renderer.info.render.points.
+     * @default true
+     */
+    points: boolean;
+    /**
+     * Shows renderer.info.memory.geometries.
+     * @default true
+     */
+    geometries: boolean;
+    /**
+     * Shows renderer.info.memory.textures.
+     * @default true
+     */
+    textures: boolean;
+    /**
+     * Shows the number of compiled WebGL programs from renderer.info.programs.
+     * @default true
+     */
+    programs: boolean;
+    /**
+     * Refresh rate of the displayed values.
+     * @default 10
+     */
+    logsPerSecond: number;
+}
+
 /**
  * The `Light3D` class represents a managed light source.
  * @category 3D Objects
@@ -1315,7 +1418,8 @@ export declare class Light3D extends Obj3D {
     /* Excluded from this release type: traverse */
 }
 
-/** Defines the light shadow settings used to configure shadow map resolution and shadow camera limits.
+/**
+ * Defines the light shadow settings used to configure shadow map resolution and shadow camera limits.
  * @category Cfg
  */
 export declare interface LightCfg {
@@ -1351,7 +1455,8 @@ export declare interface LightCfg {
     far: number;
 }
 
-/** Defines the menu bar settings used to display licensed UI controls and branding.
+/**
+ * Defines the menu bar settings used to display licensed UI controls and branding.
  * @category Cfg
  */
 export declare interface MenuBarCfg {
@@ -1400,7 +1505,8 @@ export declare class Mesh3D extends Obj3D {
     /* Excluded from this release type: traverse */
 }
 
-/** Defines the mesh-specific rendering settings used to control shadows and frustum culling.
+/**
+ * Defines the mesh-specific rendering settings used to control shadows and frustum culling.
  * @category Cfg
  */
 export declare interface MeshCfg {
@@ -1421,7 +1527,8 @@ export declare interface MeshCfg {
     frustumCulled: boolean;
 }
 
-/** Defines the GLTF/GLB model loading settings used to fetch models and configure optional Draco decoding.
+/**
+ * Defines the GLTF/GLB model loading settings used to fetch models and configure optional Draco decoding.
  * @category Cfg
  */
 export declare interface ModelCfg {
@@ -1762,7 +1869,8 @@ export declare class OrbitCtrls {
     private updatePointersStart;
 }
 
-/** Defines the Orbit Controls settings used to rotate, pan, zoom and constrain the camera around a target.
+/**
+ * Defines the Orbit Controls settings used to rotate, pan, zoom and constrain the camera around a target.
  * @category Cfg
  */
 export declare interface OrbitCtrlsCfg {
@@ -1863,15 +1971,11 @@ export declare interface OrbitCtrlsEvent {
  */
 export declare type PauseObjectActions = 'all' | 'finished' | 'last' | 'none';
 
-/** Defines the post-processing settings used by the rendering pipeline.
+/**
+ * Defines the post-processing settings used by the rendering pipeline.
  * @category Cfg
  */
 export declare interface PostCfg {
-    /**
-     * Enables GPU-based auto activation for post-processing.
-     * @default true
-     */
-    auto: boolean;
     /**
      * Whether the GUI post-processing dropdown is open.
      * @default false
@@ -1982,7 +2086,8 @@ export declare class Raycast {
     private updatePointer;
 }
 
-/** Defines the raycasting settings used to detect selectable objects around the pointer.
+/**
+ * Defines the raycasting settings used to detect selectable objects around the pointer.
  * @category Cfg
  */
 export declare interface RaycastCfg {
@@ -2003,7 +2108,8 @@ export declare interface RaycastCfg {
     countClosestObjs: number;
 }
 
-/** Defines the renderer settings used to control frame timing, resolution, shadows, tone mapping and output color space.
+/**
+ * Defines the renderer settings used to control frame timing, resolution, shadows, tone mapping and output color space.
  * @category Cfg
  */
 export declare interface RenderCfg {
@@ -2042,11 +2148,6 @@ export declare interface RenderCfg {
      * @default 10
      */
     deltaTimesMax: number;
-    /**
-     * Activates the GUI module via lazy loading.
-     * @default false
-     */
-    gui: boolean;
     /**
      * Output color space.
      * @default THREE.SRGBColorSpace
@@ -2083,7 +2184,6 @@ export declare interface RenderCfg {
     webgl: {
         /**
          * Parameters passed to `THREE.WebGLRenderer`.
-         * @default antialias: true, alpha: false, powerPreference: 'low-power'
          */
         parameters: THREE_TYPE.WebGLRendererParameters;
     };
@@ -2093,7 +2193,6 @@ export declare interface RenderCfg {
     webgpu: {
         /**
          * Parameters passed to `THREE.WebGPURenderer`.
-         * @default antialias: true, alpha: false
          */
         parameters: WebGpuRendererParameters;
     };
@@ -2102,13 +2201,14 @@ export declare interface RenderCfg {
 /** Defines the available renderer backends. */
 export declare type Renderer = 'webgl' | 'webgpu' | 'auto';
 
-/** Defines the scene settings used to configure background, environment, model, fog and lights.
+/**
+ * Defines the scene settings used to configure background, environment, model, fog and lights.
  * @category Cfg
  */
 export declare interface SceneCfg {
     /**
      * Custom element tag in which the canvas is rendered.
-     * @default 'comp-canvas'
+     * @default 'ilu-canvas'
      */
     canvas: string;
     /**
@@ -2136,7 +2236,8 @@ export declare interface SceneRenderedEvent {
     type: 'SCENE_RENDERED';
 }
 
-/** Defines the SMAA anti-aliasing pass settings used to smooth jagged edges in the rendered image.
+/**
+ * Defines the SMAA anti-aliasing pass settings used to smooth jagged edges in the rendered image.
  * @category Cfg
  */
 export declare interface SmaaCfg {
@@ -2152,7 +2253,8 @@ export declare interface SmaaCfg {
     guiOpened: boolean;
 }
 
-/** Defines the screen-space ambient occlusion settings used to enhance depth and shading.
+/**
+ * Defines the screen-space ambient occlusion settings used to enhance depth and shading.
  * @category Cfg
  */
 export declare interface SsaoCfg {
@@ -2168,7 +2270,8 @@ export declare interface SsaoCfg {
     guiOpened: boolean;
 }
 
-/** Defines the WebGL screen-space ambient occlusion settings.
+/**
+ * Defines the WebGL screen-space ambient occlusion settings.
  * @category Cfg
  */
 export declare interface SsaoWebGlCfg {
@@ -2189,7 +2292,8 @@ export declare interface SsaoWebGlCfg {
     maxDistance: number;
 }
 
-/** Defines the WebGPU screen-space ambient occlusion settings.
+/**
+ * Defines the WebGPU screen-space ambient occlusion settings.
  * @category Cfg
  */
 export declare interface SsaoWebGpuCfg {
@@ -2230,7 +2334,8 @@ export declare interface SsaoWebGpuCfg {
     resolutionScale: number;
 }
 
-/** Defines the shared screen-space reflection settings.
+/**
+ * Defines the shared screen-space reflection settings.
  * @category Cfg
  */
 export declare interface SsrCfg {
@@ -2246,7 +2351,8 @@ export declare interface SsrCfg {
     guiOpened: boolean;
 }
 
-/** Defines the WebGL screen-space reflection settings.
+/**
+ * Defines the WebGL screen-space reflection settings.
  * @category Cfg
  */
 export declare interface SsrWebGlCfg {
@@ -2317,7 +2423,8 @@ export declare interface SsrWebGlCfg {
     maxRoughness: number;
 }
 
-/** Defines the WebGPU screen-space reflection settings.
+/**
+ * Defines the WebGPU screen-space reflection settings.
  * @category Cfg
  */
 export declare interface SsrWebGpuCfg {
@@ -2388,7 +2495,8 @@ export declare class StateMachine {
     start(stateMachine: AnyStateMachine): void;
 }
 
-/** Defines the application state machine settings used to control inspector-related state.
+/**
+ * Defines the application state machine settings used to control inspector-related state.
  * @category Cfg
  */
 export declare interface StateMachineCfg {
@@ -2399,72 +2507,6 @@ export declare interface StateMachineCfg {
     inspector: boolean;
 }
 
-/** Defines the built-in engine stats panel settings used to display FPS, CPU/frame timing and renderer.info values.
- * @category Cfg
- */
-export declare interface StatsCfg {
-    /**
-     * Enables or disables stats data collection.
-     * @default true
-     */
-    enabled: boolean;
-    /**
-     * Shows the FPS value.
-     * @default true
-     */
-    fps: boolean;
-    /**
-     * Shows the measured CPU/update time in milliseconds.
-     * @default true
-     */
-    cpu: boolean;
-    /**
-     * Shows the frame time in milliseconds.
-     * @default true
-     */
-    frame: boolean;
-    /**
-     * Shows renderer.info.render.calls.
-     * @default true
-     */
-    calls: boolean;
-    /**
-     * Shows renderer.info.render.triangles.
-     * @default true
-     */
-    triangles: boolean;
-    /**
-     * Shows renderer.info.render.lines.
-     * @default true
-     */
-    lines: boolean;
-    /**
-     * Shows renderer.info.render.points.
-     * @default true
-     */
-    points: boolean;
-    /**
-     * Shows renderer.info.memory.geometries.
-     * @default true
-     */
-    geometries: boolean;
-    /**
-     * Shows renderer.info.memory.textures.
-     * @default true
-     */
-    textures: boolean;
-    /**
-     * Shows the number of compiled WebGL programs from renderer.info.programs.
-     * @default true
-     */
-    programs: boolean;
-    /**
-     * Refresh rate of the displayed values.
-     * @default 10
-     */
-    logsPerSecond: number;
-}
-
 /** Function returned by an event subscription. Calling it removes the associated listener. */
 export declare type Unsubscribe = () => void;