> 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/noite que leva 2 horas para ser concluído, então há 12 ciclos completos por dia. Os jogadores também podem alterar as configurações para experimentar um horário fixo específico do dia, por exemplo, para ver sempre Decentraland com um céu noturno às 22h. Por esse motivo, a hora em Decentraland pode variar de um jogador para outro. Use `getWorldTime()` para buscar a hora do dia que o jogador está experimentando dentro de Decentraland. ```ts import { getWorldTime } from '~system/Runtime' executeTask(async () => { let time = await getWorldTime({}) console.log(time.seconds) }) ``` {% hint style="info" %} **💡 Dica**: O `getWorldTime()` é assíncrona. Veja [Funções assíncronas](/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md) se você não estiver familiarizado com elas. {% endhint %} `getWorldTime()` retorna um objeto com uma `seconds` propriedade. Essa propriedade indica quantos segundos se passaram (em tempo de Decentraland) desde o início do dia, supondo que o ciclo completo dure 24 horas. Divida o valor dos segundos por 60 para obter os minutos e, por 60 novamente, para obter as horas desde o início do dia. Por exemplo, se o `seconds` valor é *36000*, ele corresponde a *10h*. Em tempo de Decentraland, o sol sempre nasce às 6:15 e se põe às 19:50. Você pode usar essa informação para alterar a cena de acordo, por exemplo, para tocar sons de pássaros quando há luz do dia e grilos quando está escuro, ou para ativar os materiais emissivos nos postes de luz 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) { // período noturno console.log('tocando sons de grilos') } else { // período diurno console.log('tocando sons de pássaros') } }) ``` ## Obter dados do Realm Os jogadores em Decentraland existem em vários *realms*. Jogadores em diferentes realms não podem se ver, interagir ou conversar entre si, mesmo que estejam em parcelas iguais. Dividir os jogadores dessa forma permite que Decentraland lide com uma quantidade ilimitada de jogadores sem encontrar limitações. Isso também agrupa os jogadores que estão em regiões próximas, para garantir que os tempos de ping entre jogadores que interagem sejam aceitáveis. Se a sua cena envia dados para um [servidor de terceiros](/creator/content-creator-pt/scenes-sdk7/rede/third-party-servers.md) para sincronizar mudanças entre jogadores em tempo real, então muitas vezes é importante que as mudanças sejam sincronizadas apenas entre jogadores que estão no mesmo realm. Você deve tratar todas as mudanças que pertencem a um realm como separadas das de um realm diferente. Caso contrário, os jogadores verão as coisas mudarem de um jeito estranho, sem que ninguém faça a mudança. ```ts import { getRealm } from '~system/Runtime' executeTask(async () => { const { realmInfo } = await getRealm({}) if (!realmInfo) return console.log(`Você está no realm: `, realmInfo.realmName) }) ``` {% hint style="info" %} **💡 Dica**: O `getRealm()` é assíncrona. Veja [Funções assíncronas](/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md) se você não estiver familiarizado com elas. {% endhint %} Decentraland lida com suas comunicações entre jogadores (incluindo posições de jogadores, chat, mensagens do messageBus e mudanças de estado de smart items) por meio de uma rede descentralizada de servidores de comunicação, e cada um desses servidores é chamado de **Realm**. Cada um desses servidores pode suportar vários **rooms** (também chamados de **islands**), cada um agrupando um conjunto diferente de jogadores que estão próximos uns dos outros no mapa de Decentraland. O `getRealm()` a função retorna 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, removendo todos os parâmetros de consulta (credentials) * `isPreview`: *(boolean)* Verdadeiro se a cena estiver sendo executada como uma prévia local, em vez de publicada em Decentraland. * `isConnectedSceneRoom`: *(boolean)* Verdadeiro se o usuário estiver conectado à room da cena. {% hint style="warning" %} **📔 Nota**: O `layer` propriedade está obsoleta e deve ser evitada. {% endhint %} À medida que os jogadores se movem pelo mapa, eles podem trocar de room para serem agrupados com os jogadores que estão agora mais próximos deles. As rooms também ajustam seus limites dinamicamente para acomodar um grupo administrável de pessoas, então, mesmo que um jogador fique parado, conforme jogadores entram e saem do mundo, esse jogador pode acabar em outra room. Jogadores na mesma `room` estão em comunicação e compartilharão mensagens pelo MessageBus, mesmo que estejam longe demais para se ver. Jogadores no mesmo servidor, mas em rooms diferentes, atualmente não estão se comunicando, mas podem passar a se comunicar à medida que se movem pelo mapa e mudam de room. Para reagir a mudanças relacionadas ao realm ou à room do jogador, use o `onChange` função na `RealmInfo` component, que o engine adiciona ao `engine.RootEntity`engine.RootEntity. `getRealm()`. ```ts import { engine, RealmInfo } from '@dcl/sdk/ecs' export function main() { RealmInfo.onChange(engine.RootEntity, (realmInfo) => { if (!realmInfo) return console.log('Realm alterado: ', realmInfo.realmName) }) } ``` {% hint style="warning" %} **📔 Nota**: Quando a cena é carregada pela primeira vez, talvez ainda não haja uma room atribuída ao jogador. O Explorer acabará atribuindo uma room ao jogador, mas isso às vezes pode ocorrer alguns segundos após a cena ser carregada. {% endhint %} ## Obter a plataforma do jogador Os jogadores podem acessar Decentraland por várias plataformas, incluindo o aplicativo desktop oficial e as versões descontinuadas para web e desktop, bem como [clientes experimentais alternativos](https://github.com/decentraland/protocol-squad) desenvolvidos para outros engines. Use `getExplorerInformation()` para saber em qual plataforma o jogador atual está executando Decentraland. ```ts import { getExplorerInformation } from '~system/Runtime'; executeTask(async () => { let data = await getExplorerInformation({}) console.log("PLATFORM: ", data.platform, " AGENT: ", data.agent) }) ``` Ao usar o aplicativo desktop oficial de Decentraland, essa função deve retornar os seguintes dados: ``` { agent: unity-explorer, platform: desktop } ``` Jogadores que usam o aplicativo desktop oficial de Decentraland provavelmente terão uma experiência muito mais suave do que aqueles no navegador, já que o navegador impõe limitações de desempenho sobre quanto do poder de processamento da máquina a aba do navegador pode usar. Eles também ficarão sem muitos recursos, como controle de câmera, luzes dinâmicas, congelar o movimento do jogador, melhorias de UI, etc. ## Obter idioma do jogador Use `getPlayerLanguage()` para saber em qual idioma o cliente do jogador está definido. Ele retorna uma [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) tag, como `'en'`, `'es'` ou `'pt-BR'`. Use isso para escolher qual tradução dos textos da sua cena mostrar. ```ts import { getPlayerLanguage, onPlayerLanguageChanged } from '@dcl/sdk/platform' console.log('IDIOMA: ', getPlayerLanguage()) // Reaja à troca de idioma do jogador no meio da sessão onPlayerLanguageChanged.add(({ language }) => { console.log('IDIOMA ALTERADO PARA: ', language) }) ``` `onPlayerLanguageChanged` dispara sempre que o jogador altera o idioma do cliente enquanto está na sua cena. Clientes mais antigos nunca o emitem. {% hint style="warning" %} **📔 Nota**: `getPlayerLanguage()` retorna `'en'` até que o Explorer tenha informado seu idioma de volta à cena, o que acontece logo após a cena iniciar. Ele também retorna `'en'` em clientes que não informam um idioma. Ambas as funções exigem `@dcl/sdk` a versão 7.30.0 ou mais recente. {% endhint %} ## O componente EngineInfo O `EngineInfo`acompanha dados sobre o ciclo de vida da cena, o que às vezes pode ser útil para identificar quando um evento está ocorrendo em relação à inicialização da cena. Este componente é adicionado ao `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--------------' ) }) ``` Você pode usar `sceneHidden` para pausar trabalhos que exigem muitos recursos enquanto a cena não estiver visível: ```ts engine.addSystem((deltaTime) => { const engineInfo = EngineInfo.getOrNull(engine.RootEntity) if (engineInfo?.sceneHidden) return // A lógica normal de jogabilidade só é executada quando a cena está visível }) ``` O `EngineInfo` o componente contém os seguintes dados: * `frameNumber`: Contador de quadros do engine. * `totalRuntime`: Tempo total de execução desta cena, em segundos. * `tickNumber`: Contador de ticks da cena de acordo com [ADR-148](https://adr.decentraland.org/adr/ADR-148). * `sceneHidden`: `true` quando a cena está escondida atrás da UI em tela cheia do Explorer. Isso cobre a tela de carregamento, e também o mapa, a mochila e o menu de configurações. Use isso para silenciar o áudio e pausar trabalhos pesados enquanto o jogador não puder ver a cena. {% hint style="warning" %} **📔 Nota**: O `EngineInfo` componente deve ser importado via > `import { EngineInfo } from "@dcl/sdk/ecs"` Veja [Imports](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com isso facilmente. {% endhint %} ### Reaja ao desaparecimento da tela de carregamento O `scene_hidden` campo informa se o jogador realmente pode ver a sua cena ou se ela está coberta pela UI em tela cheia do Explorer. Enquanto a tela de carregamento estiver ativa, `sceneHidden` é `true`. No momento em que a tela de carregamento desaparece e o jogador tem sua primeira visão do mundo, ele passa a ficar `false`. Ele volta a ficar `true` novamente mais tarde sempre que uma UI em tela cheia do Explorer cobrir a cena, como o mapa, a mochila ou o menu de configurações. Isso o torna um bom sinal para silenciar [áudio](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md) e pausar sistemas custosos, retomando depois quando ele voltar a ficar `false`. Esta é a única forma de uma cena saber quando acontece essa primeira revelação. Use isso para segurar qualquer coisa que, de outra forma, aconteceria atrás da tela de carregamento e seria perdida pelo jogador: cinematics de introdução, sons de boas-vindas, um tween que só faz sentido se for assistido, uma UI de abertura ou um evento de analytics que só deve contar quando o jogador estiver realmente presente. ```ts import { engine, EngineInfo } from '@dcl/sdk/ecs' function onSceneRevealed() { // Agora o jogador está olhando para a cena, inicie a introdução aqui console.log('A tela de carregamento acabou de desaparecer') } 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**: Sua cena continua sendo executada normalmente enquanto `sceneHidden` é `true`, ela apenas não está sendo exibida. Não use este campo para pausar a lógica da sua cena; use-o para sincronizar o que o jogador deve testemunhar. `scene_hidden` requer um `@dcl/sdk` e uma versão recente do Decentraland Explorer. Em clientes mais antigos, o campo permanece em seu valor padrão de `false`, então uma cena que espera por ele ainda é executada — ela só não ficará em sincronia com o desaparecimento da tela 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=&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.