Luces

Aprende cómo usar luces en tu escena

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

De forma predeterminada, la escena se ilumina con una sola 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 Skybox Control 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 ella.

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 predeterminado será apenas visible con el sol del mediodía, como en el mundo real. Puedes usar el Skybox Control para forzar al skybox a la hora nocturna, o aumentar el brillo estableciendo el 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 específica. La dirección de la luz está definida por el componente Transform de la entidad. La apertura del cono está definida por los 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
})

La innerAngle es el ángulo del cono interior, donde la luz tiene su brillo máximo, y el outerAngle es el ángulo del cono exterior, donde la luz se desvanece gradualmente hacia los bordes del cono. Puedes jugar con estos valores para crear diferentes 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 está definido por el color propiedad del LightSource componente, y la intensidad está definida por el 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 cualquier color que quieras, lo que 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 predeterminada es 16000; este es el brillo de una bombilla promedio en el mundo real y puede verse hasta a unos 10 metros de distancia de 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 cuarta del valor de intensidad (intensity^0.25).

Con una intensidad de 625, la luz es visible hasta a unos 5 metros de distancia.
Con una intensidad de 10000, la luz es visible hasta a unos 10 metros de distancia.
Con una intensidad de 160000, la luz es visible hasta a unos 20 metros de distancia.

Sombras

Cada luz puede proyectar sombras o no. De forma predeterminada, no lo hacen, pero puedes activarlas estableciendo el shadow propiedad del LightSource componente en 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 admiten sombras. Si hay varias luces en la escena, puede que algunas no estén proyectando sombras; ver Optimización de luces para más información.

Encender y apagar una luz

El componente LightSource tiene una active propiedad que se puede usar para encender y apagar una luz. Esto es útil si quieres apagar una luz sin eliminarla de la escena, o sin establecer el intensity en 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,
	active: true
})

const lightSwitch = engine.addEntity()

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

MeshRenderer.setBox(lightSwitch)

MeshCollider.setBox(lightSwitch)

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

Optimización de luces

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, empezando por las que estén más alejadas.

El número de luces activas permitido 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.

Calidad baja: máximo 4 luces (en una escena con suficientes parcelas)
Calidad media: máximo 6 luces (en una escena con suficientes parcelas)
Calidad alta: 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 solo renderizará sombras de hasta 3 fuentes de luz. Si hay más de 3 luces con sombras, el engine desactivará automáticamente las sombras de las luces restantes que estén más alejadas.

Además del número máximo de luces permitidas, las sombras también dependen de la distancia al jugador. Las distancias exactas varían según el tipo de luz y la configuración de calidad del jugador, pero como regla general:

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)
A más de 20 metros de distancia: las sombras no se renderizan

Las propias fuentes de luz siguen iluminando la escena a distancias mucho mayores: solo se desactivan cuando el jugador está a más de 160 metros de distancia (10 parcelas). Esto hace que las luces sean adecuadas para configuraciones a gran escala, como la iluminación de escenarios en eventos en vivo, donde la mayor parte de la audiencia está lejos de las fuentes de luz.

También es importante tener en cuenta 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.

Rango de luz

El componente LightSource tiene una range propiedad que se puede usar para establecer la distancia máxima a la que la luz es visible. De forma predeterminada, el valor de la range propiedad es -1, lo que significa que el rango de la luz depende de la intensidad de la luz.

El rango se calcula como la raíz cuarta del valor de intensidad (intensity^0.25).

Con una intensidad de 16000, el rango es de unos 11 metros.
Con una intensidad de 160000, el rango es de unos 20 metros.
Con una intensidad de 1600000, el rango es de unos 36 metros.

La configuración predeterminada garantiza que la curva de caída sea suave y se vea natural. Pero, en caso de que quieras limitar el rango 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 en la distancia proporcionada. Esto es útil si quieres crear una luz que solo sea visible en un área específica, o para optimizar el rendimiento de tu escena. Establecer la range en un valor mayor que lo que la luz puede alcanzar realmente con su intensidad actual no tendrá ningún efecto.

Máscaras de luz

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

Las máscaras suelen usarse más con luces spot, pero también pueden usarse con luces puntuales. A continuación se muestra 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 de abajo para producir un efecto divertido en el que la luz solo es visible en las áreas donde la textura es blanca. También puedes usar esto con luces de cualquier color e intensidad.

Con una imagen en blanco y negro, la luz o bien incide en un área o no lo hace. También es posible pasar una imagen con colores, y esos colores teñirán tu luz en cada área; esto puede usarse para proyectar un logotipo o una imagen de color sobre una superficie.

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

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 tener bordes visibles 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 de abajo muestra cada una de las letras en distintos lados del cubo (Y arriba, -Y abajo, X a la derecha, -X a la izquierda, Z al frente, -Z atrás).

💡 Consejo: Combina luces con un Particle System para conseguir efectos visuales más ricos. Por ejemplo, combina un Particle System de partículas de fuego con mezcla aditiva y una luz puntual cálida para crear una hoguera convincente.

💡 Consejo: Para ver un ejemplo funcional de este componente, consulta la 0,4-dynamic-lights escena de prueba, que cubre tanto LightSource.Type.Point y LightSource.Type.Spot, cambios en tiempo de ejecución mediante LightSource.getMutable(), sombras, y shadowMaskTexture.

AnteriorPosicionamiento de entidades

SiguienteMateriales

Última actualización hace 20 días