1.4.7: 1.21.11 Holograms

Author: GavinGoGaming

.github/workflows/build.yml

@@ -27,8 +27,8 @@ jobs:
       uses: softprops/action-gh-release@v2
       with:
         tag_name: "latest-1.21.11"
-        name: "[1.4.6 for 1.21.11] Development Build"
-        body: "Push-ly development build for Caramel. Updated on every push - ignore the 'commits to master since this release', github works weird."
+        name: "[1.4.7 for 1.21.11] Development Build"
+        body: "Push-ly development build for Caramel. Updated on every push - ignore the 'commits to master since this release' if you're on the latest tag."
         prerelease: false
         files: |
               ./target/*.jar

docs/holos.md

@@ -0,0 +1,160 @@
+# Holograms
+
+Caramel holograms are lightweight wrappers around Minecraft `TextDisplay` entities, designed for easy multi-line floating text.
+They use holograms
+
+---
+
+## Creating a hologram
+
+You can create a hologram either empty, or pre-filled with lines.
+
+```java
+// Empty hologram as a base
+CaramelHologram hologram = new CaramelHologram();
+
+// Hologram with initial lines
+CaramelHologram hologram = new CaramelHologram(List.of(
+        new CaramelHologramLine(CaramelUtility.colorcomp("Hello")),
+        new CaramelHologramLine(CaramelUtility.colorcomp("World"))
+));
+````
+
+Before spawning, you **must** set a location:
+
+```java
+hologram.setLocation(location);
+```
+
+---
+
+<br/><br/>
+
+## Managing lines
+
+You can fully control the hologram’s lines after creation.
+
+```java
+hologram.addLine(new CaramelHologramLine(Component.text("New Line")));
+hologram.addFront(new CaramelHologramLine(Component.text("Top Line")));
+hologram.addBack(new CaramelHologramLine(Component.text("Bottom Line")));
+```
+
+Removing lines:
+
+```java
+hologram.removeLine(0); // via index
+hologram.removeLine(line); // via direct line object
+hologram.clear(); // removes all lines, keeps it spawned if it is
+```
+
+Replacing all lines:
+
+```java
+hologram.setLines(List.of(
+  new CaramelHologramLine(Component.text("Replaced"))
+));
+```
+
+Retrieving lines:
+
+```java
+List<CaramelHologramLine> lines = hologram.getLines();
+```
+
+---
+
+<br/><br/>
+
+## Line spacing
+
+Line spacing is controlled via `lineHeight`.
+
+```java
+hologram.setLineHeight(0.25);
+double spacing = hologram.getLineHeight();
+```
+
+Values are in **world units (blocks)**, not pixels.
+Typical values range from `0.22` to `0.30`.
+
+---
+
+<br/><br/>
+
+## Showing and hiding
+
+Once configured, the hologram can be shown or hidden without despawning:
+
+```java
+hologram.show();
+hologram.hide();
+```
+
+* `show()` spawns the hologram if needed and makes it visible
+* `hide()` visually hides it without removing entities
+
+---
+
+<br/><br/>
+
+## Updating holograms
+
+If line content or formatting changes, call `update()` to reapply settings:
+
+```java
+hologram.update();
+```
+
+This reapplies all `CaramelHologramLine` settings to their backing `TextDisplay` entities.
+
+---
+
+<br/><br/>
+
+## Destroying holograms
+
+To fully remove the hologram and clean up entities:
+
+```java
+hologram.destroy();
+```
+
+This removes all spawned `TextDisplay` entities and clears internal state.
+
+---
+
+<br/><br/>
+
+## Accessing entities
+
+If you need direct access to the underlying displays:
+
+```java
+List<TextDisplay> entities = hologram.getEntities();
+```
+
+This can be useful for advanced effects or debugging.
+
+---
+
+<br/><br/>
+
+## Summary
+
+Typical usage flow:
+
+```java
+CaramelHologram hologram = new CaramelHologram();
+hologram.setLocation(location);
+
+hologram.addLine(new CaramelHologramLine(Component.text("Line 1")));
+hologram.addLine(new CaramelHologramLine(Component.text("Line 2")));
+
+hologram.setLineHeight(0.25);
+hologram.show();
+```
+
+That’s all you need for clean, stable holograms.
+
+```

docs/index.md

@@ -9,7 +9,7 @@ Caramel is a multipurpose AIO api for PaperAPI plugins. ***Caramel can not and w
 ![Not for Forge](https://cdn.jsdelivr.net/npm/@intergrav/devins-badges@3/assets/cozy/unsupported/forge_vector.svg)
 
 ## Quickstart
-- Simply drop in the latest Caramel jarfile from [here](https://github.com/klashdevelopment/Caramel/releases/tag/latest-1.21)
+- Simply drop in the latest Caramel jarfile from [Releases](https://github.com/klashdevelopment/Caramel/releases)
 
 ## Quickstart (Developer)
 - Make sure you have Paper API 1.21.11 in your pom
@@ -24,7 +24,7 @@ Caramel is a multipurpose AIO api for PaperAPI plugins. ***Caramel can not and w
 <dependency>
    <groupId>dev.klash</groupId>
    <artifactId>Caramel</artifactId>
-   <version>1.4.6</version>
+   <version>1.4.7</version>
    <scope>provided</scope>
 </dependency>
 ```
@@ -41,7 +41,8 @@ Caramel has a few main features.
 - [Commands](https://pages.klash.dev/Caramel/commands)
 - [Items](https://pages.klash.dev/Caramel/items) (WIP Docs)
 - [Guis](https://pages.klash.dev/Caramel/guis)
+- [Holograms](https://pages.klash.dev/Caramel/holos)
 - [Currencies](https://pages.klash.dev/Caramel/currencies)
 - [Recipes](https://pages.klash.dev/Caramel/recipes)
 - [YAML Configs](https://pages.klash.dev/Caramel/configs)
-- [SQL Configs](https://pages.klash.dev/Caramel/sql)
+- [SQL Databases](https://pages.klash.dev/Caramel/sql)

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>dev.klash</groupId>
     <artifactId>Caramel</artifactId>
-    <version>1.4.6</version>
+    <version>1.4.7 </version>
     <packaging>jar</packaging>
 
     <name>Caramel</name>

src/main/java/dev/klash/caramel/Caramel.java

@@ -3,6 +3,7 @@
 import com.samjakob.spigui.SpiGUI;
 import dev.klash.caramel.commands.CaramelCommand;
 import dev.klash.caramel.gui.CaramelGuiList;
+import dev.klash.caramel.hologram.CaramelHologram;
 import dev.klash.caramel.plugin.ImplCaramelDefault;
 import dev.klash.caramel.recipe.CaramelRecipe;
 import dev.klash.caramel.recipe.CaramelRecipeList;
@@ -11,6 +12,7 @@
 import org.bukkit.command.Command;
 import org.bukkit.command.CommandSender;
 import org.bukkit.entity.Player;
+import org.bukkit.entity.TextDisplay;
 import org.bukkit.plugin.java.JavaPlugin;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -56,6 +58,11 @@ public void onEnable() {
         currencies.register(new ImplCaramelDefault.CaramelBaseDefaultCurrency());
     }
 
+    @Override
+    public void onDisable() {
+        ImplCaramelDefault.demoHolos.forEach(CaramelHologram::destroy);
+    }
+
     public CaramelRecipeList createRecipeList(CaramelRecipe... recipes) {
         CaramelRecipeList recipeList = new CaramelRecipeList();
         for(CaramelRecipe recipe : recipes) {

src/main/java/dev/klash/caramel/CaramelListening.java

@@ -22,7 +22,7 @@ public void onItemClick(PlayerInteractEvent event) {
                         if(gui.finalCheck.apply(event.getPlayer())) {
                             event.setCancelled(true);
                             event.getPlayer().closeInventory();
-                            Bukkit.getScheduler().scheduleSyncDelayedTask(Caramel.getInstance(), () -> gui.open(event.getPlayer()), 1L);
+                            Bukkit.getRegionScheduler().runDelayed(Caramel.getInstance(), event.getPlayer().getLocation(), (st) -> gui.open(event.getPlayer()), 1L);
                         }
                     }
                 }

src/main/java/dev/klash/caramel/CaramelUtility.java

@@ -14,11 +14,14 @@
 import net.kyori.adventure.text.format.TextDecoration;
 import net.kyori.adventure.text.minimessage.MiniMessage;
 import org.apache.logging.log4j.util.TriConsumer;
+import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
+import org.bukkit.Location;
 import org.bukkit.Material;
 import org.bukkit.entity.Player;
 import org.bukkit.event.inventory.InventoryClickEvent;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.plugin.java.JavaPlugin;
 
 import java.util.ArrayList;
 import java.util.Arrays;