Luzes

Aprenda como usar luzes em sua cena

As luzes são uma parte fundamental dos gráficos 3D. Elas são usadas para iluminar a cena e criar uma sensação de profundidade e realismo, e podem ser usadas para criar diferentes humores e atmosferas.

Por padrão, a cena é iluminada com uma única luz direcional. Esta é uma luz que brilha em uma direção específica e é usada para simular o sol ou a lua. Veja Controle do Skybox para mais informações.

Você pode adicionar até 1 luz por parcela na sua cena.

Existem dois tipos de luzes suportadas:

• Luz pontual (Point light): Uma luz que brilha em todas as direções a partir de um ponto específico.

• Luz spot (Spot light): Uma luz que brilha em uma direção específica e cobre apenas uma área em forma de cone.

Adicionando uma luz

Para adicionar uma luz à sua cena, você precisa criar uma entidade de luz e adicionar o LightSource componente a ela.

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: Uma luz com o brilho padrão será dificilmente visível com o sol ao meio-dia, como no mundo real. Você pode usar o Controle do Skybox para forçar o skybox para o período noturno, ou aumentar o brilho definindo a intensity propriedade do LightSource componente para um valor maior.

Luzes Spot

Luzes spot são luzes que brilham em uma direção específica e cobrem uma área específica em forma de cone. A direção da luz é definida pelo componente Transform da entidade. A abertura do cone é definida pelo innerAngle e outerAngle propriedades do 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
})

O innerAngle é o ângulo do cone interno, onde a luz está em brilho total, e o outerAngle é o ângulo do cone externo, onde a luz gradualmente desaparece em direção às bordas do cone. Você pode brincar com esses valores para criar efeitos diferentes, para luzes mais focadas ou mais difusas.

Intensidade e cor

Todas as luzes, tanto pontuais quanto spot, têm uma cor e uma intensidade. A cor é definida pelo color propriedade do LightSource componente, e a intensidade é definida pela intensity propriedade.

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,
})

A cor é um Color3 objeto; se não especificado será branco. Você pode definir isso para qualquer cor que desejar, o que pode ter grande impacto no clima da cena.

A intensidade é expressa em candelas (lumens/m^2 a 1 m de distância, ou lumens divididos por 4*pi).

A intensidade padrão é 16000; esta é o brilho de uma lâmpada média no mundo real e pode ser vista até cerca de 10 metros de distância da fonte de luz. Se você precisar que a luz seja visível de mais longe, ou durante o dia, você pode aumentar a intensidade.

A distância na qual a luz é visível é a raiz quadrada do valor da intensidade.

• Com intensidade de 100, a luz é visível até cerca de 10 metros de distância.

• Com intensidade de 1000, a luz é visível até cerca de 31 metros de distância.

• Com intensidade de 10000, a luz é visível até cerca de 100 metros de distância.

Sombras

Cada luz pode gerar sombras ou não. Por padrão não geram, mas você pode habilitá-las definindo o shadow propriedade do LightSource componente para 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: Sombras são suportadas apenas para luzes spot. Luzes pontuais (Point lights) não suportam sombras. Se houver múltiplas luzes na cena, algumas delas podem não estar projetando sombras; veja Light optimization para mais informações.

Ligando e desligando uma luz

O componente LightSource tem uma active propriedade que pode ser usada para ligar e desligar uma luz. Isso é útil se você quiser apagar uma luz sem removê-la da cena, ou sem definir a intensity para 0 e perder a referência do que a intensidade original era.

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,
		// RAYCAST DE DIREÇÃO LOCAL
			button: InputAction.IA_POINTER,
			hoverText: 'Click',
		},
	},
	function () {
		LightSource.getMutable(light).active = !LightSource.getMutable(light).active
	}
)

Light optimization

As fontes de luz podem ter um impacto considerável no desempenho da sua cena. Por esse motivo, o engine otimizará automaticamente a cena desativando algumas luzes ou suas sombras, começando pelas que estão mais distantes.

O número permitido de luzes ativas em uma cena é limitado a uma por parcela, e além disso depende das configurações de qualidade selecionadas pelo usuário.

• Baixa qualidade: Máximo de 4 luzes (em uma cena com parcelas suficientes)

• Qualidade média: Máximo de 6 luzes (em uma cena com parcelas suficientes)

• Alta qualidade: Máximo de 10 luzes (em uma cena com parcelas suficientes)

Se houver mais luzes do que o permitido, o engine desativará automaticamente luzes com base na proximidade da fonte de luz ao jogador. À medida que o jogador se move, o engine reativará luzes que estiverem suficientemente próximas ao jogador.

Em todos os casos, o engine renderizará sombras para no máximo 3 fontes de luz. Se houver mais luzes com sombras do que 3, o engine desativará automaticamente as sombras para as luzes restantes que estiverem mais distantes.

Além do número máximo de luzes permitidas, as sombras também dependem da distância do jogador.

• A menos de 10 metros de distância: Sombras são renderizadas como sombras suaves (alta qualidade)

• Entre 10 e 20 metros de distância: Sombras são renderizadas como sombras duras (baixa qualidade)

• Entre 20 e 40 metros de distância: Sombras não são renderizadas

• A mais de 40 metros de distância: Fontes de luz não são renderizadas de forma alguma

Também é importante notar que as luzes são renderizadas apenas se o jogador estiver dentro da cena. Se o jogador estiver fora da cena, as luzes não serão renderizadas.

Alcance da luz

O componente lightSource tem uma range propriedade que pode ser usada para definir a distância máxima na qual a luz é visível. Por padrão, o valor da range propriedade é -1, o que significa que o alcance da luz depende da intensidade da luz.

• Com intensidade de 16000, o alcance é de 10 metros.

• Com intensidade de 160000, o alcance é de 31 metros.

• Com intensidade de 1600000, o alcance é de 100 metros.

A configuração padrão garante que a curva de queda seja suave e pareça natural. Mas caso você queira limitar o alcance da luz, você pode definir a range propriedade para um 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: Definir a range propriedade para um número positivo cortará abruptamente a luz na distância fornecida. Isso é útil se você quiser criar uma luz que seja visível apenas em uma área específica, ou para otimizar o desempenho da sua cena. Definir a range para um valor maior do que o que a luz pode realmente alcançar com sua intensidade atual não terá nenhum efeito.

Máscaras de luz

Você pode usar uma máscara de luz para produzir alguns efeitos interessantes. Em vez de iluminar toda a área, você pode aplicar uma textura para ser usada como um filtro que iluminará apenas partes da área.

Máscaras são mais tipicamente usadas com luzes spot, mas também podem ser usadas com luzes pontuais. Abaixo está um exemplo de uma luz spot com uma 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 exemplo, você pode aplicar a imagem abaixo para produzir um efeito divertido onde a luz é visível apenas nas áreas onde a textura é branca. Você pode usar isso com luzes de qualquer cor e intensidade.

Com uma imagem em preto e branco, a luz ou atinge uma área ou não. Também é possível passar uma imagem com cores, e essas cores irão colorir (tint) sua luz em cada área; isso pode ser usado para projetar um logo colorido ou imagem em uma superfície.

📔 Nota: A imagem usada como máscara deve ter altura e largura em pixels que sejam potências de 2 (ex: 1024, 512, 256). Este recurso não funciona para imagens que tenham dimensões diferentes.

Ao aplicar uma máscara a uma luz pontual, a textura será mapeada como um cubo ao redor da fonte de luz. Se você quiser evitar ter bordas visíveis entre os lados do cubo, certifique-se de que a textura tenha continuidade nas bordas.

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 exemplo, a imagem abaixo exibe cada uma das letras em diferentes lados do cubo (Y em cima, -Y embaixo, X à direita, -X à esquerda, Z na frente, -Z atrás).