Bukkit

This guide is under construction.

In MyTitles API, everything is located in package "com.dannycrafts.myTitles". Also, a lot of functions throw the exception "IOException", this exception is only thrown when an unexpected write/read error occurs with its database. The dependency is the actual .jar file itself.

To use this API, it is recommended to import the package:

import com.dannycrafts.myTitles.*;

Also, we need to load the plugin. Let's say we have a plugin called "MyPlugin":

import com.dannycrafts.myTitles;
import org.bukkit.plugin.java.JavaPlugin;

public class MyPlugin extends JavaPlugin
{
    protected MyTitles myTitles;

    public void onEnable()
    {
        // Plugin startup code here...
    }
}

The following example loads the plugin MyTitles, assuming it is in the "onEnable" function:

// Load plugin:
org.bukkit.plugin.Plugin myTitlesPlugin = this.getServer().getPluginManager().getPlugin( "MyTitles" );
// Check if loaded:
if ( plugin != null )
{
    // Check if enabled:
    if ( plugin.isEnabled() )
    {
        // Check if it is really the MyTitles plugin, and not another plugin called MyTitles:
        if ( plugin instanceof com.dannycrafts.myTitles.Plugin )
        {
            // Get interface for my plugin:
            this.myTitles = ( (com.dannycrafts.myTitles.Plugin )plugin ).getInterface( "my_plugin" );
        }
    }
}

The "Plugin.getInterface" method returns a MyTitles object (the interface) for a plugin. The string that it requires should be an unique identifier for your plugin. Plugins that use other identifiers can't access your titles. This way, multiple titles with the same name can exist, as long as they were registered by different plugins.

Titles

Registration

boolean MyTitles.registerTitle( String name, String prefix, String suffix ) throws IOException, Title.InvalidNameException;

boolean MyTitles.registerTitle( Title.Info titleInfo ) throws IOException, Title.InvalidNameException;

These function register a title. Titles need to be registered before they can be used. When a title with that name already exists, "Title.AlreadyExistsException" will be thrown. The functions returns false if a title with that name already exists, true if not.

boolean MyTitles.unregisterTitle( String name ) throws IOException;

boolean MyTitles.unregisterTitle( Title title ) throws IOException;

These functions unregister a title. All players will lose the title if they owned it, and all title variations that exist for this title will also be removed. If Title objects exists for that title, it should not be used anymore. If you try to unregister a title with a name that doesn't exist, it returns false, otherwise true will be returned.

void MyTitles.putTitles( ArrayList<Title.Info> titles ) throws IOException, Title.InvalidNameException;

This function registers all given titles that are not registered yet, and unregisters all titles that are registered but not given. This is very useful if your plugin needs a (few) title(s) to be present. It is even more useful if your plugin needs a bunch of titles to be present when that bunch might change depending on configurations.

Title MyTitles.getTitle( String name ) throws IOException;

This function retrieves the title object that is registered under the name. When the title doesn't exist, the return value is null.

Title[] MyTitles.getTitles() throws IOException;

This function returns all titles that are registered for your plugin.

Title Object

static class Title.Affixes
{
    String prefix;
    String suffix;

    Affixes( String prefix, String suffix );
}

static class Title.Info
{
    String name;
    Affixes affixes;

    Info( String name, Affixes affixes );
    Info( String name, String prefix, String suffix );
}

The title class contains two other classes which will be used a lot. The first class "Title.Affixes" contains the affixes (prefix and suffix) for a title. The second class "Title.Info" contains the name and affixes for a title.

String Title.getName() throws IOException;
void Title.setName( String name ) throws IOException;
String Title.getPrefix() throws IOException;
void Title.setPrefix( String prefix ) throws IOException;
String Title.getSuffix() throws IOException;
void Title.setSuffix( String suffix ) throws IOException;
Affixes Title.getAffixes() throws IOException;
void Title.setAffixes( Title.Affixes affixes ) throws IOException;
Info Title.getInfo() throws IOException;
void Title.setInfo( Title.Info info ) throws IOException;

These functions get and set title information, changes will be reflected in the database.

Variations

Title variations can be added for titles. Once added, the plugin can decide which player uses which variation of the title.

Management

boolean Title.addVariation( Variation.Info variationInfo ) throws IOException, Variation.InvalidNameException;

This function adds a variation to the title. A variation name may only contain alphabetic (upper- and lowercase) letters, numbers, '-' and '_'. This function returns false if a variation of with that name already exists, else it returns true.

boolean Title.removeVariation( String variationName ) throws IOException;

boolean Title.removeVariation( Variation variation ) throws IOException;

This function removes the variation from the title. When a variation with that name for that title doesn't exist, it returns false, else it returns true.

void Title.putVariations( Variation.Info[] variations ) throws IOException, Variation.InvalidNameException;

This function registers all given title variations for the title that are not registered yet, and unregisters all title variations for the title that are registered but not given. This function throws Variation.InvalidNameException if a name of a variation in not correct. This is very useful if your plugin needs a (few) title variations(s) to be present. It is even more useful if your plugin needs a bunch of titles to be present when that bunch might change depending on configurations.

Variation Title.getVariation( String variationName ) throws IOException;

Retrieves a variation object for the given name, or null is no variation exists with that name for the title.

Variation[] Title.getVariations() throws IOException;

Returns a list of all title variations for the title.

Variation Object

static class Variation.Affixes
{
    String prefix;
    String suffix;

    Affixes( String prefix, String suffix );
}

static class Variation.Info
{
    String name;
    Affixes affixes;

    Info( String name, Affixes affixes );
    Info( String name, String prefix, String suffix );
}

The Variation class contains two other classes which will be used a lot. The first class "Variation.Affixes" contains the affixes (prefix and suffix) for a title variation. The second class "Variation.Info" contains the name and affixes for a title variation.

String Variation.getName() throws IOException;
void Variation.setName( String name ) throws IOException;
String Variation.getPrefix() throws IOException;
void Variation.setPrefix( String prefix ) throws IOException;
String Variation.getSuffix() throws IOException;
void Variation.setSuffix( String suffix ) throws IOException;
Affixes Variation.getAffixes() throws IOException;
void Variation.setAffixes( Variation.Affixes affixes ) throws IOException;
Info Variation.getInfo() throws IOException;
void Variation.setInfo( Variation.Info info ) throws IOException;

These functions get and set title variation information, this changes the database, not just the Variation object.

Players

In MyTitles, Player objects represent players that have been logged in once. Also be careful that Player is part of package "com.dannycrafts.myTitles", not of package "org.bukkit.entity".

Player MyTitles.getPlayer( String playerName ) throws IOException;

This function returns a Player object by its player name, or null if the player doesn't exist. This player doesn't have to be online, it just need to have logged in on the server once so it can register the player.

String Player.getName()  throws IOException;

This function returns the player's name.

String Player.getDisplayName() throws IOException;

String Player.getDisplayName( Title.Affixes affixes ) throws IOException;

String Player.getDisplayName( Title title ) throws IOException;

The first function returns how the player's name looks like with the title he currently uses. The second function returns how the player's name would look like with the given affixes. The third function returns how the player's name would look like with the given title, if that player has a variation for that title, it will affect the outcome.

Titles

boolean Player.giveTitle( Title title ) throws IOException;

Awards a title to the player. Returns false if the player already owns that title, true if not.

boolean Player.takeTitle( Title title ) throws IOException;

Takes a title from the player. Returns false if the player doesn't own the title, true if he does.

Title[] Player.getOwnedTitles() throws IOException;

Returns a list of all titles that the player owns.

Title Variation

boolean Player.setTitleVariation( Variation variation ) throws IOException;

This function sets the players title variation. Returns false if the player doesn't own the title that the variation belongs to.

Variation Player.getTitleVariation( Title title ) throws IOException;

This function returns the variation that is set for the player's given title. Returns null if the player doesn't that title, or if no variation is set for the player.

boolean Player.resetTitleVariation( Title title ) throws IOException

This function resets the title variation for the player. Returns false if the player doesn't own that title, true otherwise.