> ## 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.

# Overview

> Features, permissions, and how NameplateBuilder works.

<Info>This documentation is written for **NameplateBuilder >= v4.260326.7** with **API >= v2.2.0**.</Info>

## The Problem

Hytale gives each entity a single `Nameplate` component. When multiple mods try to set it, they overwrite each other. NameplateBuilder fixes this by acting as a central aggregator - mods register named **segments**, and the system composites them into one nameplate string per entity, per viewer, every tick.

## Core Features

* **Multi-mod aggregation** - Any number of mods contribute segments. NameplateBuilder handles compositing, ordering, and per-viewer preferences
* **Opt-in NPC model** - Only Hytale-namespace NPCs are auto-seeded with nameplates. Other mods use resolvers or `NameplateAPI.setText()` to opt in, preventing conflicts
* **Built-in segments** - Player Name (with anonymize variant), Health, Stamina, and Mana (each with Current/Max, Percentage, and Bar variants). Built-in segments are shown with a distinct warm-purple tint in the UI
* **Death cleanup** - Nameplates are automatically cleared when an entity dies, instead of lingering through the death animation
* **Crouch hiding** - Player nameplates are hidden when crouching
* **Persistent preferences** - All player settings and admin config are saved as JSON to disk and survive server restarts

## Welcome Message

When a player joins, a coloured message is displayed:

* **Green** when nameplates are available - `[ServerName] - Use /npb to customize your nameplates.`
* **Red** when all segments are admin-disabled - `[ServerName] - Nameplates are disabled on this server.`

Admins can enable/disable welcome messages server-wide. Players can also individually toggle it off via General settings.

## Player Customization

Players open `/npb` (aliases: `/nameplatebuilder`, `/nameplateui`) to access a full UI with:

* **One chain per entity type** - A single NPC chain and a single Player chain. All segments from all mods appear in one ordered list
* **Drag-and-drop reordering** - Segments in the chain can be reordered by dragging and dropping
* **Per-block separators** - Each segment can have its own separator to the next
* **Format variants** - Mods can register multiple display formats (e.g. health as `42/67`, `63%`, or `||||||------`)
* **Prefix/suffix wrapping** - Custom text to wrap segment output (e.g. `HP: [` and `]`)
* **Bar customization** - Change the empty-fill character in bar variants
* **Chain/Settings sub-tabs** - Each editor page has a Chain tab (segment ordering) and a Settings tab (per-chain toggles, mod killswitches, world/instance toggles)
* **Multi-profile preview** - Preview bar shows different entity profiles auto-generated from runtime observation
* **Nameplate offset** - Configurable vertical offset for NPCs using invisible anchor entities
* **View-cone filtering** - "Only Show NPC Nameplates When Looking" mode (\~25 degree cone, up to 12 blocks, enabled by default)
* **Live preview** - Real-time composited text preview in the editor

## Admin Controls

Admins with the `nameplatebuilder.admin` permission can:

* **Master killswitch** - Disable all NameplateBuilder processing server-wide. Actively clears existing nameplates
* **Per-chain killswitches** - Disable NPC nameplates, Player nameplates, or both independently
* **Per-mod killswitches** - Enable/disable segments from specific mods (namespace-level control)
* **Per-world/instance killswitches** - Two-column layout for worlds and instances. Disabled locations show no nameplates for any player
* **Chain locking** - Lock the NPC and/or Player chain order so all players see the admin's configured segment order. Admins can still edit locked chains directly while players see a read-only view
* **Required segments** - Force specific segments to always display for all players
* **Disabled segments** - Hide specific segments from all players entirely
* **NPC blacklist** - Blacklist specific NPC types from ever receiving nameplates
* **Regex pattern blacklist** - Add patterns (e.g. `Citizen.*`) to bulk-exclude NPCs by role name. Default patterns for Citizen, Mount, and Pet NPCs are seeded on first install
* **Server name** - Set a custom display name for the join welcome message
* **Welcome messages** - Global toggle for join messages. Disabled by default

All admin killswitches override player settings. Players see "(Disabled by Admin)" on affected toggles and cannot re-enable them.

## Permissions

| Permission               | Description                                                                                                                                         |
| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nameplatebuilder.admin` | Grants access to the admin section (NPCs, Players, Configuration) in the UI. Without this permission, the ADMIN section is hidden from the sidebar. |