> 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 Avatars comportam-se e têm um aspeto consistentes em toda a Decentraland enquanto caminham pelas Scenes. No entanto, pode adicionar uma `AvatarModifierArea` a uma região da sua Scene para afetar o comportamento dos Avatars dos jogadores quando entram nessa área.

{% hint style="danger" %}
**❗Aviso**\
Limite a quantidade de `AvatarModifierAreas` que utiliza na sua Scene a apenas algumas. Se utilizar demasiadas, o desempenho poderá ser significativamente afetado.
{% endhint %}

### Colocar Avatar Modifier Areas

Adicione uma entidade com um componente `AvatarModifierArea` e posicione essa entidade utilizando um componente `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),
})
```

Ao criar um componente `AvatarModifierArea` , tem de fornecer o seguinte:

* `area`: Tamanho da área de modificação
* `modifiers`: uma matriz que enumera os modificadores a aplicar na área. Esta propriedade utiliza valores do enum `AvatarModifierType` .

Os modificadores suportados são:

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

Todos os efeitos de uma `AvatarModifierArea` só ocorrem dentro da região da respetiva área. Os jogadores regressam ao normal quando saem da área.

Uma `AvatarModifierArea` afeta apenas os jogadores que se encontram dentro da área. Entrar na área não afeta a forma como os outros jogadores que estão fora dela são vistos.

Os efeitos de uma `AvatarModifierArea` são calculados localmente para cada jogador. Pode ter uma `AvatarModifierArea` presente na Scene para alguns jogadores, mas não para outros. Por exemplo, poderia criar um jogo de «marco polo» em que apenas um jogador na Scene tem uma área de modificadores que oculta todos os outros jogadores. Todos os outros jogadores que não têm esta área de modificadores na sua versão local da Scene conseguem ver-se normalmente.

Se a área ocultar Avatars, os jogadores que não têm a área na sua versão local da Scene verão todos os Avatars normalmente, incluindo os que se veem como ocultos. Os jogadores que têm a área verão a si próprios e todos os outros Avatars afetados pela área quando entrarem nela.

{% hint style="warning" %}
**📔 Nota**: As áreas de modificadores de Avatar são afetadas pela *posição* e *rotação* do componente Transform da entidade que as contém, mas não são afetadas pela *escala*.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: O componente `AvatarModifierArea`tem de ser importado através de

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

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

### Ocultar avatares

Quando um jogador entra numa `AvatarModifierArea` que tem o modificador `AvatarModifierType.AMT_HIDE_AVATARS` , o avatar do jogador deixa de ser renderizado. Isto aplica-se tanto ao jogador na perspetiva de terceira pessoa como aos outros jogadores que entrem 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),
})
```

Isto permite substituir o avatar predefinido do Decentraland por qualquer avatar personalizado que queira mostrar na sua Scene. Consulte [Substituir o avatar do jogador](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/npc-avatars.md#replace-the-players-avatar). Tenha em atenção que, se quiser ver os outros jogadores com avatares personalizados, terá de tratar da sincronização das posições dos jogadores.

### Desativar o pop-up do passaporte

Quando um jogador entra numa `AvatarModifierArea` que tem o modificador `AvatarModifierType.AMT_DISABLE_PASSPORTS` , clicar no jogador deixa de abrir a UI do passaporte, que mostra a biografia, o 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 jogos em que abrir esta UI acidentalmente poderia interromper o desenrolar do jogo, por exemplo, num jogo de tiros multijogador.

### Ocultar etiquetas de nome

Quando um jogador entra numa `AvatarModifierArea` que tem o modificador `AvatarModifierType.AMT_HIDE_NAMETAGS` , a etiqueta de nome do jogador fica oculta, enquanto o avatar 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 em palcos, apresentações ou cenas com guião, quando pretende ocultar as etiquetas de nome dos jogadores sem ocultar os próprios avatares. Por exemplo, pode querer proporcionar uma experiência visual sem distrações durante uma atuação, mantendo os avatares visíveis, mas ocultando os nomes flutuantes que poderiam distrair o público.

`AMT_HIDE_NAMETAGS` também oculta quaisquer placas personalizadas adicionadas com o componente [`AvatarNametag`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-nametags.md) .

{% hint style="info" %}
**💡 Sugestão**: `AMT_HIDE_AVATARS` já oculta as etiquetas de nome juntamente com o avatar, por isso não precisa de adicionar `AMT_HIDE_NAMETAGS` ao usar `AMT_HIDE_AVATARS`. Use `AMT_HIDE_NAMETAGS` apenas quando quiser ocultar as etiquetas de nome e manter os avatares visíveis.
{% endhint %}

Pode combinar `AMT_HIDE_NAMETAGS` com outros modificadores, 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" %}
**💡 Sugestão**: a etiqueta de nome fica oculta apenas enquanto a cabeça ou o tronco do jogador estiver dentro da área. Se a área for demasiado baixa e o jogador saltar duas vezes por cima dela, a etiqueta de nome reaparecerá por breves instantes. Torne a área suficientemente alta para abranger a amplitude de movimentos prevista.
{% endhint %}

### Excluir avatares

Pode excluir uma lista de jogadores dos efeitos de uma área de modificadores adicionando os respetivos IDs de jogador a uma matriz na propriedade `excludeIds` da área de modificadores.

Este exemplo oculta todos os avatares numa área, exceto os dos jogadores com IDs específicos. Pode usar esta funcionalidade, por exemplo, num evento ao vivo, para mostrar apenas os anfitriões do evento no palco e ocultar os restantes jogadores que subam ao palco.

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

As áreas de modificadores são executadas localmente na instância de cada jogador. A lista de IDs excluídos pode ser diferente para cada jogador. No exemplo abaixo, cada jogador exclui o próprio ID de um modificador que oculta os avatares, para que cada um veja o próprio avatar e nenhum dos outros.

```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 nos jogadores que entram ou saem de uma área), mantenha a lista ordenada. Use `.sort()` no array, para que a lista permaneça na mesma ordem cada vez que for passada. Assim, apenas as alterações na lista são calculadas. Caso contrário, isso pode afetar significativamente o desempenho da cena.

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

{% endhint %}

### Áreas sobrepostas e alterações em runtime

Cada avatar tem um sinalizador de ligado/desligado para cada efeito, e não uma contagem das áreas em que está. Cada área grava nesse mesmo sinalizador, e a última gravação prevalece. Há duas consequências que costumam surpreender:

* **Ao sair de uma área, o avatar volta a ser exibido, mesmo que ainda esteja dentro de outra.** Ao sair de uma área pequena que oculta avatares, o avatar volta a ficar visível, embora uma área que oculta avatares em toda a cena ainda cubra esse local.
* **Uma área cuja `excludeIds` inclui um jogador define o estado desse jogador como «visível» ao entrar**, para cada efeito listado pela própria área. Isso substitui o efeito de uma área que oculta todos, na qual o jogador também esteja.

Prefira usar uma área de cada vez para cada avatar. Se as áreas se sobrepuserem, configure-as de modo que concordem em relação a todos os efeitos.

**Remover um modificador no local não o desfaz.** Quando você altera os campos de uma área, o cliente reaplica os modificadores listados no momento. Nada restaura um efeito cujo modificador foi removido da lista, então esvaziar `modifiers`, ou substituir `AMT_HIDE_AVATARS` por `AMT_HIDE_NAMETAGS`, mantém os avatares ocultos. Adicionar um modificador no local funciona.

Para mudar uma área para um conjunto diferente de modificadores, remova a entidade e crie a substituta no mesmo frame:

```ts
import { AvatarModifierArea, AvatarModifierType, engine, Entity, Transform } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

// Substitua a área em vez de editar seus modificadores no local
function setModifiers(oldArea: Entity, modifiers: AvatarModifierType[]): Entity {
	engine.removeEntity(oldArea) // isso também volta a exibir todos os avatares dentro dela

	const area = engine.addEntity()
	Transform.create(area, { position: Vector3.create(8, 1, 8) })
	AvatarModifierArea.create(area, {
		area: Vector3.create(16, 5, 16),
		modifiers,
		excludeIds: [],
	})
	return area
}
```

### Depurar áreas de modificadores

Pode ser difícil saber exatamente quais partes da cena são abrangidas pelas áreas de modificadores com base apenas no código. O feedback visual ajuda bastante a confirmar se elas estão bem posicionadas.

Para verificar as posições de uma `AvatarModifierArea` ou de uma `CameraModeArea`, atribua à entidade que a contém um `MeshRenderer` componente com uma `box` forma e defina a escala com o mesmo tamanho da `area` da área do modificador.

{% hint style="warning" %}
**📔 Nota**: As áreas de modificador não são afetadas pela propriedade `scale` do transform; o tamanho é determinado pela propriedade `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),
})
```

Para ativar os efeitos da área do modificador, a cabeça ou o torso do jogador tem de entrar na área. O efeito não será ativado se apenas os pés do jogador estiverem na área. Certifique-se de que o jogador não consegue evitar facilmente a área saltando.

{% hint style="warning" %}
**📔 Nota**: A área completa deve caber dentro dos limites da sua cena.
{% endhint %}

{% hint style="info" %}
**💡 Dica**: Para ver exemplos funcionais, consulte a cena de teste [`9,99-modifier-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/9,99-modifier-areas) , que combina `AvatarModifierArea` com `excludeIds`modificado em tempo de execução, 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 modificador `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-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.
