Home

MLAPI is very simple and powerful to use. This page will walk you through creation of a simple controller and tag line.

Step One: Obtaining an Instance of the API.

Make sure you include the proper dependencies in plugin.yml:

depends: [MultiLineAPI]

Then, in your onEnable, obtain an instance of the plugin "MultiLineAPI" and cast it to IMultiLIneAPI. For example:

@Override
public void onEnable() {
    IMultiLineAPI lineAPI = (IMultiLineAPI) Bukkit.getPluginManager().getPlugin("MultiLineAPI");
    if (lineAPI == null) {
        throw new IllegalStateException("Failed to start demo plugin! MultiLineAPI could not be found!");
    }
}

Step Two: Create a Tag Controller implementation.

You should create a class that contains your tag controller implementation. It must extend ITagController. Here is an example:

public class DemoController implements ITagController {
    private final JavaPlugin parent;
    private final ITagController.TagLine line;

    public DemoController(JavaPlugin parent) {
        this.parent = parent;
        this.line = new DemoLine();
    }

    @Override
    public List<TagLine> getFor(Entity target) {
        return Collections.singletonList(this.line);
    }

    @Override
    public String getName(Entity target, Player viewer, String previous) {
        return ChatColor.BLUE + previous;
    }

    @Override
    public EntityType[] getAutoApplyFor() {
        return new EntityType[]{
             EntityType.PLAYER
        };
    }

    @Override
    public JavaPlugin getPlugin() {
        return parent;
    }

    @Override
    public int getPriority() {
        return 0;
    }

    @Override
    public int getNamePriority() {
        return 0;
    }
}

Let's break down the parts of the controller:

• #getFor() - Returns the tag lines that should be shown for an entity. This should never change during the lifetime of one instance of the server! For example, it would be okay to have this change its return value based on the user's configuration on server startup, but not okay for this to change when the user runs a command while the server is already running.
• #getName() - This method is called when a tag's name is updated for any reason. The parameters given represent the target entity, the player who is viewing it, and the line before it in the priority - Higher priorities are run after lower priorities. **If your tag controller does not wish to modify the name, do not implement this method. Implementations of this method should exercise extreme caution to make sure that they use the 'previous' variable, because if they do not, lower priority controllers will have their changes overwritten.
• #getAutoApplyFor() - This method should return the list of entity types that you wish for this controller to be enabled for. This is not permanent - through MultiLineAPI#getOrCreateTag() and Tag#addTagController() you can add tags to other entities dynamically; however, if you always are adding it for a specific type this method is here for your convenience.
• #getPlugin() - Gets the plugin associated with the controller. This method is not used directly by MultiLineAPI; however, it can help with debugging.
• #getPriority() - Gets the priority of the lines controlled by this controller. Higher priorities are shown above lower priorities.
• #getNamePriority() - Gets the priority of the changes this controller makes to the nametag. Higher priorities are run after lower priorities.

Step Three: Create and Return a TagLine.

You should create a class for each line return. Lines must extend ITagController.TagLine. Here is an example:

public class DemoLine implements ITagController.TagLine {

    @Override
    public String getText(Entity target, Player viewer) {
        return "Hello, " + viewer.getName() + "!";
    }

    @Override
    public boolean keepSpaceWhenNull(Entity target) {
        return false;
    }
}

The required methods are pretty easy to understand:

• #getText() - Gets the String that this line should display. This is called whenever anything updates the line. If this method returns null, the text, along with the black shading behind it, will disappear entirely
• #keepSpaceWhenNull() - Gets whether or not the space for this line should be kept when the return value of #getText() is null.

Once you've implemented your line, you must add it to the return of your tag controller's #getFor(). Note: You should never create new line objects in #getFor() - they should be the same object for every entity. This is already shown in the above controller implementation.

Step Four: Registering Your Controller

Simply call IMultiLineAPI#addDefaultTagController() in onEnable if you would like your tag controller to be added to entities by default (but only the types you specify in #getAutoApplyFor()).

lineAPI.addDefaultTagController(new DemoController(this));

Refreshing the Line

You can choose to refresh the line using a few different methods:

Scope:	Targets:	One Line	One controller	The whole tag
One Tag (ITag)	Everyone	#update(ITagController.TagLine)	#update(ITagController)	#update() OR IMultiLineAPI#update(Entity)
	One Player	#update(ITagController.TagLine, Player)	#update(ITagController, Player)	#update(Player) OR IMultiLineAPI#update(Entity, Player)
All Tags (IMultiLineAPI)	Everyone	#update(ITagController.TagLine)	#update(ITagController)
	One Player	#update(ITagController.TagLine, Player)	#update(ITagController, Player)

Refreshing the Name

You can choose to refresh the line using a few different methods:

Scope:	Targets:
One Tag (ITag)	Everyone	#updateName()
	One Player	#updateName(Player)
All Tags (IMultiLineAPI)	Everyone	#updateNames()
	One Player	#updateNames(Player)