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

# 런타임 데이터

씬이 실행되는 컨텍스트와 씬 자체에서 데이터를 가져옵니다.

## Decentraland 시간 가져오기

Decentraland는 2시간에 걸쳐 완료되는 낮/밤 주기를 따르므로, 하루에 12번의 전체 주기가 있습니다. 플레이어는 설정을 변경해 하루의 특정 고정된 시간을 경험할 수도 있습니다. 예를 들어 항상 오후 10시의 밤하늘로 Decentraland를 볼 수 있습니다. 이러한 이유로 Decentraland 시간은 플레이어마다 다를 수 있습니다.

다음을 사용하세요 `getWorldTime()` Decentraland 안에서 플레이어가 경험하고 있는 하루 중 시간을 가져옵니다.

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

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

{% hint style="info" %}
**💡 팁**:  `getWorldTime()` 함수는 비동기입니다.  [비동기 함수](/creator/content-creator-ko/sdk7/programming-patterns/async-functions.md) 에 익숙하지 않다면 참고하세요.
{% endhint %}

`getWorldTime()` 는 객체를 반환하며, 다음과 같은 `seconds` 속성을 포함합니다. 이 속성은 하루가 시작된 이후 경과한 초 수(Decentraland 시간 기준)를 나타냅니다. 전체 주기가 24시간이라고 가정합니다. 초 값은 60으로 나누어 분으로, 다시 60으로 나누어 하루가 시작된 이후의 시간으로 구할 수 있습니다. 예를 들어,  `seconds` 값이 *36000*이면, 이는 *오전 10시*.

Decentraland 시간에서 해는 항상 6:15에 떠오르고 19:50에 집니다.

이 정보를 사용해 장면을 그에 맞게 바꿀 수 있습니다. 예를 들어 낮에는 새소리를, 어두울 때는 귀뚜라미 소리를 재생하거나, 어두울 때 가로등의 발광 재질을 켜는 식입니다.

```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) {
    // 밤 시간
    console.log('귀뚜라미 소리를 재생 중')
  } else {
    // 낮 시간
    console.log('새소리를 재생 중')
  }
})
```

## 릴름 데이터 가져오기

Decentraland의 플레이어는 여러 개의 분리된 *릴름*에 존재합니다. 서로 다른 릴름의 플레이어는 같은 구획 위에 서 있어도 서로를 볼 수 없고, 상호작용하거나 채팅할 수 없습니다. 이렇게 플레이어를 분리하면 Decentraland가 제한 없이 무한한 수의 플레이어를 처리할 수 있습니다. 또한 서로 가까운 지역의 플레이어를 짝지어, 상호작용하는 플레이어 간 핑 시간이 허용 가능한 수준이 되도록 합니다.

장면이  [제3자 서버](/creator/content-creator-ko/sdk7/networking/third-party-servers.md) 로 플레이어 간 변경 사항을 실시간으로 동기화하는 데이터를 전송한다면, 변경 사항이 같은 릴름의 플레이어들 사이에서만 동기화되도록 하는 것이 종종 중요합니다. 하나의 릴름에 속한 모든 변경 사항은 다른 릴름의 변경 사항과 분리해 처리해야 합니다. 그렇지 않으면 누구도 변경하지 않았는데도 플레이어에게 무언가가 기묘하게 바뀌는 것처럼 보일 수 있습니다.

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

executeTask(async () => {
  const { realmInfo } = await getRealm({})
  if (!realmInfo) return
  console.log(`당신이 있는 릴름: `, realmInfo.realmName)
})
```

{% hint style="info" %}
**💡 팁**:  `getRealm()` 함수는 비동기입니다.  [비동기 함수](/creator/content-creator-ko/sdk7/programming-patterns/async-functions.md) 에 익숙하지 않다면 참고하세요.
{% endhint %}

Decentraland는 플레이어 위치, 채팅, messageBus 메시지, 스마트 아이템 상태 변경을 포함한 플레이어 간 통신을 분산형 통신 서버 네트워크를 통해 처리하며, 이들 각 서버를  **릴름**이라고 합니다. 각 서버는 여러 개의 분리된  **룸** (또는  **아일랜드**)을 지원할 수 있으며, 각 룸은 Decentraland 지도에서 서로 가까운 서로 다른 플레이어 집합을 묶습니다.

해당 `getRealm()` 함수는 다음 정보를 반환합니다:

* `baseUrl`: *(string)* 릴름 서버의 도메인
* `realmName`: *(string)* 릴름 서버의 이름
* `networkId`: *(number)* 이더리움 네트워크
* `commsAdapter`: *(string)* 쿼리 매개변수(자격 증명)를 모두 제거한 통신 어댑터
* `isPreview`: *(boolean)* 장면이 Decentraland에 게시된 것이 아니라 로컬 미리보기로 실행 중이면 true입니다.
* `isConnectedSceneRoom`: *(boolean)* 사용자가 장면 룸에 연결되어 있으면 true입니다.

{% hint style="warning" %}
**📔 참고**:  `layer` 속성은 더 이상 사용되지 않으므로 피해야 합니다.
{% endhint %}

플레이어가 지도를 이동하면서, 이제 자신에게 가장 가까운 플레이어들과 묶이도록 룸을 바꿀 수 있습니다. 룸은 또한 관리 가능한 사람 수에 맞게 경계를 동적으로 조정하므로, 플레이어가 가만히 있어도 다른 플레이어가 세계에 들어오고 나가면서 그 플레이어는 다른 룸에 있게 될 수 있습니다. 같은  `룸` 의 플레이어들은 통신하며, 서로 볼 수 없을 만큼 멀리 떨어져 있어도 MessageBus를 통해 메시지를 공유합니다. 같은 서버에 있지만 다른 룸에 있는 플레이어들은 현재는 통신하지 않지만, 지도를 이동하며 룸이 바뀌면 통신하게 될 수도 있습니다.

플레이어의 릴름이나 룸 관련 변경 사항에 반응하려면  `onChange` 다음의 함수 `RealmInfo` 컴포넌트를 사용하세요. 엔진이 이를  `engine.RootEntity`. `getRealm()`.

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

export function main() {
	RealmInfo.onChange(engine.RootEntity, (realmInfo) => {
		if (!realmInfo) return
		console.log('릴름이 변경됨: ', realmInfo.realmName)
	})
}
```

{% hint style="warning" %}
**📔 참고**: 장면이 처음 로드될 때는 아직 플레이어에게 할당된 룸이 없을 수 있습니다. Explorer가 결국 플레이어에게 룸을 할당하지만, 이는 장면이 로드된 뒤 몇 초 후에 발생할 수도 있습니다.
{% endhint %}

## 플레이어 플랫폼 가져오기

플레이어는 공식 데스크톱 앱, 더 이상 사용되지 않는 웹 및 데스크톱 버전은 물론  [다른 엔진용으로 만들어진 대체 실험용 클라이언트](https://github.com/decentraland/protocol-squad) 도 통해 Decentraland에 접속할 수 있습니다.

다음을 사용하세요 `getExplorerInformation()` 현재 플레이어가 어떤 플랫폼에서 Decentraland를 실행 중인지 확인합니다.

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

executeTask(async () => {
  let data = await getExplorerInformation({})
  console.log("플랫폼: ", data.platform, " 에이전트: ", data.agent)
})
```

공식 Decentraland 데스크톱 앱을 사용할 때 이 함수는 다음 데이터를 반환해야 합니다:

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

공식 Decentraland 데스크톱 앱을 사용하는 플레이어는 브라우저에서 사용하는 플레이어보다 훨씬 더 원활한 경험을 할 가능성이 큽니다. 브라우저는 탭이 기기의 처리 능력 중 얼마만큼을 사용할 수 있는지에 대해 성능 제한을 두기 때문입니다. 또한 카메라 제어, 동적 조명, 플레이어 이동 고정, UI 향상 기능 등 많은 기능이 빠져 있습니다.

## 플레이어 언어 가져오기

다음을 사용하세요 `getPlayerLanguage()` 플레이어의 클라이언트가 어떤 언어로 설정되어 있는지 확인합니다. 다음을 반환합니다: [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) 태그, 예를 들면 `'en'`, `'es'` 또는 `'pt-BR'`. 장면 텍스트의 어떤 번역을 표시할지 선택하는 데 사용하세요.

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

console.log('언어: ', getPlayerLanguage())

// 플레이어가 세션 중간에 언어를 바꿀 때 반응
onPlayerLanguageChanged.add(({ language }) => {
  console.log('언어가 다음으로 변경됨: ', language)
})
```

`onPlayerLanguageChanged` 플레이어가 당신의 장면에 있는 동안 클라이언트 언어를 변경할 때마다 발생합니다. 오래된 클라이언트는 이 이벤트를 발생시키지 않습니다.

{% hint style="warning" %}
**📔 참고**: `getPlayerLanguage()` 반환합니다 `'en'` Explorer가 언어를 장면에 보고할 때까지, 이는 장면 시작 직후에 발생합니다. 또한 다음을 반환합니다 `'en'` 언어를 보고하지 않는 클라이언트에서. 두 함수 모두  `@dcl/sdk` 7.30.0 이상 버전이 필요합니다.
{% endhint %}

## EngineInfo 컴포넌트

해당 `EngineInfo`컴포넌트는 장면의 생명 주기에 대한 데이터를 추적하며, 이벤트가 장면 초기화 시점과 상대적으로 언제 발생하는지 알 때 유용할 수 있습니다.

이 컴포넌트는  `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--------------'
  )
})
```

다음과 같이 사용할 수 있습니다. `sceneHidden` 를 사용해 장면이 보이지 않는 동안 리소스를 많이 사용하는 작업을 일시 중지할 수 있습니다:

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

  // 일반 게임플레이 로직은 장면이 보일 때만 실행됩니다
})
```

해당 `EngineInfo` 컴포넌트는 다음 데이터를 보유합니다:

* `frameNumber`: 엔진의 프레임 카운터.
* `totalRuntime`: 이 장면의 총 실행 시간(초).
* `tickNumber`: 장면의 틱 카운터이며  [ADR-148](https://adr.decentraland.org/adr/ADR-148).
* `sceneHidden`: `true` 은 장면이 Explorer의 전체 화면 UI 뒤에 숨겨져 있을 때입니다. 여기에는 로딩 화면뿐 아니라 지도, 백팩, 설정 메뉴도 포함됩니다. 이를 사용해 플레이어가 장면을 볼 수 없을 때 오디오를 음소거하고 무거운 작업을 일시 중지하세요.

{% hint style="warning" %}
**📔 참고**:  `EngineInfo` 구성 요소는 다음을 통해 가져와야 합니다

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

참고: [가져오기](/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 를 통해 쉽게 처리하는 방법을 확인하세요.
{% endhint %}

### 로딩 화면이 사라지는 것에 반응하기

해당 `scene_hidden` 필드는 플레이어가 실제로 당신의 장면을 볼 수 있는지, 아니면 Explorer의 전체 화면 UI에 가려져 있는지를 알려줍니다. 로딩 화면이 표시되는 동안에는  `sceneHidden` 은 `true`. 로딩 화면이 사라지고 플레이어가 세상을 처음 보게 되는 순간, 이 값은  `false`.

이 값은  `true` 나중에 지도, 백팩, 설정 메뉴처럼 전체 화면 Explorer UI가 장면을 가릴 때마다 다시  [오디오](/creator/content-creator-ko/sdk7/3d/sounds.md) 를 음소거하고 비용이 큰 시스템을 일시 중지한 다음,  `false`.

이것이 장면이 그 첫 번째 공개 시점을 알 수 있는 유일한 방법입니다. 로딩 화면 뒤에서 실행되어 플레이어가 놓치게 될 모든 것, 즉 오프닝 시네마틱, 시작할 때 재생해야 할 환영 사운드, 봐야만 제대로 의미가 있는 트윈, 오프닝 UI, 또는 플레이어가 실제로 도착한 뒤에만 집계되어야 하는 분석 이벤트 등을 지연시키는 데 사용하세요.

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

function onSceneRevealed() {
  // 플레이어가 이제 장면을 보고 있으므로, 여기서 인트로를 시작합니다
  console.log('로딩 화면이 막 사라졌습니다')
}

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

  // 한 번만 실행
  engine.removeSystem(waitForSceneRevealed)
  onSceneRevealed()
})
```

{% hint style="warning" %}
**📔 참고**: 당신의 장면은  `sceneHidden` 은 `true`동안에는 정상적으로 계속 실행되며, 단지 표시되지 않을 뿐입니다. 이 필드를 사용해 장면 로직을 일시 중지하지 말고, 플레이어가 무엇을 보게 될지의 타이밍을 맞추는 데 사용하세요.

`scene_hidden` 최신 `@dcl/sdk` 및 Decentraland Explorer의 최근 버전이 필요합니다. 오래된 클라이언트에서는 필드가 기본값인  `false`로 유지되므로, 이를 기다리는 장면도 계속 실행되지만 로딩 화면이 사라지는 것과는 동기화되지 않습니다.
{% 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-ko/sdk7/interactivity/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.