Illutions Engine API - v0.26.0
    Preparing search index...

    Class Engine

    The Engine class serves as the core runtime of the illutions Engine. It initializes and manages the Three.js scene, renderer, camera, lighting, post-processing, and loaded models. The class orchestrates rendering, animation playback, and material updates, while integrating system events, raycasting, and performance monitoring. It provides the foundation for real-time interaction and visual consistency across all scene components.

    Index
    addOnFrameUpdate animCamCurveTo animCamTo animMaterialColor animMaterialNumeric enableAaMode enableSsao enableSsr playClip playClipCam removeAmbientLight removeFog removeHemisphereLight removeOnFrameUpdate setAmbientLight setFog setHemisphereLight setMaterialProperties stopAnimClip toggleFullscreen updateCanvasResize use

    • Registers a callback that is executed on every requestAnimationFrame update.

      Parameters

      • cb: (deltaTime: number) => void

        Callback executed once per frame with deltaTime.

      Returns void

    • Animates the camera on a curved path towards a target position while optionally updating the camera's look-at target.

      Parameters

      • params: {
            aimTarget?: string | Vector3 | Obj3D;
            camTarget: string | Vector3 | Obj3D;
            duration?: number;
            ease?: string;
            radiusOut?: number;
        }

        Parameter object for the animation.

        • OptionalaimTarget?: string | Vector3 | Obj3D

          The target the camera should face during or after the animation.

        • camTarget: string | Vector3 | Obj3D

          The target the camera should move toward.

        • Optionalduration?: number

          The animation duration in seconds. Default: 2

        • Optionalease?: string

          The easing function name for GSAP. Default: 'power1.inOut'

        • OptionalradiusOut?: number

          The outward curve radius used to shape the camera path. Default: 1

      Returns void

      The method resolves camTarget and optionally aimTarget to world positions and animates the camera position along a curved trajectory instead of a straight line. If aimTarget is provided, the camera target position is interpolated towards the resolved aim position while the camera moves along the curve.

      Events

      AnimEvent

    • Animates the THREE.PerspectiveCamera towards a target object and frames it based on its own geometry. The camera keeps the resolved target object as the look-at target while its distance is calculated from the object's bounding size and the camera's field of view.

      Parameters

      • params: { dist?: number; duration?: number; ease?: string; target: string | Obj3D }

        Parameter object for the animation.

        • Optionaldist?: number

          Framing factor applied to the calculated camera distance. Default: 1

        • Optionalduration?: number

          The animation duration in seconds. Default: 1

        • Optionalease?: string

          The easing function name for GSAP. Default: 'power2.inOut'

        • target: string | Obj3D

          The target object or the name of the target object.

      Returns void

      Only the target object's own geometry is used to calculate the bounding size. Child objects are intentionally ignored.

      Events

      AnimEvent

    • The method finds a Three.js mesh by name, validates that it has a material with color properties and animates them (e.g. color, emissive, ...).

      Parameters

      • params: { duration?: number; ease?: string; mesh: string } & {
            [key: string]: string | number | Color;
        }

        Parameter object for the animation.

        • Optionalduration?: number

          The animation duration in seconds. Default: 0

        • Optionalease?: string

          The easing function name for GSAP. Default: 'power1.inOut'

        • mesh: string

          The name of the mesh object whose material color should be animated.

        • [key: string]: string | number | Color

      Returns void

      Additional properties of params can specify one or more material color fields to animate (e.g. color, emissive, ...), with their target color values. Values may be color strings, numbers, or THREE.Color instances.

      Events

      AnimEvent

    • The method finds a Three.js mesh by name, validates that it has a material with numeric properties (e.g. metalness, roughness, opacity, etc.) and animates them over time using GSAP.

      Parameters

      • params: {
            duration?: number;
            ease?: string;
            infinite?: boolean;
            mesh: string;
            startValue?: number | null;
            [key: string]: any;
        }

        Parameter object for the animation.

        • [key: string]: any
        • Optionalduration?: number

          The animation duration in seconds. Default: 0

        • Optionalease?: string

          The easing function name for GSAP. Default: 'power1.inOut'

        • Optionalinfinite?: boolean

          If true, the animation loops infinitely. Default: false

        • mesh: string

          The name of the mesh object whose material property will be animated.

        • OptionalstartValue?: number | null

          The starting value of the property. Default: Current material's value

      Returns void

      Additional properties of params can specify one or more material numeric fields to animate (e.g. metalness, roughness, opacity, ...) with their target numeric values. Only the first provided property will be animated per call.

      Events

      AnimFadeEvent

    • Selects the active anti-aliasing mode. The modes 'fxaa', 'smaa' and 'traa' lazy-load their required modules.

      Parameters

      • aaMode: "none" | "fxaa" | "smaa" | "traa"

        The anti-aliasing mode to use.

      Returns Promise<void>

    • Enables or disables screen-space ambient occlusion. Passing true lazy-loads the required module.

      Parameters

      • enable: boolean

        Whether SSAO should be enabled.

      Returns Promise<void>

    • Enables or disables screen-space reflections. In WebGL mode, the SSR pass also synchronizes the ground reflector and the optional selective reflection objects. When SSR is disabled, the reflector is detached from the pass and hidden. Passing true lazy-loads the required module.

      Parameters

      • enable: boolean

        Whether SSR should be enabled.

      Returns Promise<void>

    • Finds a Three.js animation clip by name and plays it through the THREE.AnimationMixer.

      Parameters

      • params: {
            blendMode?: BlendMode;
            clip: string;
            duration?: number;
            ease?: string;
            endSpeed?: number;
            fadeDuration?: number;
            fadeDurationFinish?: number;
            finishMode?: FinishMode;
            layer: string;
            loopMode?: LoopMode;
            reset?: boolean;
            reverse?: boolean;
            singleAction?: boolean;
            startSpeed?: number;
            stopMode?: StopMode;
        }

        Parameters for controlling the animation playback.

        • OptionalblendMode?: BlendMode

          How the action is blended with other active actions. Default: 'normal'

        • clip: string

          The name of the animation clip to play.

        • Optionalduration?: number

          Duration in seconds for speed interpolation. Default: 0

        • Optionalease?: string

          GSAP easing function name. Default: 'power1.inOut'

        • OptionalendSpeed?: number

          Target playback speed. Default: 1

        • OptionalfadeDuration?: number

          Duration in seconds for fading affected previous actions out and the new action in. Default: 0

        • OptionalfadeDurationFinish?: number

          Duration in seconds for finishMode: 'fadeOut'. Default: 0

        • OptionalfinishMode?: FinishMode

          Whether the final pose is held or faded out after the final loop. Default: 'hold'

        • layer: string

          The freely named layer used to group animation actions.

        • OptionalloopMode?: LoopMode

          Number of plays or 'infinite' for endless looping. Default: 1

        • Optionalreset?: boolean

          If true, resets the clip before a new playback. Default: false

        • Optionalreverse?: boolean

          If true, plays the clip in reverse. Default: false

        • OptionalsingleAction?: boolean
        • OptionalstartSpeed?: number

          Initial playback speed for speed interpolation. Default: 0

        • OptionalstopMode?: StopMode

          Which previous actions of the same layer are stopped before playback. Default: 'all'

      Returns void

      Calling a running or fading-in action again is ignored. A finished or stopped action starts again, while an unfinished fading-out action continues at its current time and fades back in from its current weight.

      finishMode and fadeDurationFinish have no effect when loopMode is 'infinite'.

      Events

      ClipEvent

    • Finds a camera animation clip by name and plays it through the THREE.AnimationMixer.

      Parameters

      • params: {
            blendMode?: BlendMode;
            clip: string;
            duration?: number;
            ease?: string;
            endSpeed?: number;
            fadeDuration?: number;
            layer: string;
            loopMode?: LoopMode;
            reset?: boolean;
            reverse?: boolean;
            startSpeed?: number;
            stopMode?: StopMode;
        }

        Parameters for controlling the camera animation playback.

        • OptionalblendMode?: BlendMode

          How the action is blended with other active actions. Default: 'normal'

        • clip: string

          The name of the camera animation clip to play.

        • Optionalduration?: number

          Duration in seconds for speed interpolation. Default: 0

        • Optionalease?: string

          GSAP easing function name. Default: 'power1.inOut'

        • OptionalendSpeed?: number

          Target playback speed. Default: 1

        • OptionalfadeDuration?: number

          Duration in seconds for fading affected previous actions out and the new action in. Default: 0

        • layer: string

          The freely named layer used to group camera animation actions.

        • OptionalloopMode?: LoopMode

          Number of plays or 'infinite' for endless looping. Default: 1

        • Optionalreset?: boolean

          If true, resets the clip before a new playback. Default: false

        • Optionalreverse?: boolean

          If true, plays the clip in reverse. Default: false

        • OptionalstartSpeed?: number

          Initial playback speed for speed interpolation. Default: 0

        • OptionalstopMode?: StopMode

          Which previous actions of the same layer are stopped before playback. Default: 'all'

      Returns void

      Calling a running or fading-in action again is ignored. A finished or stopped action starts again, while an unfinished fading-out action continues at its current time and fades back in from its current weight.

      Events

      ClipEvent

    • The method removes the existing THREE.AmbientLight from the scene and releases its resources. If no ambient light exists, the method exits without performing any action.

      Returns void

    • The method removes the existing THREE.Fog from the scene. If no fog exists, the method exits without performing any action.

      Returns void

    • The method removes the existing THREE.HemisphereLight from the scene and releases its resources. If no hemisphere light exists, the method exits without performing any action.

      Returns void

    • Removes a previously registered frame update callback.

      Parameters

      • cb: (deltaTime: number) => void

        Callback to remove.

      Returns void

    • The method creates or updates a Three.js THREE.AmbientLight instance in the scene.

      Parameters

      • params: { color?: ColorRepresentation; intensity?: number }

        Parameter object for controlling the ambient light.

        • Optionalcolor?: ColorRepresentation

          The ambient light color. If omitted and the light already exists, the current color remains unchanged.

        • Optionalintensity?: number

          The ambient light intensity. If omitted and the light already exists, the current intensity remains unchanged.

      Returns void

      The method does not apply any default values when creating the light. Creation is skipped unless both color and intensity are defined. When updating an existing light, the scene reflects changes automatically on the next render call.

    • The method creates or updates a Three.js THREE.Fog instance in the scene.

      Parameters

      • params: { color?: ColorRepresentation; far?: number; near?: number }

        Parameter object for controlling the fog.

        • Optionalcolor?: ColorRepresentation

          The fog color. If omitted and the fog already exists, the current color remains unchanged.

        • Optionalfar?: number

          The far distance where fog ends. If omitted and the fog already exists, the current far value remains unchanged.

        • Optionalnear?: number

          The near distance where fog starts. If omitted and the fog already exists, the current near value remains unchanged.

      Returns void

      The method does not apply any default values when creating the fog. Creation is skipped unless color, near and far are defined. When updating an existing fog, the scene reflects changes automatically on the next render call.

    • The method creates or updates a Three.js THREE.HemisphereLight instance in the scene.

      Parameters

      • params: {
            groundColor?: ColorRepresentation;
            intensity?: number;
            skyColor?: ColorRepresentation;
        }

        Parameter object for controlling the hemisphere light.

        • OptionalgroundColor?: ColorRepresentation

          The ground light color. If omitted and the light already exists, the current ground color remains unchanged.

        • Optionalintensity?: number

          The hemisphere light intensity. If omitted and the light already exists, the current intensity remains unchanged.

        • OptionalskyColor?: ColorRepresentation

          The sky light color. If omitted and the light already exists, the current sky color remains unchanged.

      Returns void

      The method does not apply any default values when creating the light. Creation is skipped unless skyColor, groundColor and intensity are defined. When updating an existing light, the scene reflects changes automatically on the next render call.

    • The method finds a Three.js mesh by name, validates that it has a material, and updates one or more of its material properties at runtime. It supports both numeric and color values as well as texture paths (map, emissiveMap), which are automatically loaded via THREE.TextureLoader.

      Parameters

      • params: { obj: string; [key: string]: any }

        Parameter object for setting material properties.

        • [key: string]: any
        • obj: string

          The name of the mesh whose material properties should be modified.

      Returns void

      Additional properties of params can define one or more material fields to update (e.g. color, roughness, metalness, map, emissiveMap, ...), each with its target value. Texture paths provided as strings are loaded asynchronously and assigned to the corresponding material slots. Unsupported or mismatched property types are ignored with a warning in debug mode.

    • The method finds a Three.js animation clip by name, validates that it exists within the loaded GLTF, and stops its playback via the THREE.AnimationMixer. It supports smooth fade-out transitions using GSAP before stopping the clip completely.

      Parameters

      • params: { clipName: string; ease?: string; fadeOut?: number }

        Parameter object for controlling the stop behavior.

        • clipName: string

          The name of the animation clip to stop.

        • Optionalease?: string

          The easing function name for the fade-out transition. Default: 'power1.inOut'

        • OptionalfadeOut?: number

          The fade-out duration in seconds before stopping the clip. Default: 0

      Returns void

      The method gradually reduces the clip's playback speed to zero when fadeOut is greater than zero. It emits CLIP_SPEED_START, CLIP_SPEED_COMPLETE, and finally CLIP_CANCEL. If no speed transition is specified, the clip is canceled immediately.

      Events

      ClipEvent

    • Toggles the browser fullscreen mode for the associated canvas element.

      Returns void

    • Updates the renderer, post-processing composer, and ground reflector to match the current canvas size. Ensures that the rendering resolution and reflection buffers remain consistent when the viewport changes.

      Returns void

    • Registers and executes a low-level extension function with access to the public Engine API.

      Parameters

      • extension: (engine: Engine) => void

        Function that receives the current Engine instance and can use its public members and methods.

      Returns void

      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.

    Settings
    Member Visibility

    On This Page
    Methods