아바타 이름표

아바타 이름표 위에 사용자 지정 라벨을 표시하여 순위, 역할 또는 팀을 보여줍니다.

이 AvatarNametag 이 컴포넌트는 아바타의 일반 이름표 위에 작은 플레이트를 추가해, 씬이 선택한 텍스트를 표시합니다. 이를 사용해 순위, 역할, 팀 또는 씬이 플레이어에 대해 추적하는 그 밖의 항목(예: "VIP", "Team Red", "Club Owner")을 보여줄 수 있습니다.

플레이어의 일반 이름표 위에 씬이 제공하는 플레이트

이 페이지는 플레이트를 추가하고, 스타일을 지정하고, 플레이어가 들어오고 나갈 때 그 상태를 유지하는 방법을 다룹니다.

📔 참고: AvatarNametag 필요 @dcl/sdk 버전 7.28.0 이상.

플레이어에게 플레이트 추가

필수 필드는 레이블, 표시할 텍스트입니다.

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

// 현재 플레이어의 이름표 위에 "클럽 소유자"를 표시
AvatarNametag.create(engine.PlayerEntity, {
	label: '클럽 소유자',
})

플레이트는 기본적으로 클라이언트 고유의 이름표 색상을 사용하므로, 추가 작업 없이도 나머지 인터페이스와 어울립니다.

💡 팁: 아바타가 로드될 때까지 기다리지 않고도 컴포넌트를 작성할 수 있습니다. 아바타가 아직 로딩 중이라면, 준비되는 즉시 플레이트가 적용됩니다.

컴포넌트가 작동하는 곳

AvatarNametag 아바타를 가진 엔티티에서만 동작합니다:

• 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.

💡 팁: 플레이트에는 텍스트가 필요하지 않습니다. 예를 들어 팀 소속을 표시하기 위해 색상으로 구분된 플레이트만 보여주려면, 다음을 설정하세요: 레이블 를 공백 문자열로 설정하고 다음을 선택하세요: 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 = ['파란 팀', '빨간 팀']

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가 재사용되어 다음에 들어오는 플레이어에게 할당될 수 있으므로, 오래된 엔티티에 쓴 플레이트가 엉뚱한 아바타 위에 나타날 수 있습니다.

이를 올바르게 유지하는 두 가지 규칙이 있습니다:

• 엔티티를 새로 확인하세요. 바로 매번 쓰기 전에, 엔티티를 캐시하지 말고.

• 플레이어가 나가면 컴포넌트를 제거하세요.

태그 함수를 타이머로 다시 실행하면 나중에 들어온 플레이어도 잡을 수 있고, 오래된 엔티티를 붙잡고 있지 않게 됩니다. 1초마다 실행하면 충분합니다:

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 값을.