0. About

The Spiffy HUD API allows you to add your own custom text placeholders via an extension mod, so you can use them in text elements.

1. Preparing Your Workspace

To prepare your workspace for the Spiffy HUD API, please take a look at the Prepare Workspace wiki page.

2. Adding New Placeholders

Every custom placeholder needs to be wrapped into a PlaceholderTextContainer. This container needs to be registered to the PlaceholderTextRegistry.

2.1. Creating the Container

You only need one class for a custom placeholder and that's PlaceholderTextContainer. This class provides the actual value and other important things of your placeholder.

Spiffy HUD will get the current value of the container every tick, so you can update its content.

Create a subclass of PlaceholderTextContainer for your placeholder and give it a fitting name. In this case, I will name my example class ExamplePlaceholderTextContainer.

2.1.1. The Placeholder Identifier

Every placeholder has a unique placeholder identifier. This identifier needs to be unique, so just use your username or the mod id as prefix. It is not possible to register two placeholders with the same name.

The identifier is defined in the constructor of the container, so you should just set it here.

public ExamplePlaceholderTextContainer() {
    super("example_placeholder_identifier");
}

2.1.2. The Placeholder

Your placeholder gets replaced with the actual value when adding it to a text element, but Spiffy HUD needs to know what exactly this placeholder is, so it can automatically add it to input fields.

Every placeholder should start and end with %.

@Override
public String getPlaceholder() {
    return "%example_placeholder%";
}

2.1.3. The Category

The layout editor will categorize your placeholders by its categories, so the user can find it a bit easier.

@Override
public String getCategory() {
    return "Example Category";
}

If you return null here, the placeholder will be automatically added to the Other category.

2.1.4. The Display Name

Your placeholder needs a display name, so users will be able to identify it in the layout editor.

@Override
public String getDisplayName() {
    return "Example Placeholder";
}

2.1.5. The Description

This description is shown when hovering over the button to add this placeholder to a text input field in the editor.

@Override
public String[] getDescription() {
    return new String[] {
        "This is a multiline",
        "placeholder description."
    };
}

You can return null here if you don't want to set a description.

2.1.6. The Value Getter

The most important part of your placeholder is the actual value that it gets replaced with.

Some placeholder values need to be updated from time to time, so Spiffy will call the getter method every render tick.

Keep in mind that this method will be called every render tick for every text element in a layout, so don't use performance-killing stuff here!

@Override
public String replacePlaceholders(String rawIn) {

    String placeholder = this.getPlaceholder();
    String realValue = "" + System.currentTimeMillis();

    //Replacing all placeholder occurrences with the real value and returning it
    return rawIn.replace(placeholder, realValue);

}

2.1.7 Full Example

This is a full working PlaceholderTextContainer example.

package de.keksuccino.spiffyhud.api.placeholder.example;

import de.keksuccino.spiffyhud.api.placeholder.PlaceholderTextContainer;

//This needs to be registered to the PlaceholderTextRegistry at mod init
public class ExamplePlaceholderTextContainer extends PlaceholderTextContainer {

    public ExamplePlaceholderTextContainer() {
        super("example_placeholder_identifier");
    }

    @Override
    public String replacePlaceholders(String rawIn) {

        String placeholder = this.getPlaceholder();
        String realValue = "" + System.currentTimeMillis();

        //Replacing all placeholder occurrences with the real value and returning it
        return rawIn.replace(placeholder, realValue);

    }

    @Override
    public String getPlaceholder() {
        return "%example_placeholder%";
    }

    @Override
    public String getCategory() {
        return "Example Category";
    }

    @Override
    public String getDisplayName() {
        return "Example Placeholder";
    }

    @Override
    public String[] getDescription() {
        return new String[] {
                "This is a multiline",
                "placeholder description."
        };
    }

}

2.2. Registering the Container

Your placeholder class is ready to use now, so you should tell FancyMenu about its existence.

The last step you need to do is to register your PlaceholderTextContainer to the PlaceholderTextRegistry when your extension mod is getting initialized.

package de.keksuccino.extension;

import net.minecraftforge.fml.common.Mod;
import de.keksuccino.spiffyhud.api.placeholder.PlaceholderTextRegistry;

@Mod("modid")
public class ExampleModMainClass {
	
   public ExampleModMainClass() {
      try {
			
         //Register your PlaceholderTextContainer to the PlaceholderTextRegistry at mod init.
         PlaceholderTextRegistry.registerPlaceholder(new ExamplePlaceholderTextContainer());
	    	
      } catch (Exception e) {
         e.printStackTrace();
      }
   }

}

Now you can use your own placeholder in text elements!