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.
NameplateBuilder persists all player settings and admin configuration to disk so they survive server restarts.

​
Player Preferences

Directory: players/ Each player’s preferences are stored in a separate JSON file named by their UUID. Segments are referenced by composite key in the format pluginId|segmentId. File: players/{uuid}.json 
{
  "npcChain": ["EliteMobs|health", "EliteMobs|tier"],
  "playerChain": ["NameplateBuilder|player_name", "MyMod|guild"],
  "enabled": true,
  "lookAt": true,
  "offset": 0.5,
  "welcomeMessage": false,
  "separators": {
    "EliteMobs|health": " - "
  },
  "variants": {
    "EliteMobs|health": 2
  },
  "prefixes": {
    "EliteMobs|health": "HP: ["
  },
  "suffixes": {
    "EliteMobs|health": "]"
  },
  "barFills": {
    "EliteMobs|health": "."
  }
}
Per-player files provide thread safety on busy servers - concurrent joins never contend on a single file. All writes are atomic (write to a temp file, then rename) for crash safety.

​
Admin Configuration

File: config.json 
{
  "serverName": "My Awesome Server",
  "required": ["NameplateBuilder|player_name", "EliteMobs|health"],
  "disabled": ["MyMod|debug_info"],
  "blacklistPatterns": ["Citizen.*", "Mount_.*", "Pet_.*"]
}
The blacklistPatterns array contains Java regex patterns that match NPC role names. Any NPC whose role name matches a pattern is excluded from receiving nameplates. The default patterns Citizen.*, Mount_.*, and Pet_.* are seeded on first install. Segments are referenced by the composite key pluginId|segmentId.

​
Mutual Exclusion

A segment cannot be both required and disabled. If an admin marks a required segment as disabled, it is automatically removed from the required set (and vice versa). This is enforced both in the UI and in the persistence layer.

​
Migration from Pre-v4.260326.7

Older versions stored player preferences in a single preferences.txt file and admin configuration in admin_config.txt. On first load, NameplateBuilder automatically migrates both files to the new JSON format:
  • preferences.txt is split into individual players/{uuid}.json files
  • admin_config.txt is converted to config.json
The old files are left in place but are no longer read after migration completes. You can safely delete them once you’ve confirmed the server is running correctly on the new version.

​
File Location

All files are stored in the mod’s data directory: 
%APPDATA%/Hytale/UserData/Saves/<save>/mods/NameplateBuilder/
  config.json
  players/
    550e8400-e29b-41d4-a716-446655440000.json
    ...