Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/max1mde/hologramlib

Packet based text display hologram library with minimessage and emoji support
https://github.com/max1mde/hologramlib

api hologram java minecraft minimessage packet-based plugin

Last synced: 12 days ago
JSON representation

Packet based text display hologram library with minimessage and emoji support

Awesome Lists containing this project

README 

        




FOLIA ✅ PAPER ✅ PURPUR ✅ 1.19.4 - 1.21 ✅


Join Discord Server

Version

jitpack 

Downloads






Leave a :star: if you like this library :octocat:







Contents


• Installation


• Example plugin with which uses HologramLib








First Steps

   • Initializing Manager


   • Rendering Modes


   • Creation


   • Leaderboards


   • Passengers


   • Viewers


   • Transformations


   • Management






# 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



# Installation



- Download packet events https://www.spigotmc.org/resources/80279/

- Download HologramLib-[version]**.jar** file from the [latest release](https://github.com/max1mde/HologramLib/releases)

- Upload the HologramLib-[version]**.jar** and packet events file on your server (_yourserver/**plugins**_ folder)

- Add the plugin as a dependency to your plugin and use it



> [!NOTE]  

> You might also want to add [packetevents](https://github.com/retrooper/packetevents/wiki/Depending-on-pre%E2%80%90built-PacketEvents) as a compile-only dependency to your plugin  

> if you want to use (import) certain features, such as the `ItemStack` for the item hologram.



**Gradle installation**

```groovy

repositories {

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

}



dependencies {

  compileOnly 'com.github.max1mde:HologramLib:1.6.1'

}

```

**Maven installation**

```xml



  jitpack.io

  https://jitpack.io



  com.github.max1mde

  HologramLib

  1.6.1

  provided



```

Add this to your plugin

`plugin.yml`

```yml

depend:

  - HologramLib

```



# Example/Showcase Plugin

https://github.com/max1mde/ExampleHologramPlugin



# First Steps



### Initializing HologramManager

```java

private HologramManager hologramManager;



@Override

public void onEnable() {

    hologramManager = HologramLib.getManager().orElse(null);

    if (hologramManager == null) {

        getLogger().severe("Failed to initialize HologramLib manager.");

        return;

    }

}

```



> [!IMPORTANT]

> If you are shading the library use `HologramLib.getManager()` instead!



### Hologram Rendering Modes

```java

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



#### Text Hologram

```java

TextHologram hologram = new TextHologram("unique_id")

    .setMiniMessageText("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);

```

#### Block Hologram

````java

BlockHologram blockHologram = new BlockHologram("unique_id")

    .setBlock(1) 

    .setOnFire(false)

    .setBillboard(Display.Billboard.VERTICAL)

    .setScale(1.0F, 1.0F, 1.0F)

    .setViewRange(1.0);

````



#### Item Hologram

````java

ItemHologram itemHologram = new ItemHologram("unique_id")

    .setItem(new ItemStack.Builder()

        .type(ItemTypes.DIAMOND_SWORD)

        .build())

    .setGlowing(true)

    .setGlowColor(Color.ORANGE)

    .setOnFire(false)

    .setDisplayType(ItemDisplayMeta.DisplayType.FIXED)

    .setBillboard(Display.Billboard.VERTICAL)

    .setScale(2.0F, 2.0F, 0.01F)

    .setViewRange(1.0);

````



#### Spawning any hologram (including leaderboard objects)

````java

hologramManager.spawn(hologram, location);

````



### Leaderboard Creation






```java

Map 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()

);



/*

 Update the leaderboard later if needed

 */

hologramManager.updateLeaderboard(

        leaderboard,

        updatedData,

        /*

         ou can also use different options here 

         which will be applied to the leaderboard

         */

        leaderboard.getOptions()

);

```



### Setting a hologram as a passenger

```java

hologramManager.attach(hologram, parentEntityId);

```



### Managing Hologram Viewers

This only makes sense if you set the holograms `RenderMode` to `VIEWER_LIST`

```java

hologram.addViewer(player);

hologram.removeViewer(player);

hologram.removeAllViewers();



// The players who see the hologram

List currentViewers = hologram.getViewers();

```



### Advanced Transformations

```java

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

```java

Optional retrievedHologram = hologramManager.getHologram("unique_id");



hologramManager.remove("unique_id");



hologramManager.remove(hologram/leaderboard);



hologramManager.removeAll();

```



Contributions to this repo or the example plugin are welcome!