Luces

Aprende cómo usar luces en tu escena

Las luces son una parte fundamental de los gráficos 3D. Se utilizan para iluminar la escena y crear una sensación de profundidad y realismo, y pueden usarse para crear distintos estados de ánimo y atmósferas.

Por defecto, la escena está iluminada con una única luz direccional. Esta es una luz que brilla en una dirección específica y se usa para simular el sol o la luna. Ver Control de Skybox para más información.

Puedes añadir hasta 1 luz por parcela en tu escena.

Hay dos tipos de luces compatibles:

• Luz puntual: Una luz que brilla en todas las direcciones desde un punto específico.

• Luz spot: Una luz que brilla en una dirección específica y cubre solo un área con forma de cono.

Añadir una luz

Para añadir una luz a tu escena, necesitas crear una entidad de luz y añadir el LightSource componente a la misma.

import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
  type: LightSource.Type.Point({})
})

📔 Nota: Una luz con el brillo por defecto será apenas visible con el sol del mediodía, como en el mundo real. Puedes usar el Control de Skybox para forzar que el skybox sea de noche, o aumentar el brillo estableciendo la intensity propiedad del LightSource componente a un valor más alto.

Luces spot

Las luces spot son luces que brillan en una dirección específica y cubren un área con forma de cono. La dirección de la luz está definida por el componente Transform de la entidad. La apertura del cono está definida por el innerAngle y outerAngle propiedades del LightSource component.

import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
  rotation: Quaternion.fromEulerDegrees(-90, 0, 0),
})

LightSource.create(light, {
	type: LightSource.Type.Spot({
      innerAngle: 30,
      outerAngle: 60
    }),
	shadow: true
})

El innerAngle es el ángulo del cono interior, donde la luz tiene su máxima intensidad, y el outerAngle es el ángulo del cono exterior, donde la luz se va desvaneciendo gradualmente hacia los bordes del cono. Puedes jugar con estos valores para crear distintos efectos, para luces más enfocadas o más difusas.

Intensidad y color

Todas las luces, tanto puntuales como spot, tienen un color y una intensidad. El color se define mediante el color propiedad del LightSource componente, y la intensidad se define mediante la intensity propiedad.

import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
  type: LightSource.Type.Point({}),
  color: Color3.Red(),
  intensity: 10000,
})

El color es un Color3 objeto, si no se especifica será blanco. Puedes establecerlo en el color que desees, lo cual puede tener un gran impacto en el estado de ánimo de la escena.

La intensidad se expresa en candelas (lúmenes/m^2 a 1 m de distancia, o lúmenes divididos por 4*pi).

La intensidad por defecto es 16000, este es el brillo de una bombilla promedio en el mundo real y puede verse hasta aproximadamente 10 metros de distancia desde la fuente de luz. Si necesitas que la luz sea visible desde más lejos, o durante el día, puedes aumentar la intensidad.

La distancia a la que la luz es visible es la raíz cuadrada del valor de la intensidad.

• Con una intensidad de 100, la luz es visible hasta alrededor de 10 metros de distancia.

• Con una intensidad de 1000, la luz es visible hasta alrededor de 31 metros de distancia.

• Con una intensidad de 10000, la luz es visible hasta alrededor de 100 metros de distancia.

Sombras

Cada luz puede proyectar sombras o no. Por defecto no lo hacen, pero puedes habilitarlas estableciendo la shadow propiedad del LightSource componente a true.

import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
  rotation: Quaternion.fromEulerDegrees(-90, 0, 0),
})

LightSource.create(light, {
	type: LightSource.Type.Spot({
      innerAngle: 30,
      outerAngle: 60
    }),
	shadow: true
})

📔 Nota: Las sombras solo son compatibles con las luces spot. Las luces puntuales no soportan sombras. Si hay múltiples luces en la escena, algunas de ellas pueden no estar proyectando sombras, ver Light optimization para más información.

Encender y apagar una luz

El componente LightSource tiene una active propiedad que puede usarse para encender o apagar una luz. Esto es útil si quieres apagar una luz sin quitarla de la escena, o sin establecer la intensity a 0 y perder la referencia de cuál era la intensidad original.

import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
  rotation: Quaternion.fromEulerDegrees(-90, 0, 0),
})

LightSource.create(light, {
	type: LightSource.Type.Spot({
      innerAngle: 30,
      outerAngle: 60
    }),
	shadow: true
})

const switch = engine.addEntity()

Transform.create(switch, {
  position: Vector3.create(8, 1, 10),
})

MeshRenderer.setBox(switch, {})

MeshCollider.setBox(switch, {})

pointerEventsSystem.onPointerDown(
	{
		entity: switch,
		opts: {
			button: InputAction.IA_POINTER,
			hoverText: 'Click',
		},
	},
	function () {
		LightSource.getMutable(light).active = !LightSource.getMutable(light).active
	}
)

Light optimization

Las fuentes de luz pueden tener un impacto bastante grande en el rendimiento de tu escena. Por esta razón, el engine optimizará automáticamente la escena desactivando algunas de las luces o sus sombras, comenzando por las que están más lejos.

El número de luces activas permitidas en una escena está limitado a una por parcela, y más allá de eso depende de la configuración de calidad seleccionada por el usuario.

• Baja calidad: Máximo 4 luces (en una escena con suficientes parcelas)

• Calidad media: Máximo 6 luces (en una escena con suficientes parcelas)

• Alta calidad: Máximo 10 luces (en una escena con suficientes parcelas)

Si hay más luces de las permitidas, el engine desactivará automáticamente las luces según la proximidad de la fuente de luz al jugador. A medida que el jugador se mueve, el engine volverá a activar las luces que estén lo suficientemente cerca del jugador.

En todos los casos, el engine renderizará sombras solo para hasta 3 fuentes de luz. Si hay más de 3 luces con sombras, el engine desactivará automáticamente las sombras para las luces restantes que estén más lejos.

Además del número máximo de luces permitidas, las sombras también dependen de la distancia al jugador.

• A menos de 10 metros de distancia: Las sombras se renderizan como sombras suaves (alta calidad)

• Entre 10 y 20 metros de distancia: Las sombras se renderizan como sombras duras (baja calidad)

• Entre 20 y 40 metros de distancia: Las sombras no se renderizan

• A más de 40 metros de distancia: Las fuentes de luz no se renderizan en absoluto

También es importante notar que las luces solo se renderizan si el jugador está dentro de la escena. Si el jugador está fuera de la escena, las luces no se renderizarán.

Alcance de la luz

El componente LightSource tiene una range propiedad que puede usarse para establecer la distancia máxima a la que la luz es visible. Por defecto, el valor de la range propiedad es -1, lo que significa que el alcance de la luz depende de la intensidad de la misma.

• Con una intensidad de 16000, el alcance es de 10 metros.

• Con una intensidad de 160000, el alcance es de 31 metros.

• Con una intensidad de 1600000, el alcance es de 100 metros.

La configuración por defecto garantiza que la curva de caída sea suave y se vea natural. Pero en caso de que quieras limitar el alcance de la luz, puedes establecer la range propiedad a un número positivo.

import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
  type: LightSource.Type.Point({}),
  intensity: 16000,
  range: 20,
})

📔 Nota: Establecer la range propiedad a un número positivo cortará abruptamente la luz a la distancia indicada. Esto es útil si deseas crear una luz que solo sea visible en un área específica, o para optimizar el rendimiento de tu escena. Establecer la range a un valor mayor del que la luz puede alcanzar con su intensidad actual no tendrá ningún efecto.

Máscaras de luz

Puedes usar una máscara de luz para producir algunos efectos interesantes. En lugar de iluminar toda el área, puedes aplicar una textura que se use como filtro y que solo ilumine partes del área.

Las máscaras se usan más típicamente con luces spot, pero también pueden usarse con luces puntuales. A continuación hay un ejemplo de una luz spot con una máscara aplicada.

import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
	type: LightSource.Type.Spot({
      innerAngle: 30,
      outerAngle: 60
    }),
	shadow: true,
	shadowMaskTexture: Material.Texture.Common({src: "assets/scene/images/lightmask1.png"})         
})

Por ejemplo, puedes aplicar la imagen a continuación para producir un efecto divertido donde la luz solo sea visible en las áreas donde la textura es blanca. Puedes usar esto con luces de cualquier color e intensidad.

Con una imagen en blanco y negro, la luz o bien impacta un área o no. También es posible pasar una imagen con colores, y esos colores tintarán tu luz en cada área; esto puede usarse para proyectar un logo o imagen coloreada sobre una superficie.

📔 Nota: La imagen usada como máscara debe tener una altura y un ancho en píxeles que sea una potencia de 2 (por ejemplo: 1024, 512, 256). Esta función no funciona con imágenes que tengan dimensiones diferentes.

Al aplicar una máscara a una luz puntual, la textura se envolverá como un cubo alrededor de la fuente de luz. Si quieres evitar que se vean bordes entre los lados del cubo, asegúrate de que la textura tenga continuidad en los bordes.

import { engine, LightSource } from '@dcl/sdk/ecs'

const light = engine.addEntity()

Transform.create(light, {
  position: Vector3.create(10, 3, 10),
})

LightSource.create(light, {
	type: LightSource.Type.Point({}),
	shadowMaskTexture: Material.Texture.Common({src: "assets/scene/images/point-light-mask1.png"})         
})

Por ejemplo, la imagen a continuación muestra cada una de las letras en diferentes lados del cubo (Y en la parte superior, -Y en la parte inferior, X a la derecha, -X a la izquierda, Z en el frente, -Z en la parte trasera).