> 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/runtime-data.md).

# Dados de Runtime

Obtenha dados do contexto em que sua scene está sendo executada e da própria scene.

## Obter a hora de Decentraland

Decentraland segue um ciclo de dia e noite que demora 2 horas a completar-se, pelo que há 12 ciclos completos por dia. Os jogadores também podem alterar as definições para experimentar uma hora específica e fixa do dia, por exemplo, para ver sempre Decentraland com um céu noturno das 22h. Por este motivo, a hora de Decentraland pode variar de jogador para jogador.

Utilize `getWorldTime()` para obter a hora do dia que o jogador está a experienciar dentro de Decentraland.

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

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

{% hint style="info" %}
**💡 Dica**: A função `getWorldTime()` é assíncrona. Consulte [Funções assíncronas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md) se não estiver familiarizado com elas.
{% endhint %}

`getWorldTime()` devolve um objeto com uma propriedade `seconds` . Esta propriedade indica quantos segundos decorreram (na hora de Decentraland) desde o início do dia, assumindo que o ciclo completo dura 24 horas. Divida o valor de segundos por 60 para obter os minutos e, novamente por 60, para obter as horas decorridas desde o início do dia. Por exemplo, se o valor `seconds` for *36000*, corresponde às *10h*.

Na hora de Decentraland, o sol nasce sempre às 6h15 e põe-se às 19h50.

Pode utilizar esta informação para alterar a cena em conformidade, por exemplo, para reproduzir sons de pássaros durante o dia e grilos quando está escuro, ou para ativar os materiais emissivos dos candeeiros de rua quando está escuro.

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

executeTask(async () => {
  let time = await getWorldTime({})
  console.log(time.seconds)
  if (time.seconds < 6.25 * 60 * 60 || time.seconds > 19.85 * 60 * 60) {
    // night time
    console.log('playing cricket sounds')
  } else {
    // day time
    console.log('playing bird sounds')
  }
})
```

## Obter dados do realm

Os jogadores em Decentraland estão distribuídos por vários *realms*. Os jogadores em realms diferentes não se conseguem ver, interagir nem conversar entre si, mesmo que estejam nos mesmos parcels. Esta divisão permite a Decentraland suportar um número ilimitado de jogadores sem atingir quaisquer limites. Também associa jogadores que se encontram em regiões próximas, para garantir que os tempos de ping entre jogadores que interagem são aceitáveis.

Se a sua cena enviar dados para um [servidor de terceiros](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/third-party-servers.md) para sincronizar alterações entre jogadores em tempo real, é frequentemente importante que as alterações sejam sincronizadas apenas entre jogadores que estão no mesmo realm. Deve tratar todas as alterações de um realm separadamente das de outro realm. Caso contrário, os jogadores verão coisas a mudar de forma misteriosa, sem que ninguém tenha feito a alteração.

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

executeTask(async () => {
  const { realmInfo } = await getRealm({})
  if (!realmInfo) return
  console.log(`You are in the realm: `, realmInfo.realmName)
})
```

{% hint style="info" %}
**💡 Dica**: A função `getRealm()` é assíncrona. Consulte [Funções assíncronas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md) se não estiver familiarizado com elas.
{% endhint %}

Decentraland gere as comunicações entre jogadores (incluindo posições dos jogadores, chat, mensagens do MessageBus e alterações de estado de smart items) através de uma rede descentralizada de servidores de comunicação. Cada um destes servidores é chamado **Realm**. Cada um destes servidores pode suportar várias **salas** (também chamadas **ilhas**), cada uma agrupando um conjunto diferente de jogadores que estão próximos uns dos outros no mapa de Decentraland.

A função `getRealm()` devolve as seguintes informações:

* `baseUrl`: *(string)* O domínio do servidor do realm
* `realmName`: *(string)* O nome do servidor do realm
* `networkId`: *(number)* A rede Ethereum
* `commsAdapter`: *(string)* Adaptador de comunicação, sem os parâmetros de consulta (credenciais)
* `isPreview`: *(boolean)* Verdadeiro se a cena estiver a ser executada como uma pré-visualização local, em vez de estar publicada em Decentraland.
* `isConnectedSceneRoom`: *(boolean)* Verdadeiro se o utilizador estiver ligado à sala da cena.

{% hint style="warning" %}
**📔 Nota**: A propriedade `layer` está obsoleta e deve ser evitada.
{% endhint %}

À medida que os jogadores se deslocam pelo mapa, podem mudar de sala para serem agrupados com os jogadores que se encontram agora mais perto deles. As salas também ajustam dinamicamente os seus limites para acomodar um grupo gerível de pessoas. Por isso, mesmo que um jogador fique parado, à medida que outros jogadores entram e saem do mundo, poderá dar por si noutra sala. Os jogadores na mesma `room` comunicam entre si e partilham mensagens através do MessageBus, mesmo que estejam demasiado longe para se verem. Atualmente, os jogadores no mesmo servidor, mas em salas diferentes, não comunicam entre si. No entanto, poderão passar a comunicar à medida que se deslocam pelo mapa e mudam de sala.

Para reagir a alterações relacionadas com o realm ou a sala do jogador, use a função `onChange` no componente `RealmInfo` , que o engine adiciona à entidade `engine.RootEntity`. Este componente contém os mesmos campos devolvidos por `getRealm()`.

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

export function main() {
	RealmInfo.onChange(engine.RootEntity, (realmInfo) => {
		if (!realmInfo) return
		console.log('Realm changed: ', realmInfo.realmName)
	})
}
```

{% hint style="warning" %}
**📔 Nota**: Quando a cena é carregada pela primeira vez, é possível que ainda não tenha sido atribuída uma sala ao jogador. O Explorer acabará por atribuir uma sala ao jogador, mas, por vezes, isso pode acontecer alguns segundos depois de a cena ser carregada.
{% endhint %}

## Obter a plataforma do jogador

Os jogadores podem aceder a Decentraland através de várias plataformas, incluindo a aplicação oficial para computador e as versões Web e para computador obsoletas, bem como [clientes experimentais alternativos](https://github.com/decentraland/protocol-squad) criados para outros engines.

Use `getExplorerInformation()` para saber em que plataforma o jogador atual está a executar Decentraland.

```ts
import { getExplorerInformation } from '~system/Runtime';

executeTask(async () => {
  let data = await getExplorerInformation({})
  console.log("PLATFORM: ", data.platform, " AGENT: ", data.agent)
})
```

Ao utilizar a aplicação oficial de ambiente de trabalho da Decentraland, esta função deve devolver os seguintes dados:

```
{
    agent: unity-explorer,
    platform: desktop
}
```

É provável que os jogadores que utilizam a aplicação oficial de ambiente de trabalho da Decentraland tenham uma experiência muito mais fluida do que os que utilizam o browser, uma vez que este impõe limitações de desempenho à quantidade de capacidade de processamento da máquina que o separador pode utilizar. Também não terão acesso a muitas funcionalidades, como o controlo da câmara, luzes dinâmicas, o congelamento do movimento do jogador, melhorias da UI, etc.

## Obter o idioma do jogador

Utilize `getPlayerLanguage()` para saber em que idioma está definido o cliente do jogador. Devolve uma etiqueta [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) como `'en'`, `'es'` ou `'pt-BR'`. Utilize-a para escolher que tradução dos textos da sua scene deve apresentar.

```ts
import { getPlayerLanguage, onPlayerLanguageChanged } from '@dcl/sdk/platform'

console.log('LANGUAGE: ', getPlayerLanguage())

// Reagir à mudança de idioma do jogador durante a sessão
onPlayerLanguageChanged.add(({ language }) => {
  console.log('LANGUAGE CHANGED TO: ', language)
})
```

`onPlayerLanguageChanged` é acionado sempre que o jogador altera o idioma do cliente enquanto está na sua scene. Os clientes mais antigos nunca o emitem.

{% hint style="warning" %}
**📔 Nota**: `getPlayerLanguage()` devolve `'en'` até o Explorer comunicar o respetivo idioma à scene, o que acontece pouco depois de esta iniciar. Também devolve `'en'` em clientes que não comunicam um idioma. Ambas as funções requerem a versão `@dcl/sdk` 7.30.0 ou posterior.
{% endhint %}

## O componente EngineInfo

O `EngineInfo`component acompanha dados sobre o ciclo de vida da scene, que podem, por vezes, ser úteis para determinar quando ocorre um evento em relação à inicialização da scene.

Este component é adicionado à `engine.RootEntity`.

```ts
engine.addSystem((deltaTime) => {
  const engineInfo = EngineInfo.getOrNull(engine.RootEntity)
  if (!engineInfo) return

  console.log(
    '--------------' +
      '\nframeNumber: ' +
      engineInfo.frameNumber +
      '\ntickNumber: ' +
      engineInfo.tickNumber +
      '\ntotalRuntime: ' +
      engineInfo.totalRuntime +
      '\nsceneHidden: ' +
      engineInfo.sceneHidden +
      '\n--------------'
  )
})
```

Pode usar `sceneHidden` para pausar tarefas que consomem muitos recursos enquanto a cena não está visível:

```ts
engine.addSystem((deltaTime) => {
  const engineInfo = EngineInfo.getOrNull(engine.RootEntity)
  if (engineInfo?.sceneHidden) return

  // A lógica normal do jogo é executada apenas quando a cena está visível
})
```

O `EngineInfo` component contém os seguintes dados:

* `frameNumber`: Contador de frames do Engine.
* `totalRuntime`: Tempo total de execução desta cena, em segundos.
* `tickNumber`: Contador de ticks da cena, conforme definido no [ADR-148](https://adr.decentraland.org/adr/ADR-148).
* `sceneHidden`: `true` quando a cena está oculta pela UI em ecrã inteiro do Explorer. Isso inclui o ecrã de carregamento, o mapa, a mochila e o menu de definições. Use este campo para silenciar o áudio e pausar tarefas pesadas enquanto o jogador não consegue ver a cena.

{% hint style="warning" %}
**📔 Nota**: O `EngineInfo` component tem de ser importado através de

> `import { EngineInfo } from "@dcl/sdk/ecs"`

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

### Reagir ao desaparecimento gradual do ecrã de carregamento

O `scene_hidden` campo indica se o jogador consegue realmente ver a sua cena ou se esta está coberta pela UI em ecrã inteiro do Explorer. Enquanto o ecrã de carregamento está visível, `sceneHidden` é `true`. Assim que o ecrã de carregamento desaparece gradualmente e o jogador vê o mundo pela primeira vez, passa a `false`.

Mais tarde, volta a `true` sempre que uma UI do Explorer em ecrã inteiro cobre a cena, como o mapa, a mochila ou o menu de definições. É um bom sinal para silenciar o [áudio](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md) e pausar sistemas dispendiosos, retomando-os quando voltar a `false`.

Esta é a única forma de uma cena saber quando ocorre essa primeira revelação. Use-a para impedir que algo aconteça por trás do ecrã de carregamento e passe despercebido ao jogador: cenas cinematográficas de introdução, sons de boas-vindas, um Tween que só faz sentido quando é visto, uma UI de abertura ou um evento de análise que só deve ser contabilizado quando o jogador já está mesmo na cena.

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

function onSceneRevealed() {
  // O jogador está agora a ver a cena; inicie aqui a introdução
  console.log('The loading screen just faded out')
}

engine.addSystem(function waitForSceneRevealed() {
  const engineInfo = EngineInfo.getOrNull(engine.RootEntity)
  if (!engineInfo || engineInfo.sceneHidden) return

  // Executar apenas uma vez
  engine.removeSystem(waitForSceneRevealed)
  onSceneRevealed()
})
```

{% hint style="warning" %}
**📔 Nota**: A sua cena continua a funcionar normalmente enquanto `sceneHidden` é `true`, apenas não está a ser apresentado. Não utilize este campo para pausar a lógica da sua Scene; utilize-o para controlar o momento em que o jogador deve ver algo.

`scene_hidden` requer uma versão atualizada do `@dcl/sdk` e uma versão recente do Decentraland Explorer. Nos clientes mais antigos, o campo mantém o valor predefinido de `false`, pelo que uma Scene que aguarde por esse valor continua a ser executada — simplesmente, não fica sincronizada com o esbatimento da animação de saída do ecrã de carregamento.
{% 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/runtime-data.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.
