feat: add AvatarNametag component (id 1221)

[popuz]

Adds PBAvatarNametag — a plate with scene-provided text drawn above a player's native nametag. Immediate use case: player ranks in Clean The Club, which today are faked with a billboarded TextShape on the NAME_TAG anchor by every scene that wants them.

Single new file: proto/decentraland/sdk/components/avatar_nametag.proto. Component id 1221 (verified free).

Addressing

The component is attached to the player entity itself — engine.PlayerEntity for the local player, getPlayer({ userId }).entity for anyone else. There is deliberately no target/userId field:

• the scene already holds that entity at the point where it would otherwise pass an address (engine.getEntitiesWith(PlayerIdentityData)), so a target field would be a round trip through a string and back;
• two entities targeting the same player would need a conflict rule, and the CRDT has no authority model to express one;
• comms drops every entity id below 512, so a component on a player entity is local-only by construction. Scenes that want everyone to see the same plate distribute it through their own state — the doc comment says so explicitly.

Player entity ids (32..255) are reused after a disconnect, so the comment also tells creators to resolve the entity on every write and to remove the component when the player leaves.

Colors

Both color fields are Color3 and optional. The Avatar* family is Color3 throughout; Color4 is the UI convention. Plate opacity is already driven by the client's distance fade, so a per-tag alpha would multiply with it. Omitting a color inherits the client's native nametag styling, which is why the defaults are worded semantically rather than as RGB literals — the nametag restyle is still in design and a literal here would propagate into generated docstrings.

Field numbers 4–6 are left free for a later show_background / opacity / icon slot; under WIRE_JSON breaking rules those are pure additions.

No length limit

The protocol has no validation mechanism (no protovalidate, no PGV) and there is no precedent for stating a numeric cap. The visual limit already exists and is adaptive: the plate is single-line with overflow: hidden and an ellipsis. The comment describes the single-line behaviour rather than prescribing a transformation, so the client stays free to change how it handles a stray newline.

public/sdk-components.proto intentionally untouched

That aggregate is not exhaustive — 19 components are missing from it, including all of 1209–1220 consecutively. Both consumers glob decentraland/sdk/components/**/*.proto directly (unity-explorer/scripts/src/build-protocol.ts, js-sdk-toolchain's compileEcsComponents), so adding an import there would be cosmetic.

Base

Opened against experimental rather than main because the consuming client (unity-explorer) pins experimental builds — a main-based tarball lacks common/options.proto and the Pulse protos and would drop the Pulse bindings on codegen.

🤖 Generated with Claude Code

[github-actions]

Test this pull request on NPM or Yarn

• The @dcl/protocol package can be tested in scenes by running the following NPM command:

  npm install "https://sdk-team-cdn.decentraland.org/@dcl/protocol/branch//dcl-protocol-1.0.0-32498846622.commit-459a0eb.tgz"

• The @dcl/protocol package can be tested in scenes by running the following YARN command:

  yarn add "https://sdk-team-cdn.decentraland.org/@dcl/protocol/branch//dcl-protocol-1.0.0-32498846622.commit-459a0eb.tgz"