> 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/interatividade/skybox-control.md).

# Controle do Skybox

Altere a hora do skybox, substitua o céu pela sua própria textura ou altere a cor do céu, das nuvens e das estrelas e controle o sol e o nevoeiro

Pode alterar a forma como um jogador vê o skybox enquanto está na sua scene. Isto também afeta a tonalidade e a direção da iluminação global.

O céu em Decentraland segue um ciclo predefinido de dia/noite que demora 2 horas a completar, por isso há 12 ciclos completos em cada dia real. Se a scene não impuser uma hora fixa do dia, os jogadores também podem mudar para uma hora específica do dia, alterando um controlo deslizante na sua UI.

Sempre que os jogadores entram numa scene com uma hora do dia diferente, ou a scene altera dinamicamente a hora do dia, o skybox transita suavemente para este novo valor ao longo de alguns segundos.

## Hora fixa do dia

Pode definir uma hora do dia fixa para a sua cena. Todos os jogadores verão a cena com esta hora do dia, e o Skybox não seguirá o ciclo dia/noite.

No Creator Hub, abra as definições da scene e clique no separador **Definições** para encontrar a secção **Skybox** . Desmarque a opção **Automático** e defina a hora do dia pretendida.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-12f9c4e1e3a7bb1f0b20c3635a396d14bb8bc28b%2Ffixed-time-of-day.webp?alt=media)

Também pode definir a hora do dia do Skybox no código da sua cena. Para isso, adicione a seguinte secção ao seu `scene.json` no nível raiz:

```json
 "skyboxConfig": {
    "fixedTime": 36000
  }
```

O número corresponde ao número de segundos desde o início do dia, entre 0 (que corresponde à *00:00*) e 86400 (que corresponde à *24:00*). Qualquer número superior a 86400 também é interpretado como meia-noite.

Aqui estão mais alguns exemplos de valores válidos:

* 0 segundos => *00:00*
* 21600 segundos => *06:00*
* 43200 segundos => *12:00*
* 64800 segundos => *18:00*
* 86400 segundos => *24:00*

## Ler a hora do dia

Pode ler a hora do dia a partir do código da sua scene usando a função `getWorldTime()` .

```ts
import { getWorldTime } from '~system/Runtime'

executeTask(async () => {
  let time = await getWorldTime({})
  console.log(time.seconds)
})
```

A função devolve um número entre 0 e 86400, em que 0 corresponde à meia-noite e 86400 às 24:00. Este valor é atualizado se a scene alterar dinamicamente a hora do dia ou se o jogador alterar a hora do dia na UI. Caso contrário, devolve o valor correspondente ao ciclo predefinido de dia/noite.

## Alterar dinamicamente a hora do dia

Pode alterar dinamicamente a hora do dia usando o componente `SkyboxTime` . Este componente só pode ser adicionado à entidade raiz da scene `engine.RootEntity`.

```ts
import { SkyboxTime } from '@dcl/sdk/ecs'

function main() {
  SkyboxTime.create(engine.RootEntity, { fixedTime: 36000 })
}
```

A propriedade `fixedTime` é um número entre 0 e 86400, em que 0 corresponde à meia-noite e 86400 às 24:00. Qualquer número superior a 86400 também é interpretado como meia-noite.

Sempre que este componente é adicionado ou removido, ou quando a propriedade `fixedTime` é alterada, a hora do dia do skybox transita suavemente para este novo valor ao longo de alguns segundos. O mesmo acontece quando o jogador sai da scene ou entra nela. Enquanto a hora do dia do skybox estiver fixa, o skybox deixará de acompanhar a progressão do seu ciclo de dia/noite e os jogadores não poderão alterar a hora do dia através da UI.

Por predefinição, a transição ocorre sempre no sentido para a frente, mas pode alterar este comportamento definindo a propriedade `transitionMode` como `TransitionMode.TM_FORWARD` ou `TransitionMode.TM_BACKWARD`.

```ts
import { SkyboxTime, TransitionMode } from '@dcl/sdk/ecs'

function main() {
  SkyboxTime.create(engine.RootEntity, { fixedTime: 36000, transitionMode: TransitionMode.TM_BACKWARD })
}
```

### Escolher a transição mais curta

As mudanças nunca são instantâneas: percorrem sempre todas as horas intermédias. `TM_FORWARD` avança sempre, passando pela meia-noite. Assim, mudar das 10:00 para as 08:40 percorre quase um dia inteiro de céu, em vez de recuar 80 minutos.

Determine qual é o sentido mais curto e indique o modo correspondente:

```ts
import { engine, SkyboxTime, TransitionMode } from '@dcl/sdk/ecs'

const DAY = 86400

// Move to a new time of day the short way round
function setTimeOfDay(fixedTime: number) {
  const current = SkyboxTime.getOrNull(engine.RootEntity)?.fixedTime
  // sem SkyboxTime definido ainda, a cena não sabe a hora atual, por isso basta avançar
  let transitionMode = TransitionMode.TM_FORWARD
  if (current !== undefined) {
    const forward = (fixedTime - current + DAY) % DAY
    // avançar mais de meio dia significa que recuar é o caminho mais curto
    if (forward > DAY / 2) transitionMode = TransitionMode.TM_BACKWARD
  }
  SkyboxTime.createOrReplace(engine.RootEntity, { fixedTime, transitionMode })
}
```

Para um salto grande que não queira que o jogador veja, esconda-o atrás de uma UI em ecrã inteiro: apareça gradualmente, altere a hora, aguarde e depois desapareça gradualmente.

## Céu, sol e nevoeiro personalizados

Três componentes permitem que a sua cena controle o ambiente enquanto o jogador estiver dentro dela:

* `Skybox`: substitui o céu pela sua própria textura ou altera as cores do céu procedural, das nuvens e das estrelas.
* `Sun`: altera as cores, reduz a intensidade, oculta ou fixa a direção da luz do sol (e da lua).
* `EnvironmentFog`: altera as cores do nevoeiro à distância e a sua densidade.

Tal como `SkyboxTime`, os três só podem ser adicionados à entidade raiz da cena, `engine.RootEntity`. Em qualquer outra entidade, não têm efeito. Todos os campos são opcionais: tudo o que deixar de fora mantém o comportamento predefinido associado à hora do dia.

{% hint style="warning" %}
**📔 Nota**: Os componentes `Skybox`, `Sun` e `EnvironmentFog` ainda não são suportados na aplicação móvel nem no Explorer Bevy. Os jogadores nesses clientes veem o céu, o sol e o nevoeiro normais; por isso, certifique-se de que a sua cena continua a funcionar sem estas substituições.
{% endhint %}

```ts
import { engine, Skybox, Sun, EnvironmentFog } from '@dcl/sdk/ecs'
import { Color4, Vector3 } from '@dcl/sdk/math'

function main() {
  Skybox.create(engine.RootEntity, {
    skyboxTexture: 'images/sky.png'
  })
  Sun.create(engine.RootEntity, { intensity: 0.5, direction: Vector3.create(-1, -1, 0) })
  EnvironmentFog.create(engine.RootEntity, {
    color: { keys: [{ time: 0, color: Color4.create(0.6, 0.2, 0.1, 1) }] },
    density: 0.01
  })
}
```

### Âmbito e reposição

As substituições de `Skybox`, `Sun` e `EnvironmentFog` só se aplicam enquanto o jogador estiver dentro da sua cena. Quando o jogador sai da cena, um componente é removido ou um campo deixa de estar definido, o céu e a iluminação voltam aos valores predefinidos; ao entrar novamente na cena, as substituições são aplicadas outra vez. As alterações são aplicadas imediatamente, sem transição.

{% hint style="warning" %}
**📔 Nota**: Enquanto estiverem ativas, estas substituições são globais: os parcels vizinhos vistos a partir da sua cena também são renderizados com o seu céu, sol e nevoeiro.
{% endhint %}

### Textura de céu personalizada

`skyboxTexture` substitui o céu visível por uma imagem dos assets da cena. Defina-a como o caminho do ficheiro de imagem, tal como faria com o `src` de uma textura. A imagem tem de ser um panorama equirectangular (uma imagem de latitude-longitude com proporção 2:1): o centro horizontal aponta para o eixo Z positivo (norte) da cena, a linha superior corresponde ao zénite e a linha inferior, ao nadir. Não são suportados layouts em cruz de cubo, 3x2 nem de cubemap com seis faces.

```ts
import { engine, Skybox } from '@dcl/sdk/ecs'

function main() {
  Skybox.create(engine.RootEntity, {
    skyboxTexture: 'images/sky.png'
  })
}
```

A imagem envolve o ambiente horizontalmente e é filtrada bilinearmente. Se não for possível carregar a imagem, o céu padrão permanece.

Mantenha um tamanho razoável para a imagem: o panorama inteiro é baixado e mantido na memória enquanto a cena está carregada. 2048x1024 pixels é suficiente para a maioria dos céus; não ultrapasse 4096x2048. Use um formato compactado, como `.jpg` para céus fotográficos.

A textura altera apenas a aparência do céu: a luz solar continua acompanhando o horário do dia, a luz ambiente continua acompanhando `skyColors` (para que você possa combiná-la com a imagem), e os componentes `Sun` e `EnvironmentFog` continuam se aplicando sobre ela. Na predefinição de qualidade Alta, os reflexos em materiais brilhantes também acompanham a textura do céu.

### Cores do céu, nuvens e estrelas

Se você mantiver o céu procedural, o componente `Skybox` permite recolori-lo e ajustar a camada de nuvens e o campo de estrelas.

```ts
import { engine, Skybox, ColorGradient } from '@dcl/sdk/ecs'
import { Color4 } from '@dcl/sdk/math'

// Um gradiente com uma única chave é uma cor constante
function constant(color: Color4): ColorGradient {
  return { keys: [{ time: 0, color }] }
}

function main() {
  Skybox.create(engine.RootEntity, {
    skyColors: {
      zenith: constant(Color4.create(0.55, 0.25, 0.12, 1)),
      horizon: constant(Color4.create(0.95, 0.55, 0.3, 1)),
      nadir: constant(Color4.create(0.35, 0.15, 0.08, 1))
    },
    clouds: { opacity: 0.3, speed: 0.01, color: constant(Color4.create(0.9, 0.6, 0.4, 1)) },
    stars: { brightness: 4.62 }
  })
}
```

* `skyColors`: a cor do céu no `zenith` (diretamente acima), no `horizon`, e no `nadir` (o céu abaixo do horizonte, visível onde quer que o terreno não o cubra, por exemplo, em grandes altitudes ou em um World com o terreno [landscape](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/scene-metadata.md#landscape-terrain) desativado). Essas cores também determinam a luz ambiente da cena: a cor do zênite ilumina os objetos por cima, a cor do horizonte, pelas laterais, e a cor do nadir, por baixo, fazendo com que os objetos e Avatars combinem com o céu ao redor. `skyColors.rim` é um brilho estreito desenhado exatamente na linha do horizonte, como o brilho de um pôr do sol; quando você não define esse valor, ele acompanha a sua `horizon` cor, se você definir uma (caso contrário, mantém o valor padrão), então só é necessário defini-lo para adicionar um destaque (por exemplo, um contorno laranja de nascer do sol em um céu escuro).
* `clouds.opacity`: de 0 (sem nuvens) a 1, o valor padrão. `clouds.speed`: a velocidade com que a camada de nuvens gira ao redor do céu, em radianos por segundo: 0.01 por padrão (uma volta a cada \~10 minutos), 0 para nuvens estáticas; valores negativos são considerados como 0. `clouds.color`: a tonalidade da camada de nuvens; sem esse valor, as nuvens mantêm as cores padrão correspondentes ao horário do dia, mesmo em um céu recolorido.
* `stars.brightness`: um multiplicador aplicado à textura das estrelas, 4.62 por padrão (valores acima de 1 são HDR, 0 oculta as estrelas, valores negativos são considerados como 0). As estrelas só ficam visíveis durante a parte noturna do dia.

Enquanto `skyboxTexture` estiver definido, a textura substituirá o céu procedural: `clouds` e `stars` não têm efeito, e `skyColors` já não colorem o céu, mas continuam a determinar a luz ambiente.

### Sol

O componente `Sun` altera a luz direcional do sol e da lua.

```ts
import { engine, Sun } from '@dcl/sdk/ecs'
import { Color4, Vector3 } from '@dcl/sdk/math'

function main() {
  Sun.create(engine.RootEntity, {
    color: { keys: [{ time: 0, color: Color4.create(1, 0.65, 0.4, 1) }] },
    intensity: 0.5,
    direction: Vector3.create(-1, -1, 0)
  })
}
```

* `color`: a cor da luz direcional. Também matiza o disco solar.
* `visible`: `true` por predefinição. Defina como `false` para ocultar os discos do sol e da lua e o reflexo da lente do sol, por exemplo, quando estes apareceriam através de uma `skyboxTexture`. A luz emitida pelo sol não é afetada.
* `intensity`: um multiplicador da intensidade da luz ao longo do dia, cujo valor predefinido é 1. O valor 0 desliga a luz solar; valores negativos são considerados como 0.
* `direction`: a direção em que a luz solar se propaga, em coordenadas da cena: `(0, -1, 0)` coloca o sol diretamente por cima, e `(-1, -1, 0)` coloca-o no lado positivo do eixo X (este) do céu, a 45 graus acima do horizonte. Enquanto estiver definida, a posição do sol mantém-se fixa a qualquer hora do dia, mas a cor e a intensidade continuam a acompanhar a hora do dia. Deixe-a por definir ou defina-a como `(0, 0, 0)`, para manter a trajetória normal do sol no céu.

### Nevoeiro

O componente `EnvironmentFog` altera o nevoeiro de distância.

```ts
import { engine, EnvironmentFog } from '@dcl/sdk/ecs'
import { Color4 } from '@dcl/sdk/math'

function main() {
  EnvironmentFog.create(engine.RootEntity, {
    color: { keys: [{ time: 0, color: Color4.create(0.85, 0.5, 0.3, 1) }] },
    density: 0.01
  })
}
```

* `color`: a cor do nevoeiro.
* `density`: a rapidez com que os objetos desaparecem no nevoeiro, expressa como densidade exponencial por metro: o nevoeiro a uma determinada distância é `1 - e^(-density * distance)`, por isso `1 / density` é aproximadamente a distância a que dois terços do campo de visão ficam cobertos pelo nevoeiro. O valor predefinido é 0.0005 (cerca de 2 km); 0.02 cobre com nevoeiro cerca de dois terços do campo de visão a 50 m e quase todo o campo a 150 m, enquanto 0 torna o nevoeiro invisível. Valores negativos são considerados como 0.

A decisão de renderizar ou não o nevoeiro é uma definição de qualidade escolhida pelo jogador; uma cena não pode ativá-lo nem desativá-lo.

### Gradientes de cor ao longo do dia

Todas as cores nestes componentes são um `ColorGradient`: uma lista de `keys`, cada um com um `time` e uma `Color4`. O `time` é a hora do dia normalizada, de 0 (*00:00*) a 1 (*24:00*), portanto 0,5 é meio-dia. É o relógio de `SkyboxTime` dividido por 86400: `fixedTime: 21600` (6 h) corresponde a `time: 0.25`. A cor é interpolada entre as keys vizinhas; antes da primeira key e depois da última, é usada a cor dessa key. Os valores de tempo fora do intervalo de 0 a 1 são limitados a esse intervalo e, se duas keys tiverem o mesmo `time`, prevalece a que aparece mais tarde na lista. Um gradiente com uma única key é simplesmente uma cor constante.

```ts
import { engine, Skybox } from '@dcl/sdk/ecs'
import { Color4 } from '@dcl/sdk/math'

function main() {
  Skybox.createOrReplace(engine.RootEntity, {
    skyColors: {
      horizon: {
        keys: [
          { time: 0, color: Color4.create(0.05, 0.05, 0.2, 1) }, // midnight
          { time: 0.25, color: Color4.create(0.95, 0.5, 0.4, 1) }, // dawn
          { time: 0.5, color: Color4.create(0.7, 0.9, 1, 1) }, // noon
          { time: 0.75, color: Color4.create(0.95, 0.4, 0.2, 1) }, // dusk
          { time: 1, color: Color4.create(0.05, 0.05, 0.2, 1) } // midnight again, so there's no jump
        ]
      }
    }
  })
}
```

Os gradientes não dão a volta à meia-noite, por isso repita a mesma cor em `time: 0` e `time: 1` se o dia tiver de se repetir sem descontinuidades. Os valores de cor não estão limitados a 1: valores superiores a 1 produzem um sol ou céu mais brilhante, em HDR. O canal alfa é ignorado. Use até 8 keys por gradiente: gradientes mais longos são reamostrados para 8 keys espaçadas uniformemente, suavizando os detalhes entre elas. Combine gradientes com `SkyboxTime` para fixar o dia num ponto específico do gradiente.

### Escuridão total

Para que as luzes colocadas na sua cena sejam a única fonte de iluminação, elimine tudo o que o ambiente contribui: a luz solar e o respetivo disco, as cores do céu (e, com elas, a luz ambiente), o nevoeiro, as nuvens e as estrelas.

```ts
import { engine, Skybox, Sun, EnvironmentFog } from '@dcl/sdk/ecs'
import { Color4 } from '@dcl/sdk/math'

function main() {
  const black = { keys: [{ time: 0, color: Color4.Black() }] }

  Skybox.createOrReplace(engine.RootEntity, {
    skyColors: { zenith: black, horizon: black, nadir: black },
    clouds: { opacity: 0 },
    stars: { brightness: 0 }
  })
  Sun.createOrReplace(engine.RootEntity, { intensity: 0, visible: false })
  EnvironmentFog.createOrReplace(engine.RootEntity, { color: black })
}
```

{% hint style="warning" %}
**📔 Nota**: No perfil de qualidade Low, as luzes da cena são desligadas, pelo que uma cena completamente escura é apresentada a preto para esses jogadores. Use materiais emissivos para manter visíveis os elementos essenciais.
{% endhint %}

Consulte [Lights](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/lights.md) para adicionar luzes pontuais e focais à sua cena.

{% hint style="info" %}
**💡 Sugestão**: Para ver exemplos funcionais de controlo do skybox, consulte as cenas de teste [`2,1-skybox-sdk-scene-a`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/2,1-skybox-sdk-scene-a) e [`3,1-skybox-sdk-scene-b`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/3,1-skybox-sdk-scene-b) que controlam `SkyboxTime` e `TransitionMode` em tempo real a partir de um painel de UI, e [`2,0-skybox-scene-json`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/2,0-skybox-scene-json), que lê o `fixedTime` definido em `scene.json` novamente durante a execução através de `getSceneInformation()`. A [`2,2-skybox-control`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/2,2-skybox-control) scene explora os `Skybox`, `Sun` e `EnvironmentFog` components: texturas do céu, predefinições do ambiente, ocultação do sol e um modo de escuridão total.
{% 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/interatividade/skybox-control.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.
