From 2fdb8b3732ba4ad91fc362f45054ca9752610552 Mon Sep 17 00:00:00 2001 From: Vitaly Popuzin Date: Mon, 31 Aug 2026 18:37:45 +0200 Subject: [PATCH 1/2] feat: AvatarNametag component (id 1221) A scene-authored plate drawn above an avatar's nametag, for a rank or a role the scene assigns to a player. Valid on the local player entity, on a player's entity in the scene, or on any entity with an AvatarShape. The plate is local to the client that renders it and is never relayed; only the scene the player currently stands in can write it. The three colors are optional and fall back to the client's native nametag colors, and an empty label draws the plate without text, for color-coding. Co-Authored-By: Claude Fable 5 --- .../sdk/components/avatar_nametag.proto | 31 +++++++++++++++++++ public/sdk-components.proto | 1 + 2 files changed, 32 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..0e1564f5 --- /dev/null +++ b/proto/decentraland/sdk/components/avatar_nametag.proto @@ -0,0 +1,31 @@ +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. + 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"; From 62ced6e1e94addc66b5586c75e0427e152dd48db Mon Sep 17 00:00:00 2001 From: Vitaly Popuzin Date: Mon, 31 Aug 2026 19:08:26 +0200 Subject: [PATCH 2/2] docs: label whitespace widens the plate; hidden-word sizing trick Co-Authored-By: Claude --- proto/decentraland/sdk/components/avatar_nametag.proto | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proto/decentraland/sdk/components/avatar_nametag.proto b/proto/decentraland/sdk/components/avatar_nametag.proto index 0e1564f5..a139c9f7 100644 --- a/proto/decentraland/sdk/components/avatar_nametag.proto +++ b/proto/decentraland/sdk/components/avatar_nametag.proto @@ -22,7 +22,9 @@ option (common.ecs_component_id) = 1221; // // 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. + // 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)