> 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 시간은 플레이어마다 다를 수 있습니다.

사용: `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는 어떤 제한에도 부딪히지 않고 무제한의 플레이어를 처리할 수 있습니다. 또한 서로 가까운 지역에 있는 플레이어를 짝지어, 상호작용하는 플레이어 간의 핑 시간이 적절하도록 보장합니다.

씬이 다음으로 데이터를 보낸다면 [3rd party 서버](/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(`You are in the realm: `, 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)* 모든 쿼리 매개변수(자격 증명)를 제거한 Comms 어댑터
* `isPreview`: *(boolean)* 씬이 Decentraland에 게시된 것이 아니라 로컬 미리보기로 실행 중이면 true입니다.
* `isConnectedSceneRoom`: *(boolean)* 사용자가 씬 룸에 연결되어 있으면 true입니다.

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

플레이어가 맵을 이동하면서, 이제 가장 가까운 다른 플레이어들과 묶이도록 룸을 바꿀 수 있습니다. 룸은 관리 가능한 사람 수에 맞추기 위해 경계를 동적으로 조정하기도 하므로, 플레이어가 가만히 있어도 다른 플레이어들이 세계에 들어오고 나가면서 그 플레이어가 다른 룸에 있게 될 수 있습니다. 같은 `room` 은 통신되며, 서로를 볼 수 있을 만큼 멀어도 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('Realm changed: ', 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("PLATFORM: ", data.platform, " AGENT: ", data.agent)
})
```

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

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

공식 Decentraland 데스크톱 앱을 사용하는 플레이어는 브라우저가 탭에서 사용할 수 있는 기기의 처리 능력에 성능 제한을 두기 때문에, 브라우저를 사용하는 플레이어보다 훨씬 더 부드러운 경험을 할 가능성이 높습니다. 또한 카메라 제어, 동적 조명, 플레이어 이동 고정, UI 향상 등 많은 기능이 빠져 있을 것입니다.

## 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 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-ko/sdk7/interactivity/runtime-data.md?ask=<question>&goal=<endgoal>
```

`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.