Migration Guide

This documentation is written for NameplateBuilder >= v4.260326.7 with API >= v2.2.0.

Select your current API version below to see what needs to change.

From API 1.0.0 to 2.1.0
From API 2.0.0 to 2.1.0
From API 2.1.0 to 2.2.0
Already on 2.2.0

What Changed

API 2.0.0 has two changes:

All method names were renamed for clarity (required - your code won’t compile until you rename them)
Resolvers were added as a new way to provide segment text (optional but recommended - your existing tick systems still work)

Step 1: Update Dependencies

Replace the API jar in your libs/ folder and update both files:build.gradle:

dependencies {
    compileOnly files('libs/NameplateBuilder-API-2.2.0.jar')
}

manifest.json:

{
  "Dependencies": {
    "Frotty27:NameplateBuilder": ">=4.260326.7"
  }
}

Step 2: Rename Methods

Find and replace these five method names across your code. The behavior is identical - only the names changed.

Find	Replace with
`NameplateAPI.describe(`	`NameplateAPI.define(`
`NameplateAPI.describeVariants(`	`NameplateAPI.defineVariants(`
`NameplateAPI.undescribe(`	`NameplateAPI.undefine(`
`NameplateAPI.register(`	`NameplateAPI.setText(`
`NameplateAPI.remove(`	`NameplateAPI.clearText(`

After this step, your code compiles and works exactly as before. You’re done with the required migration.NameplateData methods are unchanged. If you use data.setText(), data.getText(), etc. directly on the component, nothing needs to change.

Step 3: Switch to Resolvers (Recommended)

This step is optional. Your renamed setText() / clearText() code works fine. But if your segment’s value comes from an ECS component on the entity (health, stats, faction, etc.), resolvers are simpler and more efficient.The idea: Instead of writing a tick system that reads a component and calls setText() every tick, you give NameplateBuilder a function that does the reading. NameplateBuilder calls it automatically - no tick system needed.

Before (1.0.0 pattern)

You had to write a tick system class, register it, handle spawn initialization with CommandBuffer, and update every tick:

// In setup():
NameplateAPI.define(this, "health", "Health",
        SegmentTarget.ALL, "67/69");

getEntityStoreRegistry().registerSystem(
    new HealthNameplateSystem(NameplateAPI.getComponentType()));

// Separate tick system class:
final class HealthNameplateSystem extends EntityTickingSystem<EntityStore> {
    // ... constructor, getQuery(), getGroup() ...

    @Override
    public void tick(float deltaTime, int index, ArchetypeChunk<EntityStore> chunk,
                     Store<EntityStore> store, CommandBuffer<EntityStore> commandBuffer) {
        // Check if entity has stats
        EntityStatMap stats = chunk.getComponent(index, statMapType);
        if (stats == null) return;

        Ref<EntityStore> entityRef = chunk.getReferenceTo(index);

        // Initialize if needed (can't use setText here - store is locked)
        if (store.getComponent(entityRef, nameplateDataType) == null) {
            NameplateData data = new NameplateData();
            data.setText("health", computeHealth(stats));
            commandBuffer.putComponent(entityRef, nameplateDataType, data);
            return;
        }

        // Update every tick
        NameplateData data = chunk.getComponent(index, nameplateDataType);
        if (data != null) {
            data.setText("health", computeHealth(stats));
        }
    }
}

After (2.0.0 with resolver)

Everything is in setup(). No tick system class needed:

@Override
protected void setup() {
    NameplateAPI.define(this, "health", "Health",
            SegmentTarget.ALL, "67/69")
        .requires(EntityStatMap.getComponentType())
        .resolver((store, entityRef, variantIndex) -> {
            EntityStatMap stats = store.getComponent(entityRef, statMapType);
            if (stats == null) return null;
            int current = Math.round(stats.get(health).get());
            int max = Math.round(stats.get(health).getMax());
            return current + "/" + max;
        });
}

What you can delete: The entire tick system class (HealthNameplateSystem), its registration in setup(), and the CommandBuffer initialization logic. The resolver replaces all of it.You can also add .cacheTicks(100) for data that rarely changes (faction, level, tier) to avoid recomputing every tick. See Resolvers for the full guide.

When to Keep Using `setText()`

Keep your existing setText() / clearText() code if your segment’s value doesn’t come from an ECS component. For example:

A bounty stored in your mod’s config file or database
A title assigned by an admin via a chat command
A buff applied through an event, not stored as a component

In these cases there’s no component for a resolver to read, so setText() is the right approach.Rule of thumb: If you’re reading a component inside a tick system and calling setText() with the result, that’s a resolver. If you’re reacting to an event or command, keep setText().

Summary

What	Required?	Action
API jar	Yes	Replace with `NameplateBuilder-API-2.2.0.jar`
Manifest version	Yes	Change to `">=4.260326.7"`
Rename 5 methods	Yes	`describe` -> `define`, `register` -> `setText`, `remove` -> `clearText`, etc.
Switch tick systems to resolvers	Recommended	Replace component-reading tick systems with `.resolver()`
Keep `setText()` for external data	Keep as-is	No change needed for event/command/database-driven segments
`NameplateData` methods	No change	`data.setText()`, `data.getText()`, etc. are identical

What Changed

API 2.1.0 is a backward-compatible addition. Existing 2.0.0 code compiles and runs without changes. Two new methods were added to SegmentBuilder:

enabledByDefault() - marks a segment as enabled by default on both chains for new players
enabledByDefault(SegmentTarget target) - marks a segment as enabled by default on specific chain(s) for new players

Each mod can mark at most 3 segments as enabledByDefault.

Step 1: Update Dependencies

Replace the API jar in your libs/ folder and update both files:build.gradle:

dependencies {
    compileOnly files('libs/NameplateBuilder-API-2.2.0.jar')
}

manifest.json:

{
  "Dependencies": {
    "Frotty27:NameplateBuilder": ">=4.260326.7"
  }
}

Step 2: Use `enabledByDefault()` (Optional)

If you want your segment to appear in new players’ chains automatically, chain enabledByDefault() onto your define() call:

NameplateAPI.define(this, "health", "Health",
        SegmentTarget.ALL, "67/69")
    .enabledByDefault()
    .resolver((store, entityRef, variantIndex) -> {
        // ...
    });

You can also target a specific chain:

NameplateAPI.define(this, "faction", "Faction",
        SegmentTarget.NPCS, "<Undead>")
    .enabledByDefault(SegmentTarget.NPCS)
    .resolver((store, entityRef, variantIndex) -> {
        // ...
    });

See Advanced - Default Segments for full details.

Summary

What	Required?	Action
API jar	Yes	Replace with `NameplateBuilder-API-2.2.0.jar`
Manifest version	Yes	Change to `">=4.260326.7"`
`enabledByDefault()`	Optional	Chain onto `define()` for up to 3 segments per mod

What Changed

API 2.2.0 is a backward-compatible addition. Existing 2.1.0 code compiles and runs without changes. One new method was added to SegmentBuilder:

replaces(String segmentId) - when your segment has a value for an entity, the target built-in segment is hidden for that entity

This only targets NameplateBuilder’s built-in segments: entity-name, player-name, health, stamina, mana.

Step 1: Update Dependencies

Replace the API jar in your libs/ folder and update both files:build.gradle:

dependencies {
    compileOnly files('libs/NameplateBuilder-API-2.2.0.jar')
}

manifest.json:

{
  "Dependencies": {
    "Frotty27:NameplateBuilder": ">=4.260326.7"
  }
}

Step 2: Use `replaces()` (Optional)

If your segment provides a context-specific version of a built-in segment (like a pet name replacing the entity name), chain replaces() onto your define() call:

NameplateAPI.define(this, "pet-name", "Pet Name",
        SegmentTarget.NPCS, "Fluffy")
    .replaces("entity-name")
    .enabledByDefault(SegmentTarget.NPCS)
    .resolver((store, entityRef, variantIndex) -> {
        var name = store.getComponent(entityRef, petNameType);
        return name != null ? name.getName() : null;
    });

When the resolver returns a value, entity-name is hidden for that entity. When it returns null, entity-name shows normally. Players don’t need to change anything in their chain.See Advanced - Replacing Built-in Segments for full details.

Summary

What	Required?	Action
API jar	Yes	Replace with `NameplateBuilder-API-2.2.0.jar`
Manifest version	Yes	Change to `">=4.260326.7"`
`replaces()`	Optional	Chain onto `define()` to replace a built-in segment per-entity

Getting Started

Player Guide

Modding Guide

Reference

What Changed

Step 1: Update Dependencies

Step 2: Rename Methods

Step 3: Switch to Resolvers (Recommended)

Before (1.0.0 pattern)

After (2.0.0 with resolver)

When to Keep Using `setText()`

Summary

What Changed

Step 1: Update Dependencies

Step 2: Use `enabledByDefault()` (Optional)

Summary

What Changed

Step 1: Update Dependencies

Step 2: Use `replaces()` (Optional)

Summary

You’re up to date

​What Changed

​Step 1: Update Dependencies

​Step 2: Rename Methods

​Step 3: Switch to Resolvers (Recommended)

​Before (1.0.0 pattern)

​After (2.0.0 with resolver)

​When to Keep Using setText()

​Summary

​What Changed

​Step 1: Update Dependencies

​Step 2: Use enabledByDefault() (Optional)

​Summary

​What Changed

​Step 1: Update Dependencies

​Step 2: Use replaces() (Optional)

​Summary

​You’re up to date

What Changed

Step 1: Update Dependencies

Step 2: Rename Methods

Step 3: Switch to Resolvers (Recommended)

Before (1.0.0 pattern)

After (2.0.0 with resolver)

When to Keep Using `setText()`

Summary

What Changed

Step 1: Update Dependencies

Step 2: Use `enabledByDefault()` (Optional)

Summary

What Changed

Step 1: Update Dependencies

Step 2: Use `replaces()` (Optional)

Summary

You’re up to date