Raise item labels and add GitHub build

Author: Arbousier1

.github/workflows/build.yml

@@ -0,0 +1,42 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Java 25 build
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Java 25
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "25"
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Run checks and build production jar
+        run: ./gradlew clean check shadowJar --no-daemon --no-build-cache --rerun-tasks
+
+      - name: Upload production jar
+        if: success()
+        uses: actions/upload-artifact@v4
+        with:
+          name: InteractionVisualizer-${{ github.sha }}
+          path: build/libs/InteractionVisualizer-*.jar
+          if-no-files-found: error
+          retention-days: 14

common/src/main/java/com/loohp/interactionvisualizer/entities/DroppedItemDisplay.java

@@ -32,6 +32,7 @@
 import net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer;
 import org.bukkit.Bukkit;
 import org.bukkit.Color;
+import org.bukkit.Location;
 import org.bukkit.Material;
 import org.bukkit.NamespacedKey;
 import org.bukkit.World;
@@ -51,6 +52,9 @@
 import org.bukkit.inventory.meta.Damageable;
 import org.bukkit.inventory.meta.ItemMeta;
 import org.bukkit.persistence.PersistentDataType;
+import org.bukkit.util.Transformation;
+import org.joml.Quaternionf;
+import org.joml.Vector3f;
 
 import java.util.HashMap;
 import java.util.HashSet;
@@ -79,6 +83,7 @@ public final class DroppedItemDisplay extends VisualizerRunnableDisplay implemen
     private String mediumColor = "";
     private String lowColor = "";
     private int cramp = 6;
+    private double labelYOffset = 0.8D;
     private int updateRate = 20;
     private int ticksUntilUpdate;
     private int despawnTicks = 6000;
@@ -98,6 +103,9 @@ public void onReload(InteractionVisualizerReloadEvent event) {
         mediumColor = configString("Entities.Item.Options.Color.Medium");
         lowColor = configString("Entities.Item.Options.Color.Low");
         cramp = InteractionVisualizer.plugin.getConfiguration().getInt("Entities.Item.Options.Cramping");
+        double configuredLabelYOffset = InteractionVisualizer.plugin.getConfiguration()
+                .getDouble("Entities.Item.Options.LabelYOffset");
+        labelYOffset = Double.isFinite(configuredLabelYOffset) ? configuredLabelYOffset : 0.8D;
         updateRate = Math.max(1, InteractionVisualizer.plugin.getConfiguration().getInt("Entities.Item.Options.UpdateRate"));
         int configuredDespawnTicks = InteractionVisualizer.plugin.getConfiguration().getInt("Entities.Item.Options.DespawnTicks");
         despawnTicks = configuredDespawnTicks > 0 ? configuredDespawnTicks : 6000;
@@ -229,14 +237,10 @@ private void update(Item item) {
             label.text(text);
         }
         boolean mounted = item.equals(label.getVehicle()) || item.addPassenger(label);
-        if (created) {
-            // Mount before revealing the label so Paper can pair both entities
-            // with their passenger relationship in the initial tracking bundle.
-            showToEligibleViewers(label);
-        }
         if (mounted) {
             // A mounted display follows the item on every client render frame.
             // Text refreshes stay low-frequency without sampling item positions.
+            setLabelVerticalTranslation(label, mountedLabelTranslation(labelYOffset, item.getHeight()));
             if (label.getInterpolationDuration() != 0) {
                 label.setInterpolationDuration(0);
             }
@@ -246,16 +250,22 @@ private void update(Item item) {
         } else {
             // Preserve a safe fallback if another plugin cancels the mount or
             // changes either entity during the update.
+            setLabelVerticalTranslation(label, 0.0F);
             int transitionTicks = Math.min(59, updateRate);
             if (label.getTeleportDuration() != transitionTicks) {
                 label.setTeleportDuration(transitionTicks);
             }
-            label.teleport(item.getLocation().add(0.0, item.getHeight() * 1.7, 0.0));
+            label.teleport(labelLocation(item));
+        }
+        if (created) {
+            // Mount and configure the final render height before revealing the
+            // label so the first tracking bundle cannot flash at item height.
+            showToEligibleViewers(label);
         }
     }
 
     private TextDisplay spawnLabel(Item item) {
-        return item.getWorld().spawn(item.getLocation().add(0.0, item.getHeight() * 1.7, 0.0),
+        return item.getWorld().spawn(labelLocation(item),
                 TextDisplay.class, display -> {
                     display.setPersistent(false);
                     display.setVisibleByDefault(false);
@@ -277,6 +287,27 @@ private TextDisplay spawnLabel(Item item) {
                 });
     }
 
+    private Location labelLocation(Item item) {
+        return item.getLocation().add(0.0, labelYOffset, 0.0);
+    }
+
+    static float mountedLabelTranslation(double yOffset, double itemHeight) {
+        return (float) (yOffset - itemHeight);
+    }
+
+    private static void setLabelVerticalTranslation(TextDisplay label, float targetY) {
+        Transformation current = label.getTransformation();
+        Vector3f translation = current.getTranslation();
+        if (Math.abs(translation.y - targetY) <= 1.0E-4F) {
+            return;
+        }
+        label.setTransformation(new Transformation(
+                new Vector3f(translation.x, targetY, translation.z),
+                new Quaternionf(current.getLeftRotation()),
+                new Vector3f(current.getScale()),
+                new Quaternionf(current.getRightRotation())));
+    }
+
     private void reconcileEligibleViewers() {
         Map<UUID, Player> desired = new HashMap<>();
         for (Player player : InteractionVisualizerAPI.getPlayerModuleList(Modules.HOLOGRAM, KEY)) {

common/src/main/resources/config.yml

@@ -273,6 +273,8 @@ Entities:
       RegularFormat: "{Item} &bx{Amount} &6[{Timer}&6]"
       SingularFormat: "{Item} &6[{Timer}&6]"
       ToolsFormat: "{Item} &6[{Durability}&6]"
+      #Vertical distance from the dropped item entity origin to its text label
+      LabelYOffset: 0.8
       #Hide if there is more than this defined amount of item entities in one block
       Cramping: 6
       #How often the item display updates

common/src/test/java/com/loohp/interactionvisualizer/config/SparrowConfigurationTest.java

@@ -105,4 +105,17 @@ void preservesDotsInImmediateSectionKeys() throws Exception {
                 Map.of("myplugin:life.steal", "Life Steal", "myplugin:frost", "Frost"),
                 configuration.getConfigurationSection("enchantments").getValues(false));
     }
+
+    @Test
+    void defaultConfigKeepsDroppedItemLabelsAboveTheItem() throws Exception {
+        Path file = temporaryDirectory.resolve("plugin-config.yml");
+        Files.writeString(file, "", StandardCharsets.UTF_8);
+
+        SparrowConfiguration configuration = new SparrowConfiguration(
+                file.toFile(),
+                SparrowConfigurationTest.class.getClassLoader().getResourceAsStream("config.yml"),
+                false);
+
+        assertEquals(0.8D, configuration.getDouble("Entities.Item.Options.LabelYOffset"));
+    }
 }

common/src/test/java/com/loohp/interactionvisualizer/entities/DroppedItemDisplayPositionTest.java

@@ -0,0 +1,24 @@
+/*
+ * This file is part of InteractionVisualizer.
+ *
+ * Copyright (C) 2026. Contributors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ */
+
+package com.loohp.interactionvisualizer.entities;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class DroppedItemDisplayPositionTest {
+
+    @Test
+    void compensatesForTheItemsPassengerAttachmentHeight() {
+        assertEquals(0.55F, DroppedItemDisplay.mountedLabelTranslation(0.8D, 0.25D), 1.0E-6F);
+    }
+}