> 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/avatars/modifier-areas.md).

# 아바타 수정 영역

씬의 특정 지역 안에 있는 플레이어에 대해 아바타를 숨기거나, 이름표를 숨기거나, 패스포트를 비활성화합니다

아바타는 장면을 이동하는 동안 디센트럴랜드 전역에서 일관되게 행동하고 보입니다. 하지만 다음을 추가할 수 있습니다 `AvatarModifierArea` 장면의 한 영역에 추가하여, 플레이어 아바타가 그 영역에 들어올 때 어떻게 행동할지에 영향을 줄 수 있습니다.

{% hint style="danger" %}
**❗경고**\
다음의 수량은 제한해 주세요 `AvatarModifierAreas` 장면에서 사용하는 수를 몇 개로만 제한해 주세요. 너무 많이 사용하면 성능에 큰 영향을 줄 수 있습니다.
{% endhint %}

### 아바타 수정 영역 배치

다음이 포함된 엔티티를 추가하세요 `AvatarModifierArea` 컴포넌트를 추가하고, 이 엔티티의 위치를 다음을 사용해 지정하세요 `Transform` 컴포넌트를 추가해야 합니다.

```ts
const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})
```

다음의 `AvatarModifierArea` 컴포넌트를 사용하려면 다음 항목을 제공해야 합니다:

* `area`: 수정 영역의 크기
* `modifiers`: 영역에서 구현할 수정자의 목록을 나열한 배열입니다. 이 속성은 다음의 값을 사용합니다 `AvatarModifierType` 열거형.

지원되는 수정자는 다음과 같습니다:

* `AvatarModifierType.AMT_HIDE_AVATARS`
* `AvatarModifierType.AMT_DISABLE_PASSPORTS`
* `AvatarModifierType.AMT_HIDE_NAMETAGS`

다음의 모든 효과는 `AvatarModifierArea` 해당 영역의 범위 내에서만 적용됩니다. 플레이어는 영역 밖으로 나가면 정상으로 돌아갑니다.

하나의 `AvatarModifierArea` 영역 안에 있는 플레이어에게만 영향을 줍니다. 영역에 들어간다고 해서 영역 밖의 다른 플레이어를 보는 방식에는 영향을 주지 않습니다.

다음의 효과는 `AvatarModifierArea` 각 플레이어에 대해 로컬로 계산됩니다. 다음을 둘 수 있습니다 `AvatarModifierArea` 일부 플레이어에게만 장면에 표시되고 다른 플레이어에게는 표시되지 않는 다음을. 예를 들어, 장면의 한 플레이어만 다른 모든 플레이어를 숨기는 수정 영역을 갖는 "마르코 폴로" 게임을 만들 수 있습니다. 로컬 버전의 장면에서 이 수정 영역을 가지고 있지 않은 다른 플레이어들은 서로를 정상적으로 볼 수 있습니다.

영역이 아바타를 숨기면, 로컬 버전의 장면에서 해당 영역이 없는 플레이어는 자신이 숨겨져 있다고 느끼는 경우를 포함해 모든 아바타를 정상적으로 보게 됩니다. 영역이 있는 플레이어는 그 안에 들어갔을 때 자신과 다른 모든 아바타가 그 영역의 영향을 받는 것으로 경험하게 됩니다.

{% hint style="warning" %}
**📔 참고**: 아바타 수정 영역은 다음의 영향을 받습니다 *위치* 과 *회전* 호스트 엔티티의 Transform 컴포넌트의 영향을 받지만, 다음의 영향은 받지 않습니다 *크기*.
{% endhint %}

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

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

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

### 아바타 숨기기

플레이어가 다음에 들어가면 `AvatarModifierArea` 다음을 가진 `AvatarModifierType.AMT_HIDE_AVATARS` 수정자가 적용되면, 플레이어의 아바타가 더 이상 렌더링되지 않습니다. 이는 3인칭 시점의 플레이어에게도 적용되고, 다른 플레이어가 그 영역에 들어올 때도 적용됩니다.

```ts
const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})
```

이를 통해 기본 디센트럴랜드 아바타를 장면에 표시하고 싶은 사용자 지정 아바타로 대체할 수 있습니다. 다음을 참조하세요 [플레이어의 아바타 교체](/creator/content-creator-ko/sdk7/interactivity/avatars/npc-avatars.md#replace-the-players-avatar). 다른 플레이어를 사용자 지정 아바타로 보이게 하려면, 플레이어 위치 동기화는 직접 처리해야 한다는 점에 유의하세요.

### 여권 팝업 비활성화

플레이어가 다음에 들어가면 `AvatarModifierArea` 다음을 가진 `AvatarModifierType.AMT_DISABLE_PASSPORTS` 수정자가 적용되면, 해당 플레이어를 클릭해도 더 이상 플레이어 소개, 인벤토리 등을 보여주는 여권 UI가 열리지 않습니다.

```ts
const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_DISABLE_PASSPORTS],
	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})
```

이 기능은 실수로 이 UI를 열면 게임 흐름이 끊길 수 있는 게임, 예를 들어 멀티플레이어 슈팅 게임에서 특히 유용합니다.

### 이름표 숨기기

플레이어가 다음에 들어가면 `AvatarModifierArea` 다음을 가진 `AvatarModifierType.AMT_HIDE_NAMETAGS` 수정자가 적용되면 아바타 자체는 보이지만 플레이어의 이름표는 숨겨집니다.

```ts
const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_HIDE_NAMETAGS],
	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})
```

이는 아바타 자체는 숨기지 않고 플레이어 이름표만 없애고 싶은 무대, 발표, 또는 스크립트된 장면에서 유용합니다. 예를 들어, 공연 중에는 아바타는 보이지만 떠다니는 이름이 관객의 시선을 방해하지 않도록 깔끔한 시각 경험을 제공하고 싶을 수 있습니다.

`AMT_HIDE_NAMETAGS` 또한 다음을 사용해 추가된 사용자 지정 플레이트도 숨깁니다 [`AvatarNametag`](/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-nametags.md) 컴포넌트를 추가해야 합니다.

{% hint style="info" %}
**💡 팁**: `AMT_HIDE_AVATARS` 이미 아바타와 함께 이름표도 숨기므로, 다음을 추가할 필요가 없습니다 `AMT_HIDE_NAMETAGS` 다음을 사용할 때 `AMT_HIDE_AVATARS`. 다음을 사용하세요 `AMT_HIDE_NAMETAGS` 아바타는 보이게 두고 이름표만 숨기고 싶을 때만 사용하세요.
{% endhint %}

다음을 결합할 수 있습니다 `AMT_HIDE_NAMETAGS` 다음과 같은 다른 수정자와 함께 `AMT_DISABLE_PASSPORTS` 를 같은 영역에 적용하세요:

```ts
const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_HIDE_NAMETAGS, AvatarModifierType.AMT_DISABLE_PASSPORTS],
	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})
```

{% hint style="info" %}
**💡 팁**: 이름표는 플레이어의 머리나 몸통이 영역 안에 있을 때만 숨겨집니다. 영역이 너무 낮아서 플레이어가 이중 점프로 그 위를 넘으면 이름표가 잠깐 다시 나타납니다. 예상되는 이동 범위를 덮을 만큼 영역을 충분히 높게 만드세요.
{% endhint %}

### 아바타 제외

플레이어 ID를 다음의 배열에 추가하여, 수정 영역의 영향을 받지 않을 플레이어 목록을 제외할 수 있습니다 `excludeIds` 수정 영역의 속성에

이 예시는 특정 ID를 가진 플레이어의 아바타를 제외하고 영역 안의 모든 아바타를 숨깁니다. 예를 들어 라이브 이벤트에서 무대 위에 있는 진행자만 보여 주고 무대로 뛰어오르는 다른 플레이어는 숨기는 데 사용할 수 있습니다.

```ts
const entity = engine.addEntity()

AvatarModifierArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
	excludeIds: ['0xx1...', '0xx2...'],
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
})
```

{% hint style="warning" %}
**📔 참고**: 플레이어 ID는 모두 소문자로 작성되어야 합니다. 다음을 사용하세요 `.toLowerCase()` 필요하다면.
{% endhint %}

수정 영역은 각 플레이어 인스턴스에서 로컬로 실행됩니다. 제외된 ID 목록은 플레이어마다 다를 수 있습니다. 아래 예시에서는 각 플레이어가 아바타를 숨기는 수정자에서 자기 자신의 ID를 제외하여, 각자 자신의 아바타만 보고 다른 아바타는 보지 않게 됩니다.

```ts
import { getPlayer } from '@dcl/sdk/src/players'

export function main() {
	let userData = getPlayer()
	if (!userData) return

	const entity = engine.addEntity()

	AvatarModifierArea.create(entity, {
		area: Vector3.create(16, 5, 16),
		modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
		excludeIds: [userData.userId],
	})

	Transform.create(entity, {
		position: Vector3.create(8, 0, 8),
	})
}
```

{% hint style="danger" %}
**❗경고**\
제외된 ID 목록이 주기적으로 변경될 예정이라면(예: 플레이어가 영역에 들어오거나 나갈 때), 목록의 순서를 유지하세요. 다음을 수행하세요 `.sort()` 을 배열에 적용하여, 전달될 때마다 목록의 순서가 동일하게 유지되도록 하세요. 이렇게 하면 목록의 변경 사항만 계산됩니다. 그렇지 않으면 장면 성능에 큰 영향을 줄 수 있습니다.

```ts
AvatarModifierArea.create(entity, {
	area: Vector3.create(16, 5, 16),
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
	excludeIds: myAvatarList.sort(),
})
```

{% endhint %}

### 수정 영역 디버그

코드만으로는 수정 영역이 장면의 어느 부분을 덮는지 정확히 알기 어려울 수 있습니다. 시각적 피드백은 제대로 배치되었는지 확인하는 데 큰 도움이 됩니다.

다음의 위치를 확인하려면 `AvatarModifierArea` 나 `CameraModeArea`, 이를 보유한 엔티티에 다음을 부여하세요 `MeshRenderer` 다음이 포함된 컴포넌트를 `박스` 모양으로 설정하고, 스케일을 다음과 같은 크기로 맞추세요 `area` 수정 영역의

{% hint style="warning" %}
**📔 참고**: 수정 영역은 다음의 영향을 받지 않습니다 `크기` transform의 속성은 영향을 주지 않으며, 크기는 해당 `area` 속성으로 정의됩니다.
{% endhint %}

```ts
const entity = engine.addEntity()
const areaSize = Vector3.create(8, 3, 8)

AvatarModifierArea.create(entity, {
	area: areaSize,
	modifiers: [AvatarModifierType.AMT_HIDE_AVATARS],
  	excludeIds: []
})

Transform.create(entity, {
	position: Vector3.create(8, 0, 8),
	scale: areaSize,
})

MeshRenderer.setBox(entity)
Material.setPbrMaterial(entity, {
	albedoColor: Color4.create(0.5, 0.5, 0.5, 0.5),
})
```

수정 영역의 효과를 활성화하려면 플레이어의 머리나 몸통이 영역 안으로 들어가야 합니다. 플레이어의 발만 영역 안에 있으면 효과가 적용되지 않습니다. 점프로 쉽게 영역을 피하지 못하도록 하세요.

{% hint style="warning" %}
**📔 참고**: 전체 영역은 장면의 경계 안에 들어가야 합니다.
{% endhint %}

{% hint style="info" %}
**💡 팁**: 동작하는 예시는 다음을 참조하세요 [`9,99-modifier-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/9,99-modifier-areas) 테스트 장면은 다음을 결합합니다 `AvatarModifierArea` 런타임에 변경되는 다음과 `excludeIds`, 그리고 [`10,99-avatar-modifier-hide-nametags`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/10,99-avatar-modifier-hide-nametags), 이것은 다음을 분리합니다 `AMT_HIDE_NAMETAGS` 수정자
{% 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/avatars/modifier-areas.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.