@needle-tools/engine
Version:
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.
212 lines (211 loc) • 6.93 kB
TypeScript
import { Color, Vector3 } from "three";
import type { ILight } from "../engine/engine_types.js";
import { Behaviour } from "./Component.js";
/**
* Defines the type of light in a scene.
* @see {@link Light} for configuring light properties and behavior
*/
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.
* @see {@link Light} for configuring light properties and behavior
*/
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}
* @see {@link Light} for configuring shadow settings
*/
declare enum LightShadows {
/** No shadows are cast */
None = 0,
/** Hard-edged shadows without filtering */
Hard = 1,
/** Soft shadows with PCF filtering */
Soft = 2
}
/**
* [Light](https://engine.needle.tools/docs/api/Light) creates a light source in the scene for illuminating 3D objects.
*
* **Light types:**
* - `Directional` - Sun-like parallel rays (best for outdoor scenes)
* - `Point` - Omnidirectional from a point (bulbs, candles)
* - `Spot` - Cone-shaped (flashlights, stage lights)
*
* **Shadows:**
* Enable shadows via `shadows` property. Configure quality with shadow resolution
* settings. Directional lights support adaptive shadow cascades.
*
* **Performance tips:**
* - Use baked lighting (`lightmapBakeType = Baked`) when possible
* - Limit shadow-casting lights (1-2 recommended)
* - Reduce shadow resolution for mobile
*
* **Debug:** Use `?debuglights` URL parameter for visual helpers.
*
* @example Configure a directional light
* ```ts
* const light = myLight.getComponent(Light);
* light.intensity = 1.5;
* light.color = new Color(1, 0.95, 0.9); // Warm white
* light.shadows = LightShadows.Soft;
* ```
*
* @summary Light component for various light types and shadow settings
* @category Rendering
* @group Components
* @see {@link LightType} for available light types
* @see {@link ReflectionProbe} for environment reflections
* @see {@link Camera} for rendering configuration
*/
export declare class Light extends Behaviour implements ILight {
/**
* The type of light (spot, directional, point, etc.)
* Can not be changed at runtime.
*/
private type;
/**
* The maximum distance the light affects.
* Only applicable for spot and point lights.
*/
get range(): number;
set range(value: number);
private _range;
/**
* The full outer angle of the spotlight cone in degrees.
* Only applicable for spot lights.
*/
get spotAngle(): number;
set spotAngle(value: number);
private _spotAngle;
/**
* The angle of the inner cone in degrees for soft-edge spotlights.
* Must be less than or equal to the outer spot angle.
* Only applicable for spot lights.
*/
get innerSpotAngle(): number;
set innerSpotAngle(value: number);
private _innerSpotAngle;
/**
* 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;
/**
* 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 {};