Перейти к содержимому
Mineforgian

HologramLib | Leaderboards & Custom Holograms

Packet-based text display library with animations, leaderboards, emojis, minimessage, and more!

Загрузки
7K
Подписчики
31
Обновлён
30 октября 2025 г.
Лицензия
GPL-3.0-or-later

Опубликован 22 июня 2024 г.

Исходный кодСообщить об ошибке

FOLIA ✅ PAPER ✅ PURPUR ✅ 1.19.4 - 1.21.5 ✅

Version Join Discord Server Version jitpack
HologramLib

An easy-to-use, packet-based text/item/block display hologram API with MiniMessage and emoji support.

FEATURES

  • Text, Block & Item Holograms
  • Text animations
  • Minimessage support
  • Packet based
  • Per player holograms
  • Leaderboard generators
  • Advanced hologram customization
  • Attachment and parenting support
  • Flexible rendering modes
DISCLAIMER This API only works on 1.19.4+
The holograms do not work for Bedrock players
There can be some issues when using spigot on older versions (Preferably use Paper or a fork of it)
It's just a Java API. This plugin does not work standalone.

SETUP

  • Download the plugin .jar
  • Download Packet Events
  • Upload the .jar files onto your server (yourserver/plugins folder)
  • Add the plugin as a dependency to your plugin and use it

PROJECT SETUP

Gradle installation

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

dependencies {
  compileOnly 'com.github.HologramLib:HologramLib:1.7.6'
}

Maven installation

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

<dependency>
  <groupId>com.github.HologramLib</groupId>
  <artifactId>HologramLib</artifactId>
  <version>1.7.6</version>
  <scope>provided</scope>
</dependency>

Add this to your plugin plugin.yml

depend:
  - HologramLib

Code examples

Getting the instance

private HologramManager hologramManager;

@Override
public void onLoad() {
    HologramLib.onLoad(this); /*Only needed if you shade HologramLib*/
}

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

Creating a hologram

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

Spawning and despawning

hologramManager.spawn(hologram, <location>);
hologramManager.remove(hologram);

Animations

TextAnimation animation = new TextAnimation()
        .addFrame( "<red>First frame")
        .addFrame("<green>Second frame")
        .addFrame("Third frame\n" +
                "Second line in third frame")
        .addFrame("Last frame");
animation.setDelay(20L); // 1 second
animation.setDelay(20L * 2);
hologramManager.applyAnimation(this.hologram, animation);

Leaderboard

Map<Integer, String> leaderboardData = new LinkedHashMap<>() {{
    put(1, "MaximDe:1000");
    put(2, "dream:950");
    put(3, "BastiGHG:500");
    put(4, "Wichtiger:400");
    // ... more entries
}};

LeaderboardHologram leaderboard = hologramManager.generateLeaderboard(
        location,
        leaderboardData,
        LeaderboardHologram.LeaderboardOptions.builder()
                .title("Top Players - Kills")
                .showEmptyPlaces(true)
                .scale(1.2f)
                .maxDisplayEntries(10)
                .suffix("kills")
                .topPlayerHead(true)
                .build()
);

Wiki

Code examples & more https://github.com/HologramLib/HologramLib/wiki

Example/Showcase Plugin

https://github.com/HologramLib/ExamplePlugin

More info https://maximjsx.com/projects/hologramlib

Ченджлог

1.8.3Релиз1.21.8, 1.21.9, 1.21.10 · 30 октября 2025 г.

What's Changed

  • Bump depdendency versions
  • Bug fixes

Skipped releases on Modrinth:

  • 1.8.2 Better number formatting in leaderboards by @RootException in #41
  • 1.8.1 Dependency updates Updated version of FoliaLib Updated version of packetevents Updated version of EntityLib
1.8.0Релиз1.21.6, 1.21.7, 1.21.8 · 3 сентября 2025 г.

The Leaderboard Update

What's Changed

Breaking Changes in the API 🚨

If you are already using HologramLib's leaderboards, you MUST update your plugin before updating HologramLib on your server ⚠️

Everything regarding Leaderboards is new including imports!

Here is a small example:

Map<UUID, LeaderboardHologram.PlayerScore> scores = new HashMap<>();

LeaderboardHologram.LeaderboardOptions pvpOptions = LeaderboardHologram.LeaderboardOptions.builder()
        .title("PvP Champions")
        .suffix("Kills")
        .showEmptyPlaces(false)
        .maxDisplayEntries(10)
        .sortOrder(LeaderboardHologram.SortOrder.DESCENDING)
        .headMode(LeaderboardHologram.HeadMode.RESOURCEPACK)
        .leaderboardType(LeaderboardHologram.LeaderboardType.ALL_PLAYER_HEADS)
        .build();

LeaderboardHologram pvpLeaderboard = new LeaderboardHologram(pvpOptions, "pvp_lb");
pvpLeaderboard.setAllScores(scores);

/* You can combine the leaderboard with others in a paginated leaderboard
but you can also just spawn the pvpLeaderboard for example
directly using hologramManager.spawn(pvpLeaderboard, location)
*/
PagedLeaderboard pagedLeaderboard = new PagedLeaderboard("paged_holo")
        .addPage(pvpLeaderboard)
        .addPage(<... another page>)
        .setArrowBackgrounds(pvpLeaderboard.getBackgroundHologram().getBackgroundColor())
        .setLeftArrowText("<red><<")
        .setRightArrowText("<red>>>")
        .setArrowOffset(3.5)
        .setClickSounds(Sound.BLOCK_AMETHYST_CLUSTER_FALL, Sound.BLOCK_AMETHYST_CLUSTER_FALL)
        .addPage(economyLeaderboard)
        .rotate(0);
hologramManager.spawn(pagedLeaderboard, location);

For the resourcepack option you also need the resourcepack zip file from below on your server. Download

[!NOTE]
The wiki was partially updated already

image

New Contributors

Full Changelog: https://github.com/HologramLib/HologramLib/compare/1.7.7...1.8.0

1.7.7Релиз1.21.3, 1.21.4, 1.21.5 · 25 июля 2025 г.
  • Bugfixes
    • Attachement issues

Full Changelog: https://github.com/HologramLib/HologramLib/compare/1.7.6...1.7.7

1.7.6Релиз1.21.5, 1.21.6, 1.21.7 · 9 июля 2025 г.

Changes

  • Added support for NOT_ATTACHED_PLAYER render mode that excludes attached players from viewing the hologram
  • Added Hologram#attachToPlayer(Player)

Full Changelog: https://github.com/HologramLib/HologramLib/compare/1.7.5...1.7.6

Also included 1.7.5:

Full Changelog: https://github.com/HologramLib/HologramLib/compare/1.7.4...1.7.5

1.7.4Релиз1.21.3, 1.21.4, 1.21.5 · 22 мая 2025 г.

What's Changed

  • Improved performance (thanks to @RootException)
  • Fixed alot of bugs

New Contributors

Full Changelog: https://github.com/HologramLib/HologramLib/compare/1.7.3...1.7.4

1.7.1Релиз1.21.2, 1.21.3, 1.21.4 · 25 февраля 2025 г.

What's Changed

  • Add back Hologram#getViewers() and also an additional method Hologram#getViewerUUIDs() which is more efficient and just returns the viewers as UUID's

Full Changelog: https://github.com/max1mde/HologramLib/compare/1.7.0...1.7.1

1.7.0Релиз1.21.2, 1.21.3, 1.21.4 · 16 февраля 2025 г.

What's Changed

API Breaking Changes

  • Replaced Hologram#nearbyEntityScanningDistance with Hologram#maxPlayerRenderDistanceSquared (Default value is now 62500)

Full Changelog: https://github.com/max1mde/HologramLib/compare/1.6.9...1.7.0

1.6.9Релиз1.21.1, 1.21.2, 1.21.3 · 12 февраля 2025 г.

What's Changed

Dependency:

com.github.max1mde:HologramLib:1.6.9

Full Changelog: https://github.com/max1mde/HologramLib/compare/1.6.8...1.6.9

Комментарии

Загружаем…