Gate dropped label visibility optimizations

Arbousier1 · Arbousier1 · commit e25627ee44f3 · 2026-07-14T10:13:55.000+08:00
diff --git a/common/src/main/java/com/loohp/interactionvisualizer/entities/DroppedItemDisplay.java b/common/src/main/java/com/loohp/interactionvisualizer/entities/DroppedItemDisplay.java
diff --git a/common/src/main/java/com/loohp/interactionvisualizer/entities/DroppedItemVisibilityPolicy.java b/common/src/main/java/com/loohp/interactionvisualizer/entities/DroppedItemVisibilityPolicy.java
@@ -0,0 +1,79 @@
+/*
+ * 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;
+
+/**
+ * Validated configuration for the opt-in dropped-item visibility controls.
+ * Disabled culling preserves the legacy server-side label lifecycle;
+ * rate limiting is independently opt-in.
+ */
+record DroppedItemVisibilityPolicy(
+        int viewDistance,
+        boolean rateLimitEnabled,
+        int bucketSize,
+        int restorePerTick
+) {
+
+    static final int DEFAULT_BUCKET_SIZE = 128;
+    static final int DEFAULT_RESTORE_PER_TICK = 32;
+    static final int DEFAULT_VIEW_DISTANCE = 64;
+    private static final int MIN_VIEW_DISTANCE = 8;
+    private static final int MAX_VIEW_DISTANCE = 512;
+
+    static DroppedItemVisibilityPolicy create(boolean cullingEnabled,
+                                              int configuredViewDistance,
+                                              boolean rateLimitEnabled,
+                                              int configuredBucketSize,
+                                              int configuredRestorePerTick) {
+        int requestedViewDistance = configuredViewDistance > 0
+                ? configuredViewDistance
+                : DEFAULT_VIEW_DISTANCE;
+        int viewDistance = cullingEnabled
+                ? Math.max(MIN_VIEW_DISTANCE, Math.min(MAX_VIEW_DISTANCE, requestedViewDistance))
+                : 0;
+        int bucketSize = configuredBucketSize > 0
+                ? configuredBucketSize
+                : DEFAULT_BUCKET_SIZE;
+        int restorePerTick = configuredRestorePerTick > 0
+                ? configuredRestorePerTick
+                : DEFAULT_RESTORE_PER_TICK;
+        return new DroppedItemVisibilityPolicy(
+                viewDistance, rateLimitEnabled, bucketSize, restorePerTick);
+    }
+
+    static DroppedItemVisibilityPolicy legacyDefaults() {
+        return create(false, DEFAULT_VIEW_DISTANCE, false,
+                DEFAULT_BUCKET_SIZE, DEFAULT_RESTORE_PER_TICK);
+    }
+
+    boolean cullingEnabled() {
+        return viewDistance > 0;
+    }
+
+    boolean controlsPerViewerVisibility() {
+        return cullingEnabled() || rateLimitEnabled;
+    }
+
+    int effectiveViewDistance(int trackingDistance) {
+        if (!cullingEnabled()) {
+            throw new IllegalStateException("View-distance culling is disabled");
+        }
+        return Math.min(viewDistance, Math.max(1, trackingDistance));
+    }
+
+    float labelViewRange() {
+        if (!cullingEnabled()) {
+            return 1.0F;
+        }
+        return (float) Math.max(0.125D, Math.min(8.0D, viewDistance / 64.0D));
+    }
+}
diff --git a/common/src/main/java/com/loohp/interactionvisualizer/entities/VisibilityTokenBucket.java b/common/src/main/java/com/loohp/interactionvisualizer/entities/VisibilityTokenBucket.java
@@ -41,7 +41,9 @@ void cancel(T value) {
     }
 
     List<T> drain(int capacity, int refill, Predicate<T> stillWanted) {
-        tokens = Math.min(Math.max(1, capacity), tokens + Math.max(0, refill));
+        int safeCapacity = Math.max(1, capacity);
+        long replenished = (long) tokens + Math.max(0, refill);
+        tokens = (int) Math.min(safeCapacity, replenished);
         if (tokens == 0 || pending.isEmpty()) {
             return List.of();
         }
@@ -58,6 +60,21 @@ List<T> drain(int capacity, int refill, Predicate<T> stillWanted) {
         return ready;
     }
 
+    List<T> drainAll(Predicate<T> stillWanted) {
+        if (pending.isEmpty()) {
+            return List.of();
+        }
+
+        List<T> ready = new ArrayList<>(pending.size());
+        while (!pending.isEmpty()) {
+            T value = pending.removeFirst();
+            if (queued.remove(value) && stillWanted.test(value)) {
+                ready.add(value);
+            }
+        }
+        return ready;
+    }
+
     void clear() {
         pending.clear();
         queued.clear();
diff --git a/common/src/main/java/com/loohp/interactionvisualizer/managers/PerformanceMetrics.java b/common/src/main/java/com/loohp/interactionvisualizer/managers/PerformanceMetrics.java
@@ -45,6 +45,9 @@ public final class PerformanceMetrics implements Listener {
     private boolean configVisibilityRateLimit;
     private int configVisibilityBucketSize;
     private int configVisibilityRestorePerTick;
+    private DroppedLabelVisibilityConfig droppedLabelVisibilityConfig =
+            new DroppedLabelVisibilityConfig(false, 64, false, 128, 32);
+    private DroppedLabelVisibilityConfig configDroppedLabelVisibility = droppedLabelVisibilityConfig;
     private boolean configEventDrivenBlockUpdates;
     private int configBlockUpdateMaxDirtyPerTick;
     private long startedNanos;
@@ -82,6 +85,15 @@ public static boolean isCollecting() {
         return INSTANCE.collecting;
     }
 
+    public static void droppedLabelVisibilityConfig(boolean cullingEnabled,
+                                                     int viewDistance,
+                                                     boolean rateLimitEnabled,
+                                                     int bucketSize,
+                                                     int restorePerTick) {
+        INSTANCE.droppedLabelVisibilityConfig = new DroppedLabelVisibilityConfig(
+                cullingEnabled, viewDistance, rateLimitEnabled, bucketSize, restorePerTick);
+    }
+
     public static boolean start(String requestedLabel) {
         if (INSTANCE.collecting) {
             return false;
@@ -92,6 +104,7 @@ public static boolean start(String requestedLabel) {
         INSTANCE.configVisibilityRateLimit = InteractionVisualizer.visibilityRateLimiting;
         INSTANCE.configVisibilityBucketSize = InteractionVisualizer.visibilityRateLimitBucketSize;
         INSTANCE.configVisibilityRestorePerTick = InteractionVisualizer.visibilityRateLimitRestorePerTick;
+        INSTANCE.configDroppedLabelVisibility = INSTANCE.droppedLabelVisibilityConfig;
         INSTANCE.configEventDrivenBlockUpdates = InteractionVisualizer.eventDrivenBlockUpdates;
         INSTANCE.configBlockUpdateMaxDirtyPerTick = InteractionVisualizer.blockUpdateMaxDirtyPerTick;
         INSTANCE.startedNanos = System.nanoTime();
@@ -287,7 +300,8 @@ private Snapshot createSnapshot(LegacyTextComponentCache.CacheMetrics textCache)
         mean = samples == 0 ? 0.0D : mean / samples;
         long elapsedNanos = Math.max(1L, System.nanoTime() - startedNanos);
         return new Snapshot(label, configStaticAnchor, configPacketOnlyStatic, configVisibilityRateLimit,
-                configVisibilityBucketSize, configVisibilityRestorePerTick, configEventDrivenBlockUpdates,
+                configVisibilityBucketSize, configVisibilityRestorePerTick, configDroppedLabelVisibility,
+                configEventDrivenBlockUpdates,
                 configBlockUpdateMaxDirtyPerTick, LegacyTextComponentCache.isEnabled(),
                 elapsedNanos, samples, tickSamplesDropped,
                 percentile(sorted, 0.50D), percentile(sorted, 0.95D), percentile(sorted, 0.99D),
@@ -319,13 +333,22 @@ private static String sanitizeLabel(String value) {
         return sanitized.substring(0, Math.min(48, sanitized.length()));
     }
 
+    public record DroppedLabelVisibilityConfig(
+            boolean cullingEnabled,
+            int viewDistance,
+            boolean rateLimitEnabled,
+            int bucketSize,
+            int restorePerTick) {
+    }
+
     public record Snapshot(
             String label,
             boolean staticAnchorDuringAnimation,
             boolean packetOnlyStatic,
             boolean visibilityRateLimit,
             int visibilityBucketSize,
             int visibilityRestorePerTick,
+            DroppedLabelVisibilityConfig droppedLabelVisibility,
             boolean eventDrivenBlockUpdates,
             int blockUpdateMaxDirtyPerTick,
             boolean legacyTextComponentCache,
@@ -407,6 +430,10 @@ public String json() {
                     "{\"label\":\"%s\",\"staticAnchorDuringAnimation\":%b," +
                             "\"packetOnlyStatic\":%b,\"visibilityRateLimit\":%b," +
                             "\"visibilityBucketSize\":%d,\"visibilityRestorePerTick\":%d," +
+                            "\"droppedLabelVisibilityCulling\":%b,\"droppedLabelViewDistance\":%d," +
+                            "\"droppedLabelVisibilityRateLimit\":%b," +
+                            "\"droppedLabelVisibilityBucketSize\":%d," +
+                            "\"droppedLabelVisibilityRestorePerTick\":%d," +
                             "\"eventDrivenBlockUpdates\":%b,\"blockUpdateMaxDirtyPerTick\":%d," +
                             "\"legacyTextComponentCache\":%b," +
                             "\"seconds\":%.3f,\"tickSamples\":%d,\"observedTps\":%.6f," +
@@ -430,7 +457,10 @@ public String json() {
                             "\"legacyTextCacheHits\":%d,\"legacyTextCacheHitRate\":%.6f," +
                             "\"legacyTextSameRawFastPaths\":%d}",
                     label, staticAnchorDuringAnimation, packetOnlyStatic, visibilityRateLimit,
-                    visibilityBucketSize, visibilityRestorePerTick, eventDrivenBlockUpdates,
+                    visibilityBucketSize, visibilityRestorePerTick,
+                    droppedLabelVisibility.cullingEnabled(), droppedLabelVisibility.viewDistance(),
+                    droppedLabelVisibility.rateLimitEnabled(), droppedLabelVisibility.bucketSize(),
+                    droppedLabelVisibility.restorePerTick(), eventDrivenBlockUpdates,
                     blockUpdateMaxDirtyPerTick, legacyTextComponentCache,
                     seconds(), tickSamples, observedTps(), droppedTickSamples,
                     msptP50, msptP95, msptP99,
diff --git a/common/src/main/resources/config.yml b/common/src/main/resources/config.yml
@@ -281,11 +281,15 @@ Entities:
       #This is in ticks (20 ticks = 1 second)
       #Setting this too low might impact performance
       UpdateRate: 20
-      #Maximum distance in blocks at which a dropped-item label is kept active
-      #Labels outside every eligible player's range are not spawned server-side
-      ViewDistance: 64
-      #Smooth label visibility bursts when entering areas with many dropped items
+      #Experimental server-side distance culling for dropped-item labels
+      VisibilityCulling:
+        #Preserves the legacy label lifecycle unless explicitly enabled after validation
+        Enabled: false
+        ViewDistance: 64
+      #Experimental smoothing for label visibility bursts
       VisibilityRateLimit:
+        #Independent from Settings.Performance.VisibilityRateLimit and disabled by default
+        Enabled: false
         BucketSize: 128
         RestorePerTick: 32
       #Paper does not expose its internal per-item despawn rate. This value
diff --git a/common/src/test/java/com/loohp/interactionvisualizer/entities/DroppedItemVisibilityPolicyTest.java b/common/src/test/java/com/loohp/interactionvisualizer/entities/DroppedItemVisibilityPolicyTest.java
@@ -0,0 +1,83 @@
+/*
+ * 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 java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class DroppedItemVisibilityPolicyTest {
+
+    @Test
+    void disabledCullingAndLimiterPreserveLegacyVisibility() {
+        DroppedItemVisibilityPolicy policy = DroppedItemVisibilityPolicy.create(false, 64, false, 128, 32);
+
+        assertFalse(policy.cullingEnabled());
+        assertFalse(policy.rateLimitEnabled());
+        assertFalse(policy.controlsPerViewerVisibility());
+        assertEquals(1.0F, policy.labelViewRange());
+    }
+
+    @Test
+    void eachExperimentalControlCanEnablePerViewerVisibility() {
+        DroppedItemVisibilityPolicy culling = DroppedItemVisibilityPolicy.create(true, 64, false, 128, 32);
+        DroppedItemVisibilityPolicy limiting = DroppedItemVisibilityPolicy.create(false, 64, true, 128, 32);
+
+        assertTrue(culling.controlsPerViewerVisibility());
+        assertTrue(limiting.controlsPerViewerVisibility());
+        assertEquals(64, culling.effectiveViewDistance(96));
+        assertEquals(48, culling.effectiveViewDistance(48));
+    }
+
+    @Test
+    void clampsDistanceAndRepairsInvalidBucketValues() {
+        DroppedItemVisibilityPolicy minimum = DroppedItemVisibilityPolicy.create(true, 1, true, 0, -1);
+        DroppedItemVisibilityPolicy maximum = DroppedItemVisibilityPolicy.create(true, 4096, true, 512, 64);
+        DroppedItemVisibilityPolicy repaired = DroppedItemVisibilityPolicy.create(true, 0, false, 128, 32);
+
+        assertEquals(8, minimum.viewDistance());
+        assertEquals(DroppedItemVisibilityPolicy.DEFAULT_BUCKET_SIZE, minimum.bucketSize());
+        assertEquals(DroppedItemVisibilityPolicy.DEFAULT_RESTORE_PER_TICK, minimum.restorePerTick());
+        assertEquals(512, maximum.viewDistance());
+        assertEquals(8.0F, maximum.labelViewRange());
+        assertEquals(DroppedItemVisibilityPolicy.DEFAULT_VIEW_DISTANCE, repaired.viewDistance());
+    }
+
+    @Test
+    void bundledConfigurationKeepsBothControlsDisabled() throws IOException {
+        try (InputStream stream = getClass().getClassLoader().getResourceAsStream("config.yml")) {
+            assertNotNull(stream);
+            String config = new String(stream.readAllBytes(), StandardCharsets.UTF_8)
+                    .replace("\r\n", "\n");
+            int itemOptions = config.indexOf("  Item:\n");
+            int villager = config.indexOf("  Villager:\n", itemOptions);
+            String droppedItemOptions = config.substring(itemOptions, villager);
+
+            assertTrue(droppedItemOptions.contains(
+                    "      VisibilityCulling:\n"
+                            + "        #Preserves the legacy label lifecycle unless explicitly enabled after validation\n"
+                            + "        Enabled: false\n"
+                            + "        ViewDistance: 64\n"));
+            assertTrue(droppedItemOptions.contains(
+                    "      VisibilityRateLimit:\n"
+                            + "        #Independent from Settings.Performance.VisibilityRateLimit and disabled by default\n"
+                            + "        Enabled: false\n"));
+        }
+    }
+}
diff --git a/common/src/test/java/com/loohp/interactionvisualizer/entities/VisibilityTokenBucketTest.java b/common/src/test/java/com/loohp/interactionvisualizer/entities/VisibilityTokenBucketTest.java
@@ -43,4 +43,24 @@ void deduplicatesAndDropsCancelledOrStaleRequests() {
 
         assertEquals(List.of(1), bucket.drain(4, 0, value -> value != 3));
     }
+
+    @Test
+    void drainsImmediatelyWhenRateLimitingIsDisabled() {
+        VisibilityTokenBucket<Integer> bucket = new VisibilityTokenBucket<>(0);
+        bucket.request(1);
+        bucket.request(2);
+        bucket.request(3);
+        bucket.cancel(2);
+
+        assertEquals(List.of(1, 3), bucket.drainAll(ignored -> true));
+        assertEquals(List.of(), bucket.drainAll(ignored -> true));
+    }
+
+    @Test
+    void largeConfiguredLimitsDoNotOverflowTokenRefill() {
+        VisibilityTokenBucket<Integer> bucket = new VisibilityTokenBucket<>(Integer.MAX_VALUE);
+        bucket.request(1);
+
+        assertEquals(List.of(1), bucket.drain(Integer.MAX_VALUE, Integer.MAX_VALUE, ignored -> true));
+    }
 }
diff --git a/common/src/test/java/com/loohp/interactionvisualizer/managers/PerformanceMetricsSlowestTickTest.java b/common/src/test/java/com/loohp/interactionvisualizer/managers/PerformanceMetricsSlowestTickTest.java
@@ -76,7 +76,9 @@ void resetRestoresNoSampleSentinel() {
     @Test
     void snapshotJsonPublishesSlowestTickAttributionInMilliseconds() {
         PerformanceMetrics.Snapshot snapshot = new PerformanceMetrics.Snapshot(
-                "diagnostic", false, false, false, 128, 32, true, 64, true,
+                "diagnostic", false, false, false, 128, 32,
+                new PerformanceMetrics.DroppedLabelVisibilityConfig(true, 64, true, 128, 32),
+                true, 64, true,
                 1_000_000_000L, 20, 0L,
                 1.0D, 2.0D, 3.0D, 4.0D, 50.25D,
                 4242, 1_783_951_200_123L, 7L, 12_345_678L,
@@ -93,6 +95,11 @@ void snapshotJsonPublishesSlowestTickAttributionInMilliseconds() {
         assertTrue(json.contains("\"msptMaxEndEpochMillis\":1783951200123"));
         assertTrue(json.contains("\"msptMaxBlockUpdateChecks\":7"));
         assertTrue(json.contains("\"msptMaxBlockUpdateMs\":12.345678"));
+        assertTrue(json.contains("\"droppedLabelVisibilityCulling\":true"));
+        assertTrue(json.contains("\"droppedLabelViewDistance\":64"));
+        assertTrue(json.contains("\"droppedLabelVisibilityRateLimit\":true"));
+        assertTrue(json.contains("\"droppedLabelVisibilityBucketSize\":128"));
+        assertTrue(json.contains("\"droppedLabelVisibilityRestorePerTick\":32"));
         assertTrue(json.contains("\"legacyTextCacheHits\":95"));
         assertTrue(json.contains("\"legacyTextCacheHitRate\":0.950000"));
         assertTrue(json.contains("\"legacyTextSameRawFastPaths\":200"));
diff --git a/docs/evidence/b93d990-frameview-manifest.csv b/docs/evidence/b93d990-frameview-manifest.csv
@@ -0,0 +1,20 @@
+kind,group,run,filename,bytes,sha256
+frame_csv,frameview-factor-fixed-b1-true,1,FvSDKPerFrameStreamDataT202671422749.csv,6306563,d4320664ec2af8c203661c489a312715c45ab237fc75a3029dbd54914ef4a60b
+frame_csv,frameview-factor-fixed-b1-true,2,FvSDKPerFrameStreamDataT20267142280.csv,6720934,bc4a57880fd4b27aa3a38127285d49dabec660e14cd5fdb654d9b96057781e47
+frame_csv,frameview-factor-fixed-b1-true,3,FvSDKPerFrameStreamDataT202671422811.csv,6330701,f16dfd8ccae2677e684305efca6f4116e7b4b0526029e018a75d27867578c228
+frame_csv,frameview-factor-fixed-b1-true,4,FvSDKPerFrameStreamDataT202671422856.csv,6510632,90e2a0d973f0d8bc6c90362201f610ff42a65001d1d9b4cd246266aab76ac7cc
+frame_csv,frameview-factor-fixed-b1-true,5,FvSDKPerFrameStreamDataT20267142296.csv,6346557,ab8281084fbd67329252ce96dee8ea6c7aa613fba1e0711edd6708b3449beb42
+frame_csv,frameview-factor-fixed-b1-true,6,FvSDKPerFrameStreamDataT202671422917.csv,6448228,a4417984976612dc07100198e6eead419327260b770cd3436dbd0eb34ed1999a
+frame_csv,frameview-factor-fixed-a-false,1,FvSDKPerFrameStreamDataT202671423030.csv,5738113,a393cabfe2ea96a47bb5aad5f326758e3f9cb99a0ebfa98a19b40931a51c8455
+frame_csv,frameview-factor-fixed-a-false,2,FvSDKPerFrameStreamDataT202671423041.csv,5901362,32ffcb234ef262cdd70cc140b1b035e47c375faebdb7a3fd438b8788be431a4b
+frame_csv,frameview-factor-fixed-a-false,3,FvSDKPerFrameStreamDataT202671423052.csv,4896593,d2d3a1d033420096cc33275494ede656c4d090ffc6c437ad9bf52187fbbb69a2
+frame_csv,frameview-factor-fixed-a-false,4,FvSDKPerFrameStreamDataT202671423129.csv,5837042,9cb1cf1fd6eff142667be94056c8eff344ef51b75deef80628af51c7b674eec5
+frame_csv,frameview-factor-fixed-a-false,5,FvSDKPerFrameStreamDataT202671423140.csv,5829160,dfdfcce44636e62f95bf8b125fcb4c69f30ebd64c432e4f4c9276aacf52bc969
+frame_csv,frameview-factor-fixed-a-false,6,FvSDKPerFrameStreamDataT202671423151.csv,5952325,8460fb70fc46cae9c3e97e0ea601d16192e4ef44836b2c2874cf6c0acbb6a2e3
+frame_csv,frameview-factor-fixed-b2-true,1,FvSDKPerFrameStreamDataT202671423312.csv,6485056,b28d8a55d3fab5e17bc09fadf763e27f017b143cf4f2902b76fe285e33d48625
+frame_csv,frameview-factor-fixed-b2-true,2,FvSDKPerFrameStreamDataT202671423323.csv,6607308,e194516293101015ebc3eed0e95ff0afb7f1fd9956e2fbfe26690bc78dfb7487
+frame_csv,frameview-factor-fixed-b2-true,3,FvSDKPerFrameStreamDataT202671423333.csv,5771658,1a8a162135fa3a60de76bfc734c5154cec4024479c50284fe9d09a2c0a2c5925
+frame_csv,frameview-factor-fixed-b2-true,4,FvSDKPerFrameStreamDataT202671423414.csv,6661103,41e8c16f65488b7a95293f99adb59a7bfc7c88300152b3c37d66d7885075288b
+frame_csv,frameview-factor-fixed-b2-true,5,FvSDKPerFrameStreamDataT202671423425.csv,6624424,ee9488513fbf428c3bfa7e577700c8c4b594ba51d31832c24328f29fdb1e343a
+frame_csv,frameview-factor-fixed-b2-true,6,FvSDKPerFrameStreamDataT202671423436.csv,6548953,40a1672b2e0ab5d5bdfd448a51a79f1cd19229da89f199d54a97f599709b298e
+analysis_db,frameview-factor-fixed-summary,,performance-validation.sqlite,28672,6f7799fb095c0ad3fff2e4da3b2006cd470631df081f9df4abf863a054d48bcc
diff --git a/docs/phase2-evidence-b93d990.md b/docs/phase2-evidence-b93d990.md
diff --git a/docs/phase2-performance-validation.md b/docs/phase2-performance-validation.md
