> 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 demora 2 horas a ser concluído, pelo que existem 12 ciclos completos todos os dias. Os jogadores também podem alterar as definições para experienciar uma hora do dia fixa específica, por exemplo, para ver sempre Decentraland com um céu noturno das 22h. Por esta razão, a hora de Decentraland pode variar de jogador para jogador. Use `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 `getWorldTime()` função é assíncrona. Consulte [Funções assíncronas](/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 `seconds` propriedade. Esta propriedade indica quantos segundos passaram (no tempo 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 minutos e novamente por 60 para obter as horas desde o início do dia. Por exemplo, se o `seconds` valor for *36000*, corresponde a *10h*. No tempo de Decentraland, o sol nasce sempre às 6:15 e põe-se às 19:50. Pode utilizar esta informação para alterar a Scene em conformidade, por exemplo, para reproduzir sons de pássaros quando há luz do dia e grilos quando está escuro, ou para ligar 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) { // hora noturna console.log('a reproduzir sons de grilos') } else { // hora diurna console.log('a reproduzir sons de pássaros') } }) ``` ## Obter dados do realm Os jogadores em Decentraland existem em vários *realms*. Os jogadores em realms diferentes não se conseguem ver, interagir ou conversar entre si, mesmo que estejam nos mesmos parcels. Dividir os jogadores desta forma permite que Decentraland suporte uma quantidade ilimitada de jogadores sem encontrar quaisquer limitações. Também agrupa jogadores que estão em regiões próximas, para assegurar que os tempos de ping entre jogadores que interagem são aceitáveis. Se a sua Scene enviar dados para um [Server de terceiros](/creator/content-creator-pt/scenes-sdk7/networking/third-party-servers.md) para sincronizar alterações entre jogadores em tempo real, então é frequentemente importante que as alterações sejam sincronizadas apenas entre jogadores que estão no mesmo realm. Deve tratar todas as alterações que pertencem a um realm separadamente das que pertencem a um realm diferente. Caso contrário, os jogadores verão as coisas a mudar de forma estranha, sem que ninguém faça a alteração. ```ts import { getRealm } from '~system/Runtime' executeTask(async () => { const { realmInfo } = await getRealm({}) if (!realmInfo) return console.log(`Está no realm: `, realmInfo.realmName) }) ``` {% hint style="info" %} **💡 Dica**: A `getRealm()` função é assíncrona. Consulte [Funções assíncronas](/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 de jogadores, chat, mensagens de MessageBus e alterações de estado de smart items) através de uma rede descentralizada de Servers de comunicação, cada um destes Servers é chamado de **Realm**. Cada um destes Servers pode suportar várias **rooms** (também chamadas **islands**), cada uma agrupando um conjunto diferente de jogadores que estão próximos uns dos outros no mapa de Decentraland. Os `getRealm()` A função devolve as seguintes informações: * `baseUrl`: *(string)* O domínio do Server do realm * `realmName`: *(string)* O nome do Server do realm * `networkId`: *(number)* A rede Ethereum * `commsAdapter`: *(string)* Adaptador de comunicações, removendo todos os parâmetros de query (credenciais) * `isPreview`: *(boolean)* Verdadeiro se a Scene estiver a ser executada como um Preview local, em vez de publicada em Decentraland. * `isConnectedSceneRoom`: *(boolean)* Verdadeiro se o utilizador estiver ligado à room da Scene. {% hint style="warning" %} **📔 Nota**: A `layer` A propriedade está obsoleta e deve ser evitada. {% endhint %} À medida que os jogadores se movem pelo mapa, podem mudar de rooms para serem agrupados com os jogadores que agora estão mais próximos deles. As rooms também deslocam as suas fronteiras dinamicamente para acomodar um grupo de pessoas gerível, pelo que, mesmo que um jogador fique parado, à medida que os jogadores entram e saem do mundo, o jogador pode encontrar-se noutra room. 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 Server mas em rooms diferentes não comunicam entre si, mas poderão comunicar à medida que se deslocam pelo mapa e mudam de rooms. Para reagir a alterações relativas ao realm ou à room do jogador, utilize a função `onChange` no `RealmInfo` Component, que o Engine adiciona a `engine.RootEntity`. Este Component 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 alterado: ', realmInfo.realmName) }) } ``` {% hint style="warning" %} **📔 Nota**: Quando a Scene é carregada pela primeira vez, poderá ainda não haver uma room atribuída ao jogador. O Explorer acabará por atribuir uma room ao jogador, mas isto pode por vezes ocorrer alguns segundos depois de a Scene 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 desktop e versões web e desktop obsoletas, bem como [clients 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("PLATAFORMA: ", data.platform, " AGENTE: ", data.agent) }) ``` Ao utilizar a aplicação oficial de desktop do 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 desktop do Decentraland tenham uma experiência muito mais fluida do que os que utilizam o browser, uma vez que o browser impõe limitações de desempenho à quantidade de capacidade de processamento da máquina que o separador do browser pode utilizar. Também não terão muitas funcionalidades, como controlo de câmara, luzes dinâmicas, congelamento do movimento do jogador, melhoramentos da UI, etc. ## O Component EngineInfo Os `EngineInfo`Component acompanha dados sobre o ciclo de vida da Scene, o que pode por vezes ser útil para saber quando ocorre um Event, relativamente à inicialização da Scene. Este Component é adicionado a `engine.RootEntity`. ```ts engine.addSystem((deltaTime) => { const engineInfo = EngineInfo.getOrNull(engine.RootEntity) if (!engineInfo) return console.log( '--------------' + '\nnúmeroDeFrames: ' + engineInfo.frameNumber + '\nnúmeroDeTicks: ' + engineInfo.tickNumber + '\ntempoTotalDeExecução: ' + engineInfo.totalRuntime + '\nsceneHidden: ' + engineInfo.sceneHidden + '\n--------------' ) }) ``` Pode utilizar `sceneHidden` para pausar trabalho que exige muitos recursos enquanto a Scene não está visível: ```ts engine.addSystem((deltaTime) => { const engineInfo = EngineInfo.getOrNull(engine.RootEntity) if (engineInfo?.sceneHidden) return // A lógica normal de gameplay é executada apenas quando a Scene está visível }) ``` Os `EngineInfo` Component contém os seguintes dados: * `frameNumber`: Contador de frames do Engine. * `totalRuntime`: Tempo total de execução desta Scene, em segundos. * `tickNumber`: Contador de ticks da Scene conforme [ADR-148](https://adr.decentraland.org/adr/ADR-148). * `sceneHidden`: `true` quando a Scene está oculta por trás da UI em ecrã inteiro do Explorer. Isto abrange o ecrã de carregamento, bem como o mapa, a mochila e o menu de definições. Utilize isto para silenciar o áudio e pausar trabalho pesado enquanto o jogador não consegue ver a Scene. {% hint style="warning" %} **📔 Nota**: A `EngineInfo` Component tem de ser importado através de > `import { EngineInfo } from "@dcl/sdk/ecs"` Veja [Imports](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como tratar disto facilmente. {% endhint %} ### Reagir ao desaparecimento gradual do ecrã de carregamento Os `scene_hidden` O campo indica-lhe se o jogador consegue realmente ver a sua Scene ou se esta está coberta pela UI em ecrã inteiro do Explorer. Enquanto o ecrã de carregamento estiver visível, `sceneHidden` é `true`. No momento em que o ecrã de carregamento desaparece gradualmente e o jogador vê o mundo pela primeira vez, passa a `false`. Passa a `true` novamente mais tarde, sempre que uma UI do Explorer em ecrã inteiro cobre a Scene, como o mapa, a mochila ou o menu de definições. Isto torna-o num bom sinal para silenciar [áudio](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md) e pausar Systems dispendiosos, retomando-os quando voltar a `false`. Esta é a única forma de uma Scene saber quando essa primeira revelação acontece. Utilize-a para reter tudo o que, de outra forma, seria reproduzido por trás do ecrã de carregamento e passaria despercebido ao jogador: cinemáticas introdutórias, sons de boas-vindas, um Tween que só é bem compreendido se for visto, uma UI de abertura ou um Event de analytics que só deve contar quando o jogador está realmente presente. ```ts import { engine, EngineInfo } from '@dcl/sdk/ecs' function onSceneRevealed() { // O jogador está agora a olhar para a Scene; inicie aqui a introdução console.log('O ecrã de carregamento acabou de desaparecer gradualmente') } 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 Scene continua a ser executada normalmente enquanto `sceneHidden` é `true`, apenas não está a ser apresentada. Não utilize este campo para pausar a lógica da sua Scene; utilize-o para determinar o momento do que o jogador deve testemunhar. `scene_hidden` requer um `@dcl/sdk` atualizado e uma versão recente do Decentraland Explorer. Em clients mais antigos, o campo mantém o respetivo valor predefinido de `false`, pelo que uma Scene que espera por ele continua a ser executada — apenas não estará sincronizada com o desaparecimento gradual 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.