Basic tutorial

This basic tutorial will explain you how to check that HolographicDisplays is enabled (if stricly required) and how to create your first hologram.

 

1) Download and recommandations

First of all, use the latest version of HolographicDisplays while coding and ask your plugin's users to do the same. The API is constantly being expanded, and some methods could be missing in previous versions.

Download the API: link to the page (without the actual plugin's classes, to avoid being confused. It's just like downloading Bukkit instead of CraftBukkit)

2) Check if HolographicDisplays is enabled

To use the API, you have to check if the plugin is installed and enabled. You can use the following code in your plugin.yml and in your onEnable() to check that the plugin is installed and enabled.

 

Add a soft-dependency to your plugin.yml:

softdepend: [HolographicDisplays]

If you use depend in place of softdepend your users will see an error on the console when the server starts if HolographicDisplays is not enabled, and your onEnable() will not be called. I personally prefer to use softdepend because you can customize the error message.

 

If HolographicDisplays is strictly required, you can use the following code:

@Override
public void onEnable() {

	if (!Bukkit.getPluginManager().isPluginEnabled("HolographicDisplays")) {
		getLogger().severe("*** HolographicDisplays is not installed or not enabled. ***");
		getLogger().severe("*** This plugin will be disabled. ***");
		this.setEnabled(false);
		return;
	}
	
	// Rest of the code
}

 

If it's not strictly required, you can just check if the plugin is enabled, and use a field in your plugin to see if you should make calls to the API:

private boolean useHolographicDisplays;

@Override
public void onEnable() {
	useHolographicDisplays = Bukkit.getPluginManager().isPluginEnabled("HolographicDisplays");

	// Rest of the code
}

 

3) Start using the API

The API is a class called HologramsAPI, all the methods are static. With the method createHologram(...) you can create a hologram with some lines. The method returns the hologram just created. Example:

Plugin plugin = ... // Your plugin's instance
Location where = ... // A Location object
Hologram hologram = HologramsAPI.createHologram(plugin, where);
textLine = hologram.appendTextLine("A hologram line");

Done! With just two lines of code you created a hologram. The TextLine object represents the line you added: it can be used to retrieve and modify the content of that line. Inserting a line before won't change its content: the TextLine is not related to the position of line inside the hologram.

4) Return types

Before reading further tutorials, you should be aware that when you append or insert a line, an object is returned:

TextLine textLine1 = hologram.appendTextLine("...");
TextLine textLine2 = hologram.insertTextLine(0, "...");

ItemLine itemLine1 = hologram.appendItemLine(new ItemStack(Material.STONE));
ItemLine itemLine2 = hologram.insertItemLine(0, new ItemStack(Material.STONE));

5) What to do now?

If you think this tutorial is enough, you may want to read the full API documentation, that is located here. The most relevant classes are HologramsAPI and the interface Hologram.