API Reference

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<EntityStore, NameplateData>`	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<EntityStore>`	The entity store
`entityRef`	`Ref<EntityStore>`	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.

SegmentResolver - Functional Interface

@FunctionalInterface
public interface SegmentResolver {
    String resolve(Store<EntityStore> store, Ref<EntityStore> entityRef, int variantIndex);
}

Parameter	Type	Description
`store`	`Store<EntityStore>`	The entity store for reading components
`entityRef`	`Ref<EntityStore>`	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<Map.Entry>`	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

Guides

Quick Start - Add your first segment in 5 minutes
Resolvers - requires(), cacheTicks(), and format variants
Manual Text - setText(), tick system patterns
Format Variants - Multiple display formats per segment
Migration Guide - Upgrading from API 1.0.0

Getting Started

Player Guide

Modding Guide

Reference

NameplateAPI - Static Methods

Segment Definition

Per-Entity Text

Component Access

Parameter Details

SegmentBuilder - Instance Methods

SegmentResolver - Functional Interface

NameplateData - Instance Methods

SegmentTarget - Enum

Exceptions

Key Conventions

Segment IDs

Variant Key Suffixes (Manual Text Only)

Hidden Keys

Guides

​NameplateAPI - Static Methods

​Segment Definition

​Per-Entity Text

​Component Access

​Parameter Details

​SegmentBuilder - Instance Methods

​SegmentResolver - Functional Interface

​NameplateData - Instance Methods

​SegmentTarget - Enum

​Exceptions

​Key Conventions

​Segment IDs

​Variant Key Suffixes (Manual Text Only)

​Hidden Keys

​Guides

NameplateAPI - Static Methods

Segment Definition

Per-Entity Text

Component Access

Parameter Details

SegmentBuilder - Instance Methods

SegmentResolver - Functional Interface

NameplateData - Instance Methods

SegmentTarget - Enum

Exceptions

Key Conventions

Segment IDs

Variant Key Suffixes (Manual Text Only)

Hidden Keys

Guides