Lights

Aprende cómo usar lights en tu scene

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 usarse para crear distintos estados de ánimo y atmósferas.

De forma predeterminada, la escena está iluminada 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. Consulta Control del skybox para más información.

Puedes añadir hasta 1 luz por parcel 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.

Agregar una luz

Para añadir una luz a tu escena, necesitas crear una entity de luz y añadir el LightSource component 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 apenas será visible con el sol del mediodía, como en el mundo real. Puedes usar el Control del skybox para forzar el skybox a la noche, o aumentar el brillo estableciendo el intensity propiedad del LightSource component 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 específica con forma de cono. La dirección de la luz está definida por el component Transform de la entity. La apertura del cono está definida por los innerAngle y outerAngle propiedades del LightSource componente.

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 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 distintos efectos, con 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 component, y la intensidad está definida por 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 al color que quieras, lo que puede tener un gran impacto en el estado de ánimo de la escena.

La intensidad se expresa en candels (lumens/m^2 a 1 m de distancia, o lumens divididos por 4*pi).

La intensidad predeterminada es 16000; esta es el brillo de una bombilla promedio en el mundo real y puede verse hasta a unos 10 metros de distancia de la source 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 intensidad.

Con una intensidad de 100, la luz es visible hasta unos 10 metros de distancia.
Con una intensidad de 1000, la luz es visible hasta unos 31 metros de distancia.
Con una intensidad de 10000, la luz es visible hasta unos 100 metros de distancia.

Sombras

Cada luz puede proyectar sombras o no. Por defecto no lo hacen, pero puedes activarlas estableciendo el shadow propiedad del LightSource component 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 luces spot. Las luces puntuales no admiten sombras. Si hay varias luces en la escena, es posible que algunas no estén proyectando sombras; consulta Optimización de luces para más información.

Encender y apagar una luz

El component LightSource tiene una active propiedad que puede usarse para encender y apagar una luz. Esto es útil si quieres apagar una luz sin quitarla de la escena, o sin establecer el 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
	}
)

Optimización de luces

Las source 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 lejos.

La cantidad de luces activas permitidas en una escena está limitada a una por parcel, y a partir de ahí depende de los ajustes de calidad seleccionados por el usuario.

Calidad baja: Máximo 4 luces (en una escena con suficientes parcels)
Calidad media: Máximo 6 luces (en una escena con suficientes parcels)
Calidad alta: Máximo 10 luces (en una escena con suficientes parcels)

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

En todos los casos, el engine solo renderizará sombras para hasta 3 source de luz. Si hay más luces con sombras que 3, el engine desactivará automáticamente las sombras de 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 player.

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 source de luz no se renderizan en absoluto

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

Alcance de la luz

El component lightSource tiene una range propiedad que puede usarse 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 alcance de la luz depende de la intensidad de la luz.

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 predeterminada garantiza que la curva de atenuación 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á bruscamente la luz a 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 a un valor mayor del 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 algunos efectos interesantes. En lugar de iluminar toda el área, puedes aplicar una texture para usarla como filtro que solo iluminará 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 de abajo para producir un efecto divertido en el que la luz solo es 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 está o bien impactando un área o no. También es posible pasar una imagen con colores, y estos colores teñirán tu luz en cada área; esto puede usarse para proyectar un logo o imagen de color sobre una surface.

📔 Nota: La imagen usada como máscara debe tener una altura y anchura en píxeles que sea una potencia de 2 (por ejemplo: 1024, 512, 256). Esta feature no funciona para imágenes que tienen dimensiones diferentes.

Al aplicar una máscara a una luz puntual, la texture se envolverá como un cubo alrededor de la source de luz. Si quieres evitar bordes visibles entre los lados del cubo, asegúrate de que la texture 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 obtener efectos visuales más ricos. Por ejemplo, combina un Particle System de fuego con blend aditivo y una luz puntual cálida para crear una fogata convincente.

AnteriorEntity Positioning SiguienteMaterials

Última actualización hace 1 mes