HologramLib

HologramLib - это пакетная библиотека для разработчиков плагинов, которая позволяет легко создавать и управлять голограммами на серверах Minecraft. Если тебе когда-нибудь хотелось повесить в воздухе красиво оформленный текст, анимированное объявление или топ игроков - HologramLib возьмёт на себя всю низкоуровневую работу.

Зачем нужна эта библиотека?

В ванильном Майнкрафте нет нормальных голограмм - максимум можно наклепать брони с именными табличками, но это и кустарно, и по производительности так себе. Для сервера с PvP, мини-играми или экономикой вывод статистики в воздух - стандартная задача. HologramLib решает её без костылей: голограммы рендерятся через пакеты, что даёт прирост FPS и гибкость.

Она подходит для:

• Таблиц лидеров (kill/death, топ по деньгам, уровни)
• Анимированных новостей или ивентов
• Указателей на карте (например, в данжах)
• Визуального оформления магазинов или варпов

Особенности

• Текстовые, блочные и предметные голограммы - можно вывести любой предмет, блок или цветной текст
• Анимации - фреймы с задержками, смена цвета, движущиеся строки
• MiniMessage - поддержка градиентов, смайликов (вроде :smile:), переводов строк
• Пакетная система - без лишних сущностей на сервере, нагрузка меньше
• Персонализация - голограммы видны конкретным игрокам (per-player)
• Лидерборды - генерация таблицы с заголовком, суффиксом и даже головой топ-1
• Прикрепление - можно повесить голограмму на игрока или объект
• Гибкая настройка - билборд, тень, прозрачность, выравнивание, масштаб, макс. ширина строки

Совместимость

• Folia, Paper, Purpur - все поддерживаются
• Spigot - возможны баги на старых версиях, лучше используй Paper
• Версии Minecraft - 1.19.4 - 1.21.5
• Только Java API - не запускается как самостоятельный плагин, нужна интеграция в свой код
• Не работает для Bedrock-игроков

Установка

1. Скачай HologramLib.jar и Packet Events.jar
2. Кинь их в папку plugins на сервере
3. В своём плагине пропиши зависимость в plugin.yml и используй API

Быстрый старт в коде

Получение менеджера:

private HologramManager hologramManager;

@Override
public void onEnable() {
    hologramManager = HologramLib.getManager().orElse(null);
    if (hologramManager == null) {
        getLogger().severe("Не удалось инициализировать HologramLib");
    }
}

Создание голограммы:

TextHologram hologram = new TextHologram("unique_id")
    .setMiniMessageText("<aqua>Привет, мир!")
    .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);
hologramManager.remove(hologram);

Анимация:

TextAnimation animation = new TextAnimation()
        .addFrame("<red>Первый кадр")
        .addFrame("<green>Второй кадр")
        .addFrame("Третий кадр")
        .addFrame("Последний кадр");
animation.setDelay(20L); // 1 секунда
hologramManager.applyAnimation(hologram, animation);

Лидерборд:

Map<Integer, String> data = new LinkedHashMap<>();
data.put(1, "PlayerX:1000");
data.put(2, "Dream:950");

LeaderboardHologram lb = hologramManager.generateLeaderboard(
    location, data,
    LeaderboardHologram.LeaderboardOptions.builder()
        .title("Топ убийц")
        .showEmptyPlaces(true)
        .scale(1.2f)
        .maxDisplayEntries(10)
        .suffix("убийств")
        .topPlayerHead(true)
        .build()
);

Настройка сборки

Для Gradle:

repositories {
  maven { url 'https://jitpack.io' }
}
dependencies {
  compileOnly 'com.github.HologramLib:HologramLib:1.7.6'
}

Для Maven:

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

Не забудь указать зависимость в plugin.yml:

depend:
  - HologramLib

Важно знать

• Если шейдишь HologramLib в свой плагин - вызови HologramLib.onLoad(this) в onLoad()
• Для лидербордов можно задавать количество записей, показывать голову топ-1, пустые места
• Голограммы с привязкой к игроку движутся за ним - идеально для меток или спецэффектов
• Библиотека облегчает работу с PacketEvents, без неё API не запустится

Скачай HologramLib и забудь про костыли с брони-стойками - твой сервер станет визуально богаче, а игроки оценят живые таблицы лидеров прямо в воздухе.