> 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-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/modifier-areas.md).

# 头像修饰区域

在场景中的某个区域内隐藏头像、隐藏姓名标签，或禁用玩家护照

当头像在场景中移动时，它们在整个 Decentraland 中的行为和外观都保持一致。不过，你可以添加一个 `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` 组件时，你必须提供以下内容：

* `区域`：修饰区域的大小
* `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 { AvatarModifierArea } from "@dcl/sdk/ecs"`

参见 [导入](/creator/content-creator-zh/chang-jing-sdk7/ru-men/coding-scenes.md#imports) ，了解如何轻松处理这些内容。
{% endhint %}

### 隐藏头像

当玩家走进一个 `AvatarModifierArea` 并且带有 `AvatarModifierType.AMT_HIDE_AVATARS` 修改器时，该玩家的头像将停止渲染。这既适用于第三人称视角下的玩家，也适用于其他玩家走入该区域时。

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

这让你可以用任何你想在场景中展示的自定义头像替换默认的 Decentraland 头像，参见 [替换玩家头像](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/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` 也会隐藏通过 [`头像名牌`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/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` 组件，并带有一个 `盒体` 形状，并将缩放设置为与 `区域` 修改区域相同的大小。

{% hint style="warning" %}
**📔 注意**：修改区域不受 `缩放` 变换的属性影响，它们的大小基于其 `区域` 属性定义。
{% 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-修饰区域`](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-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/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.