Skip to main content
A segment can have multiple display formats. For example, a health segment could show "42/67", "63%", or "||||||------". Players pick their preferred format in the /npb UI, and NameplateBuilder tells your code which one they chose.

​
How It Works

There are three parts:
  1. Register variant names - Tell the UI what formats are available
  2. Handle the variant index - Return the right format in your resolver (or push the right text manually)
  3. NameplateBuilder handles the rest - The UI shows a format picker, saves the player’s choice, and passes the selected index to your code

​
Step 1: Register Variant Names

Call defineVariants() after define() in your setup() method. Pass a list of human-readable names for each format: 
NameplateAPI.define(this, "health", "Health",
        SegmentTarget.ALL, "67/67");

NameplateAPI.defineVariants(this, "health", List.of(
    "Current/Max",    // index 0 - the default format
    "Percentage",     // index 1
    "Bar"             // index 2
));
The first name in the list (index 0) is the default format. Players see these names in the format picker popup when they click the “Format” button on a chain block.

​
Variant names with examples

You can include an example in parentheses. The UI extracts it and shows it as a preview: 
NameplateAPI.defineVariants(this, "health", List.of(
    "Current/Max (42/67)",
    "Percentage (63%)",
    "Bar (||||||------)"
));

​
Step 2: Handle the Variant Index

​
With Resolvers

The variantIndex parameter tells you which format the player selected. Use a switch to return the right text: 
NameplateAPI.define(this, "health", "Health",
        SegmentTarget.ALL, "67/67")
    .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 switch (variantIndex) {
            case 1 -> {
                int percent = max > 0 ? Math.round(100f * current / max) : 0;
                yield percent + "%";
            }
            case 2 -> {
                int filled = max > 0 ? Math.round(20f * current / max) : 0;
                yield "|".repeat(filled) + "-".repeat(20 - filled);
            }
            default -> current + "/" + max;
        };
    });
The default case handles index 0 (the default format) and any unexpected index.

​
With Manual Text

If you’re using setText() instead of a resolver, push each variant using suffixed keys: 
int current = 42;
int max = 67;

// Variant 0 (default) - use the base key
data.setText("health", current + "/" + max);

// Variant 1 - append ".1" to the key
data.setText("health.1", Math.round(100f * current / max) + "%");

// Variant 2 - append ".2" to the key
data.setText("health.2", "|".repeat(13) + "-".repeat(7));
When the player selects variant 2, NameplateBuilder looks for the key "health.2". If it exists, that text is used. If it’s missing, it falls back to the base key "health". Always set the base key. The suffixed keys are optional - if you skip one, the player sees the default format instead. This means you can support some variants but not all, and it degrades gracefully.

​
Segments Without Variants

If your segment only has one display format, simply don’t call defineVariants(). The format button won’t appear on the chain block in the UI, and the segment always displays its base text. You can ignore the variantIndex parameter in your resolver.

​
Prefix, Suffix, and Bar Customization

When a player selects a format variant, the UI also lets them configure:
  • Prefix - Text prepended before the value (e.g. "HP: [")
  • Suffix - Text appended after the value (e.g. "]")
  • Bar empty fill - The character used for unfilled positions in bar variants
These are handled entirely by NameplateBuilder. You don’t need to do anything in your mod - just return the raw value and NameplateBuilder wraps it with whatever prefix/suffix the player configured.

​
Next Steps