https://github.com/max1mde/hologramapi

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

api hologram java minecraft minimessage packet-based plugin

Last synced: 27 days ago
JSON representation

Packet based text display hologram api with minimessage and emoji support

• Host: GitHub
• URL: https://github.com/max1mde/hologramapi
• Owner: max1mde
• License: gpl-3.0
• Created: 2023-07-26T18:15:07.000Z (over 1 year ago)
• Default Branch: master
• Last Pushed: 2024-12-12T19:43:44.000Z (about 1 month ago)
• Last Synced: 2024-12-12T20:37:15.028Z (about 1 month ago)
• Topics: api, hologram, java, minecraft, minimessage, packet-based, plugin
• Language: Java
• Homepage: https://www.spigotmc.org/resources/111746
• Size: 899 KB
• Stars: 9
• Watchers: 2
• Forks: 4
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        







 





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

# 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](https://github.com/max1mde/HologramAPI/releases)

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

```groovy

repositories {

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

}

dependencies {

  compileOnly 'com.github.max1mde:HologramAPI:1.4.7'

}

```

**Maven installation**

```xml

  jitpack.io

  https://jitpack.io

  com.github.max1mde

  HologramAPI

  1.4.7

  provided

```

Add this to your plugin

`plugin.yml`

```yml

depend:

  - HologramAPI

```

# Example/Showcase Plugin

https://github.com/max1mde/ExampleHologramPlugin

# First Steps

### Initializing HologramManager

```java

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

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

hologramManager.spawn(hologram, location);

```

### Leaderboard Creation



```java

Map 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

```java

hologramManager.attach(hologram, parentEntityId);

```

### Managing Hologram Viewers

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

hologramManager.removeAll();

```

Contributions to this repo or the example plugin are welcome!