> 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 servir para crear distintos ambientes y atmósferas.

De forma predeterminada, la escena se ilumina con una sola luz direccional. Esta luz brilla en una dirección específica y se usa para simular el sol o la luna. Consulta [Control del Skybox](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/skybox-control.md) para obtener más información.

Puedes añadir hasta 1 luz por parcela en tu escena.

Hay dos tipos de luces compatibles:

* Luz puntual: luz que brilla en todas las direcciones desde un punto específico.
* Foco: luz que brilla en una dirección específica y cubre solo un área en forma de cono.

{% hint style="warning" %}
**📔 Nota**: Decentraland ignora las luces integradas dentro de un archivo `.glb` o `.gltf` . Si tu modelo 3D se exportó con luces, estas no iluminarán nada en la escena. Las únicas fuentes de luz válidas son las entidades que tienen el componente `LightSource` . Si quieres que una lámpara ilumine, añade un `LightSource` a la misma entidad o a una entidad secundaria colocada donde está la bombilla.
{% endhint %}

{% hint style="info" %}
**💡 Consejo**: el catálogo de recursos de Creator Hub incluye elementos interactivos listos para usar: **Foco** y **Luz puntual** en la categoría **luces** . Cada uno incluye un modelo, un componente `LightSource`configurado y las acciones Encender, Apagar y Alternar, así que no necesitas escribir código. También hay un modelo decorativo de **Foco** en **decoraciones**, que solo es un modelo y no emite luz. Elige un elemento de la categoría **luces** si quieres iluminar de verdad.
{% endhint %}

## Añadir una luz

Para añadir una luz a tu escena, tienes que crear una entidad de luz y añadirle el 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**: Una luz con el brillo predeterminado apenas será visible bajo el sol del mediodía, como ocurre en el mundo real. Puedes usar [Control del Skybox](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/skybox-control.md) para forzar que el Skybox esté de noche, o aumentar el brillo asignando un valor más alto a la propiedad `intensity` del componente `LightSource` .
{% endhint %}

## Focos

Las luces focales son luces que brillan en una dirección específica y cubren un área con forma de cono. La dirección de la luz se define mediante el componente Transform de la entidad: la luz brilla en la dirección hacia delante de la entidad (su eje +Z local). La apertura del cono se define mediante las propiedades `innerAngle` y `outerAngle` del componente `LightSource` .

El ejemplo siguiente gira la entidad 90 grados alrededor de su eje X, de modo que la luz apunta directamente hacia abajo. Una rotación de -90 grados la apunta hacia el cielo.

```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 el brillo máximo, y `outerAngle` es el ángulo del cono exterior, donde la luz se desvanece gradualmente hacia los bordes del cono. Puedes probar con estos valores para crear distintos efectos y conseguir luces más concentradas o más difusas.

## Intensidad y color

Todas las luces, tanto las puntuales como las focales, tienen un color y una intensidad. El color se define mediante la propiedad `color` del componente `LightSource` , y la intensidad se define mediante la propiedad `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,
})
```

El color es un objeto `Color3` ; si no se especifica, será blanco. Puedes establecer el color que quieras, lo que puede influir mucho 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, que equivale al brillo de una bombilla promedio en el mundo real y puede verse desde 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 se ve la luz es la raíz cuarta del valor de intensidad (`intensity^0.25`).

* Con una intensidad de 625, la luz es visible desde una distancia de hasta unos 5 metros.
* Con una intensidad de 10000, la luz es visible desde una distancia de hasta unos 10 metros.
* Con una intensidad de 160000, la luz es visible desde una distancia de hasta unos 20 metros.

## Sombras

Cada luz puede proyectar sombras o no. De forma predeterminada, no las proyecta, pero puedes habilitarlas estableciendo la propiedad `shadow` del componente `LightSource` 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 las luces focales. Las luces puntuales no admiten sombras. Si hay varias luces en la escena, es posible que algunas no proyecten 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 se puede usar para encender y apagar una luz. Esto es útil si quieres apagar una luz sin quitarla de la escena ni establecer la `intensity` en 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: 'Hacer clic',
		},
	},
	function () {
		const lightSource = LightSource.getMutable(light)
		lightSource.active = !lightSource.active
	}
)
```

## Optimización de la iluminación

Las fuentes de luz pueden afectar considerablemente al rendimiento de la escena. Por este motivo, el motor optimiza la escena automáticamente desactivando algunas 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 parcela y, a partir de ahí, depende de los ajustes de calidad seleccionados por el usuario.

* Calidad baja: no hay luces de escena
* Calidad media: máximo de 6 luces (en una escena con suficientes parcelas)
* Calidad alta: máximo de 10 luces (en una escena con suficientes parcelas)
* Móvil: la aplicación tiene sus propios ajustes preestablecidos, desde ninguna luz de escena en calidad muy baja hasta 8 luces en calidad alta. Consulta [Luces y partículas en dispositivos móviles](https://docs.decentraland.org/creator/content-creator-es/desarrollar-para-movil/desarrollar/optimize-performance.md#lights-and-particles).

El control deslizante de ajustes de calidad puede reducir aún más el límite de un ajuste preestablecido.

Si hay más luces de las permitidas, el motor las desactivará automáticamente según la proximidad de la fuente de luz al jugador. A medida que el jugador se mueve, el motor volverá a activar las luces que estén lo bastante cerca.

{% hint style="warning" %}
**📔 Nota**: con el ajuste preestablecido de calidad baja, las luces de escena se apagan por completo. Un componente `LightSource` configurado correctamente no mostrará nada, y ningún ajuste de intensidad, alcance o material cambiará eso. Si una luz «no funciona», comprueba primero el ajuste de calidad. Considera la calidad media como el nivel mínimo compatible con tu escena, en lugar de exigir la calidad alta.

Que un material emisivo brille no demuestra que la luz esté funcionando. La malla de una lámpara que brilla y la luz que proyecta sobre las superficies cercanas son dos cosas distintas que hay que comprobar.
{% endhint %}

Como algunos jugadores no ven ninguna luz de escena (calidad baja en escritorio y muy baja en dispositivos móviles), asegúrate de que la escena siga funcionando sin ellas. Todo lo que los jugadores necesiten ver, como el camino que deben seguir o un objeto con el que puedan interactuar, debe destacar mediante materiales emisivos, texturas o el skybox. Usa `LightSource` como complemento, no como única señal. Lo mismo se aplica a las sombras: no hagas que una sombra sea la única forma de identificar la ubicación de un objeto.

En todos los casos, el motor solo renderizará sombras para un máximo de 3 fuentes de luz. Si hay más de 3 luces con sombras, el motor 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 los ajustes de calidad del jugador, pero, como regla general:

* A menos de 10 metros: las sombras se renderizan como sombras suaves (calidad alta)
* Entre 10 y 20 metros: las sombras se renderizan como sombras duras (calidad baja)
* A más de 20 metros: las sombras no se renderizan

Las 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 parcelas). Esto hace que las luces sean adecuadas para configuraciones a gran escala, como la iluminación de escenarios en eventos en directo, 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 se puede usar para establecer la distancia máxima a la que se ve la luz. De forma predeterminada, el valor de la propiedad `range` 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 tenga un aspecto natural. Sin embargo, si quieres limitar el alcance de la luz, puedes establecer la propiedad `range` en 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**: Establecer la propiedad `range` en un número positivo hará que la luz se corte bruscamente a la distancia indicada. Esto resulta útil si quieres crear una luz que solo sea visible en un área específica o si quieres optimizar el rendimiento de la escena. Establecer la propiedad `range` en un valor superior al alcance real de la luz con su intensidad actual no tendrá ningún efecto.
{% endhint %}

## Máscaras de luz

Puedes usar una máscara de luz para crear efectos interesantes. En lugar de iluminar toda el área, puedes aplicar una textura como filtro para iluminar solo algunas partes.

Las máscaras suelen usarse con focos, pero también pueden usarse con luces puntuales. A continuación, se muestra un ejemplo de un 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 crear un efecto divertido en el que la luz solo sea visible en las áreas donde la textura es blanca. Puedes usarla 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-627d50cd64d3a398f5981e4214ce8acea38db1ae%2Flightmask1.webp?alt=media)

Con una imagen en blanco y negro, la luz ilumina un área o no la ilumina. También puedes usar una imagen en color; esos colores teñirán la luz en cada área. Esto permite proyectar un logotipo o una imagen en color sobre una superficie.

{% hint style="warning" %}
**📔 Nota**: La imagen usada como máscara debe tener una altura y una anchura en píxeles que sean potencias de 2 (por ejemplo, 1024, 512 o 256). Esta función no funciona con imágenes de otras dimensiones.
{% endhint %}

Al aplicar una máscara a una luz puntual, la textura se envuelve alrededor de la fuente de luz como un cubo. Para evitar que se vean los bordes entre las caras del cubo, asegúrate de que los bordes de la textura tengan continuidad.

```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 letra en una cara distinta del cubo (Y arriba, -Y abajo, X a la derecha, -X a la izquierda, Z al frente y -Z atrás).

![](https://1216664193-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" %}
**💡 Consejo**: Combina luces con un [Particle System](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/particle-system.md) para lograr efectos visuales más ricos. Por ejemplo, combina un sistema de partículas de fuego con mezcla aditiva y 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 [`0,4-dynamic-lights`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,4-dynamic-lights) escena de prueba, que abarca tanto `LightSource.Type.Point` como `LightSource.Type.Spot`, los cambios en tiempo de ejecución mediante `LightSource.getMutable()`, las sombras y `shadowMaskTexture`.
{% endhint %}

## Luces en la oscuridad

Las luces se aprecian mejor cuando el cielo no compite con ellas. Los componentes `Skybox`, `Sun` y `EnvironmentFog` pueden oscurecer por completo la luz del sol, los colores del cielo (y, con ellos, la luz ambiental), la niebla, las nubes y las estrellas, para que las luces sean la única fuente de iluminación. Consulta [Oscuridad total](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/skybox-control.md#complete-darkness).

Con el ajuste preestablecido de calidad baja, las luces de la escena no se renderizan, por lo que para esos jugadores una escena completamente oscura se verá totalmente negra. Usa materiales emisivos para que todo lo esencial siga siendo visible. La aplicación móvil y el Explorer de Bevy aún no admiten estos componentes, por lo que los jugadores que usen esos clientes seguirán viendo el cielo habitual.


---

# 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=<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.
