HologramLib

A packet-based hologram library for Bukkit/Spigot plugins, designed for efficiency using movement listeners instead of server ticks.

Features

• Create and manage holograms with minimal performance impact
• Generic HologramManager<InternalIdType> for custom internal ID types
• Text holograms with dynamic metadata updates
• Placeholder support via PlaceholderAPI (non-ticking by default)
• No reliance on scheduled tasks for moving/updating holograms

Installation

Gradle

Add the repository:

repositories {
maven { url = uri("https://repo.tcoded.com/releases/") }
}

Add the dependency:

dependencies {
implementation("com.tcoded:HologramLib:1.3.4")
}

(REQUIRED) Shade with Shadow plugin to avoid package conflicts:

plugins {
id ("com.gradleup.shadow") version '9.1.0'
}
shadowJar {
relocate("com.tcoded.hologramlib", "your.plugin.package.hologramlib")
}

Maven

<repositories>
<repository>
<id>tcoded-releases</id>
<url>https://repo.tcoded.com/releases/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.tcoded</groupId>
<artifactId>HologramLib</artifactId>
<version>1.3.4</version>
</dependency>
</dependencies>

Shade with Maven Shade Plugin:

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.6.1</version>
<executions>
<execution>
<phase>package</phase>
<goals><goal>shade</goal></goals>
<configuration>
<relocations>
<relocation>
<pattern>com.tcoded.hologramlib</pattern>
<shadedPattern>your.plugin.package.hologramlib</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>

Quick Start

Initialization

In your main JavaPlugin class:

publicclassMyPluginextendsJavaPlugin {
privateHologramLibhologramLib;
@OverridepublicvoidonEnable() {
hologramLib = newHologramLib(this);
}
}

Hologram Manager

Obtain a manager with your internal ID type (e.g., Location):

importcom.tcoded.hologramlib.manager.HologramManager;
HologramManager<Location> manager = hologramLib.getHologramManager();

The internal ID type must have a proper equals() and hashCode() implementation for uniqueness.

Creating a Text Hologram

importorg.bukkit.Location;
importnet.kyori.adventure.text.Component;
importcom.tcoded.hologramlib.hologram.TextHologram;
importcom.tcoded.hologramlib.hologram.TextHologramLine;
// Create a new hologram instance/* Location loc = new Location(getServer().getWorld("world"), x, y, z); */TextHologram<Location> hologram = manager.create(loc);
hologram.setLocation(loc);
// Set initial text lineTextHologramLinefirstLine = hologram.getLine(0);
firstLine.getMeta().setText(Component.text("Hello"));
// Add another lineTextHologramLinesecondLine = manager.createLine();
secondLine.getMeta().setText(Component.text("World"));
hologram.addLine(secondLine);
// Show hologram to all tracked playershologram.show();

Managing Lines

importnet.kyori.adventure.text.Component;
importcom.tcoded.hologramlib.hologram.TextHologramLine;
// Add a new lineTextHologramLinenewLine = manager.createLine();
newLine.getMeta().setText(Component.text("Another line"));
hologram.addLine(newLine); // This will automatically show if isVisible()// Get a lines (by index, or all)hologram.getLine(0);
hologram.getLines();
// Remove a line (by index)hologram.removeLine(1);

Editing Metadata

importnet.kyori.adventure.text.Component;
// Change text of first linehologram.getLine(0).getMeta().setText(Component.text("Updated Text"));
// Adjust vertical offset (height) of first linehologram.getLine(0).setHeight(0.5);
// Apply metadata changes to all tracked playershologram.updateMeta();

Removing Holograms

// Remove a specific hologram by its internal IDmanager.killAndRemove(hologram.getInternalId());
// Or remove all hologramsmanager.killAndRemoveAll();

Frequently Asked Questions (FAQ)

What is <InternalIdType>?

As you have likely noticed, HologramLib takes a generic <InternalIdType>. This is a unique key/identifier for each hologram you create. Instead of requiring all your projects to keep track of holograms themselves, HologramLib has an internal mapping of ID to Hologram instance. The internal Map implementation is a ConcurrentHashMap making it safe to use in multithreaded environments.

• (Disable) Don't want to use this?
  • You can simply use an incrementing Integer or UUID for each hologram you create.
• (Easy) Want to tie holograms to locations?
  • Use Location as your InternalIdType for position-based holograms. You can now create and retrieve Holograms based on a Location.
• (Advanced) Use a unique identifier for each hologram:
  • NPC or custom object with stable hashCode() and equals(). This approach makes it easy to update holograms if the object it is tied to changes without requiring you to write another mapping.

How can I make placeholders update?

HologramLib does not tick holograms by default. To update the placeholders, you will need to tick the holograms that require updates. Simply create a repeating async task and call hologram.updateMeta(). This method will re-calculate the text, and therefore placeholders in the hologram's lines.

// Example: Update all holograms every second using FoliaLib// https://github.com/TechnicallyCoded/FoliaLibprivateFoliaLibfoliaLib;
privateHologramLib<UUID> hologramLib;
@OverridepublicvoidonEnable() {
// FoliaLib SetupfoliaLib = newFoliaLib(this);
PlatformSchedulerscheduler = foliaLib.getScheduler();
// HologramLib SetuphologramLib = newHologramLib<>(this);
// HologramLib TickingConsumer<WrappedTask> updater = task -> hologramManager.getHolograms().forEach(Hologram::updateMeta);
scheduler.runTimerAsync(updater, 20L, 20L);
}

License

ARR License