Leave a ⭐ if you like this API

Features

• Text animations
• Minimessage support
• Packet based
• Per player holograms
• Dynamic leaderboard creation
• Advanced hologram customization
• Attachment and parenting support
• Flexible rendering modes

Installation

• Download packet events https://www.spigotmc.org/resources/80279/
• Download HologramAPI-[version].jar file from the latest release
• Upload the HologramAPI-[version].jar and packet events file on your server (yourserver/plugins folder)
• Add the plugin as a dependency to your plugin and use it

Gradle installation

repositories {
  maven { url 'https://jitpack.io' }
}

dependencies {
  compileOnly 'com.github.max1mde:HologramAPI:1.4.7'
}

Maven installation

<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

<dependency>
  <groupId>com.github.max1mde</groupId>
  <artifactId>HologramAPI</artifactId>
  <version>1.4.7</version>
  <scope>provided</scope>
</dependency>

Add this to your plugin plugin.yml

depend:
  - HologramAPI

Example/Showcase Plugin

https://github.com/max1mde/ExampleHologramPlugin

First Steps

Initializing HologramManager

private HologramManager hologramManager;

@Override
public void onEnable() {
    hologramManager = HologramAPI.getManager().orElse(null);
    if (hologramManager == null) {
        getLogger().severe("Failed to initialize HologramAPI manager.");
        return;
    }
}

Important

If you are shading the library use HologramAPI.getManager(<Your plugin instance>) instead!

Hologram Rendering Modes

// Different rendering modes available
TextHologram hologram = new TextHologram("example", RenderMode.NEARBY);
// Modes include:
// - NEARBY: Render for players near the hologram
// - ALL: Render for all online players
// - VIEWER_LIST: Render only for manually added viewers
// - NONE: Do not render

Note

Display.Billboard.CENTER = the hologram rotates to the player like a nametag (default value) Display.Billboard.FIXED = The holograms rotation is fixed Display.Billboard.VERTICAL = The hologram only rotates to the left and right (is horizontally fixed) Display.Billboard.HORIZONTAL = The hologram only rotates up and down (is vertically fixed)

Hologram Creation

TextHologram hologram = new TextHologram("unique_id")
    .setMiniMessageText("<aqua>Hello world!")
    .setSeeThroughBlocks(false)
    .setBillboard(Display.Billboard.VERTICAL)
    .setShadow(true)
    .setScale(1.5F, 1.5F, 1.5F)
    .setTextOpacity((byte) 200)
    .setBackgroundColor(Color.fromARGB(60, 255, 236, 222).asARGB())
    .setAlignment(TextDisplay.TextAlignment.CENTER)
    .setViewRange(1.0)
    .setMaxLineWidth(200);

hologramManager.spawn(hologram, location);

Leaderboard Creation

Map<Integer, String> leaderboardData = new LinkedHashMap<>() {{
    put(1, "PlayerOne:1000");
    put(2, "PlayerTwo:950");
    put(3, "PlayerThree:900");
    // ... more entries
}};

TextHologram leaderboard = hologramManager.generateLeaderboard(
    location,
    leaderboardData,
    HologramManager.LeaderboardOptions.builder() // There are even more options in this builder like the title and footer design
        .title("Top Players")
        .showEmptyPlaces(true)
        .scale(1.2f)
        .maxDisplayEntries(10)
        .suffix("kills")
        .build()
);

/*
 Update the leaderboard later if needed
 */
hologramManager.updateLeaderboard(
    leaderboard, 
    updatedData, 
    HologramManager.LeaderboardOptions.builder().build()
);

Setting a hologram as a passenger

hologramManager.attach(hologram, parentEntityId);

Managing Hologram Viewers

hologram.addViewer(player);
hologram.removeViewer(player);
hologram.removeAllViewers();

// The players who see the hologram
List<Player> currentViewers = hologram.getViewers();

Advanced Transformations

hologram.setTranslation(0, 1, 0) 
    .setLeftRotation(0, 1, 0, 0) 
    .setRightRotation(0, 1, 0, 0)
    .update();  // Apply changes (make them visible to the player)

Hologram Retrieval and Management

Optional<TextHologram> retrievedHologram = hologramManager.getHologram("unique_id");

hologramManager.remove("unique_id");

hologramManager.remove(hologram);

hologramManager.removeAll();

Contributions to this repo or the example plugin are welcome!