> ## 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.
# API Reference
> Complete method tables for NameplateAPI, SegmentBuilder, SegmentResolver, NameplateData, and related types.
This documentation is written for **NameplateBuilder >= v4.260326.7** with **API >= v2.2.0**.
## NameplateAPI - Static Methods
### Segment Definition
| Method | Returns | Description |
| :-------------------------------------------------------- | :--------------- | :------------------------------------------------------------------- |
| `define(plugin, segmentId, displayName)` | `SegmentBuilder` | Define a segment. Defaults to `SegmentTarget.ALL`, no example. |
| `define(plugin, segmentId, displayName, target)` | `SegmentBuilder` | Define a segment with an entity target hint. |
| `define(plugin, segmentId, displayName, target, example)` | `SegmentBuilder` | Define a segment with target hint and example preview text. |
| `defineVariants(plugin, segmentId, variantNames)` | `void` | Register format variant names for a segment. Index 0 is the default. |
| `undefine(plugin, segmentId)` | `void` | Remove a segment definition from the UI at runtime. |
### Per-Entity Text
| Method | Returns | Description |
| :------------------------------------------- | :------ | :------------------------------------------------------------------------------------------ |
| `setText(store, entityRef, segmentId, text)` | `void` | Set or update nameplate text for a segment on an entity. Creates `NameplateData` if needed. |
| `clearText(store, entityRef, segmentId)` | `void` | Clear a segment's text from an entity. Auto-removes `NameplateData` if empty. |
### Component Access
| Method | Returns | Description |
| :------------------- | :------------------------------------------ | :-------------------------------------------- |
| `getComponentType()` | `ComponentType` | Get the component type for direct ECS access. |
### Parameter Details
**`define()` parameters:**
| Parameter | Type | Description |
| :------------ | :-------------- | :-------------------------------------------------------------------------- |
| `plugin` | `JavaPlugin` | Your plugin instance (pass `this` from `setup()`) |
| `segmentId` | `String` | Unique key for this segment within your plugin (e.g. `"health"`, `"guild"`) |
| `displayName` | `String` | Human-readable name shown in the UI (e.g. `"Health Bar"`) |
| `target` | `SegmentTarget` | UI hint for which entity types this applies to |
| `example` | `String` | Preview text shown in the UI (e.g. `"67/67"`). Nullable. |
**`setText()` parameters:**
| Parameter | Type | Description |
| :---------- | :------------------- | :------------------------------------------------------------------------- |
| `store` | `Store` | The entity store |
| `entityRef` | `Ref` | Reference to the target entity |
| `segmentId` | `String` | The segment key (must match what you passed to `define()`) |
| `text` | `String` | The text value to display. Must not be blank - use `clearText()` to clear. |
## SegmentBuilder - Instance Methods
Returned by `define()`. Methods chain fluently and write through to the registry immediately - no `build()` call needed.
| Method | Returns | Description |
| :------------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolver(resolver)` | `SegmentBuilder` | Register a function that computes text per entity every tick. |
| `requires(componentType)` | `SegmentBuilder` | Optimization hint: only call the resolver for entities whose archetype contains this component. |
| `cacheTicks(ticks)` | `SegmentBuilder` | How many ticks to cache the resolver result per entity. Default: 1 (every tick). |
| `enabledByDefault()` | `SegmentBuilder` | Mark this segment as enabled by default on both NPC and Player chains for new players. Max 3 per mod. |
| `enabledByDefault(target)` | `SegmentBuilder` | Mark this segment as enabled by default on specific chain(s) for new players. Max 3 per mod. |
| `replaces(segmentId)` | `SegmentBuilder` | When this segment has a value for an entity, hide the target built-in segment for that entity. Only targets built-in segments: `entity-name`, `player-name`, `health`, `stamina`, `mana`. See [Advanced - Replacing Built-in Segments](/modding/advanced#replacing-built-in-segments). |
## SegmentResolver - Functional Interface
```java theme={null}
@FunctionalInterface
public interface SegmentResolver {
String resolve(Store store, Ref entityRef, int variantIndex);
}
```
| Parameter | Type | Description |
| :------------- | :------------------- | :----------------------------------------------------------------------------------- |
| `store` | `Store` | The entity store for reading components |
| `entityRef` | `Ref` | Reference to the entity being processed |
| `variantIndex` | `int` | The viewer's selected variant (0 = default) |
| **Returns** | `String` | The segment text to display, or `null` if this segment does not apply to this entity |
## NameplateData - Instance Methods
| Method | Return | Description |
| :------------------- | :--------------- | :------------------------------------------------------- |
| `setText(key, text)` | `void` | Set or update a segment's text. Pass `null` to remove. |
| `getText(key)` | `String` | Get a segment's current text. Returns `null` if not set. |
| `removeText(key)` | `void` | Remove a segment. |
| `getEntries()` | `Set` | Unmodifiable view of all key-value entries. |
| `isEmpty()` | `boolean` | Returns `true` if no entries exist. |
## SegmentTarget - Enum
| Value | UI Tag | Description |
| :-------- | :---------- | :--------------------------- |
| `ALL` | `[All]` | Applies to all entity types |
| `PLAYERS` | `[Players]` | Intended for player entities |
| `NPCS` | `[NPCs]` | Intended for NPC entities |
The target is a **UI hint only**. It does not restrict which entity types you can set text on or which entities a resolver runs for (use `requires()` for that).
## Exceptions
| Exception | Parent | When It's Thrown |
| :--------------------------------- | :------------------- | :--------------------------------------------------------------------------- |
| `NameplateException` | `RuntimeException` | Base class - not thrown directly |
| `NameplateNotInitializedException` | `NameplateException` | API called before NameplateBuilder loaded. Check `manifest.json` dependency. |
| `NameplateArgumentException` | `NameplateException` | `null` or blank passed to a required parameter. |
## Key Conventions
### Segment IDs
* Must be non-null and non-blank
* Scoped to your plugin - two mods can both use `"health"` without conflict
* Used as the key in `NameplateData.setText()` and `NameplateData.getText()`
### Variant Key Suffixes (Manual Text Only)
* Variant 0 (default) uses the base key: `"health"`
* Variant 1 uses `.1` suffix: `"health.1"`
* Variant 2 uses `.2` suffix: `"health.2"`
* The aggregator falls back to the base key if a suffixed key is missing
* Not needed when using resolvers - the `variantIndex` parameter handles this
### Hidden Keys
* Keys starting with `_` (underscore) are hidden metadata
* Stored in `NameplateData` but never shown in output or UI
* Example: `"_spawn_tick"`, `"_phase"`
* See [Advanced - Hidden Metadata Keys](/modding/advanced#hidden-metadata-keys)
## Guides
* **[Quick Start](/modding/quick-start)** - Add your first segment in 5 minutes
* **[Resolvers](/modding/resolvers)** - `requires()`, `cacheTicks()`, and format variants
* **[Manual Text](/modding/manual-text)** - `setText()`, tick system patterns
* **[Format Variants](/modding/format-variants)** - Multiple display formats per segment
* **[Migration Guide](/modding/migration)** - Upgrading from API 1.0.0