> 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. Elas são usadas para iluminar a cena e criar uma sensação de profundidade e realismo, e podem ser usadas para criar diferentes ambientes e atmosferas. Por padrão, a cena é iluminada por 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 [Skybox Control](/creator/content-creator-pt/scenes-sdk7/interatividade/skybox-control.md) para mais informações. Você pode adicionar até 1 light por Parcel na sua cena. Há dois tipos de luzes suportados: * Luz pontual: Uma luz que brilha em todas as direções a partir de um ponto específico. * Luz spot: Uma luz que brilha em uma direção específica e cobre apenas uma área em forma de cone. {% hint style="warning" %} **📔 Nota**: Luzes que estão embutidas dentro de um `.glb` ou `.gltf` file são ignoradas pelo Decentraland. Se o seu modelo 3D foi exportado com luzes nele, elas não iluminarão nada na cena. As únicas fontes válidas de luz são entities que possuem o `LightSource` componente. Se você quiser que um modelo de lâmpada brilhe, adicione um `LightSource` à mesma entity, ou a uma child entity posicionada onde a lâmpada está. {% endhint %} {% hint style="info" %} **💡 Dica**: O catálogo de assets do Creator Hub tem smart items prontos **Spotlight** e **Point Light** smart items, na **lights** categoria. Cada um agrupa um modelo, um LightSource configurado, `LightSource`e ações Turn On, Turn Off e Toggle, então você não precisa escrever nenhum código. Há também uma **Spotlight** sob **decorações**, que é apenas um modelo e não emite luz. Escolha na **lights** categoria quando quiser iluminação real. {% endhint %} ## Adicionando uma light Para adicionar uma light à sua cena, você precisa criar uma entity de luz e adicionar o `LightSource` componente a ela. ```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 light com o brilho padrão mal será visível sob o sol do meio-dia, como no mundo real. Você pode usar o [Skybox Control](/creator/content-creator-pt/scenes-sdk7/interatividade/skybox-control.md) para forçar o skybox para a noite, ou aumentar o brilho definindo o `intensity` propriedade do `LightSource` componente para um valor mais alto. {% endhint %} ## Luzes spot As 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 entity. A abertura do cone é definida pelas `innerAngle` e `outerAngle` propriedades do `LightSource` componente. ```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 interno, onde a luz está com brilho total, e o `outerAngle` é o ângulo do cone externo, onde a luz vai se apagando gradualmente 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 point 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. ```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 `Color3` object, se não for especificado, será branco. Você pode definir isso para qualquer cor que quiser, o que pode ter um 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, esse é o brilho de uma lâmpada média no mundo real e pode ser visto até cerca de 10 metros de distância da light source. Se você precisar que a light fique visível de mais longe, ou durante o dia, você pode aumentar a intensidade. A distância em que a light fica visível é a raiz quarta do valor da intensidade (`intensity^0.25`). * Com uma intensidade de 625, a light fica visível até cerca de 5 metros de distância. * Com uma intensidade de 10000, a light fica visível até cerca de 10 metros de distância. * Com uma intensidade de 160000, a light fica visível até cerca de 20 metros de distância. ## Sombras Cada light pode ou não lançar sombras. Por padrão, não lançam, mas você pode ativá-las definindo o `shadow` propriedade do `LightSource` componente 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**: Sombras só têm suporte para spot lights. Point lights não têm suporte a sombras. Se houver várias luzes na cena, algumas delas podem não estar lançando sombras, veja [Otimização de luz](#light-optimization) para mais informações. {% endhint %} ## Ligando e desligando uma light O componente LightSource tem uma `active` propriedade que pode ser usada para ligar e desligar uma light. Isso é útil se você quiser desligar uma light sem removê-la da cena, ou sem definir o `intensity` para 0 e perder a referência de qual era a 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: 'Clique', }, }, function () { const lightSource = LightSource.getMutable(light) lightSource.active = !lightSource.active } ) ``` ## Otimização de luz As fontes de luz podem ter um impacto bastante grande no desempenho da sua cena. Por isso, o engine vai otimizar automaticamente a cena desativando algumas das luzes ou as suas sombras, começando pelas que estão mais distantes. O número de lights ativas permitidas em uma cena é limitado a uma por Parcel, e além disso depende das configurações de qualidade selecionadas pelo usuário. * Baixa qualidade: nenhuma light da cena * Qualidade média: máximo de 6 lights (em uma cena com parcels suficientes) * Alta qualidade: máximo de 10 lights (em uma cena com parcels suficientes) O controle deslizante de configurações de qualidade pode reduzir ainda mais o limite de um preset. Se houver mais lights do que o permitido, o engine desativará automaticamente lights com base na proximidade da light source ao player. À medida que o player se move, o engine reativará as lights que estiverem próximas o suficiente do player. {% hint style="warning" %} **📔 Nota**: No preset de baixa qualidade, as lights da cena são desligadas completamente. Um `LightSource` então não mostra nada, e nenhuma quantidade de ajustes de intensidade, alcance ou material muda isso. Se uma light "não funciona", verifique a configuração de qualidade antes de qualquer outra coisa. Considere Medium como a configuração mínima que sua cena suporta, em vez de exigir High. Um material emissivo que brilha não é prova de que uma light está funcionando. Um mesh de lâmpada brilhando e a luz que ele projeta nas superfícies próximas são duas coisas separadas a verificar. {% endhint %} Em todos os casos, o engine só vai renderizar sombras para até 3 light sources. Se houver mais lights com sombras do que 3, o engine desativará automaticamente as sombras das lights restantes que estiverem mais distantes. Além do número máximo de lights permitidas, as sombras também dependem da distância do player. As distâncias exatas variam conforme o tipo de light e as configurações de qualidade do player, mas, como regra geral: * A menos de 10 metros de distância: as sombras são renderizadas como soft shadows (alta qualidade) * Entre 10 e 20 metros de distância: as sombras são renderizadas como hard shadows (baixa qualidade) * A mais de 20 metros de distância: as sombras não são renderizadas As próprias fontes de luz continuam iluminando a cena a distâncias muito maiores: elas só são desativadas quando o player está a mais de 160 metros de distância (10 parcels). Isso torna as lights adequadas para configurações em grande escala, como iluminação de palco em eventos ao vivo, onde a maior parte da plateia está longe das light sources. Também é importante notar que as lights só são renderizadas se o player estiver dentro da cena. Se o player estiver fora da cena, as lights não serão renderizadas. ## Alcance da light O componente lightSource tem um `range` propriedade que pode ser usada para definir a distância máxima em que a light fica visível. Por padrão, o valor da `range` propriedade é -1, o que significa que o alcance da light depende da intensidade da light. 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 padrão garante que a curva de queda seja suave e pareça natural. Mas, caso queira limitar o alcance da light, você pode definir a `range` propriedade para 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 `range` propriedade para um número positivo cortará a light abruptamente na distância fornecida. Isso é útil se você quiser criar uma light 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 light realmente consegue alcançar com sua intensidade atual não terá nenhum efeito. {% endhint %} ## 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 filtro, que vai iluminar apenas partes da área. As máscaras são mais comumente usadas com spot lights, mas também podem ser usadas com point lights. Abaixo está um exemplo de uma spot light 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, você pode aplicar a imagem abaixo para produzir um efeito divertido em que a luz só fica visível nas áreas em que a textura é branca. Você pode usar isso com lights de qualquer cor e intensidade. ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-1c5642751dfc0b0047732fbbb86e611b492e392f%2Flightmask1.png?alt=media\&token=18ce6d0f-109b-420f-9402-1cbe85f5d123) Com uma imagem em preto e branco, a light está atingindo uma área ou não. Também é possível passar uma imagem com cores, e essas cores vão tingir sua light em cada área; isso pode ser usado para projetar um logo ou imagem coloridos sobre uma superfície. {% hint style="warning" %} **📔 Nota**: A imagem usada como máscara deve ter altura e largura em pixels que sejam uma potência de 2 (por exemplo: 1024, 512, 256). Esse recurso não funciona para imagens que tenham dimensões diferentes. {% endhint %} Ao aplicar uma máscara a uma point light, a textura será envolvida como um cubo ao redor da light source. Se você quiser evitar bordas visíveis entre os lados do cubo, certifique-se de que a textura tenha continuidade nas bordas. ```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 exibe cada uma das letras em lados diferentes do cubo (Y no topo, -Y na parte inferior, X à direita, -X à esquerda, Z na frente, -Z na parte de trás). ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-b68fe34eaab8dbaec996c3dca754e4742076f523%2Fpoint-light-mask1.png?alt=media\&token=d8d5037c-0d0e-4098-a45d-3b944f579b6a) {% hint style="info" %} **💡 Dica**: Combine lights com um [Sistema de Partículas](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/particle-system.md) para efeitos visuais mais ricos. Por exemplo, combine um sistema de partículas de fogo com blend aditivo com uma point light quente para criar uma fogueira convincente. {% endhint %} {% hint style="info" %} **💡 Dica**: Para um exemplo funcional deste componente, veja 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` e `LightSource.Type.Spot`, alterações em runtime via `LightSource.getMutable()`, sombras e `shadowMaskTexture`. {% endhint %} --- # 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=&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.