DisplayNameComponent

Display name shown above entities. Uses the Message type for rich text formatting.

Access

DisplayNameComponent component = store.getComponent(ref, DisplayNameComponent.getComponentType());
Message displayName = component.getDisplayName();  // may be null

Setting Display Names

// create with raw text
Message name = Message.raw("Custom Name");
store.putComponent(ref, DisplayNameComponent.getComponentType(), new DisplayNameComponent(name));

// create with color
Message coloredName = Message.raw("Admin").color("#ff0000").bold(true);
store.putComponent(ref, DisplayNameComponent.getComponentType(), new DisplayNameComponent(coloredName));

// create with translation key
Message translatedName = Message.translation("npc.shopkeeper.name");
store.putComponent(ref, DisplayNameComponent.getComponentType(), new DisplayNameComponent(translatedName));

See Messages for the full Message API — formatting, colors, composition, and parameters.

Nameplate Sync

For Player entities, DisplayNameComponent automatically syncs to the Nameplate component via NameplateSystems:

1. When DisplayNameComponent changes on a player
2. The system updates the Nameplate component
3. Clients receive the update and render the nameplate

The nameplate shows the resolved text (getAnsiMessage()), meaning translations are resolved server-side.

Player Default Names

When players join a world, they automatically receive a DisplayNameComponent with their username (from PlayerAddedSystem).

Getting Display Text

DisplayNameComponent component = store.getComponent(ref, DisplayNameComponent.getComponentType());
if (component != null && component.getDisplayName() != null) {
    // get resolved plain text
    String text = component.getDisplayName().getAnsiMessage();

    // get translation key (if translatable)
    String messageId = component.getDisplayName().getMessageId();

    // get raw text (if raw message)
    String rawText = component.getDisplayName().getRawText();
}

Examples

NPC Shop Name

Message shopName = Message.raw("Blacksmith").color("#ffaa00");
store.putComponent(npcRef, DisplayNameComponent.getComponentType(), new DisplayNameComponent(shopName));

Player Title

// add title prefix to player name
Player player = store.getComponent(playerRef, Player.getComponentType());
String username = player.getUsername();

Message titledName = Message.raw("[VIP] ").color("#00ff00")
    .insert(Message.raw(username));

store.putComponent(playerRef, DisplayNameComponent.getComponentType(), new DisplayNameComponent(titledName));

Clear Display Name

store.putComponent(ref, DisplayNameComponent.getComponentType(), new DisplayNameComponent(null));
// or remove the component entirely
store.tryRemoveComponent(ref, DisplayNameComponent.getComponentType());