> 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/kinds-of-projects/smart-wearables.md).

# 스마트 웨어러블

상호작용 기능이 있는 웨어러블 만들기

스마트 웨어러블은 글로벌 씬의 한 종류입니다. 예를 들어 [포터블 경험](/creator/content-creator-ko/sdk7/kinds-of-projects/portable-experiences.md), 플레이어가 메타버스를 이동할 때 함께 가져가는 게임플레이입니다. 예를 들어, 글로벌 씬을 실행하는 동안 플레이어는 Genesis Plaza의 바닥에서 눈덩이를 집어 들고 다른 씬으로 이동한 뒤, 같은 게임을 플레이하고 있는 다른 플레이어에게 그 눈덩이를 던질 수 있습니다.

스마트 웨어러블은 플레이어가 특정 의상을 착용하면 활성화되는 휴대형 경험입니다. 스마트 웨어러블은 플레이어에게 비행할 수 있게 해 주는 제트팩 같은 새로운 능력을 부여하거나, 제네시스 시티 전체에 무작위로 동전을 배치하여 수집하도록 하는 식으로 기존 세계 위에 새로운 콘텐츠 층을 더할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: Smart Wearables는 SDK 7로만 만들 수 있습니다.

그 **크리에이터 허브** 현재는 Smart Wearables 프로젝트 생성을 지원하지 않습니다.
{% endhint %}

## 시작하기

### CLI 사용하기

1. 새 폴더에서 명령줄을 열고 다음을 실행하세요

`npx @dcl/sdk-commands init --project smart-wearable`

이 명령은 새 스마트 웨어러블의 기본 파일과 구조를 만듭니다.

## 템플릿의 파일들

새 Smart Wearable 프로젝트의 폴더는 다음의 폴더와 매우 유사합니다: [Decentraland 씬](/creator/content-creator-ko/sdk7/kinds-of-projects/scene-files.md), 하지만 다음과 같은 차이점이 있습니다:

* `wearable.json` 휴대형 경험의 모든 메타데이터를 포함합니다
* 검은색 안경 한 쌍을 위한 자리표시자 3D 모델(glasses.glb)과 썸네일(glasses.png)이 있습니다. 이들은 직접 만들고 있는 실제 웨어러블로 교체해야 합니다
* `scene.json` 훨씬 짧으며, parcels나 spawn points처럼 웨어러블과 관련 없는 속성은 포함하지 않습니다

## wearable.json에 대해

기본 `wearable.json` 파일은 다음과 같습니다:

```json
{
	"data": {
		"replaces": [],
		"hides": [],
		"tags": ["special", "new", "eyebrows"],
		"representations": [
			{
				"bodyShapes": [
					"urn:decentraland:off-chain:base-avatars:BaseMale",
					"urn:decentraland:off-chain:base-avatars:BaseFemale"
				],
				"mainFile": "glasses.glb",
				"contents": ["glasses.glb"],
				"overrideHides": [],
				"overrideReplaces": []
			}
		],
		"category": "eyewear"
	},
	"name": "스마트 웨어러블 예시",
	"description": "안경을 쓰고 새로운 세상을 보세요",
	"rarity": "mythic"
}
```

다음 필드는 필수입니다 `wearable.json`:

* `id`: 스마트 웨어러블의 고유 ID.
* `name`: 사용자가 마켓플레이스에서 보게 될 웨어러블의 이름
* `설명`: 사용자가 마켓플레이스에서 보게 될 웨어러블의 설명입니다. 마켓플레이스 사용자들은 구매하기 전에 그 기능을 미리 볼 수 없으므로, 스마트 웨어러블이 무엇을 할 수 있는지 반드시 표시하세요.
* `희귀도`: 토큰의 희귀도 공급량입니다. 가능한 값은 다음과 같습니다:
  * unique (1개)
  * mythic (10개)
  * exotic (50개)
  * legendary (100개)
  * epic (1000개)
  * uncommon (10,000개)
  * common (100,000개)

{% hint style="warning" %}
**📔 참고**: 기존 프로젝트를 포크했고 그 안에 `id`, 웨어러블을 게시하기 전에 해당 값이 고유한지 확인하세요. 다음을 사용하세요 [uuidgenerator.net](https://www.uuidgenerator.net/) 새 랜덤 UUID를 생성하려면
{% endhint %}

다음 필드들도 선택적으로 포함할 수 있습니다. 이 설정은 스마트 웨어러블을 업로드한 후 Builder UI에서도 구성할 수 있습니다.

* `데이터`: 다음 항목을 포함합니다
  * `대체`: 이 웨어러블을 착용할 때, 이 카테고리의 기본 동작에 더해 함께 벗겨야 하는 다른 웨어러블 카테고리의 목록입니다. 예: 케이프 상체를 착용하면 발도 함께 숨깁니다.
  * `숨김`: 이 웨어러블을 착용할 때, 이 카테고리의 기본 동작에 더해 함께 숨겨야 하며(하지만 벗겨지지는 않는) 다른 웨어러블 카테고리의 목록입니다.
  * `태그`: 마켓플레이스에서 웨어러블을 검색 가능하게 만드는 데 사용하는 태그입니다.
  * `표현 방식`:
    * `신체 형태`: 이 웨어러블을 사용할 수 있는 아바타 표현 형식의 목록입니다. 모든 스마트 웨어러블은 남성과 여성 신체 형태 모두에서 사용할 수 있어야 합니다.
    * `주 파일`: 웨어러블의 3D 모델이 들어 있는 주 파일입니다.
    * `파일 목록`: 웨어러블의 3D 모델을 렌더링하는 데 사용되는 파일의 전체 목록입니다. 예를 들어, 3D 모델에 텍스처가 별도 파일로 포함될 수 있습니다.
    * `숨김 재정의`: 기본값에서의 *hide* 이 웨어러블 카테고리의 동작에 대한 예외 사항
    * `대체 재정의`: 기본값에서의 *대체* 이 웨어러블 카테고리의 동작에 대한 예외 사항
  * `카테고리`: 어떤 웨어러블 카테고리를 사용할지 선택합니다. 가능한 값은 다음과 같습니다:
    * 'eyebrows'
    * 'eyes'
    * 'facial\_hair'
    * 'hair'
    * 'mouth'
    * 'upper\_body'
    * 'lower\_body'
    * 'feet'
    * 'earring'
    * 'eyewear'
    * 'hat'
    * 'helmet'
    * 'mask'
    * 'tiara'
    * 'top\_head'
    * 'skin'
    * 'hands\_wear'
* `메뉴 바 아이콘`이 이미지는 "experiences" 메뉴에서 이 휴대형 경험을 나타내는 데 사용할 이미지입니다. 이 이미지는 폴더의 루트 수준에 있어야 합니다. 권장 이미지 크기는 256x256입니다.
* `모델`: 웨어러블에 사용할 3D 모델입니다. 이 파일은 폴더의 루트 수준에 있어야 합니다.
* `bodyShape`: 이 웨어러블과 호환되는 아바타 신체 유형입니다. 가능한 값:
  * male
  * female
  * both
* `컬렉션 주소`: 게시된 웨어러블 컬렉션의 이더리움 주소입니다. 이 주소는 게시 시 할당되며, 비워 둘 수 있습니다.

## 썸네일

이름이 `thumbnail.png` 인 이미지를 폴더의 루트 수준에 포함해야 합니다. 이 이미지는 백팩과 마켓플레이스 양쪽에서 2D로 웨어러블을 나타내는 데 사용됩니다. 권장 필수 이미지 크기는 256x256입니다.

플레이어의 기대를 설정하고 여러분의 창작물을 올바르게 나타내는 이미지를 선택하세요.

## 미리보기

휴대형 경험의 미리보기를 실행하는 것은 씬의 미리보기를 실행하는 것과 같습니다. 그냥 클릭 **미리보기** Creator Hub에서 `npm run start` 또는 명령줄에서 다음을 실행하세요. 만약 `wearable.json` file이 올바르게 구성되어 있고 프로젝트가 스마트 웨어러블로 인식되면, 주변에 보이는 모든 것이 기본 빈 parcels라는 것을 알 수 있습니다. 이 미리보기 모드에서는 특정 parcels 집합에 제한되지 않으며, 세계 어디든 3D 모델이나 사운드를 추가할 수 있습니다.

스마트 웨어러블이 씬의 맥락에서 어떻게 동작하는지 테스트하려면, 다음을 사용하여 하나 또는 여러 씬의 미리보기를 실행하는 동시에 웨어러블의 미리보기도 실행할 수 있습니다.  [Workspace](/creator/content-creator-ko/sdk7/kinds-of-projects/workspaces.md). 예를 들어, 다음과 함께 스마트 웨어러블을 실행하여 [제네시스 플라자](https://github.com/decentraland-scenes/Genesis-Plaza) 씬에서 붐비는 상황이나 엘리베이터 안에서 등 어떻게 동작하는지 테스트할 수 있습니다.

## 팁

* 엔티티를 배치할 때, 위치는 Genesis Plaza의 0,0 좌표를 기준으로 한 전역 좌표라는 점에 유의하세요.
* 주변 플레이어에 반응하려면:
  * 참고 [모든 플레이어 가져오기](/creator/content-creator-ko/sdk7/interactivity/user-data.md#fetch-all-players) 주변의 다른 플레이어로부터 데이터를 얻는 방법을 알아보려면.
  * 스마트 웨어러블, 주변 씬, 그리고 다른 플레이어의 로딩은 상황에 따라 서로 다른 순서로 일어날 수 있다는 점에 유의하세요. 플레이어가 스마트 웨어러블을 이미 착용한 상태로 Decentraland에 들어오면, 다른 플레이어보다 여러분의 웨어러블의 글로벌 씬이 먼저 로드될 가능성이 큽니다. 반대로 플레이어가 먼저 씬에 로드된 다음 웨어러블을 착용하면, 웨어러블의 씬이 실행되기 시작할 때쯤 다른 플레이어는 이미 로드되어 있을 가능성이 큽니다.
  * 멀티플레이어 경험의 경우, 플레이어가 자신의 realm 안에 있는 island에 연결될 때까지 기다리세요. realm 데이터를 가져와 'room' 필드를 확인하세요. 'room' 필드가 null이면 플레이어는 아직 island에 연결되지 않은 상태이며, 다른 플레이어도 아직 로드되지 않습니다. 'room' 필드가 나타날 때까지 1초마다 이 값을 주기적으로 확인한 뒤, 그때 로직을 초기화하세요.
* 주변 씬과 상호작용하려면:
  * 주변 씬이나 다른 휴대형 경험에 직접 지시를 보낼 수는 없습니다.  `messageBus` 는 현재 각 휴대형 경험/씬마다 샌드박스 처리되어 있습니다.
  * 중간 서버를 사용하여 휴대형 경험과 씬 사이에 정보를 전달할 수 있습니다.
  * raycast를 수행하면 주변 씬의 엔티티 콜라이더에 대한 충돌을 감지할 수 있습니다. 이를 통해 정확한 충돌 위치, 법선 방향, 심지어 3D 모델의 엔티티 이름과 메쉬 이름까지 알 수 있습니다. 이는 SDK7로 작성된 씬의 엔티티에만 적용됩니다.
* 휴대형 경험 종료: 다음을 실행하세요 `kill()` 메서드로 휴대형 경험을 직접 종료합니다.

## 게시

스마트 웨어러블을 게시하려면:

1. 다음의 정보가 `wearable.json` 정확한지 확인하세요. 다른 프로젝트를 시작점으로 사용했다면, 다음이 `id` 다른 웨어러블에서 사용되지 않는 고유 식별자인지 확인하세요.
2. 실행 `npm run pack` 을 프로젝트 폴더에서 실행하세요. 그러면 다음이 생성됩니다 `smart-wearable.zip` 파일이 프로젝트 폴더에 만들어집니다.

{% hint style="warning" %}
**📔 참고**: 다음의 출력 `npm run pack` 은 압축 해제되지 않은 내보낸 프로젝트의 크기를 나타내며, 3MB 이하여야 합니다. 그보다 크면 Builder가 받아들이지 않습니다.
{% endhint %}

3. Builder를 열고, Collections 탭을 열어, +를 클릭해 새 웨어러블을 업로드하세요.
4. 압축한 `smart-wearable.zip` 파일을 Builder에 끌어다 놓고, 모든 정보가 정확한지 확인하세요.

> 참고: 웨어러블에 서로 다른 모델 표현이 포함되어 있다면, 다음과 같은 우회 방법이 필요합니다:
>
> 1. 프로젝트에서 각 표현(`male` 및 `female`),마다 새 폴더를 만들고, 각 표현의 3D 모델을 해당 폴더에 넣으세요.
> 2. 다음을 업데이트하세요 `wearable.json` 파일에 새 표현을 포함하도록 합니다.
> 3. ```lang-json
>    "representations": [{
>      "bodyShapes": ["urn:decentraland:off-chain:base-avatars:BaseMale"],
>      "mainFile": "male/glasses.glb",
>      "contents": ["male/glasses.glb"],
>      "overrideHides": [],
>      "overrideReplaces": []
>    },
>    {
>      "bodyShapes": ["urn:decentraland:off-chain:base-avatars:BaseFemale"],
>      "mainFile": "female/glasses.glb",
>      "contents": ["female/glasses.glb"],
>      "overrideHides": [],
>      "overrideReplaces": []
>    }],
>    ```
> 4. 실행 `npm run pack` 새 smart-wearable.zip 파일을 생성합니다.
> 5. 새 smart-wearable.zip 파일을 Builder에 끌어다 놓으세요.

5. wearables 편집기를 열고, 이 웨어러블을 착용했을 때 다른 웨어러블 카테고리가 비활성화되도록 “hide” 및 “remove” 카테고리가 올바르게 설정되어 있는지 확인하세요.
6. 이 웨어러블과 아마 다른 웨어러블들로 새 컬렉션을 만드세요.
7. “Mint Items” 옆의 세 점 아이콘을 눌러 “See in world”를 선택하세요. 그러면 Sepolia의 탐색기가 있는 탭이 열리며, 여기서 컬렉션의 모든 웨어러블을 Decentraland에서 시험해 보고 Genesis Plaza를 뛰어다니는 등 더 실제 같은 시나리오에서 어떻게 동작하는지 확인할 수 있습니다.
8. 이 시점이면 웨어러블을 게시할 준비가 된 것입니다.

## 제한된 작업

오용을 방지하기 위해 일부 기능은 기본적으로 휴대형 경험에서 허용되지 않으며, 권한 플래그를 추가해야 합니다.

참고 [필수 권한](/creator/content-creator-ko/sdk7/kinds-of-projects/scene-metadata.md#required-permissions) 자세한 내용은 다음을 참조하세요.

## 제한 사항

> 중요: 전체 스마트 웨어러블은 3MB 이내여야 합니다. 여기에는 3D 모델, 썸네일, 코드, 라이브러리, 사운드 파일, 추가 3D 모델, UI 이미지 등이 포함됩니다. 이 제한은 압축되지 않은 폴더 기준입니다. Builder는 이보다 큰 웨어러블은 업로드할 수 없게 합니다. 휴대형 경험의 크기를 확인하려면 다음을 실행하세요 `npm run pack`, 프로젝트 크기는 명령의 출력 텍스트에 표시됩니다. 생성된 `smart-wearable.zip` 파일을 압축 해제하고 폴더의 크기를 확인해도 됩니다.

스마트 웨어러블은 웨어러블을 착용한 플레이어에 대해서만 휴대형 경험을 실행합니다. 다른 플레이어는 효과를 보지 못합니다. 예를 들어, 휴대형 경험이 플레이어를 따라다니는 애완동물을 렌더링한다면, 주변의 다른 플레이어는 이 애완동물을 볼 수 없습니다. 그러나 다른 플레이어는 웨어러블의 씬의 일부로 실행되는 애니메이션은 볼 수 있으며, 심지어 [사용자 지정 아바타 애니메이션도](/creator/content-creator-ko/sdk7/interactivity/player-avatar.md#custom-animations) 스마트 웨어러블 파일의 일부로 업로드된 것까지 볼 수 있습니다.

스마트 웨어러블은 플레이어가 착용했을 때만 작동합니다. 이런 이유로 플레이어는 활성화된 스마트 웨어러블을 제한된 수만 가질 수 있으며, 차지하는 신체 부위에 따라 다른 웨어러블과 호환되지 않는 것도 있습니다. 예를 들어, 모자를 두 개 동시에 쓸 수는 없고, 헬멧과 머리카락을 동시에 사용할 수도 없습니다.

다른 착용 중인 웨어러블에 의해 웨어러블이 “숨김” 상태이지만 “제거”되지는 않았다면, 대응하는 웨어러블이 보이지 않더라도 스마트 웨어러블은 여전히 착용된 상태일 수 있습니다.

## 예제

[스마트 웨어러블 예제](https://github.com/decentraland/smart-wearable-sample))


---

# 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/kinds-of-projects/smart-wearables.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.