@needle-tools/engine/lib/engine-components/Light.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { Color, Vector3 } from "three";
import type { ILight } from "../engine/engine_types.js";
import { type NeedleXREventArgs } from "../engine/xr/api.js";
import { Behaviour } from "./Component.js";
/**
 * Defines the type of light in a scene.
 */
export declare enum LightType {
    /** Spot light that emits light in a cone shape */
    Spot = 0,
    /** Directional light that emits parallel light rays in a specific direction */
    Directional = 1,
    /** Point light that emits light in all directions from a single point */
    Point = 2,
    /** Area light */
    Area = 3,
    /** Rectangle shaped area light that only affects baked lightmaps and light probes */
    Rectangle = 3,
    /** Disc shaped area light that only affects baked lightmaps and light probes */
    Disc = 4
}
/**
 * Defines how a light contributes to the scene lighting.
 */
export declare enum LightmapBakeType {
    /** Light affects the scene in real-time with no baking */
    Realtime = 4,
    /** Light is completely baked into lightmaps and light probes */
    Baked = 2,
    /** Combines aspects of realtime and baked lighting */
    Mixed = 1
}
/**
 * Defines the shadow casting options for a Light.
 * @enum {number}
 */
declare enum LightShadows {
    /** No shadows are cast */
    None = 0,
    /** Hard-edged shadows without filtering */
    Hard = 1,
    /** Soft shadows with PCF filtering */
    Soft = 2
}
/**
 * The Light component creates a light source in the scene.
 * Supports directional, spot, and point light types with various customization options.
 * Lights can cast shadows with configurable settings and can be set to baked or realtime rendering.
 *
 * Debug mode can be enabled with the URL parameter `?debuglights`, which shows
 * additional console output and visual helpers for lights.
 *
 * @category Rendering
 * @group Components
 */
export declare class Light extends Behaviour implements ILight {
    /**
     * The type of light (spot, directional, point, etc.)
     */
    private type;
    /**
     * The maximum distance the light affects
     */
    range: number;
    /**
     * The full outer angle of the spotlight cone in degrees
     */
    spotAngle: number;
    /**
     * The angle of the inner cone in degrees for soft-edge spotlights
     */
    innerSpotAngle: number;
    /**
     * The color of the light
     */
    set color(val: Color);
    get color(): Color;
    _color: Color;
    /**
     * The near plane distance for shadow projection
     */
    set shadowNearPlane(val: number);
    get shadowNearPlane(): number;
    private _shadowNearPlane;
    /**
     * Shadow bias value to reduce shadow acne and peter-panning
     */
    set shadowBias(val: number);
    get shadowBias(): number;
    private _shadowBias;
    /**
     * Shadow normal bias to reduce shadow acne on sloped surfaces
     */
    set shadowNormalBias(val: number);
    get shadowNormalBias(): number;
    private _shadowNormalBias;
    /** when enabled this will remove the multiplication when setting the shadow bias settings initially */
    private _overrideShadowBiasSettings;
    /**
     * Shadow casting mode (None, Hard, or Soft)
     */
    set shadows(val: LightShadows);
    get shadows(): LightShadows;
    private _shadows;
    /**
     * Determines if the light contributes to realtime lighting, baked lighting, or a mix
     */
    private lightmapBakeType;
    /**
     * Brightness of the light. In WebXR experiences, the intensity is automatically
     * adjusted based on the AR session scale to maintain consistent lighting.
     */
    set intensity(val: number);
    get intensity(): number;
    private _intensity;
    /**
     * Maximum distance the shadow is projected
     */
    get shadowDistance(): number;
    set shadowDistance(val: number);
    private _shadowDistance?;
    private shadowWidth?;
    private shadowHeight?;
    /**
     * Resolution of the shadow map in pixels (width and height)
     */
    get shadowResolution(): number;
    set shadowResolution(val: number);
    private _shadowResolution?;
    /**
     * Whether this light's illumination is entirely baked into lightmaps
     */
    get isBaked(): boolean;
    /**
     * Checks if the GameObject itself is a {@link ThreeLight} object
     */
    private get selfIsLight();
    /**
     * The underlying three.js {@link ThreeLight} instance
     */
    private light;
    /**
     * Gets the world position of the light
     * @param vec Vector3 to store the result
     * @returns The world position as a Vector3
     */
    getWorldPosition(vec: Vector3): Vector3;
    awake(): void;
    onEnable(): void;
    onDisable(): void;
    private _webXRStartedListener?;
    private _webXREndedListener?;
    private _webARRoot?;
    onEnterXR(_args: NeedleXREventArgs): void;
    onLeaveXR(_args: NeedleXREventArgs): void;
    /**
     * Creates the appropriate three.js light based on the configured light type
     * and applies all settings like shadows, intensity, and color.
     */
    createLight(): void;
    /**
     * Coroutine that updates the main light reference in the context
     * if this directional light should be the main light
     */
    updateMainLightRoutine(): Generator<undefined, void, unknown>;
    /**
     * Controls whether the renderer's shadow map type can be changed when soft shadows are used
     */
    static allowChangingRendererShadowMapType: boolean;
    /**
     * Updates shadow settings based on whether the shadows are set to hard or soft
     */
    private updateShadowSoftHard;
    /**
     * Configures a directional light by adding and positioning its target
     * @param dirLight The directional light to set up
     */
    private setDirectionalLight;
}
export {};