@needle-tools/engine/lib/engine-components/ReflectionProbe.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 { Material, Object3D, Texture, Vector3 } from "three";
import { Context } from "../engine/engine_setup.js";
import { Behaviour } from "./Component.js";
import { EventList } from "./EventList.js";
export declare const debug: string | number | boolean;
/**
 * The [ReflectionProbe](https://engine.needle.tools/docs/api/ReflectionProbe) provides environment reflection data to materials within its defined area.
 * Use for chrome-like materials that need accurate environment reflections.
 *
 * **Setup:**
 * 1. Add ReflectionProbe component to an object
 * 2. Assign a cubemap or HDR texture
 * 3. In Renderer components, assign the probe as anchor override
 *
 * **Note:** Volume-based automatic assignment is not fully supported yet.
 * Objects (Renderer components) can explicitly reference their reflection probe.
 *
 * **Debug options:**
 * - `?debugreflectionprobe` - Log probe info
 * - `?noreflectionprobe` - Disable all reflection probes
 *
 * - Example: https://engine.needle.tools/samples/reflection-probes
 *
 * @summary Provides reflection data to materials
 * @category Rendering
 * @group Components
 * @see {@link Renderer} for material and rendering control
 * @see {@link Light} for scene lighting
 */
export declare class ReflectionProbe extends Behaviour {
    private static _probes;
    private static testBox;
    /**
     * Checks if the given material is currently using a reflection probe.
     * This is determined by checking for an override on the material's "envMap" property, which is set by the Renderer component when applying a reflection probe.
     */
    static isUsingReflectionProbe(material: Material): boolean;
    /**
     * Event invoked when a reflection probe is enabled. Used internally by Renderer components to update probes when they become active. Not recommended to call this directly in most cases.
     * @see {@link onDisabled} for the corresponding disable event.
     */
    static readonly onEnabled: EventList<ReflectionProbe>;
    /**
     * Event invoked when a reflection probe is disabled. Used internally by Renderer components to update probes when they become inactive. Not recommended to call this directly in most cases.
     * @see {@link onEnabled} for the corresponding enable event.
     */
    static readonly onDisabled: EventList<ReflectionProbe>;
    /**
     * Gets the active reflection probe for the given object and context. If `isAnchor` is true, it will only return a probe if the object is the anchor of that probe. Otherwise, it checks if the object is within the probe's influence area.
     *
     * Note: This method is used internally by the Renderer component to determine which reflection probe to apply. It is not recommended to call this method directly in most cases. Instead, assign probes to renderers using the "anchor" property or rely on automatic assignment when supported.
     * Note: Volume-based automatic assignment is not fully supported yet, so explicit assignment is recommended for now.
     *
     * @param object The object to find a reflection probe for
     * @param context The context to search within
     * @param isAnchor If true, only return a probe if the object is the anchor of that probe
     * @param anchor Optional anchor object to match against probes
     */
    static get(object: Object3D | null | undefined, context: Context, isAnchor: boolean, anchor?: Object3D): ReflectionProbe | null;
    private _texture;
    private _textureUrlInFlight?;
    /**
     * The cubemap or HDR texture used for reflections. Can be assigned directly or via a URL string.
     * When assigning via URL, the texture will be loaded asynchronously and applied once ready.
     * @param tex The texture or URL to assign to this reflection probe
     * @default null
     */
    set texture(tex: Texture | null);
    get texture(): Texture | null;
    /**
     * The intensity of the reflection probe's influence.
     *  Higher values will make reflections brighter, while lower values will make them dimmer.
     * The default value is 1, which means the reflections will be applied at their original brightness. Adjust this value to achieve the desired look for your scene.
     * @default 1
     */
    intensity: number;
    /**
     * Defines the center of the reflection probe's influence area relative to the GameObject's position.
     * The probe will affect objects within a box defined by this center and the `size` property.
     * Note: The actual influence area is determined by both the `center` and `size` properties. The `center` defines the offset from the GameObject's position, while the `size` defines the dimensions of the box around that center. Objects within this box will be influenced by the reflection probe.
     */
    center: Vector3;
    /**
     * Defines the size of the reflection probe's influence area. Objects within this box will be affected by the probe's reflections.
     * Note: The actual influence area is determined by both the `center` and `size` properties. The `center` defines the offset from the GameObject's position, while the `size` defines the dimensions of the box around that center. Objects within this box will be influenced by the reflection probe.
     */
    size: Vector3;
    /**
     * Workaround for lightmap. Compensates for the fact that lightmaps are pre-multiplied by intensity, while reflection probes are not. This means that if you use both lightmaps and reflection probes, you may need to adjust this value to get the correct balance between them. The default value of `Math.PI` is a good starting point for most cases, but you may need to tweak it based on your specific lighting setup and artistic needs.
     */
    __lightmapIntensityScale: boolean;
    private isInBox;
    constructor();
    /** @internal */
    awake(): void;
    /** @internal */
    update(): void;
    /** @internal */
    onEnable(): void;
    /** @internal */
    onDisable(): void;
    /** @internal */
    start(): void;
    /** @internal */
    onDestroy(): void;
    /**
     * Applies this reflection probe to the given object by setting material property overrides for "envMap", "envMapRotation", and "envMapIntensity".
     * This is typically called by the Renderer component when determining which reflection probe to use for a given object.
     * @param object The object to apply the reflection probe to
     * @see {@link unapply} for the corresponding method to remove the probe's influence from an object.
     */
    apply(object: Object3D): void;
    /**
     * Removes the reflection probe overrides from the given object.
     * This is typically called by the Renderer component when an object is no longer influenced by this probe or when the probe is disabled.
     * @param object The object to remove the reflection probe overrides from
     * @see {@link apply} for the corresponding method to apply the probe's influence to an object.
     */
    unapply(obj: Object3D): void;
}