> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/lights.md).

# Luzes

Saiba como usar luzes na sua scene

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

Por predefinição, a Scene é iluminada por uma única luz direcional. Esta luz brilha numa direção específica e é utilizada para simular o sol ou a lua. Consulte [Skybox Control](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/skybox-control.md) para obter mais informações.

Pode adicionar até 1 luz por Parcel na sua Scene.

Existem dois tipos de luzes suportados:

* Luz pontual: uma luz que brilha em todas as direções a partir de um ponto específico.
* Holofote: uma luz que brilha numa direção específica e cobre apenas uma área em forma de cone.

{% hint style="warning" %}
**📔 Nota**: as luzes incorporadas num ficheiro `.glb` ou `.gltf` são ignoradas pelo Decentraland. Se o seu modelo 3D tiver sido exportado com luzes, estas não iluminarão nada na Scene. As únicas fontes de luz válidas são Entities que tenham o componente `LightSource` . Se quiser que um modelo de candeeiro emita luz, adicione um `LightSource` à mesma Entity ou a uma Entity filha posicionada onde se encontra a lâmpada.
{% endhint %}

{% hint style="info" %}
**💡 Sugestão**: o catálogo de assets do Creator Hub inclui Smart items prontos a utilizar: **Spotlight** e **Point Light** , na categoria **lights** . Cada um inclui um modelo, um componente `LightSource`, e as ações Turn On, Turn Off e Toggle, pelo que não precisa de escrever código. Há também um modelo decorativo de **Spotlight** Spotlight **decorations**, que é apenas um modelo e não emite luz. Escolha na categoria **lights** lights
{% endhint %}

## Adicionar uma luz

Para adicionar uma luz à sua Scene, tem de criar uma Entity de luz e adicionar-lhe o componente `LightSource` .

```ts
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({})
})
```

{% hint style="warning" %}
**📔 Nota**: uma luz com o brilho predefinido será praticamente impercetível sob o sol do meio-dia, como no mundo real. Pode utilizar o [Skybox Control](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/skybox-control.md) para definir o céu como noturno ou aumentar o brilho, atribuindo um valor mais elevado à propriedade `intensity` do componente `LightSource` .
{% endhint %}

## Holofotes

As luzes Spot são luzes que brilham numa 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 luz brilha na direção frontal da entidade (o seu eixo +Z local). A abertura do cone é definida pelas propriedades `innerAngle` e `outerAngle` do componente `LightSource` .

O exemplo abaixo roda a entidade 90 graus em torno do seu eixo X, fazendo com que a luz aponte diretamente para baixo. Uma rotação de -90 graus aponta a luz para o céu.

```ts
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 interior, onde a luz tem brilho máximo, e o `outerAngle` é o ângulo do cone exterior, onde a luz se desvanece gradualmente em direção às extremidades do cone. Pode experimentar estes valores para criar diferentes efeitos, com luzes mais focadas ou mais difusas.

## Intensidade e cor

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

```ts
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 objeto `Color3` ; se não for especificada, será branca. Pode definir qualquer cor que pretenda, o que pode ter um grande impacto no ambiente da cena.

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

A intensidade predefinida é 16000, equivalente ao brilho de uma lâmpada comum no mundo real, e a luz pode ser vista a uma distância de até cerca de 10 metros da fonte de luz. Se precisar que a luz seja visível a uma distância maior ou durante o dia, pode aumentar a intensidade.

A distância a que a luz é visível é a raiz quarta do valor da intensidade (`intensity^0.25`).

* Com uma intensidade de 625, a luz é visível a uma distância de até cerca de 5 metros.
* Com uma intensidade de 10000, a luz é visível a uma distância de até cerca de 10 metros.
* Com uma intensidade de 160000, a luz é visível a uma distância de até cerca de 20 metros.

## Sombras

Cada luz pode projetar sombras ou não. Por predefinição, não projeta, mas pode ativar as sombras definindo a propriedade `shadow` do componente `LightSource` como `true`.

```ts
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
})
```

{% hint style="warning" %}
**📔 Nota**: as sombras só são suportadas por luzes spot. As luzes point não suportam sombras. Se houver várias luzes na cena, algumas delas poderão não projetar sombras. Consulte [Otimização da luz](#light-optimization) para obter mais informações.
{% endhint %}

## Ligar e desligar uma luz

O componente LightSource tem uma propriedade `active` que pode ser usada para ligar e desligar uma luz. Isto é útil se quiser desligar uma luz sem a remover da cena ou sem definir a propriedade `intensity` como 0 e perder a referência da intensidade original.

```ts
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: 'Clicar',
		},
	},
	function () {
		const lightSource = LightSource.getMutable(light)
		lightSource.active = !lightSource.active
	}
)
```

## Otimização da iluminação

As fontes de luz podem ter um impacto bastante significativo no desempenho da sua cena. Por esse motivo, o Engine otimiza automaticamente a cena, desativando algumas luzes ou as respetivas sombras, começando pelas que estão mais distantes.

O número de luzes ativas permitido numa cena está limitado a uma por parcela e, além disso, depende das definições de qualidade selecionadas pelo utilizador.

* Qualidade baixa: nenhuma luz de cena
* Qualidade média: máximo de 6 luzes (numa cena com parcelas suficientes)
* Qualidade alta: máximo de 10 luzes (numa cena com parcelas suficientes)
* Dispositivos móveis: a aplicação tem as suas próprias predefinições, desde nenhuma luz de cena em Muito baixa até 8 luzes em Alta. Consulte [Luzes e partículas em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/optimize-performance.md#lights-and-particles).

O controlo deslizante das definições de qualidade pode reduzir ainda mais o limite de uma predefinição.

Se houver mais luzes do que o permitido, o Engine desativa automaticamente as luzes com base na proximidade da fonte de luz ao jogador. À medida que o jogador se desloca, o Engine volta a ativar as luzes que estiverem suficientemente próximas.

{% hint style="warning" %}
**📔 Nota**: Com a predefinição de qualidade Baixa, as luzes da cena são completamente desligadas. Uma configuração `LightSource` correta não produzirá qualquer efeito, e ajustar a intensidade, o alcance ou o material não mudará isso. Se uma luz «não funcionar», verifique primeiro a definição de qualidade. Considere Média como a definição mínima compatível com a sua cena, em vez de exigir Alta.

Um material emissivo que brilha não prova que a luz está a funcionar. O brilho da malha de uma lâmpada e a luz que esta projeta nas superfícies próximas são dois aspetos distintos a verificar.
{% endhint %}

Como alguns jogadores não veem nenhuma luz de cena (qualidade Baixa no computador e Muito baixa em dispositivos móveis), certifique-se de que a sua cena continua a funcionar sem elas. Tudo o que os jogadores precisam de ver, como o caminho a seguir ou um objeto com que possam interagir, deve destacar-se através de materiais emissivos, texturas ou do skybox. Use `LightSource` como um complemento, não como a única indicação. O mesmo se aplica às sombras: não faça com que uma sombra seja a única forma de perceber onde está um objeto.

Em todos os casos, o Engine só renderiza sombras para até 3 fontes de luz. Se mais de 3 luzes tiverem sombras, o Engine desativa automaticamente as sombras das luzes restantes que estiverem mais distantes.

Além do número máximo de luzes permitido, as sombras também dependem da distância ao jogador. As distâncias exatas variam consoante o tipo de luz e as definições de qualidade do jogador, mas, de forma geral:

* A menos de 10 metros: as sombras são renderizadas como sombras suaves (qualidade alta)
* Entre 10 e 20 metros: as sombras são renderizadas como sombras marcadas (qualidade baixa)
* A mais de 20 metros: as sombras não são renderizadas

As próprias fontes de luz continuam a iluminar a cena a distâncias muito maiores: só são desativadas quando o jogador está a mais de 160 metros (10 parcelas). Isto torna as luzes adequadas para configurações de grande escala, como a iluminação de palco em eventos ao vivo, onde a maioria do público está longe das fontes de luz.

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

## Alcance da luz

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

O alcance é calculado como a raiz quarta do valor da intensidade (`intensity^0.25`).

* Com uma intensidade de 16000, o alcance é de cerca de 11 metros.
* Com uma intensidade de 160000, o alcance é de cerca de 20 metros.
* Com uma intensidade de 1600000, o alcance é de cerca de 36 metros.

A configuração predefinida garante que a curva de atenuação seja suave e tenha um aspeto natural. Mas, se quiser limitar o alcance da luz, pode definir a propriedade `range` com um número positivo.

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

{% hint style="warning" %}
**📔 Nota**: definir a propriedade `range` com um número positivo fará com que a luz seja cortada abruptamente à distância indicada. Isto é útil se quiser criar uma luz visível apenas numa área específica ou otimizar o desempenho da sua cena. Definir `range` com um valor superior ao alcance que a luz pode efetivamente atingir com a intensidade atual não terá qualquer efeito.
{% endhint %}

## Máscaras de luz

Pode usar uma máscara de luz para criar efeitos interessantes. Em vez de iluminar toda a área, pode aplicar uma textura como filtro, para iluminar apenas algumas partes da área.

As máscaras são usadas mais frequentemente com luzes de foco, mas também podem ser usadas com luzes pontuais. Abaixo encontra-se um exemplo de uma luz de foco com uma máscara aplicada.

```ts
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, pode aplicar a imagem abaixo para criar um efeito divertido, em que a luz só é visível nas áreas onde a textura é branca. Pode usar isto com luzes de qualquer cor e intensidade.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-627d50cd64d3a398f5981e4214ce8acea38db1ae%2Flightmask1.webp?alt=media)

Com uma imagem a preto e branco, a luz incide ou não numa área. Também é possível fornecer uma imagem a cores, que irão colorir a luz em cada área. Isto pode ser usado para projetar um logótipo ou uma imagem coloridos numa superfície.

{% hint style="warning" %}
**📔 Nota**: a imagem usada como máscara tem de ter uma altura e uma largura em píxeis que sejam potências de 2 (por exemplo: 1024, 512, 256). Esta funcionalidade não funciona com imagens de dimensões diferentes.
{% endhint %}

Ao aplicar uma máscara a uma luz pontual, a textura é envolvida à volta da fonte de luz como um cubo. Para evitar que as arestas entre as faces do cubo fiquem visíveis, certifique-se de que a textura tem continuidade nas extremidades.

```ts
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 apresenta cada letra numa face diferente do cubo (Y em cima, -Y em baixo, X à direita, -X à esquerda, Z à frente, -Z atrás).

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-6a29274e27fdc61c72a8762745eb6a1d3c877e34%2Fpoint-light-mask1.webp?alt=media)

{% hint style="info" %}
**💡 Dica**: combine luzes com um [Sistema de partículas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/particle-system.md) para obter efeitos visuais mais ricos. Por exemplo, combine um sistema de partículas de fogo com mistura aditiva com uma luz pontual quente para criar uma fogueira convincente.
{% endhint %}

{% hint style="info" %}
**💡 Dica**: para ver um exemplo funcional deste componente, consulte a [`0,4-dynamic-lights`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,4-dynamic-lights) cena de teste, que abrange tanto `LightSource.Type.Point` como `LightSource.Type.Spot`, alterações em tempo de execução através de `LightSource.getMutable()`, sombras e `shadowMaskTexture`.
{% endhint %}

## Luzes no escuro

É mais fácil apreciar as luzes quando o céu não compete com elas. Os componentes `Skybox`, `Sun` e `EnvironmentFog` podem apagar a luz do sol, as cores do céu (e, consequentemente, a luz ambiente), o nevoeiro, as nuvens e as estrelas, tornando as luzes a única fonte de iluminação. Consulte [Escuridão total](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/skybox-control.md#complete-darkness).

Na predefinição de qualidade Baixa, as luzes da cena não são renderizadas, pelo que uma cena totalmente escura aparece completamente preta para esses jogadores. Use materiais emissivos para manter visível tudo o que for essencial. A aplicação para dispositivos móveis e o Explorer Bevy ainda não são compatíveis com estes componentes, pelo que os jogadores nesses clientes continuam a ver o céu normal.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/lights.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
