From 76445a6d018cf88fd4931b48177cf6b18e1f3cef Mon Sep 17 00:00:00 2001
From: Vitaly Popuzin <35366872+popuz@users.noreply.github.com>
Date: Fri, 4 Sep 2026 12:03:09 +0200
Subject: [PATCH] feat: AvatarNametag component (id 1221) (#474)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A scene-authored plate drawn above an avatar's nametag — a rank or a role the scene assigns to a player.

Valid on `engine.PlayerEntity`, on a player's entity in the scene, or on any entity with an AvatarShape; ignored elsewhere. The plate is local to the client that renders it and is never relayed to other players, and only the scene the player currently stands in can write it.

`label` is a single line; empty draws the plate without text, for color-coding players. The three colors are optional: `label_color` and `background_color` fall back to the client's native nametag colors, `border_color` to `background_color`.

Implemented in decentraland/unity-explorer#9829.
---
 .../sdk/components/avatar_nametag.proto       | 33 +++++++++++++++++++
 public/sdk-components.proto                   |  1 +
 2 files changed, 34 insertions(+)
 create mode 100644 proto/decentraland/sdk/components/avatar_nametag.proto

diff --git a/proto/decentraland/sdk/components/avatar_nametag.proto b/proto/decentraland/sdk/components/avatar_nametag.proto
new file mode 100644
index 00000000..a139c9f7
--- /dev/null
+++ b/proto/decentraland/sdk/components/avatar_nametag.proto
@@ -0,0 +1,33 @@
+syntax = "proto3";
+
+package decentraland.sdk.components;
+
+import "decentraland/common/colors.proto";
+import "decentraland/sdk/components/common/id.proto";
+
+option (common.ecs_component_id) = 1221;
+
+// The AvatarNametag component adds a plate with scene-provided text above an avatar's nametag,
+// for example to show a rank or a role that the scene assigns to that player.
+//
+// Valid only on an avatar-bearing entity:
+// - the local player: `engine.PlayerEntity`
+// - another player in the scene: that player's entity
+// - an NPC: any entity with an AvatarShape
+// Writes to any other entity are ignored.
+//
+// Player entity ids are not stable across disconnects: a write to a stale entity lands on
+// whoever holds that id next. Resolve the entity from the user id on every write, and remove
+// the component when the player leaves the scene.
+//
+// The plate is local to the client that renders it; it is never relayed to other players.
+message PBAvatarNametag {
+  // The plate text: a single line, for example "Club Owner". Empty draws the plate without text,
+  // and spaces are preserved: a label of spaces widens a text-less plate. For a plate sized
+  // exactly to a word without showing it, set label_color equal to background_color instead.
+  string label = 1;
+
+  optional decentraland.common.Color3 label_color = 2;      // (default: the client's native nametag text color)
+  optional decentraland.common.Color3 background_color = 3; // (default: the client's native nametag background color)
+  optional decentraland.common.Color3 border_color = 4;     // (default: background_color, so the plate carries no visible border)
+}
diff --git a/public/sdk-components.proto b/public/sdk-components.proto
index f1a19d05..c5e2912c 100644
--- a/public/sdk-components.proto
+++ b/public/sdk-components.proto
@@ -9,6 +9,7 @@ import public "decentraland/sdk/components/avatar_base.proto";
 import public "decentraland/sdk/components/avatar_emote_command.proto";
 import public "decentraland/sdk/components/avatar_equipped_data.proto";
 import public "decentraland/sdk/components/avatar_modifier_area.proto";
+import public "decentraland/sdk/components/avatar_nametag.proto";
 import public "decentraland/sdk/components/avatar_shape.proto";
 import public "decentraland/sdk/components/billboard.proto";
 import public "decentraland/sdk/components/camera_mode_area.proto";