头像姓名标签

在头像姓名标签上方显示自定义标签，以展示等级、角色或队伍。

该 头像名牌 该组件会在头像的常规名牌上方添加一个小牌子，显示场景选择的文本。可用它来显示你场景为玩家追踪的等级、角色、队伍或其他任何信息，例如“VIP”、“红队”或“俱乐部所有者”。

由场景提供、显示在玩家常规名牌上方的牌子

本页介绍如何添加牌子、设置样式，以及在玩家进出时保持同步。

📔 注意: 头像名牌 需要 @dcl/sdk 7.28.0 或更新版本。

为玩家添加一个牌子

唯一必需的字段是 label，要显示的文本。

import { AvatarNametag, engine } from '@dcl/sdk/ecs'

// 在当前玩家的名牌上方显示“俱乐部所有者”
AvatarNametag.create(engine.PlayerEntity, {
	label: '俱乐部所有者',
})

默认情况下，牌子会使用客户端自身的名牌颜色，因此无需额外操作就能与界面其余部分保持一致。

💡 提示: 你无需等待头像完成加载后再写入组件。如果头像仍在加载，牌子会在准备好后立即应用。

组件适用的位置

头像名牌 仅对带有头像的实体起作用：

• engine.PlayerEntity，即运行该场景的玩家。

• 另一位玩家的实体，可通过其 PlayerIdentityData 组件。

• 一个 NPC 头像，即任何具有 AvatarShape 组件。

在其他任何实体上，该组件都会被忽略。

📔 注意: 牌子对渲染它的客户端来说是本地的。它不会发送给其他玩家。如果你希望每个人都看到相同的牌子，那么每个客户端都必须基于所有人都能读取的数据运行相同的逻辑。参见 多人场景中的牌子.

更改颜色

有三个可选字段使用 Color3:

• labelColor：文本颜色。默认为客户端原生名牌的文本颜色。

• backgroundColor：牌子的填充色。默认为客户端原生名牌的背景颜色。

• borderColor：牌子的轮廓。默认为 backgroundColor，因此除非你设置它，否则不会显示可见边框。

import { AvatarNametag, engine } from '@dcl/sdk/ecs'
import { Color3 } from '@dcl/sdk/math'

// 一个白色文本、深蓝色底、浅蓝色边框的牌子
AvatarNametag.create(engine.PlayerEntity, {
	label: '学生',
	labelColor: Color3.White(),
	backgroundColor: Color3.create(0.1, 0.2, 0.6),
	borderColor: Color3.create(0.78, 0.85, 1),
})

要将某个字段恢复为原生颜色，请在写入组件时不包含该字段再次写入。使用 createOrReplace 而不是 getMutable，因为只有替换整个组件才会清除你省略的字段：

// 保留标签，去掉自定义颜色，恢复原生外观
AvatarNametag.createOrReplace(engine.PlayerEntity, { label: '学生' })

移除牌子

使用 deleteFrom 以移除该牌子。头像的常规名牌不受影响：

AvatarNametag.deleteFrom(engine.PlayerEntity)

标签行为

在选择标签文本之前，有几点值得了解：

• 较长的标签会被截断 并显示省略号。请将标签保持为一两个词。

• 空标签 (''）会绘制一个不含文本的牌子。

• 空格会被保留，因此只由空格组成的标签会使没有文本的牌子变宽。这是一种调整纯色牌子大小的方法。

• 要隐藏文字但保留其宽度，请将 labelColor 设置为与 backgroundColor.

💡 提示: 牌子不一定需要任何文本。例如，要单独显示一个颜色编码的牌子，比如用于标记队伍归属，请将 label 设置为空格字符串，并选择一个 backgroundColor。

AvatarNametag.createOrReplace(engine.PlayerEntity, {
	label: '      ',
	backgroundColor: Color3.Red(),
})

在玩家到达时标记他们

标记其他玩家最简单的方法是在他们进入场景时附加该组件，使用 onEnterScene 事件。每次它都会给你一个新的实体，因此无需查找或缓存任何东西：

import { onEnterScene } from '@dcl/sdk/players'
import { AvatarNametag } from '@dcl/sdk/ecs'

export function main() {
	onEnterScene((player) => {
		AvatarNametag.createOrReplace(player.entity, { label: 'VIP' })
	})
}

参见 获取玩家数据 以了解有关跟踪玩家进出场景的更多信息。

为场景中的每位玩家标记

要一次性在所有人头上显示牌子，请遍历具有 PlayerIdentityData 组件。

将实体收集到数组中 然后再 写入它们。在仍然遍历 engine.getEntitiesWith() 时写入组件，可能会使查询在中途失效。

import { AvatarNametag, engine, Entity, PlayerIdentityData } from '@dcl/sdk/ecs'

const LABELS = ['Blue Team', 'Red Team']

function tagAllPlayers() {
	// 1. 先收集
	const players: { entity: Entity; address: string }[] = []
	for (const [entity, identity] of engine.getEntitiesWith(PlayerIdentityData)) {
		players.push({ entity, address: identity.address.toLowerCase() })
	}

	// 按地址排序可让每个客户端得到相同结果，
	// 不管玩家是按什么顺序加入的
	players.sort((a, b) => a.address.localeCompare(b.address))

	// 2. 然后写入，但仅在标签实际改变时
	players.forEach(({ entity }, index) => {
		const label = LABELS[index % LABELS.length]
		if (AvatarNametag.getOrNull(entity)?.label === label) return
		AvatarNametag.createOrReplace(entity, { label })
	})
}

在写入前与当前值比较，可以避免每次遍历都进行不必要的组件更新。

跟上玩家的加入和离开

玩家实体 ID 在断线后并不稳定。当玩家离开时，其实体 ID 会被回收，并可能分配给下一位加入的玩家，因此写入过期实体上的牌子最终会显示在错误的头像上。

遵循两条规则可确保正确：

• 在 每次 写入之前重新解析实体，而不是缓存实体。

• 当玩家离开时移除该组件。

按定时器重新运行标记函数，可以捕捉稍后加入的玩家，并且不会持有过期实体。每秒一次就足够频繁：

let timer = 0

engine.addSystem((dt: number) => {
	timer += dt
	if (timer < 1) return
	timer = 0
	tagAllPlayers()
})

多人场景中的牌子

牌子对每位玩家的客户端都是本地的。牌子不会发送给其他玩家；每位玩家的场景副本都会计算自己的牌子。如果所有玩家都应看到相同的标签，那么分配它们的逻辑必须基于所有客户端都能读取的数据，在每个客户端上得到相同结果。像上面的示例那样按钱包地址对玩家排序，就是一种实现方式。否则，你的场景需要自行同步这些分配，参见 无服务器多人.

与隐藏名牌的交互

一个 AvatarModifierArea 配合 AMT_HIDE_NAMETAGS 修饰器会连同常规名牌一起隐藏这些牌子。对 AMT_HIDE_AVATARS也同样适用，它会隐藏整个头像。

如果你希望头像只显示 仅 你的牌子，而下方不显示姓名，请将 AvatarShape 组件的 name 设为空字符串。参见 NPC 头像.

相关页面

• 头像修饰区域：隐藏场景某个区域内的头像和名牌。

• 移动玩家 和 头像动画：控制玩家的头像。

• NPC 头像：显示非玩家的头像。

• 获取玩家数据：读取有关玩家和场景中其他所有人的数据。

• 颜色类型：如何构建 Color3 值列表。