@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.
590 lines (528 loc) • 20.7 kB
text/typescript
import { CameraHelper, Color, DirectionalLight, DirectionalLightHelper, Light as ThreeLight, OrthographicCamera, PointLight, SpotLight, Vector3 } from "three";
import { serializable } from "../engine/engine_serialization_decorator.js";
import { FrameEvent } from "../engine/engine_setup.js";
import { setWorldPositionXYZ } from "../engine/engine_three_utils.js";
import type { ILight } from "../engine/engine_types.js";
import { getParam } from "../engine/engine_utils.js";
import { Behaviour, GameObject } from "./Component.js";
// https://threejs.org/examples/webgl_shadowmap_csm.html
function toDegrees(radians) {
return radians * 180 / Math.PI;
}
function toRadians(degrees) {
return degrees * Math.PI / 180;
}
const shadowMaxDistance = 300;
const debug = getParam("debuglights");
/**
* Defines the type of light in a scene.
* @see {@link Light} for configuring light properties and behavior
*/
export 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 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
*/
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 class Light extends Behaviour implements ILight {
/**
* The type of light (spot, directional, point, etc.)
* Can not be changed at runtime.
*/
private type: LightType = 0;
/**
* The maximum distance the light affects.
* Only applicable for spot and point lights.
*/
get range(): number {
return this._range;
}
set range(value: number) {
this._range = value;
if (this.light && (this.light.type === "SpotLight" || this.light.type === "PointLight") && ("distance" in this.light)) {
this.light.distance = value;
}
}
private _range: number = 1;
/**
* The full outer angle of the spotlight cone in degrees.
* Only applicable for spot lights.
*/
get spotAngle(): number {
return this._spotAngle;
}
set spotAngle(value: number) {
this._spotAngle = value;
if (this.light && this.light.type === "SpotLight" && ("angle" in this.light)) {
(this.light as SpotLight).angle = toRadians(value / 2);
}
}
private _spotAngle: number = 30;
/**
* 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 {
return this._innerSpotAngle;
}
set innerSpotAngle(value: number) {
this._innerSpotAngle = value;
if (this.light && this.light.type === "SpotLight" && ("penumbra" in this.light)) {
const outerAngle = this.spotAngle;
const innerAngle = value;
const penumbra = 1 - (toRadians(innerAngle / 2) / toRadians(outerAngle / 2));
(this.light as SpotLight).penumbra = penumbra;
}
}
private _innerSpotAngle: number = 10;
/**
* The color of the light
*/
set color(val: Color) {
this._color = val;
if (this.light !== undefined) {
this.light.color = val;
}
}
get color(): Color {
if (this.light) return this.light.color;
return this._color;
}
public _color: Color = new Color(0xffffff);
/**
* The near plane distance for shadow projection
*/
set shadowNearPlane(val: number) {
if (val === this._shadowNearPlane) return;
this._shadowNearPlane = val;
if (this.light?.shadow?.camera !== undefined) {
const cam = this.light.shadow.camera as OrthographicCamera;
cam.near = val;
}
}
get shadowNearPlane(): number { return this._shadowNearPlane; }
private _shadowNearPlane: number = .1;
/**
* Shadow bias value to reduce shadow acne and peter-panning
*/
set shadowBias(val: number) {
if (val === this._shadowBias) return;
this._shadowBias = val;
if (this.light?.shadow?.bias !== undefined) {
this.light.shadow.bias = val;
this.light.shadow.needsUpdate = true;
}
}
get shadowBias(): number { return this._shadowBias; }
private _shadowBias: number = 0;
/**
* Shadow normal bias to reduce shadow acne on sloped surfaces
*/
set shadowNormalBias(val: number) {
if (val === this._shadowNormalBias) return;
this._shadowNormalBias = val;
if (this.light?.shadow?.normalBias !== undefined) {
this.light.shadow.normalBias = val;
this.light.shadow.needsUpdate = true;
}
}
get shadowNormalBias(): number { return this._shadowNormalBias; }
private _shadowNormalBias: number = 0;
/** when enabled this will remove the multiplication when setting the shadow bias settings initially */
private _overrideShadowBiasSettings: boolean = false;
/**
* Shadow casting mode (None, Hard, or Soft)
*/
set shadows(val: LightShadows) {
this._shadows = val;
if (this.light) {
this.light.castShadow = val !== LightShadows.None;
this.updateShadowSoftHard();
}
}
get shadows(): LightShadows { return this._shadows; }
private _shadows: LightShadows = 1;
/**
* Determines if the light contributes to realtime lighting, baked lighting, or a mix
*/
private lightmapBakeType: LightmapBakeType = LightmapBakeType.Realtime;
/**
* 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) {
this._intensity = val;
if (this.light) {
this.light.intensity = val;
}
if (debug) console.log("Set light intensity to " + this._intensity, val, this)
}
get intensity(): number { return this._intensity; }
private _intensity: number = -1;
/**
* Maximum distance the shadow is projected
*/
get shadowDistance(): number {
const light = this.light;
if (light?.shadow) {
const cam = light.shadow.camera as OrthographicCamera;
return cam.far;
}
return -1;
}
set shadowDistance(val: number) {
this._shadowDistance = val;
const light = this.light;
if (light?.shadow) {
const cam = light.shadow.camera as OrthographicCamera;
cam.far = val;
cam.updateProjectionMatrix();
}
}
private _shadowDistance?: number;
// set from additional component
private shadowWidth?: number;
private shadowHeight?: number;
/**
* Resolution of the shadow map in pixels (width and height)
*/
get shadowResolution(): number {
const light = this.light;
if (light?.shadow) {
return light.shadow.mapSize.x;
}
return -1;
}
set shadowResolution(val: number) {
if (val === this._shadowResolution) return;
this._shadowResolution = val;
const light = this.light;
if (light?.shadow) {
light.shadow.mapSize.set(val, val);
light.shadow.needsUpdate = true;
}
}
private _shadowResolution?: number = undefined;
/**
* Whether this light's illumination is entirely baked into lightmaps
*/
get isBaked() {
return this.lightmapBakeType === LightmapBakeType.Baked;
}
/**
* Checks if the GameObject itself is a {@link ThreeLight} object
*/
private get selfIsLight(): boolean {
if (this.gameObject["isLight"] === true) return true;
switch (this.gameObject.type) {
case "SpotLight":
case "PointLight":
case "DirectionalLight":
return true;
}
return false;
}
/**
* The underlying three.js {@link ThreeLight} instance
*/
private light: ThreeLight | undefined = undefined;
/**
* Gets the world position of the light
* @param vec Vector3 to store the result
* @returns The world position as a Vector3
*/
public getWorldPosition(vec: Vector3): Vector3 {
if (this.light) {
if (this.type === LightType.Directional) {
return this.light.getWorldPosition(vec).multiplyScalar(1);
}
return this.light.getWorldPosition(vec);
}
return vec;
}
awake() {
this.color = new Color(this.color ?? 0xffffff);
if (debug) console.log(this.name, this);
}
onEnable(): void {
if (debug) console.log("ENABLE LIGHT", this.name);
this.createLight();
if (this.isBaked) return;
else if (this.light) {
this.light.visible = true;
this.light.intensity = this._intensity;
if (debug) console.log("Set light intensity to " + this.light.intensity, this.name)
if (this.selfIsLight) {
// nothing to do
}
else if (this.light.parent !== this.gameObject)
this.gameObject.add(this.light);
}
if (this.type === LightType.Directional)
this.startCoroutine(this.updateMainLightRoutine(), FrameEvent.LateUpdate);
}
onDisable() {
if (debug) console.log("DISABLE LIGHT", this.name);
if (this.light) {
if (this.selfIsLight)
this.light.intensity = 0;
else
this.light.visible = false;
}
}
/**
* Creates the appropriate three.js light based on the configured light type
* and applies all settings like shadows, intensity, and color.
*/
createLight() {
const lightAlreadyCreated = this.selfIsLight;
if (lightAlreadyCreated && !this.light) {
this.light = this.gameObject as unknown as ThreeLight;
this.light.name = this.name;
this._intensity = this.light.intensity;
switch (this.type) {
case LightType.Directional:
this.setDirectionalLight(this.light as DirectionalLight);
break;
}
}
else if (!this.light) {
switch (this.type) {
case LightType.Directional:
// console.log(this);
const dirLight = new DirectionalLight(this.color, this.intensity * Math.PI);
// directional light target is at 0 0 0 by default
dirLight.position.set(0, 0, -shadowMaxDistance * .5).applyQuaternion(this.gameObject.quaternion);
this.gameObject.add(dirLight.target);
setWorldPositionXYZ(dirLight.target, 0, 0, 0);
this.light = dirLight;
this.gameObject.position.set(0, 0, 0);
this.gameObject.rotation.set(0, 0, 0);
if (debug) {
const spotLightHelper = new DirectionalLightHelper(this.light as DirectionalLight, .2, this.color);
this.context.scene.add(spotLightHelper);
// const bh = new BoxHelper(this.context.scene, 0xfff0000);
// this.context.scene.add(bh);
}
break;
case LightType.Spot:
const spotLight = new SpotLight(this.color, this.intensity * Math.PI, this.range, toRadians(this.spotAngle / 2), 1 - toRadians(this.innerSpotAngle / 2) / toRadians(this.spotAngle / 2), 2);
spotLight.position.set(0, 0, 0);
spotLight.rotation.set(0, 0, 0);
this.light = spotLight;
const spotLightTarget = spotLight.target;
spotLight.add(spotLightTarget);
spotLightTarget.position.set(0, 0, this.range);
spotLightTarget.rotation.set(0, 0, 0);
break;
case LightType.Point:
const pointLight = new PointLight(this.color, this.intensity * Math.PI, this.range);
this.light = pointLight;
// const pointHelper = new PointLightHelper(pointLight, this.range, this.color);
// scene.add(pointHelper);
break;
}
}
if (this.light) {
if (this._intensity >= 0)
this.light.intensity = this._intensity;
else
this._intensity = this.light.intensity;
if (this.shadows !== LightShadows.None) {
this.light.castShadow = true;
}
else this.light.castShadow = false;
if (this.light.shadow) {
// shadow intensity is currently not a thing: https://github.com/mrdoob/three.js/pull/14087
if (this._shadowResolution !== undefined && this._shadowResolution > 4) {
this.light.shadow.mapSize.width = this._shadowResolution;
this.light.shadow.mapSize.height = this._shadowResolution;
}
else {
this.light.shadow.mapSize.width = 2048;
this.light.shadow.mapSize.height = 2048;
}
// this.light.shadow.needsUpdate = true;
// console.log(this.light.shadow.mapSize);
// return;
if (debug)
console.log("Override shadow bias?", this._overrideShadowBiasSettings, this.shadowBias, this.shadowNormalBias);
this.light.shadow.bias = this.shadowBias;
this.light.shadow.normalBias = this.shadowNormalBias;
this.updateShadowSoftHard();
const cam = this.light.shadow.camera as OrthographicCamera;
cam.near = this.shadowNearPlane;
// use shadow distance that was set explictly (if any)
if (this._shadowDistance !== undefined && typeof this._shadowDistance === "number")
cam.far = this._shadowDistance;
else // otherwise fallback to object scale and max distance
cam.far = shadowMaxDistance * Math.abs(this.gameObject.scale.z);
// width and height
this.gameObject.scale.set(1, 1, 1);
if (this.shadowWidth !== undefined) {
cam.left = -this.shadowWidth / 2;
cam.right = this.shadowWidth / 2;
}
else {
const sx = this.gameObject.scale.x;
cam.left *= sx;
cam.right *= sx;
}
if (this.shadowHeight !== undefined) {
cam.top = this.shadowHeight / 2;
cam.bottom = -this.shadowHeight / 2;
}
else {
const sy = this.gameObject.scale.y;
cam.top *= sy;
cam.bottom *= sy;
}
this.light.shadow.needsUpdate = true;
if (debug)
this.context.scene.add(new CameraHelper(cam));
}
if (this.isBaked) {
this.light.removeFromParent();
}
else if (!lightAlreadyCreated)
this.gameObject.add(this.light);
}
}
/**
* Coroutine that updates the main light reference in the context
* if this directional light should be the main light
*/
*updateMainLightRoutine() {
while (true) {
if (this.type === LightType.Directional) {
if (!this.context.mainLight || this.intensity > this.context.mainLight.intensity) {
this.context.mainLight = this;
}
yield;
}
break;
}
}
/**
* Controls whether the renderer's shadow map type can be changed when soft shadows are used
*/
static allowChangingRendererShadowMapType: boolean = true;
/**
* Updates shadow settings based on whether the shadows are set to hard or soft
*/
private updateShadowSoftHard() {
if (!this.light) return;
if (!this.light.shadow) return;
if (this.shadows === LightShadows.Soft) {
// const radius = this.light.shadow.mapSize.width / 1024 * 5;
// const samples = Mathf.clamp(Math.round(radius), 2, 10);
// this.light.shadow.radius = radius;
// this.light.shadow.blurSamples = samples;
// if (isMobileDevice()) {
// this.light.shadow.radius *= .5;
// this.light.shadow.blurSamples = Math.floor(this.light.shadow.blurSamples * .5);
// }
// if (Light.allowChangingRendererShadowMapType) {
// if(this.context.renderer.shadowMap.type !== VSMShadowMap){
// if(isLocalNetwork()) console.warn("Changing renderer shadow map type to VSMShadowMap because a light with soft shadows enabled was found (this will cause all shadow receivers to also cast shadows). If you don't want this behaviour either set the shadow type to hard or set Light.allowChangingRendererShadowMapType to false.", this);
// this.context.renderer.shadowMap.type = VSMShadowMap;
// }
// }
}
else {
this.light.shadow.radius = 1;
this.light.shadow.blurSamples = 1;
}
}
/**
* Configures a directional light by adding and positioning its target
* @param dirLight The directional light to set up
*/
private setDirectionalLight(dirLight: DirectionalLight) {
dirLight.add(dirLight.target);
dirLight.target.position.set(0, 0, -1);
// dirLight.position.add(vec.set(0,0,1).multiplyScalar(shadowMaxDistance*.1).applyQuaternion(this.gameObject.quaternion));
}
}
const vec = new Vector3(0, 0, 0);