illutions 0.21.8 → 0.22.0

package/CHANGELOG.md

@@ -1,7 +1,27 @@
-# Changelog
+# Changelog
+
+## 0.22.0
+
+### Changed
+
+- Updated the framework to Three.js r185.
+- Changed the default renderer selection to `render.api = 'auto'`.
+- Added `envCtrls.dataType` to configure environment texture data handling.
+- Replaced `SsrWebGpuCfg.opacity` with `SsrWebGpuCfg.intensity`.
+
+### Fixed
+
+- Clarified the WebGL/WebGPU renderer switch behavior.
+- Enabled WebGPU renderer loading even when post-processing is disabled.
 
-## Unreleased
-
-### Changed
-
-- Add cfg.audio.enable in config
+## 0.21.9
+
+### Changed
+
+- Removed the `CfgCtrl` class and the related `app.cfgCtrl` access point. Runtime parameters are now updated through the responsible feature APIs, such as `app.audio.set(...)`.
+
+## 0.21.8
+
+### Changed
+
+- Added `cfg.audio.enable` to the configuration.

package/README.md

@@ -3,6 +3,38 @@
 illutions is a proprietary Web 3D engine for building interactive browser-based
 3D applications with Three.js, XState, GSAP, Tweakpane and more.
 
+## Highlights
+
+**Advanced post-processing**  
+Add SSAO, SSR, FXAA and SMAA through configurable pipelines for WebGL and WebGPU.
+
+**Advanced animation control**  
+Coordinate GLTF animation clips, GSAP transitions, camera paths and custom dolly-rig camera workflows.
+
+**XState-powered application logic**  
+Model complex application flows as predictable and inspectable state machines with integrated XState 5 usage.
+
+**Resource-aware rendering**  
+An intelligent, configurable FPS limiter avoids unnecessary frames and helps reduce CPU and GPU load.
+
+**WebGL and WebGPU rendering**  
+Support established and next-generation browser rendering with automatic WebGPU selection and WebGL fallback.
+
+**Lean initial bundles**  
+Optional controls, loaders, inspectors and effects are dynamically imported only when needed.
+
+**Optimized GLTF/GLB pipeline**  
+Load assets with Draco or Meshopt mesh compression and WebP or KTX2 textures.
+
+**Built-in interaction and audio**  
+Use pointer-based raycasting and distance-aware spatial audio.
+
+**Flexible environments**  
+Load HDR, EXR and texture environments with configurable rotation, intensity and background controls.
+
+**Runtime insights and debugging**  
+Inspect runtime properties, FPS, CPU and renderer statistics with detailed state, event and console reporting.
+
 ## Installation
 
 The recommended starting point is an illutions project template. The template
@@ -38,9 +70,11 @@ await App.run(cfg);
 illutions is not open source software. It may be used only under the terms granted
 by illutions.
 
-A free license displays the illutions menu bar and attribution. Removing or hiding
-that menu bar requires an active paid illutions license subscription or another
-written agreement with illutions.
+A valid `license.json` permits commercial and non-commercial use without
+requiring the illutions menu bar or attribution to remain visible.
+
+For the 2026 introductory period, the official GitHub project templates include
+a free `license.json` valid through December 31, 2026.
 
 See the included `LICENSE` file for the legal rights and restrictions.
 

package/dist/main.d.ts

@@ -1,10 +1,13 @@
 import { AnyEventObject } from 'xstate';
 import { AnyStateMachine } from 'xstate';
+import { ao } from 'three/addons/tsl/display/GTAONode.js';
+import { createBrowserInspector } from '@statelyai/inspect';
 import { default as default_2 } from 'three/addons/tsl/display/GTAONode.js';
 import { default as default_3 } from 'three/addons/tsl/display/SSRNode.js';
 import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
 import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
+import { FXAAShader } from 'three/addons/shaders/FXAAShader.js';
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
 import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
@@ -12,16 +15,21 @@ import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 import { OrbitControls as OrbitControls_2 } from 'three/examples/jsm/controls/OrbitControls.js';
 import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
+import { Pane } from 'tweakpane';
 import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';
 import { PointerLockControls as PointerLockControls_2 } from 'three/examples/jsm/controls/PointerLockControls.js';
 import { ReflectorForSSRPass } from 'three/addons/objects/ReflectorForSSRPass.js';
 import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
 import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
+import { smaa } from 'three/addons/tsl/display/SMAANode.js';
+import { SMAAPass } from 'three/addons/postprocessing/SMAAPass.js';
 import { SSAOPass } from 'three/addons/postprocessing/SSAOPass.js';
+import { ssr } from 'three/addons/tsl/display/SSRNode.js';
 import { SSRPass } from 'three/addons/postprocessing/SSRPass.js';
 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';
+import { TierResult } from 'detect-gpu';
 
 /**
  * Defines the shared anti-aliasing settings.
@@ -92,8 +100,7 @@ export declare interface AnimFadeEvent {
  * @category Core
  */
 export declare class App<TClasses extends Classes = {}> {
-    readonly audio: Audio_2 | null;
-    readonly cfgCtrl: CfgCtrl;
+    readonly audio: Audio_2;
     readonly engine: Engine;
     readonly envCtrls: EnvCtrls;
     readonly events: Events;
@@ -127,16 +134,19 @@ export declare class App<TClasses extends Classes = {}> {
  * @category Core
  */
 declare class Audio_2 {
-    private readonly cfg;
     private readonly ctx;
     private readonly loader;
     private readonly engine;
     private readonly sounds;
-    private audioCfgLast;
-    private callback;
+    private readonly params;
     private listener;
     /* Excluded from this release type: __constructor */
     private attachSoundTo;
+    /**
+     * Returns the audio parameters currently used at runtime.
+     * @returns A snapshot of the mutable audio settings.
+     */
+    get(): Partial<AudioCfg>;
     /**
      * Checks whether an audio source with the given name is loaded.
      * @param params - Parameter object.
@@ -194,6 +204,11 @@ declare class Audio_2 {
     }): void;
     private setAllPositionalSoundsCfg;
     private setPositionalSoundCfg;
+    /**
+     * Updates one or more audio parameters at runtime.
+     * @param params - Audio parameters to update.
+     */
+    set(params: Partial<AudioCfg>): void;
     /**
      * Stops the playback of an audio with a smooth fade-out.
      * @param params - Parameter object.
@@ -208,7 +223,6 @@ declare class Audio_2 {
      * @remarks This method is intended for advanced custom integrations where developers need direct access to the engine instance. The extension is executed once immediately when `use()` is called.
      */
     use(extension: (audio: Audio_2) => void): void;
-    /* Excluded from this release type: update */
 }
 export { Audio_2 as Audio }
 
@@ -453,39 +467,9 @@ export declare interface Cfg {
     stateMachine: StateMachineCfg;
 }
 
-/** Defines the static configuration that is applied at compile-time. For runtime updates use {@link CfgCtrl}. */
+/** Defines the initial configuration that is applied when the application starts. */
 export declare const cfg: Cfg;
 
-/**
- * Controls configuration options at runtime.
- * @category Core
- */
-export declare class CfgCtrl {
-    private cfg;
-    /* Excluded from this release type: __constructor */
-    /**
-     * Applies runtime updates to `AudioCfg`.
-     *
-     * @param params - Partial audio settings to apply.
-     * @param params.refDistance - {@link AudioCfg.refDistance}.
-     * @param params.rolloffFactor - {@link AudioCfg.rolloffFactor}.
-     * @param params.maxDistance - {@link AudioCfg.maxDistance}.
-     * @param params.distanceModel - {@link AudioCfg.distanceModel}.
-     * @param params.coneInnerAngle - {@link AudioCfg.coneInnerAngle}.
-     * @param params.coneOuterAngle - {@link AudioCfg.coneOuterAngle}.
-     * @param params.coneOuterGain - {@link AudioCfg.coneOuterGain}.
-     */
-    setAudio(params: Partial<Omit<AudioCfg, 'enable'>>): void;
-    /**
-     * Applies runtime updates to `RenderCfg`.
-     *
-     * @param params - Partial render settings to apply.
-     * @param params.fpsLimiter - {@link RenderCfg.fpsLimiter}.
-     * @param params.deltaTimesMax - {@link RenderCfg.deltaTimesMax}.
-     */
-    setRender(params: Partial<RenderCfg>): void;
-}
-
 /**
  * Groups optional class registries for `Obj3D` and `Comp`.
  *
@@ -524,6 +508,8 @@ export declare interface ClipFadeEvent {
     action?: THREE_TYPE.AnimationAction;
 }
 
+declare type ColorNode = THREE_WEBGPU_TYPE.Node<'vec4'>;
+
 /**
  * Represents a reusable web-component logic unit bound to a custom element that participates in the scene lifecycle.
  * @category Components
@@ -532,7 +518,6 @@ export declare class Comp extends HTMLElement {
     /** The root HTML element that hosts the visual container for the engine. */
     canvas: Readonly<HTMLElement>;
     cfg: Cfg;
-    cfgCtrl: Readonly<CfgCtrl>;
     comps: Map<string, Comp[]> | null;
     events: Readonly<Events>;
     objs3D: Map<string, Obj3D>;
@@ -1024,6 +1009,11 @@ export declare interface EnvCtrlsCfg {
      * @default 0
      */
     backgroundIntensity: number;
+    /**
+     * Specifies the texture data type used by EXR and HDR loaders.
+     * @default 'halfFloat'
+     */
+    dataType: 'halfFloat' | 'float';
     /**
      * Enables or disables environment and background map handling.
      * @default false
@@ -1126,20 +1116,11 @@ export declare interface FogCfg {
 export declare class FpvCtrls {
     private readonly cam3D;
     private readonly canvas;
-    private readonly cfg;
     private readonly engine;
     private readonly events;
     private readonly modules;
     /* Excluded from this release type: pointerLockCtrls */
-    private minPolarAngle;
-    private maxPolarAngle;
-    private pointerSpeed;
-    private keyMoveForward;
-    private keyMoveLeft;
-    private keyMoveBackward;
-    private keyMoveRight;
-    private keyMoveUp;
-    private keyMoveDown;
+    private readonly params;
     private isMoveForward;
     private isMoveLeft;
     private isMoveBackward;
@@ -1159,7 +1140,10 @@ export declare class FpvCtrls {
     enable(): void;
     /** Disposes three.js `PointerLockControls` and cleans up their runtime resources. */
     dispose(): void;
-    /** Returns the current three.js `PointerLockControls` configuration. */
+    /**
+     * Returns the parameters currently used by three.js `PointerLockControls`.
+     * @returns A snapshot of the mutable first-person control settings.
+     */
     get(): Partial<FpvCtrlsCfg>;
     /** Returns whether three.js `PointerLockControls` are enabled. */
     isEnabled(): boolean;
@@ -1280,6 +1264,8 @@ export declare interface FxaaCfg {
     sharpness: number;
 }
 
+declare type FXAAPostNode = (input: ColorNode) => ColorNode;
+
 /**
  * Defines the GUI elements for runtime information, controls and inspection.
  * @category Cfg
@@ -1578,17 +1564,17 @@ export declare interface ModelLoadingEvent {
 }
 
 declare class Modules {
-    gpuTier: any;
-    fxaaNode: any;
-    fxaaShader: any;
-    smaaPassClass: any;
-    smaaNode: any;
-    ssaoPassClass: any;
-    gtaoNodeClass: any;
-    ssrNode: any;
-    ssrPassClass: any;
-    paneClass: any;
-    createBrowserInspector: any;
+    gpuTier: TierResult | null;
+    fxaaNode: FXAAPostNode | null;
+    fxaaShader: typeof FXAAShader | null;
+    smaaPassClass: typeof SMAAPass | null;
+    smaaNode: typeof smaa | null;
+    ssaoPassClass: typeof SSAOPass | null;
+    gtaoNodeClass: typeof ao | null;
+    ssrNode: typeof ssr | null;
+    ssrPassClass: typeof SSRPass | null;
+    paneClass: typeof Pane | null;
+    createBrowserInspector: typeof createBrowserInspector | null;
     effectComposerClass: typeof EffectComposer | null;
     envLoader: EXRLoader | HDRLoader | null;
     dracoLoader: DRACOLoader | null;
@@ -1613,8 +1599,8 @@ declare class Modules {
     tslVec3: typeof THREE_WEBTSL_TYPE.vec3 | null;
     tslVec4: typeof THREE_WEBTSL_TYPE.vec4 | null;
     tslFloat: typeof THREE_WEBTSL_TYPE.float | null;
-    tslDirectionToColor: typeof THREE_WEBTSL_TYPE.directionToColor | null;
-    tslColorToDirection: typeof THREE_WEBTSL_TYPE.colorToDirection | null;
+    packNormalToRGB: typeof THREE_WEBTSL_TYPE.packNormalToRGB | null;
+    unpackRGBToNormal: typeof THREE_WEBTSL_TYPE.unpackRGBToNormal | null;
     private cfg;
     constructor(cfg: Cfg);
     private consoleLog;
@@ -1651,8 +1637,6 @@ export declare class Obj3D {
     /** @public */
     protected canvas: HTMLElement;
     protected cfg: Cfg;
-    /** @public */
-    protected readonly cfgCtrl: Readonly<CfgCtrl>;
     /* Excluded from this release type: events */
     protected name: string;
     /** The managed `THREE.Object3D` instance for this object. It is `null` until a scene object is assigned. */
@@ -1743,7 +1727,7 @@ export declare class Obj3D {
 }
 
 /** Constructor type for `Obj3D` classes. */
-export declare type Obj3DClass = new (canvas: HTMLElement, cfg: Cfg, cfgCtrl: CfgCtrl, name: string) => Objs3D;
+export declare type Obj3DClass = new (canvas: HTMLElement, cfg: Cfg, name: string) => Objs3D;
 
 /** Defines all event types supported by `Obj3D.addEventListener`. */
 export declare type Obj3DEvent = Obj3DPosWorldEvent | Obj3DPosScreenEvent | Obj3DVisibleEvent | Obj3DPointerEvent;
@@ -1810,25 +1794,11 @@ export declare type Objs3D = Cam3D | Light3D | Mesh3D | Obj3D;
 export declare class OrbitCtrls {
     private readonly cam3D;
     private readonly canvas;
-    private readonly cfg;
     private readonly engine;
     private readonly events;
     private readonly modules;
     orbitControls: OrbitControls_2 | null;
-    private enableDamping;
-    private dampingFactor;
-    private minDistance;
-    private maxDistance;
-    private enableZoom;
-    private zoomSpeed;
-    private enableRotate;
-    private rotateSpeed;
-    private enablePan;
-    private panSpeed;
-    private autoRotate;
-    private autoRotateSpeed;
-    private minPolarAngle;
-    private maxPolarAngle;
+    private readonly params;
     private orbitCtrlsFirstChange;
     private callback;
     private listenerPointersStart;
@@ -1843,6 +1813,11 @@ export declare class OrbitCtrls {
     enable(): void;
     /** Disposes three.js `OrbitControls` and removes them from the render loop. */
     dispose(): void;
+    /**
+     * Returns the parameters currently used by three.js `OrbitControls`.
+     * @returns A snapshot of the mutable orbit control settings.
+     */
+    get(): Partial<OrbitCtrlsCfg>;
     /**
      * Returns whether three.js `OrbitControls` are currently enabled.
      * @returns `true` if `OrbitControls` are currently enabled; otherwise, `false`.
@@ -1853,8 +1828,6 @@ export declare class OrbitCtrls {
      * @param params - Object containing any subset of orbit control parameters.
      */
     set(params: Partial<OrbitCtrlsCfg>): void;
-    /** Returns the current three.js `OrbitControls` configuration. */
-    get(): Partial<OrbitCtrlsCfg>;
     /**
      * Registers and executes a low-level extension function with access to the public `OrbitCtrls` API.
      *
@@ -2120,7 +2093,7 @@ export declare interface RenderCfg {
      * - `webgpu`: use `THREE.WebGPURenderer`
      * - `auto`: use WebGPU if supported, otherwise fall back to WebGL
      *
-     * @default 'auto'
+     * @default 'webgl'
      */
     api: Renderer;
     /**
@@ -2444,10 +2417,10 @@ export declare interface SsrWebGpuCfg {
      */
     maxDistance: number;
     /**
-     * Reflection opacity value.
+     * Reflection intensity value.
      * @default 0.5
      */
-    opacity: number;
+    intensity: number;
     /**
      * Ray thickness used for SSR intersection tests.
      * @default 0.018
@@ -2519,3 +2492,10 @@ export declare interface WindowResizeEvent {
 }
 
 export { }
+
+
+declare module 'three/addons/postprocessing/SSRPass.js' {
+    interface SSRPassParams {
+        bouncing?: boolean;
+    }
+}