> 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-es/scenes-sdk7/fundamentos-del-contenido-3d/lights.md). # 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 usarse para crear diferentes 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](/creator/content-creator-es/scenes-sdk7/interactividad/skybox-control.md) para obtener más información. Puedes agregar 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 de foco: una luz que brilla en una dirección específica y cubre solo un área con forma de cono. {% hint style="warning" %} **📔 Nota**: Las luces que están incrustadas dentro de un `.glb` ni `.gltf` archivo son ignoradas por Decentraland. Si tu modelo 3D fue exportado con luces, no iluminarán nada en la escena. Las únicas fuentes de luz válidas son las entidades que tienen el `LightSource` componente. Si quieres que el modelo de una lámpara brille, agrega un `LightSource` a la misma entidad, o a una entidad hija posicionada donde está la bombilla. {% endhint %} {% hint style="info" %} **💡 Consejo**: El catálogo de activos de Creator Hub tiene **Foco** y **Luz puntual** smart items listos para usar, en la categoría de **luces** . Cada uno incluye un modelo, un `LightSource`configurado, y acciones de Encender, Apagar y Alternar, así que no necesitas escribir código. También hay una **Foco** decorativa **debajo de**decoraciones, que es solo un modelo y no emite luz. Elige de la categoría de **luces** cuando quieras iluminación real. {% endhint %} ## Agregar una luz Para agregar una luz a tu escena, necesitas crear una entidad de luz y agregarle el `LightSource` componente. ```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**: Una luz con el brillo predeterminado apenas será visible con el sol del mediodía, como en la vida real. Puedes usar el [Control del Skybox](/creator/content-creator-es/scenes-sdk7/interactividad/skybox-control.md) para forzar que el skybox muestre la noche, o aumentar el brillo configurando el `intensity` propiedad del `LightSource` componente a un valor más alto. {% endhint %} ## Luces de foco Las luces de foco son luces que brillan en una dirección específica y cubren un área concreta con forma de cono. La dirección de la luz está definida por el componente Transform de la entidad. La apertura del cono está definida por las propiedades `innerAngle` y `outerAngle` del `LightSource` component. ```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 }) ``` El `innerAngle` es el ángulo del cono interior, donde la luz tiene su máximo brillo, 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, con luces más enfocadas o más difusas. ## Intensidad y color Todas las luces, tanto puntuales como de foco, tienen un color y una intensidad. El color está definido por el `color` propiedad del `LightSource` componente, y la intensidad está definida por la `intensity` propiedad. ```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, }) ``` El color es un `Color3` objeto; si no se especifica, será blanco. Puedes establecerlo en el color que quieras, lo que puede tener un gran impacto en el ambiente 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 la vida 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 configurando el `shadow` propiedad del `LightSource` componente en `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**: Las sombras solo son compatibles con luces de foco. Las luces puntuales no admiten sombras. Si hay varias luces en la escena, algunas podrían no estar proyectando sombras; consulta [Optimización de luces](#light-optimization) para obtener más información. {% endhint %} ## Encender y apagar una luz El componente LightSource tiene una `active` propiedad que puede usarse para encender y apagar una luz. Esto es útil si quieres apagar una luz sin eliminarla de la escena, o sin configurar `intensity` a 0 y perder la referencia de cuál era la intensidad 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: '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 lejos. La cantidad de luces activas permitidas en una escena está limitada a una por Parcel, y más allá de eso depende de la configuración de calidad seleccionada por el usuario. * Calidad baja: no hay luces de escena en absoluto * Calidad media: máximo 6 luces (en una escena con suficientes Parcels) * Calidad alta: máximo 10 luces (en una escena con suficientes Parcels) El control deslizante de configuración de calidad puede reducir aún más el límite de un ajuste preestablecido. 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. {% hint style="warning" %} **📔 Nota**: En el ajuste preestablecido de calidad baja, las luces de la escena se apagan por completo. Un `LightSource` construido correctamente entonces no muestra nada, y ninguna cantidad de intensidad, alcance o ajustes del material cambia eso. Si una luz "no funciona", revisa primero la configuración de calidad. Trata Medio como el ajuste más bajo que admite tu escena, en lugar de requerir Alto. Un material emisivo que brilla no es prueba de que una luz esté funcionando. Un modelo de lámpara brillante y la luz que proyecta sobre las superficies cercanas son dos cosas separadas que debes comprobar. {% endhint %} En todos los casos, el engine solo renderizará sombras para hasta 3 fuentes 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 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: las sombras se renderizan como sombras suaves (alta calidad) * Entre 10 y 20 metros: las sombras se renderizan como sombras duras (baja calidad) * A más de 20 metros: 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 (10 Parcels). Esto hace que las luces sean adecuadas para configuraciones a gran escala, como la iluminación de escenario en eventos en vivo, donde la mayor parte del público 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. ## Alcance de la luz El componente 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 su intensidad. El alcance se calcula como la raíz cuarta del valor de intensidad (`intensity^0.25`). * Con una intensidad de 16000, el alcance es de unos 11 metros. * Con una intensidad de 160000, el alcance es de unos 20 metros. * Con una intensidad de 1600000, el alcance es de unos 36 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 configurar la `range` propiedad a un 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**: Configurar la `range` propiedad a un número positivo cortará abruptamente 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. Configurar la `range` a un valor mayor que lo que la luz realmente puede alcanzar con su intensidad actual no tendrá ningún efecto. {% endhint %} ## 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 textura para usarla como filtro que solo iluminará partes del área. Las máscaras se usan más típicamente con luces de foco, pero también pueden usarse con luces puntuales. A continuación se muestra un ejemplo de una luz de foco con una 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 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. ![](https://1216664193-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) Con una imagen en blanco y negro, la luz simplemente incide en 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 logotipo o una imagen de color sobre una superficie. {% hint style="warning" %} **📔 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 para imágenes que tienen dimensiones diferentes. {% endhint %} 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. ```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 ejemplo, la imagen de abajo muestra cada una de las letras en diferentes lados del cubo (Y arriba, -Y abajo, X a la derecha, -X a la izquierda, Z al frente, -Z atrás). ![](https://1216664193-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" %} **💡 Consejo**: Combina luces con un [Sistema de partículas](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/particle-system.md) para obtener efectos visuales más ricos. Por ejemplo, combina un sistema de partículas de fuego con mezcla aditiva con una luz puntual cálida para crear una fogata convincente. {% endhint %} {% hint style="info" %} **💡 Consejo**: Para ver un ejemplo funcional de este componente, consulta la escena de prueba [`0,4-dynamic-lights`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,4-dynamic-lights) que cubre tanto `LightSource.Type.Point` y `LightSource.Type.Spot`, cambios en tiempo de ejecución mediante `LightSource.getMutable()`, sombras, y `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-es/scenes-sdk7/fundamentos-del-contenido-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.