API

The official documentation for the API.

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.

---

As A Maven Dependency

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

<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

The API can be accessed like so:

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

public HoloAPI getHoloAPI() {
    Plugin plugin = this.getServer().getPluginManager().getPlugin("HoloAPI");
    if (plugin == null || !(plugin instanceof HoloAPI)) {
        // HoloAPI isn't installed (or loaded) on this server - nag the server owner about this
        return null;
    }

    return ((HoloAPI) plugin);
}

---

Using 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 API

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

The methods available in the Hologram Factory are as follows:

• withLocation(...) - Two different methods with different arguments. Sets the location to create the hologram at. If this is not given, HoloAPI will not be able to create the hologram.
  • Location - Uses the location coordinates and world name as the hologram location
  • Vector, String - Uses the vector coordinates and string (world name) as the hologram location
• withText(String...) - Adds the given set of strings, in order, to the hologram
• withImage(...) - Adds the given image to the hologram
  • ImageGenerator - See below for how to create a new ImageGenerator
  • String - Finds the image that corresponds with the given image id. If an image is not found, the hologram will not change.
• build() - Builds and returns the hologram. This also shows the hologram to all nearby players and tracks it using the HoloManager (see below)

---

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

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.
• createHologram(...) - 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()
• getLines()
• getSaveId()
• changeWorld()
• clearAllPlayerViews()
• getLocationFor(Player)
• show(...)
• move(...)
• clear(Player)

---

Animated Holograms

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

• getAnimatedImage() - 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 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.