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.

---

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.3</version>
    </dependency>
<!-- And so on... -->
</dependencies>

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

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

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:

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. 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)

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

Ahologram represents the visual holographic display in-game

Animated Holograms

Image and Animation Loaders

More content coming soon...