Use Sparrow virtual items for item visuals

Author: Arbousier1

README.md

@@ -17,10 +17,19 @@ outside the supported range.
 
 ## Rewrite highlights
 
-- Native Paper `ItemDisplay` and `TextDisplay` entities replace Armor Stands and
-  raw metadata packets.
-- One Paper API implementation replaces the old per-version NMS modules.
-- Per-viewer visibility uses Paper's `showEntity` / `hideEntity` API.
+- Native Paper `ItemDisplay` and `TextDisplay` entities replace Armor Stands.
+- Dropped-item visuals use shaded
+  [Sparrow Heart](https://github.com/Xiao-MoMi/sparrow-heart) client-side vanilla
+  `ITEM` entities. Empty Paper display anchors retain tracker and chunk lifecycle
+  without enabling server item collision physics.
+- One Paper API implementation replaces the old in-project per-version NMS modules.
+  InteractionVisualizer uses Heart 0.72 only for the client-side item packet path
+  on the supported 26.1/26.2 runtimes.
+- Per-viewer anchor visibility uses Paper's `showEntity` / `hideEntity` API;
+  tracker enter/leave events create and destroy the matching virtual `ITEM`.
+- Static items bob and spin entirely client-side with no animation task; only
+  active gravity motion needs per-viewer correction because Heart marks its
+  fake items as no-gravity.
 - Display updates are revision-coalesced; there is no 5 ms packet scan loop.
 - Player/chunk proximity queries use one allocation-light snapshot per world and
   server tick.
@@ -30,9 +39,8 @@ outside the supported range.
 - Gradle replaces the former Maven multi-module build and verifies the same
   sources against both supported Paper API lines.
 
-The other Sparrow modules were deliberately not added: metadata, reflection,
-NBT, heart, and Redis messaging either duplicate Paper 26 APIs, reintroduce
-version/NMS coupling, or do not serve this single-server rendering path.
+Other Sparrow modules were deliberately not added: metadata, reflection, NBT,
+and Redis messaging do not serve this single-server rendering path.
 
 ## Building
 

abstraction/src/main/java/com/loohp/interactionvisualizer/entityholders/Item.java

@@ -20,7 +20,10 @@
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.util.Vector;
 
-/** Logical state for a real, non-persistent Paper item entity. */
+/**
+ * Logical state for a client-side vanilla item visual.
+ * Velocity and gravity are animation inputs; no server item physics is enabled.
+ */
 public class Item extends VisualizerEntity {
 
     private ItemStack item;
@@ -117,6 +120,7 @@ public Vector getVelocity() {
 
     public void setVelocity(Vector velocity) {
         Vector normalized = velocity == null ? new Vector() : velocity.clone();
+        normalized.checkFinite();
         if (!this.velocity.equals(normalized)) {
             this.velocity = normalized;
             markDirty();

build.gradle.kts

@@ -13,6 +13,7 @@ val pluginVersion = version.toString()
 val paper26_1Version = "26.1.2.build.74-stable"
 val paper26_2Version = "26.2.build.56-alpha"
 val craftEngineVersion = "26.7.2"
+val sparrowHeartVersion = "0.72"
 
 val paper26_2CompileClasspath = configurations.create("paper26_2CompileClasspath") {
     isCanBeConsumed = false
@@ -35,6 +36,7 @@ dependencies {
     compileOnly(files("common/lib/LightAPI-fork-3.5.2.jar"))
 
     implementation("net.momirealms:sparrow-yaml:1.0.7")
+    implementation("net.momirealms:sparrow-heart:$sparrowHeartVersion")
 
     testImplementation(platform("org.junit:junit-bom:5.13.4"))
     testImplementation("org.junit.jupiter:junit-jupiter")
@@ -113,7 +115,7 @@ val compilePaper26_2 = tasks.register<JavaCompile>("compilePaper26_2") {
 }
 
 val verifyPaperOnlyArchitecture = tasks.register("verifyPaperOnlyArchitecture") {
-    description = "Rejects reintroduction of NMS, Armor Stands, or legacy compatibility layers."
+    description = "Rejects direct in-project NMS, Armor Stands, or legacy compatibility layers."
     group = LifecycleBasePlugin.VERIFICATION_GROUP
     val sources = sourceSets.main.get().allJava
     inputs.files(sources)
@@ -194,6 +196,7 @@ tasks.named<ShadowJar>("shadowJar") {
     mergeServiceFiles()
 
     relocate("net.momirealms.sparrow.yaml", "com.loohp.interactionvisualizer.libs.sparrow.yaml")
+    relocate("net.momirealms.sparrow.heart", "com.loohp.interactionvisualizer.libs.sparrow.heart")
 
     isPreserveFileTimestamps = false
     isReproducibleFileOrder = true
@@ -208,6 +211,26 @@ tasks.named<ShadowJar>("shadowJar") {
                 "CraftEngine must remain compileOnly, but provider classes were bundled:\n" +
                     bundledCraftEngine.joinToString("\n")
             }
+            check(jar.getEntry("com/loohp/interactionvisualizer/libs/sparrow/heart/SparrowHeart.class") != null) {
+                "The shaded Sparrow Heart runtime is missing"
+            }
+            listOf("r26_1", "r26_2").forEach { adapter ->
+                check(jar.getEntry(
+                    "com/loohp/interactionvisualizer/libs/sparrow/heart/impl/$adapter/Heart.class",
+                ) != null) {
+                    "The shaded Sparrow Heart $adapter adapter is missing"
+                }
+            }
+            val unrelocatedHeart = jar.entries().asSequence()
+                .map { it.name }
+                .filter { it.startsWith("net/momirealms/sparrow/heart/") }
+                .toList()
+            check(unrelocatedHeart.isEmpty()) {
+                "Unrelocated Sparrow Heart classes were bundled:\n" + unrelocatedHeart.joinToString("\n")
+            }
+            check(jar.getEntry("META-INF/licenses/sparrow-heart.txt") != null) {
+                "The Sparrow Heart MIT license notice is missing"
+            }
         }
     }
 }