illutions 0.21.7 → 0.21.9

package/CHANGELOG.md

@@ -1,7 +1,13 @@
-# Changelog
-
-## Unreleased
-
-### Changed
-
-- Removed the Illutions Engine defaults from `render.webgl.parameters` and `render.webgpu.parameters`. Both renderers now use the default parameter values provided by Three.js.
+# Changelog
+
+## 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

@@ -93,7 +93,6 @@ export declare interface AnimFadeEvent {
  */
 export declare class App<TClasses extends Classes = {}> {
     readonly audio: Audio_2;
-    readonly cfgCtrl: CfgCtrl;
     readonly engine: Engine;
     readonly envCtrls: EnvCtrls;
     readonly events: Events;
@@ -127,16 +126,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 +196,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 +215,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 }
 
@@ -217,6 +223,11 @@ export { Audio_2 as Audio }
  * @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
@@ -448,39 +459,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<AudioCfg>): 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`.
  *
@@ -527,7 +508,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>;
@@ -1121,20 +1101,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;
@@ -1154,7 +1125,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;
@@ -1646,8 +1620,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. */
@@ -1738,7 +1710,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;
@@ -1805,25 +1777,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;
@@ -1838,6 +1796,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`.
@@ -1848,8 +1811,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.
      *