> 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/getting-started/preview-scene.md).

# 씬 미리보기

씬 미리보기에서 볼 수 있는 내용

일단 [새 장면을 만들었거나](#create-your-first-scene) 또는 다운로드한 [장면 예제](https://studios.decentraland.org/resources?sdk_version=SDK7) 로컬에서 미리 볼 수 있습니다.

## Creator Hub의 Scene Editor 사용하기

다음이 완료되었는지 확인하세요 [Creator Hub를 설치했는지](https://github.com/decentraland/docs/tree/main/creator/sdk7/get-started/editor-installation.md).

1. 장면 프로젝트를 여세요.
2. 다음을 클릭하세요: **재생** 버튼을 오른쪽 상단 모서리에서 누르세요. 그러면 디센트럴랜드 Desktop Explorer가 새 창으로 열리고, 당신의 장면만 실행됩니다. 그곳에서 장면을 돌아다니고 상호작용 가능한 항목과 상호작용할 수 있습니다.

![
](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-30317b50bc4b4e646a1b28effe1ff76939ab0f28%2Fpreview-button.png?alt=media\&token=fbed0f2f-8063-4283-9b07-2d964c9c0e68)

### 미리 볼 위치 선택

다음 옆의 화살표를 클릭하여 **재생** 버튼을 눌러 **재생 옵션** 메뉴를 여세요. 메인 패널에서 장면을 실행할 대상을 선택합니다:

* **데스크톱 클라이언트**: 미리 보기를 디센트럴랜드 Desktop Explorer에서 엽니다. 기본값입니다.
* **웹(Bevy)**: Bevy Web 클라이언트를 사용해 브라우저에서 미리 보기를 엽니다. 다음과 동일합니다: `--web` CLI 플래그.
* **모바일용 QR 코드 표시**: 장면 미리 보기를 열 수 있는 QR 코드를 표시합니다 [디센트럴랜드 모바일 앱](/creator/content-creator-ko/build-for-mobile/mobile-client/overview.md). 컴퓨터와 같은 Wi‑Fi 네트워크에 연결된 휴대폰으로 코드를 스캔하세요. 팝업 주변의 어두운 영역을 클릭하면 닫힙니다.  [모바일에서 미리 보기](/creator/content-creator-ko/build-for-mobile/develop/preview-on-mobile.md) 자세한 내용은

### 데스크톱 클라이언트 옵션

선택하세요 **데스크톱 클라이언트** 다음에서 **재생 옵션** 메뉴에서 선택한 다음, 마우스를 올려 데스크톱 클라이언트에만 적용되는 설정이 있는 하위 메뉴를 여세요:

* **경관 지형 활성화**: 장면 주변의 경관을 켜고 끕니다. 기본적으로 활성화되어 있으며, 끄면 장면의 메모리 사용량을 줄일 수 있습니다. 장면 자체 설정에서 이미 지형을 숨기고 있으면 회색으로 비활성화됩니다.
* **다중 인스턴스 미리 보기**: 여러 Explorer 창을 동시에 실행할 수 있어 [멀티플레이어 장면을 로컬에서 테스트할 수 있습니다](#test-a-multiplayer-scene-locally). 이 기능을 켜면 각 창에서 로그인을 요청하므로, 각 창에서 다른 플레이어로 연결할 수 있습니다. 프로젝트가 SDK 7.20.4 이상을 사용할 때만 표시됩니다.
* **MCP 서버 활성화**: MCP 자동화 서버를 활성화한 상태로 Explorer를 실행하여 AI 에이전트가 실행 중인 미리 보기를 보고 제어할 수 있게 합니다. 프로젝트가 SDK 7.25.0 이상을 사용할 때만 표시됩니다.  [AI로 Vibe Coding](/creator/content-creator-ko/sdk7/getting-started/vibe-coding.md#let-the-ai-see-your-scene-in-world) 전체 워크플로는
* **에셋 압축**: 로컬에서 생성된 에셋 번들로 장면을 미리 보며, 다음 이후 프로덕션에서 렌더링되는 방식과 동일합니다 [에셋 번들 변환](/creator/content-creator-ko/sdk7/optimizing/performance-optimization.md#asset-bundle-conversion). 첫 실행에서는 모든 에셋을 변환하며, 장면이 크면 몇 분이 걸릴 수 있습니다. 플랫폼과 프로젝트의 SDK 버전이 이를 지원할 때만 표시됩니다.  [최적화된 에셋으로 미리 보기](#preview-with-optimized-assets).

장면의 콘솔 출력에는 메뉴 옵션이 필요 없습니다. Creator Hub는 미리 보기를 실행할 때마다 자동으로 엽니다.  [Creator Hub 콘솔](#the-creator-hub-console).

{% hint style="info" %}
**팁:** 디센트럴랜드 모바일 앱에서 바로 장면을 미리 볼 수도 있습니다. 다음을 사용하세요 **모바일용 QR 코드 표시** Creator Hub의 옵션을 사용하거나 다음을 실행하세요 `npm run start -- --mobile` CLI에서.  [모바일에서 미리 보기](/creator/content-creator-ko/build-for-mobile/develop/preview-on-mobile.md) 자세한 내용은
{% endhint %}

## CLI 사용하기

장면을 미리 보려면 장면의 메인 폴더에서 다음 명령을 실행하세요:

```bash
npm run start
```

누락된 종속 항목이 있으면 설치한 뒤 CLI가 시스템에 로컬 웹 서버를 만들고 다음을 통해 디센트럴랜드 Desktop 클라이언트에서 장면을 실행합니다 `decentraland://` 딥링크입니다. Desktop 클라이언트가 기본 미리 보기 대상입니다.

대신 브라우저 탭에서 미리 보려면 다음을 추가하세요 `-- --web` (또는 `-- --bevy-web`)를 추가해 다음에서 Bevy Web 클라이언트로 장면을 여세요 `decentraland.org/bevy-web/`.

장면을 변경할 때마다 미리 보기가 자동으로 다시 로드되고 업데이트되므로, 명령을 다시 실행할 필요가 없습니다.

{% hint style="warning" %}
**📔 참고**: 일부 장면은 사용자 지정 로직을 수행하거나 데이터를 저장하고 가져오기 위해 외부 서버와의 통신에 의존합니다. 이런 장면을 미리 볼 때는 보통 다른 포트에서 서버도 로컬로 실행해야 합니다. 장면과 서버를 실행하는 방법은 장면의 readme를 확인하세요.
{% endhint %}

### 미리 보기 명령의 매개변수

다음 플래그를 `npm run start` 명령에 추가해 동작을 바꿀 수 있습니다:

* `-- --web` (별칭 `-- --bevy-web`) 다음에서 Bevy Web 브라우저 클라이언트로 미리 보기를 엽니다 `decentraland.org/bevy-web/` Desktop Explorer 대신 열립니다. Chromium 기반 브라우저(Chrome 142+)는 호스팅된 페이지가 로컬 미리 보기 서버에 접근하려면 Local Network Access 권한이 필요합니다. 브라우저가 기기에서 앱에 접근하라고 요청하면 "허용"을 클릭하세요.
* `-- --mobile` (별칭 `-- -m`) 터미널에 QR 코드를 표시해 장면을 엽니다 [디센트럴랜드 모바일 앱](/creator/content-creator-ko/build-for-mobile/mobile-client/overview.md) 같은 Wi‑Fi 네트워크에 연결된 휴대폰에서 다음으로 [모바일에서 미리 보기](/creator/content-creator-ko/build-for-mobile/develop/preview-on-mobile.md).
* `-- --skip-build` 빌드는 건너뛰고 미리 보기 모드의 파일만 제공합니다.
* `-- --port` (별칭 `-- -p`) 장면을 실행할 특정 포트를 지정합니다. 그렇지 않으면 사용 가능한 포트를 사용합니다.
* `-- --no-browser` (별칭 `-- -b`) 미리 보기가 새 브라우저 탭을 열지 않도록 합니다.
* `-- -w` 또는 `-- --no-watch` 파일 시스템 변경 사항을 감시하지 않고, 장면 코드가 바뀔 때마다 핫 리로드되지 않게 합니다.
* `-- --ci` 원격 Unix 서버에서 parcel 미리 보기 도구를 실행합니다.
* `-- --multi-instance` 여러 Explorer 인스턴스를 동시에 실행할 수 있습니다.
* `-- --local-ab` 최적화된 에셋 번들로 미리 봅니다. Desktop Explorer는 미리 보기 중 장면의 에셋을 직접 에셋 번들로 변환하여, 프로덕션에서 렌더링되는 방식과 맞춥니다. 다음과 동일합니다 **에셋 압축** Creator Hub의 옵션입니다. Desktop Client에서만 사용할 수 있으며(Bevy Web 클라이언트에서는 불가).  [최적화된 에셋으로 미리 보기](#preview-with-optimized-assets).
* `-- --no-client` 모든 자동 실행(데스크톱 Explorer 딥링크, 브라우저 열기, 모바일 QR)을 억제합니다. 파일 감시기는 Explorer가 자체적으로 연결하면 여전히 데스크톱 Explorer에 알립니다. 외부 도구가 Explorer 프로세스를 관리할 때 유용합니다.
* `-- --mcp` Explorer에서 MCP 서버를 활성화합니다(딥 링크 매개변수로 전달됨).
* `-- --mcp-port` Explorer의 MCP 서버용 포트입니다(딥 링크 매개변수로 전달됨). 예: `npm run start -- --mcp --mcp-port 3001`.

{% hint style="warning" %}
**📔 참고**: 매개변수는 두 개의 대시 묶음으로 추가해야 합니다. 예: `npm run start -- --web3`.
{% endhint %}

## 최적화된 에셋으로 미리 보기

장면을 게시하면 디센트럴랜드 서버가 모든 3D 모델을 로드와 렌더링이 훨씬 가벼운 최적화 형식인 에셋 번들로 변환합니다.  [에셋 번들 변환](/creator/content-creator-ko/sdk7/optimizing/performance-optimization.md#asset-bundle-conversion). 기본적으로 로컬 미리 보기에서는 이 단계를 건너뛰고 대신 원본 모델을 로드합니다.

최적화된 에셋을 활성화하면 장면을 미리 볼 때 이 변환을 로컬에서도 실행합니다. 이렇게 하면 두 가지 이점이 있습니다:

* 미리 보기가 더 빨리 로드되고 더 부드럽게 실행됩니다. 특히 무거운 3D 모델이 있는 장면에서 그렇습니다.
* 게시 후 플레이어가 보게 될 것과 정확히 같은 모델을 볼 수 있어, 게시 전에 에셋 압축 문제를 잡아낼 수 있습니다.

이 옵션은 로컬 미리 보기에만 영향을 줍니다. 게시된 장면은 이 옵션 사용 여부와 관계없이 항상 서버에서 변환됩니다.

활성화하려면:

* **Creator Hub에서**: 열고 **재생 옵션** 옆의 **재생** 버튼을 누르고 마우스를 올린 다음 **데스크톱 클라이언트**, 그리고 **에셋 압축**.
* **CLI에서**: 실행하세요 `npm run start -- --local-ab`.

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e8a9e4c2c58d07f6493df205efe569837d4701f8%2Foptimize-assets-checkbox.png?alt=media\&token=eb756c70-de8f-4843-bed7-5424a600baa0)

이 옵션을 켜면 디센트럴랜드 explorer가 장면의 3D 모델을 로드하기 전에 사용자의 컴퓨터에서 에셋 번들로 변환합니다. 대부분의 장면에서는 거의 즉시 변환되지만, 장면의 에셋이 매우 무거우면 첫 미리 보기가 더 오래 걸릴 수 있습니다. 변환된 모델은 캐시되므로 이후 미리 보기에서는 새로 추가되거나 수정된 에셋만 변환하면 됩니다.

{% hint style="info" %}
**💡 팁**: 어떤 이유로든 에셋 변환에 실패하면, 일반 미리 보기와 마찬가지로 원본 3D 모델을 로드하도록 되돌아갑니다.
{% endhint %}

## 장면을 디센트럴랜드에 업로드하기

장면이 만족스러우면 업로드해 디센트럴랜드에 게시할 수 있습니다. 이를 위해서는 LAND, Decentraland NAME, 또는 ETH ENS 이름을 소유하고 있거나, 그런 권한을 가진 사람에게 권한을 받아야 합니다.  [게시](/creator/content-creator-ko/sdk7/publishing/publishing.md) 방법은

## 장면 크기 미리 보기

미리 보기에 표시되는 장면 크기는 장면 설정을 기준으로 합니다.

Scene Editor의 장면 메뉴 두 번째 탭에서 이를 편집하세요.

![
](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-54a1901635efda3371172e647c03614733baca17%2Fscene-parcels-3x3.png?alt=media\&token=e7133392-8474-4127-b075-5a3f4e7a4e8d)

드롭다운을 사용하고 다음을 클릭하세요 **레이아웃 적용** 장면의 크기를 변경합니다. 각 개별 parcel을 클릭해 레이아웃에서 제외하도록 토글할 수도 있습니다.

![
](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-bbc2ecb567600843892a8c8873aaa70107e66839%2Fscene-parcels-toggled.png?alt=media\&token=aa4c4612-48ac-458d-afec-453d5168d1e8)

다음을 편집할 수도 있습니다 *scene.json* 파일에서 "parcels" 필드에 여러 parcel을 나열할 수 있습니다.  [명령줄로 parcel 설정](/creator/content-creator-ko/sdk7/kinds-of-projects/scene-metadata.md#scene-parcels) 자세한 내용은

{% hint style="info" %}
**💡 팁**: 미리 보기를 실행하는 동안에는 parcel 좌표가 실제 장면에서 사용할 좌표와 일치할 필요는 없습니다. 서로 인접해 있고 같은 형태로 배치되어 있기만 하면 됩니다. 나중에 장면을 배포할 때 실제 좌표로 바꿔야 합니다 [장면을 배포할 때](#upload-a-scene-to-decentraland).
{% endhint %}

## 장면 콘솔 보기

다음을 클릭하여 콘솔을 여세요 ![
](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-a673f6b987216e9e471fdac882879c44fcf94652%2Fconsole-icon.png?alt=media\&token=1965a51b-d4b0-4caa-b9d5-d24d738c1fb8) 오른쪽 상단의 아이콘. 여기에서 오류 메시지를 볼 수 있고, 장면이 콘솔에 출력한 텍스트도 다음을 통해 볼 수 있습니다 `console.log()`.

키를 눌러서도 열 수 있습니다 **\`** 키를 누르세요. 또한 Shift + **\`** 를 눌러 콘솔을 더 넓게 열 수 있어 더 많은 텍스트를 볼 수 있습니다.

## Creator Hub 콘솔

Creator Hub는 편집기를 벗어나지 않고 동일한 출력을 보여주며, 기본값으로 그렇게 합니다. 미리 보기를 실행하면  **CONSOLE** 탭이 다음 옆에 표시됩니다 **FILE SYSTEM** 및 **ASSET PACKS** 가 편집기 하단 패널에 표시됩니다.

콘솔이 열리지 않게 하려면 다음 선택을 해제하세요 **디버그 콘솔 열기** 다음 아래에서 **재생 옵션** 다음의 **EDITOR** Creator Hub 설정 탭에서

콘솔이 방해되지 않도록 하려면 헤더의 팝아웃 아이콘을 클릭하세요. 아이콘에는 다음 레이블이 붙어 있습니다 **콘솔을 별도 창에서 열기**. 콘솔은 다음 제목의 자체 창으로 열립니다 **Console**, 편집하는 동안 두 번째 모니터로 옮겨 계속 표시해 둘 수 있습니다.

별도 창에는 **콘솔 지우기** 버튼과 **편집기에 다시 도킹** 버튼이 있어 콘솔을 하단 패널로 되돌립니다. 한편 **CONSOLE** 편집기의 탭에는 다음이 표시됩니다 **콘솔이 별도 창에서 열렸습니다** 그리고 다음을 제공합니다 **여기로 다시 도킹** 버튼도 같은 기능을 합니다.

{% hint style="info" %}
**💡 팁**: 콘솔은 분리된 상태에서도 출력을 계속 수집하므로, 다시 도킹해도 아무것도 잃지 않습니다. 미리 보기가 실행 중이지 않을 때는 다음이 표시됩니다 **장면을 실행하여 디버그 출력 보기**.
{% endhint %}

## 멀티플레이어 장면을 로컬에서 테스트하기

장면 미리 보기를 실행해 두 개 이상의 서로 다른 explorer 창에서 열면, 열려 있는 각 창은 별도의 플레이어로 인식되며 모의 통신 서버가 이 플레이어들을 동기화 상태로 유지합니다.

한 창에서 장면과 상호작용한 다음 다른 창으로 전환하면 그 상호작용의 효과가 그곳에도 표시되는 것을 볼 수 있습니다.

Creator Hub에서 다음을 켜세요 **다중 인스턴스 미리 보기** 다음에서 **데스크톱 클라이언트** 하위 메뉴의 **재생 옵션**, 그런 다음 다음을 클릭하세요 **재생** 버튼을 한 번 더 눌러 두 번째 디센트럴랜드 explorer 창을 엽니다. 두 창 모두 서로 다른 주소로 연결해야 합니다. 장면이 다시 로드되어도 동일한 세션이 유지됩니다.

![
](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-30317b50bc4b4e646a1b28effe1ff76939ab0f28%2Fpreview-button.png?alt=media\&token=fbed0f2f-8063-4283-9b07-2d964c9c0e68)

대안으로, 다음을 브라우저 URL에 입력하여 두 번째 디센트럴랜드 explorer 창을 열 수 있습니다:

> `decentraland://realm=http://127.0.0.1:8000&local-scene=true&debug=true&multi-instance=true`

### 고급: 원격 에셋 번들로 빠르게 반복하기

{% hint style="info" %}
**💡 팁**: 대부분의 장면에서 에셋 번들로 미리 보는 가장 쉬운 방법은 다음을 활성화하는 것입니다 [최적화된 에셋](#preview-with-optimized-assets), 로컬에서 모델을 변환하며 항상 최신 버전을 반영합니다. 아래 모드는 서버에 이미 게시된 번들을 재사용하는 대안입니다.
{% endhint %}

많은 3D 모델이 있는 무거운 장면에서는 다음을 재사용해 장면 로딩과 다시 로딩을 더 빠르게 할 수 있습니다 [에셋 번들](/creator/content-creator-ko/sdk7/optimizing/performance-optimization.md#asset-bundle-conversion) 디센트럴랜드 서버에 이미 게시된 것을 사용하면, 최적화되지 않은 원본 3D 모델을 로드하지 않아도 됩니다. 코드만 변경할 때 반복 작업에 특히 유용합니다.

이 모드를 활성화하려면 다음 인수로 Decentraland Desktop 클라이언트를 실행하세요:

```bash
npm run start -- --realm http://127.0.0.1:8000/ --position 0,0 --local-scene true --debug --skip-version-check true --lsd-use-remote-ab <ab-source>
```

다음 `<ab-source>` 인수는 장면이 이미 게시된 위치에 따라 달라집니다:

* **Genesis City의 경우**: `--lsd-remote-ab-server Genesis`
* **월드의 경우**: `--lsd-remote-ab-world <world-name>.dcl.eth`

예를 들어, 이미 월드에 배포된 장면의 로컬 복사본을 미리 보려면:

```bash
npm run start -- --realm http://127.0.0.1:8000/ --position 0,0 --local-scene true --debug --skip-version-check true --lsd-use-remote-ab --lsd-remote-ab-world myworld.dcl.eth
```

두 경우 모두 `--realm http://127.0.0.1:8000/` 클라이언트를 로컬 미리 보기 서버로 지정합니다(다음을 실행해 `npm run start` 먼저 서버를 시작한 뒤), 그리고 `--local-scene true` 에게 그곳에서 장면 코드를 로드하라고 지시합니다.

{% hint style="warning" %}
**📔 중요**: 이 모드를 사용할 때는 다음을 권장합니다 **모든** 아트 에셋이 이미 모두 게시되어 콘텐츠 서버에서 에셋 번들 처리가 완료된 상태여야 합니다. 새 에셋을 추가했다면 일반 미리 보기를 실행할 때처럼 원본 gltf 파일로 로드되므로 최적화된 로딩의 이점을 누리지 못합니다. 하지만 이미 게시된 에셋을 로컬에서 수정했고 파일 이름을 그대로 유지했다면, 해당 에셋의 이전 게시 버전이 보이게 됩니다.

그 경우에는 먼저 장면을 다시 배포하고, 에셋 번들이 생성될 때까지 몇 분 기다린 뒤( [에셋 번들 변환](/creator/content-creator-ko/sdk7/optimizing/performance-optimization.md#asset-bundle-conversion)), 그런 다음 코드만 반복 작업할 때 이 모드를 다시 사용하세요.
{% 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/getting-started/preview-scene.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.