106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
# 📽️ TrilerHolograms – Lightweight TextDisplay Library
|
||
|
||
**TrilerHolograms** is a modern, high-performance **Java library** for Bukkit/Spigot plugins (supporting version 1.21.10 and above). It utilizes native `TextDisplay` entities, making it significantly more efficient than traditional armor-stand-based holograms.
|
||
|
||
Designed for developers, it provides a clean, static API to manage floating text with zero hassle.
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
- ✅ **Static API**: Access everything via `HologramManager.<method>`—no constructors needed.
|
||
- 🌈 **Color Support**: Built-in support for legacy `&` color codes.
|
||
- 📏 **Multi-line Logic**: Easily create multi-line displays using standard Java `List<String>`.
|
||
- 🔄 **Safe Updates**: Update existing holograms without flickering or entity recreation.
|
||
- 🛡️ **Non-Persistent**: Entities are set to `persistent = false`, ensuring they despawn on server restarts or crashes.
|
||
- 🧩 **Zero Dependencies**: Works out of the box with standard Spigot/Paper API.
|
||
|
||
---
|
||
|
||
## 🔧 Getting Started
|
||
|
||
### 1. Create a Hologram
|
||
Define a unique ID, a location, and your text lines. If the ID already exists, the old one is automatically replaced.
|
||
|
||
```java
|
||
List<String> lines = Arrays.asList(
|
||
"&b&lTRILER NETWORK",
|
||
"&7Welcome to the lobby!",
|
||
"&eUse /play to start"
|
||
);
|
||
|
||
HologramManager.create("lobby_welcome", player.getLocation(), lines);
|
||
```
|
||
|
||
### Update Text
|
||
Perfect for dynamic data like player stats, server TPS, or countdowns:
|
||
|
||
```java
|
||
HologramManager.update("lobby_welcome", List.of(
|
||
"&b&lTRILER NETWORK",
|
||
"&aPlayers Online: " + Bukkit.getOnlinePlayers().size()
|
||
));
|
||
```
|
||
|
||
### 3. Cleanup (Required)
|
||
To ensure no "ghost" entities remain during plugin reloads or server shutdowns, call this in your main class's onDisable method:
|
||
|
||
```java
|
||
@Override
|
||
public void onDisable() {
|
||
// This removes all holograms created by this manager
|
||
HologramManager.removeAll();
|
||
}
|
||
```
|
||
|
||
## 📡 API Reference
|
||
|Method|Description
|
||
| -------------|:-------------:|
|
||
|create(id, loc, lines)|Spawns a new hologram or replaces an existing one.|
|
||
|update(id, lines)|Changes the text of an existing hologram.|
|
||
|remove(id)|Deletes a specific hologram by its ID.|
|
||
|get(id)|Returns an Optional<TextDisplay> to modify raw entity properties.|
|
||
|removeAll()|Deletes every hologram managed by this library.|
|
||
|
||
## 🧑💻 Advanced Examples
|
||
|
||
Accessing the Raw Entity
|
||
Use the get method to apply specific Minecraft Display features like glowing or scale:
|
||
```java
|
||
HologramManager.get("lobby_welcome").ifPresent(display -> {
|
||
display.setGlowing(true);
|
||
display.setGlowColorOverride(org.bukkit.Color.AQUA);
|
||
display.setShadowed(true);
|
||
});```
|
||
|
||
Dynamic Stats Hologramž
|
||
```java
|
||
new BukkitRunnable() {
|
||
@Override
|
||
public void run() {
|
||
HologramManager.update("stats", List.of(
|
||
"&6Server Stats",
|
||
"&fTPS: &a" + Bukkit.getTPS()[0]
|
||
));
|
||
}
|
||
}.runTaskTimer(plugin, 0L, 20L);
|
||
```
|
||
|
||
## 📥 Maven
|
||
Repository
|
||
```xml
|
||
<repositories>
|
||
<repository>
|
||
<id>gitea</id>
|
||
<url>https://git.triler.eu/api/packages/TrilerCode/maven</url>
|
||
</repository>
|
||
</repositories>
|
||
```
|
||
Dependency
|
||
```xml
|
||
<dependency>
|
||
<groupId>net.triler</groupId>
|
||
<artifactId>minecraft-holograms</artifactId>
|
||
<version>1.0</version>
|
||
</dependency>
|
||
``` |