API

NOTE: This page is currently not up to date. Please see the JavaDocs for a better source of information

The official documentation for the API (though not as up-to-date as the JavaDocs!).

As a general rule: If in doubt (or it isn't on this page), refer to the JavaDocs or ask DSH105 for help.

Method names, parameters (etc.) may change, meaning that this page may not reflect your specific API version. Method names that have variable sets of parameters are listed as methodName(...), usually followed by a brief explanation of the different methods and their functions.

Looking for information on TouchScreen Holograms?

The documentation can be found over on this page.

As A Maven Dependency

If you're familiar with Maven, you'll be able to automatically download HoloAPI as a dependency using the following setup.

<repositories>
    <repository>
        <id>hawk-repo</id>
        <url>http://ci.hawkfalcon.com/plugin/repository/everything/</url>
    </repository>
<!-- And so on... -->
</repositories>

<dependencies>
    <dependency>
        <groupId>com.dsh105</groupId>
        <artifactId>HoloAPI</artifactId>
        <version>1.0.7</version>
    </dependency>
<!-- And so on... -->
</dependencies>

Note: Change the version to whatever you require (even if it is a snapshot build! ;D). See here for a full version list.

If you don't use Maven, include it as a dependency in your IDE.

Please don't include the entire plugin in your JAR file. Instead, instruct your users to install HoloAPI as a required dependency.

Access The API

Any API methods can be accessed using HoloAPI.function(). For example, to retrieve the HoloManager:

import com.dsh105.holoapi.HoloAPI;
import com.dsh105.holoapi.api.HoloManager;
// Other Bukkit imports

public HoloManager myCoolFunction() {
    return HoloAPI.getManager();
}

The API

Note: Many of these features may not be included in your version of HoloAPI. This Wiki will (almost) always be updated to reflect the latest changes, of which can sometimes include snapshot builds.

The HoloAPI plugin gives developers exclusive aspects to assets of the plugin that are usually not accessible. This page will cover the following:

Hologram Factory and Animated Hologram Factory - Easy creation of holograms
Hologram Manager - Administration and storage of holograms. Can also be used to create simple holograms that are automatically removed after the specified period of time.
Holograms and AnimatedHolograms - Control certain aspects of the created holograms
Image and Animation Loaders - Use pre-loaded images and animations from the HoloAPI Configuration file
ImageGenerator and AnimatedImageGenerator - Represent images and animated images that can be used to create holograms.

Hologram Factory

The Hologram Factory is the most important class to developers using the API. Those familiar of the StringBuilder will find this easy to use.

Holograms can be created using something similar to the following:

import com.dsh105.holoapi.api.Hologram;
import com.dsh105.holoapi.api.HologramFactory;

Hologram hologram = new HologramFactory(myPlugin)    // Replace "myPlugin" with your plugin instance
    .withLocation(new Vector(x, y, z), "myWorld")
    .withText(ChatColor.GOLD + "Hey there!")
    .withImage("myImageKey")
    .withText(ChatColor.RED + "Enjoy your stay!")
    .build();

The build() method used at the end in the example will return a Hologram. Every other method returns the same HologramFactory so that the hologram can be easily built. In this case, the hologram would contain one text line saying "Hey there!", followed by an image, then lastly another line of text saying "Enjoy your stay!". This also closely resembles how the /holo build command works.

The hologram will not be created unless the build() method is called

For a list of all the available methods in this class, see the JavaDocs.

Animated Hologram Factory

The Animated Hologram Factory is similar to the Hologram Factory, but allows the creation of Animated Holograms.

import com.dsh105.holoapi.api.AnimatedHologram;
import com.dsh105.holoapi.api.AnimatedHologramFactory;

AnimatedHologram animatedHologram = new AnimatedHologramFactory(myPlugin)    // Replace "myPlugin" with your plugin instance
    .withLocation(new Vector(x, y, z), "myWorld")
    .withImage("myCoolAnimation")
    .build();

import com.dsh105.holoapi.api.AnimatedHologram;
import com.dsh105.holoapi.api.AnimatedHologramFactory;

AnimatedHologram animatedHologram = new AnimatedHologramFactory(myPlugin)    // Replace "myPlugin" with your plugin instance
    .withLocation(new Vector(x, y, z), "myWorld")
    .withText(new AnimatedTextGenerator(new Frame[] {new Frame(10, "Look at this awesome text animation!", "Wow, even has two lines"), new Frame(10, "Such second frame"), new Frame(10, "Such advance", "Many third frame")}))
    .build();

The methods have identical functionality to the normal Hologram Factory, except that the withImage() method also takes an AnimatedImageGenerator instead of an ImageGenerator (see below for information on this).

Hologram Manager

The Hologram Manager administers the Holograms created and makes sure they are all tracked and accounted for. The only methods developers really need to deal with are the following:

getAllHolograms() - Returns a map of all existing holograms and the plugin instance that created them (HashMap<Hologram, Plugin>).
getHologramsFor(Plugin) - Finds all existing holograms that belong to the specified plugin
getHologram(String) - Attempts to search for a tracked hologram with the specified ID.
createSimpleHologram(...) - Takes various parameters (see the JavaDocs for more info on this). Creates a simple hologram that is not saved to file and is removed after the specified time. Only text can be added to a simple hologram.

Tracking and saving of holograms is all handled by HoloAPI and shouldn't be touched by other plugins, unless you know what you're doing.

Holograms

The HologramFactory will return a Hologram once the build() method is called.

A brief explanation of the methods that can be found in the Hologram class is as follows:

getTagCount()
getDefaultLocation()
getPlayerViews()
refreshDisplay()
updateLine(Integer, String)
getLines()
getSaveId()
changeWorld()
clearAllPlayerViews()
getLocationFor(Player)
show(...)
move(...)
clear(Player)

Animated Holograms

The AnimatedHologram has similar methods to the Hologram, with a few additions:

getAnimatedImageKey() - Gets the animated image that is being used to build this hologram
animate() - Begins the animation if it has not already been started. Animations are started by default using the AnimationHologramFactory#build().
isAnimating() - Returns whether the hologram is currently animating
cancelAnimation() - Cancels the currently running animation. The hologram will appear as a static image on the last frame it was showing.

Image Generator

Animation Generator

Animated Text Generator

Image and Animation Loaders

The Image and AnimationLoader both implement ImageLoader and can be used to obtain pre-loaded images and animations from the HoloAPI configuration file.

Assuming you have used the method at the top of this page for obtaining the HoloAPI instance, they can be found using the following:

import com.dsh105.holoapi.HoloAPI;
import com.dsh105.holoapi.image.AnimatedImageGenerator;
import com.dsh105.holoapi.image.ImageGenerator;

public void myCoolMethod() {
    ImageGenerator image = HoloAPI.getImageLoader().getGenerator("myCoolImage");
    AnimatedImageGenerator animatedImage = HoloAPI.getAnimationLoader().getGenerator("myCoolGif");
}

In the example, we are simply loading an Image and an Animated Image, but not doing anything with them (yet). See below for more information on what to do with these.

The basic methods that can be used are:

getGenerator(String) - Gets the loaded generator from the given key. If it is a URL image and has not been previously loaded, HoloAPI will connect to the URL and download the image. This method will return null if this happens (or if the generator doesn't exist) and HoloAPI will output loading status to the console.
exists(String) - Checks if the image or animation (depending on the loader) exists and is prepared.
isLoaded() - HoloAPI takes at least ten seconds after startup to load and prepare animations. Once this is true, all images and animations have been loaded.

Feel like you can make HoloAPI better? Got something awesome to contribute? We're always looking for help! Feel free to place a fork in this repository and submit a pull request!