Getting Started (v2)

This documentation is for FancyHolograms v2. For the latest version (v3), see the v3 documentation.

FancyHolograms v2 uses a direct, manager-based approach for creating and managing holograms. This is simpler than v3's builder pattern but less feature-rich.

Include the API in your project

To include the FancyHolograms v2 API in your project, add the following dependency:

Gradle:

repositories {
    maven("https://repo.fancyinnovations.com/releases")
}

dependencies {
    compileOnly("de.oliver:FancyHolograms:2.x.x") // Replace with v2 version
}

Maven:

<repository>
    <id>fancyinnovations-releases</id>
    <name>FancyInnovations Repository</name>
    <url>https://repo.fancyinnovations.com/releases</url>
</repository>

<dependency>
    <groupId>de.oliver</groupId>
    <artifactId>FancyHolograms</artifactId>
    <version>2.x.x</version>
    <scope>provided</scope>
</dependency>

Create a text hologram

1. Create the hologram data

The TextHologramData class stores all information about a text hologram:

import de.oliver.fancyholograms.api.data.TextHologramData;
import org.bukkit.Location;
import java.util.List;

Location location = new Location(world, 100, 64, 200);

TextHologramData data = new TextHologramData("my_hologram", location);
data.setText(List.of(
    "<rainbow>Rainbow Text</rainbow>",
    "<gold>Second Line</gold>"
));

2. Create the hologram

Use the HologramManager to create the hologram from data:

import de.oliver.fancyholograms.api.FancyHologramsPlugin;
import de.oliver.fancyholograms.api.HologramManager;
import de.oliver.fancyholograms.api.hologram.Hologram;

HologramManager manager = FancyHologramsPlugin.get().getHologramManager();
Hologram hologram = manager.create(data);

3. Add the hologram

manager.addHologram(hologram);

If you don't want to persist the hologram, set data.setPersistent(false) before creating it.

Modify an existing hologram

1. Get the hologram by name

import java.util.Optional;

Optional<Hologram> optional = manager.getHologram("my_hologram");

if (optional.isPresent()) {
    Hologram hologram = optional.get();
    // Modify the hologram
}

2. Modify the hologram data

if (hologram.getData() instanceof TextHologramData textData) {
    textData.setText(List.of("<green>Updated!</green>"));
}

3. Update the hologram

After modifying the data, update the hologram for all viewers:

hologram.queueUpdate();
// or for immediate update:
hologram.forceUpdate();

Remove a hologram

manager.removeHologram(hologram);
hologram.deleteHologram();

Complete example

import de.oliver.fancyholograms.api.*;
import de.oliver.fancyholograms.api.data.TextHologramData;
import de.oliver.fancyholograms.api.hologram.Hologram;
import org.bukkit.Location;
import java.util.List;

public class HologramExample {

    public void createHologram(Location location) {
        // 1. Create data
        TextHologramData data = new TextHologramData("example_holo", location);
        data.setText(List.of(
            "<gold><bold>Welcome!</bold></gold>",
            "<gray>to our server</gray>"
        ));
        data.setPersistent(true);

        // 2. Create hologram
        HologramManager manager = FancyHologramsPlugin.get().getHologramManager();
        Hologram hologram = manager.create(data);

        // 3. Add to manager
        manager.addHologram(hologram);
    }

    public void updateHologram(String name) {
        HologramManager manager = FancyHologramsPlugin.get().getHologramManager();

        manager.getHologram(name).ifPresent(hologram -> {
            if (hologram.getData() instanceof TextHologramData textData) {
                textData.setText(List.of("<red>Updated!</red>"));
                hologram.forceUpdate();
            }
        });
    }

    public void removeHologram(String name) {
        HologramManager manager = FancyHologramsPlugin.get().getHologramManager();

        manager.getHologram(name).ifPresent(hologram -> {
            manager.removeHologram(hologram);
            hologram.deleteHologram();
        });
    }
}

Key differences from v3

Feature	v2	v3
Creation	Direct `new TextHologramData()`	Builder pattern
Management	`HologramManager`	`HologramRegistry` + `HologramController`
API Entry	`FancyHologramsPlugin.get()`	`FancyHolograms.get()`
Updates	`queueUpdate()` / `forceUpdate()`	`refreshHologram()`
Features	Simpler, fewer features	Trait system, more advanced

JavaDocs and help

Join the FancyInnovations Discord for help and support. There is a dedicated channel for help about the API (#holograms-api).

Getting Started (v2)

On this page