This documentation is for NameplateBuilder v4.260326.2 with API v2.0.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). |
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 |
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
