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

# Persistence

> File formats for player preferences and admin configuration.

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

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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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
    ...
```