> 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-pt/scenes-sdk7/interatividade/avatares/modifier-areas.md).

# Áreas de Modificador de Avatar

Oculte avatares, oculte nametags ou desative passaportes para jogadores dentro de uma região da sua scene

Os avatares comportam-se e têm uma aparência consistente em todo o Decentraland enquanto caminham pelas scenes. No entanto, você pode adicionar um `AvatarModifierArea` a uma região da sua scene para afetar como os avatares dos jogadores se comportam quando entram nessa área.

{% hint style="danger" %}
**❗Aviso**\
Limite a quantidade de `AvatarModifierAreas` que você usa na sua scene a apenas algumas. Se você usar muitas delas, isso pode ter um impacto significativo no desempenho.
{% endhint %}

### Posicionando Avatar Modifier Areas

Adicione uma entity com um `AvatarModifierArea` component e posicione esta entity usando um `Transform` component.

```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),
})
```

Ao criar um `AvatarModifierArea` component, você deve fornecer o seguinte:

* `area`: Tamanho da área modificadora
* `modifiers`: Um array que lista os modifiers a implementar na área. Esta property usa valores de `AvatarModifierType` .

Os modifiers suportados são:

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

Todos os efeitos de um `AvatarModifierArea` ocorrem apenas dentro da região da sua área. Os jogadores voltam ao normal quando saem da área.

Um `AvatarModifierArea` afeta apenas os players que estão dentro da área. Entrar na área não afeta como os outros players fora da área são percebidos.

Os efeitos de um `AvatarModifierArea` são calculados localmente para cada player. Você pode ter um `AvatarModifierArea` que está presente na scene apenas para alguns players e não para outros. Por exemplo, você pode criar um jogo de "marco polo", em que apenas um player na scene tem uma modifier area que oculta todos os outros players. Todos os outros players que não têm essa modifier area na sua versão local da scene conseguem se ver normalmente.

Se a área ocultar avatares, então os players que não têm a área na sua versão local da scene verão todos os avatares normalmente, inclusive aqueles que se percebem como ocultos. Os players que têm a área se perceberão a si mesmos e a todos os outros avatares como afetados pela área quando entrarem nela.

{% hint style="warning" %}
**📔 Observação**: As Avatar modifier areas são afetadas pelo *position* e *rotation* da Transform component da host entity, mas não são afetadas pelo *scale*.
{% endhint %}

{% hint style="warning" %}
**📔 Observação**: A `AvatarModifierArea`component deve ser importado via

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

Veja [Imports](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com isso facilmente.
{% endhint %}

### Ocultar avatares

Quando um player entra em um `AvatarModifierArea` que tem o `AvatarModifierType.AMT_HIDE_AVATARS` modifier, o avatar do player deixa de ser renderizado. Isso se aplica tanto ao player em visão em terceira pessoa quanto quando outros players entram na área.

```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),
})
```

Isso permite substituir o avatar padrão do Decentraland por qualquer avatar customizado que você queira mostrar na sua scene, veja [Substituir o avatar do jogador](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/npc-avatars.md#replace-the-players-avatar). Observe que, se quiser ver outros players com avatares customizados, você deve cuidar da sincronização das posições dos players por conta própria.

### Desativar popup do Passport

Quando um player entra em um `AvatarModifierArea` que tem o `AvatarModifierType.AMT_DISABLE_PASSPORTS` modifier, clicar neles já não abre a UI do Passport que mostra a bio do player, inventário, etc.

```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),
})
```

Isto é especialmente útil em games em que abrir esta UI por acidente poderia interromper o fluxo do game, por exemplo num jogo de tiro multijogador.

### Ocultar nametags

Quando um player entra em um `AvatarModifierArea` que tem o `AvatarModifierType.AMT_HIDE_NAMETAGS` modifier, o nametag do player é ocultado enquanto o avatar em si permanece visível.

```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),
})
```

Isto é útil para stages, apresentações ou scenes roteirizadas em que você quer suprimir os nametags dos players sem ocultar os avatares em si. Por exemplo, você pode querer uma experiência visual limpa durante uma performance, em que os avatares ficam visíveis, mas os nomes flutuantes não distraem os espectadores.

`AMT_HIDE_NAMETAGS` também oculta quaisquer placas customizadas adicionadas com o [`AvatarNametag`](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-nametags.md) component.

{% hint style="info" %}
**💡 Dica**: `AMT_HIDE_AVATARS` já oculta os nametags junto com o avatar, então você não precisa adicionar `AMT_HIDE_NAMETAGS` ao usar `AMT_HIDE_AVATARS`. Use `AMT_HIDE_NAMETAGS` apenas quando quiser ocultar os nametags enquanto mantém os avatares visíveis.
{% endhint %}

Você pode combinar `AMT_HIDE_NAMETAGS` com outros modifiers como `AMT_DISABLE_PASSPORTS` na mesma área:

```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" %}
**💡 Dica**: O nametag só fica oculto enquanto a cabeça ou o torso do player estiver dentro da área. Se a área for muito baixa e o player der um salto duplo por cima dela, o nametag reaparecerá brevemente. Faça a área alta o suficiente para cobrir a faixa de movimento esperada.
{% endhint %}

### Excluir avatares

Você pode excluir uma lista de players de serem afetados por uma modifier area adicionando os seus player IDs a um array na `excludeIds` propriedade da modifier area.

Este exemplo oculta todos os avatares numa área, exceto os de players com IDs específicos. Você poderia usar isso, por exemplo, num evento ao vivo, para mostrar apenas os anfitriões do evento no stage e ocultar quaisquer outros players que saltem para o stage.

```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" %}
**📔 Observação**: Certifique-se de que todos os player IDs estejam escritos com letras minúsculas. Use `.toLowerCase()` se necessário.
{% endhint %}

As modifier areas executam-se localmente na instância de cada player. A lista de IDs excluídos pode ser diferente para cada player. No exemplo abaixo, cada player exclui o seu próprio ID de um modifier que oculta avatares, para que cada um veja o seu próprio avatar e nenhum outro.

```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" %}
**❗Aviso**\
Se a lista de IDs excluídos for alterada periodicamente (por exemplo, com base em players que entram ou saem de uma área), certifique-se de que a lista seja mantida em ordem. Faça um `.sort()`  no array, para que a lista permaneça na mesma ordem cada vez que for passada. Dessa forma, apenas as alterações na lista são calculadas. Caso contrário, isso pode ter um impacto significativo no desempenho da scene.

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

{% endhint %}

### Depurar modifier areas

Pode ser difícil saber exatamente que partes da scene as suas modifier areas cobrem com base no código. O feedback visual ajuda bastante a confirmar que estão bem posicionadas.

Para verificar as posições de uma `AvatarModifierArea` ou um `CameraModeArea`, dê à entity que a contém um `MeshRenderer` component com um `caixa` shape e defina a escala para o mesmo tamanho da `area` da modifier area.

{% hint style="warning" %}
**📔 Observação**: As modifier areas não são afetadas pela `scale` propriedade do transform, o seu tamanho é baseado no seu `area` propriedade.
{% 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),
})
```

Para ativar os efeitos da modifier area, a cabeça ou o torso do player deve entrar na área. Não terá efeito se apenas os pés do player estiverem na área. Certifique-se de que o player não consiga evitar facilmente a área saltando.

{% hint style="warning" %}
**📔 Observação**: A área completa deve caber dentro dos limites da sua scene.
{% endhint %}

{% hint style="info" %}
**💡 Dica**: Para exemplos funcionais, veja a [`9,99-modifier-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/9,99-modifier-areas) test scene, que combina `AvatarModifierArea` com runtime-mutated `excludeIds`, e [`10,99-avatar-modifier-hide-nametags`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/10,99-avatar-modifier-hide-nametags), que isola o `AMT_HIDE_NAMETAGS` modifier.
{% 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-pt/scenes-sdk7/interatividade/avatares/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.