Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nameplatebuilder.frotty27.com/llms.txt

Use this file to discover all available pages before exploring further.

This documentation is written for NameplateBuilder >= v4.260326.7 with API >= v2.2.0.

​
Players

​
How do I open the nameplate editor?

Type /npb in chat (aliases: /nameplatebuilder, /nameplateui).

​
Why does an entity show an empty nameplate?

You have no segments enabled in your chain. Open /npb, go to the NPCs or Players tab, and add segments from the Available Blocks section.

​
Why can’t I remove a segment from my chain?

That segment has been marked as required by a server admin. Required segments appear with a yellow-tinted background and are always displayed. You can still reorder them.

​
Why don’t I see some segments in Available Blocks?

A server admin may have disabled those segments. Check the Disabled tab under NAMEPLATES to see what’s been turned off.

​
How do I change the health display format?

Click the Format button on the Health segment in your chain. Select a variant (Current/Max, Percentage, or Bar), optionally set prefix/suffix text, then click Confirm and Save.

​
Why do NPC nameplates only appear when I look at them?

The “Only Show NPC Nameplates When Looking” setting is enabled by default. You can turn it off in the General tab under /npb. This only affects NPCs - player nameplates are always visible.

​
Why does my nameplate disappear when I crouch?

Player nameplates are automatically hidden when crouching. This is built-in behavior and cannot be toggled off.

​
How do I hide nameplates entirely?

Open /npb, go to the General tab, and toggle Enable Nameplates off.

​
What does the offset setting do?

It moves the nameplate vertically above (or below) the entity. A value of 1.0 moves it one block higher. Uses invisible anchor entities for the floating effect.

​
Server Admins

​
How do I force a segment to always show?

Open /npb, go to the Required tab under ADMIN, and move the segment from the Available column to the Required column using the > button. Click Save.

​
How do I disable a segment globally?

Open /npb, go to the Disabled tab under ADMIN, and move the segment to the Disabled column. Click Save.

​
Can I both require and disable a segment?

No. A segment cannot be both required and disabled. Marking one automatically removes the other.

​
How do I change the server name in the welcome message?

Open /npb, go to the Settings tab under ADMIN, type the name, and click Save.

​
How do I block groups of NPCs from getting nameplates?

Use the regex pattern blacklist in the Blacklist sub-tab under Configuration. Add a pattern like Citizen.* to block all NPCs whose role name starts with “Citizen”. Default patterns for Citizen, Mount, and Pet NPCs are added on first install.

​
How do I lock the chain order for all players?

Open /npb, go to the admin NPCs or Players tab, switch to the Settings sub-tab, and toggle Lock Chain Order on. Players will see a read-only view. You can still edit the chain while it’s locked.

​
How do I benchmark nameplate performance?

Run /npbbench <players> <seconds> (e.g. /npbbench 50 5). This simulates the specified number of players viewing all entities with nameplates in the current world and reports tick budget usage.

​
Where is the config stored?

In your save folder: %APPDATA%/Hytale/UserData/Saves/<save>/mods/NameplateBuilder/. See Persistence for file format details.

​
Mod Developers

​
Why am I getting NameplateNotInitializedException?

Your mod is calling the API before NameplateBuilder has loaded. Add the manifest dependency: 
{
  "Dependencies": {
    "Frotty27:NameplateBuilder": ">=4.260326.7"
  }
}

​
Why does store.addComponent() throw inside my tick system?

The store is locked for structural changes during tick processing. Use commandBuffer.putComponent() instead. See Manual Text for the correct pattern.

​
Do I need to clean up nameplates when entities die?

No. NameplateBuilder automatically clears nameplates on death. See Advanced.

​
Do I need to call undefine() when my plugin shuts down?

No. NameplateBuilder automatically removes all segment descriptions when your plugin unloads.

​
Can two mods use the same segment ID?

Yes. Segment IDs are scoped to your plugin. Two mods can both register a "health" segment without conflict - they are tracked as separate entries internally using pluginId:segmentId.

​
How do I update segment text efficiently?

Call data.setText() - it’s a HashMap.put() internally. Calling it every tick is safe and cheap. The aggregator reads the latest value when it composites the nameplate.

​
How do I make my segment enabled by default for new players?

Chain .enabledByDefault() onto your define() call. You can also target specific chains with .enabledByDefault(SegmentTarget.NPCS). Each mod can mark at most 3 segments as enabled by default. See Advanced - Default Segments.

​
Can I register a PLAYERS-targeted segment on an NPC?

Yes. The SegmentTarget is a UI hint only. You can register any segment on any entity at runtime regardless of the target.