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

See the main README.md if you use Maven or Gradle. Alternatively, you can directly download the JAR file here (not recommended).

Use the latest version of HolographicDisplays while coding and ask your users to do the same. The API can change, and some methods could be missing in previous versions.

 

2) Check if HolographicDisplays is enabled

To use the API, you first 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;
	}
	
	// ...
}

 

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");

	// ...
}

 

3) Start using the API

The main API class is HolographicDisplaysAPI. 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 = ... // The location where the hologram will be placed
HolographicDisplaysAPI api = HolographicDisplaysAPI.get(plugin); // The API instance for your plugin
Hologram hologram = api.createHologram(plugin, where);
TextHologramLine textLine = hologram.getLines().appendText("A hologram line");

Done! With just two lines of code you created a hologram. The TextHologramLine object represents the line you added: it can be used to retrieve and modify the content of that line.

 

4) Return types

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

TextHologramLine textLine1 = hologram.getLines().appendText("...");
TextHologramLine textLine2 = hologram.getLines().insertText(0, "...");

ItemHologramLine itemLine1 = hologram.getLines().appendItem(new ItemStack(Material.STONE));
ItemHologramLine itemLine2 = hologram.getLines().insertItem(0, new ItemStack(Material.STONE));

 

5) What to do now?

If you think this tutorial is enough, you may want to read the javadocs API documentation. The most relevant classes are HolographicDisplaysAPI and the interface Hologram.