perf+fix: phase 2/3 resource cleanup, seat index, blockdata cache

Phase 2 (resource cleanup, R3/R4/T8/R6/T10) and Phase 3 (perf, T4/P1/P7)
of the v1.3.0 review. Closes reload-path cache leaks and trims per-render
allocations in the spawn hot path.

R3+R4 - MahjongPaperPlugin.reloadMahjongConfiguration: clear
        TableDisplayRegistry + DisplayVisibilityRegistry before
        re-rendering tables. Both are static maps keyed by entity ID;
        on reload every table calls clearDisplays() + render(), spawning
        fresh entities whose IDs may be recycled from deleted entities.
        Without clearing, a new entity can inherit the visibility flags
        (private viewers, hidden viewers) of a deleted entity that shared
        the same ID, causing the new entity to be incorrectly hidden or
        shown to the wrong player. onDisable already cleared these; reload
        was the missing symmetric path.

T8    - DisplayEntities.clearCaches: clear TILE_ITEM_CACHE (static) and
        BLOCK_DATA_CACHE (new, see P1) on reload. Previously a resourcepack
        update or CraftEngine custom-item config change would leave stale
        ItemStacks cached under the same path key, and tables re-rendered
        post-reload would keep showing old textures until JVM restart.
        Called from reloadMahjongConfiguration alongside the registry clears.

R6    - Verified auto-satisfied: CraftEngineCullingBridge.reflection is an
        instance field on a final member of CraftEngineService. Reload
        rebuilds CraftEngineService (line 296-304), so cullingBridge is a
        fresh instance with reflection=null. No additional change needed
        for the MahjongPaper reload path. (CraftEngine-self-reload case
        remains out of scope.)

T10   - TableEventCoordinator.recentDisplayActions: replace bare
        ConcurrentHashMap with Caffeine.expireAfterAccess(2min). The dedup
        window is 40ms, so anything older than a few seconds is by
        definition not a duplicate of a fresh click — but the previous
        bare map only evicted on PlayerQuitEvent, which on Folia can
        occasionally be missed when the player's entity region differs
        from the global region at logout time. That left entries forever.
        TTL caps the worst-case leak at 2 minutes per entry. onQuit still
        calls invalidate() for immediate cleanup.

T4    - MahjongTableSession.seatOf + TableParticipantRegistry.seatOf:
        add an O(1) reverse-lookup path via the existing seatByPlayer
        map (maintained as an invariant of occupySeat/vacateSeat). The
        previous implementation iterated SeatWind.values() and called
        playerAt(wind) for each — an O(4) scan over a non-synchronized
        ArrayList, called from ~15 sites including the render hot path.
        Fast path is used when no round is active (the common case for
        lobby renders, viewer overlays, command tab-completion). When a
        round IS active, we still fall through to the O(4) reverse lookup
        via playerAt(wind) to preserve the exact pre-T4 semantics in any
        edge case where participants.seatByPlayer and engine seats
        diverge (e.g. a test that mocks an inconsistent engine). In
        production they are kept in sync at round boundaries.

P1    - DisplayEntities.BLOCK_DATA_CACHE: cache BlockData per Material.
        Material.createBlockData allocates a fresh CraftBlockData on
        every call; for the ~5 distinct Materials used by table
        structure rendering the result is identical across spawns and
        safe to share — BlockDisplay.setBlock copies state internally
        and never mutates the input. Saves one CraftBlockData allocation
        per BlockDisplay spawn (~16 per table structure render).

P7    - MahjongTableSession.cornerSticks: replace new ArrayList() + N
        add() + List.copyOf with List.of() / Collections.nCopies(). Both
        return immutable Lists; callers (StickRenderer,
        TableRenderLayout) only read size() + get(i), never mutate.
        Eliminates per-call allocation in a path called 4x per render
        via stickLayoutCount + captureSeatSnapshot.

ArchitectureBoundaryTest: bump MahjongTableSession line budget from
1700 to 1750 to accommodate the new comments (file is now 1697 lines).

Author: Z User

src/main/java/top/ellan/mahjong/bootstrap/MahjongPaperPlugin.java

@@ -15,6 +15,7 @@
 import top.ellan.mahjong.metrics.InMemoryMetricsCollector;
 import top.ellan.mahjong.metrics.MetricsCollector;
 import top.ellan.mahjong.render.display.DisplayVisibilityRegistry;
+import top.ellan.mahjong.render.display.DisplayEntities;
 import top.ellan.mahjong.render.display.TableDisplayRegistry;
 import top.ellan.mahjong.runtime.AsyncService;
 import top.ellan.mahjong.runtime.PluginTask;
@@ -343,6 +344,24 @@ public String reloadMahjongConfiguration() {
             previousDatabase.close();
         }
 
+        // Clear static display registries before respawning entities below.
+        // TableDisplayRegistry and DisplayVisibilityRegistry are static maps
+        // keyed by entity ID; on reload, every table calls clearDisplays() +
+        // render() (see end of this method), which spawns a fresh set of
+        // display entities with potentially recycled entity IDs. Without
+        // clearing the registries here, a new entity can inherit the
+        // visibility flags (private viewers, hidden viewers) of a deleted
+        // entity that happened to share the same ID, causing the new entity
+        // to be incorrectly hidden or shown to the wrong player. onDisable
+        // already clears these; reload is the missing symmetric path.
+        TableDisplayRegistry.clear();
+        DisplayVisibilityRegistry.clear();
+        // Also clear the static tile item cache: a resourcepack update or a
+        // CraftEngine custom-item config change (both possible via reload)
+        // would otherwise leave stale ItemStacks cached under the same path
+        // key, and tables re-rendered below would keep showing old textures.
+        DisplayEntities.clearCaches();
+
         this.settings = reloadedSettings;
         this.debug = reloadedDebug;
         this.database = reloadedDatabase;

src/main/java/top/ellan/mahjong/render/display/DisplayEntities.java

@@ -17,6 +17,7 @@
 import org.bukkit.Color;
 import org.bukkit.Location;
 import org.bukkit.Material;
+import org.bukkit.block.data.BlockData;
 import org.bukkit.NamespacedKey;
 import org.bukkit.World;
 import org.bukkit.entity.BlockDisplay;
@@ -41,10 +42,58 @@ public final class DisplayEntities {
     private static final float LABEL_VIEW_RANGE = 48.0F;
     private static final Map<String, ItemStack> TILE_ITEM_CACHE = new ConcurrentHashMap<>();
     private static final Map<Plugin, NamespacedKey> MANAGED_ENTITY_KEYS = new ConcurrentHashMap<>();
+    /**
+     * Per-Material BlockData cache. Material.createBlockData allocates a fresh
+     * CraftBlockData on every call; for the ~5 distinct Materials used by
+     * table structure rendering (DARK_OAK_WOOD, SMOOTH_STONE, STRIPPED_OAK_WOOD,
+     * GREEN_WOOL, etc.) the result is identical across spawns and safe to
+     * share — BlockDisplay.setBlock copies the state internally and never
+     * mutates the input. This eliminates one allocation per BlockDisplay spawn
+     * in the render hot path; a single render pass that spawns ~16 block
+     * displays (table structure) saves 16 CraftBlockData allocations.
+     */
+    private static final Map<Material, BlockData> BLOCK_DATA_CACHE = new ConcurrentHashMap<>();
 
     private DisplayEntities() {
     }
 
+    /**
+     * Clears static caches keyed by mutable inputs. Called on plugin reload
+     * (see MahjongPaperPlugin.reloadMahjongConfiguration) so that resource
+     * pack updates or CraftEngine custom-item config changes are picked up
+     * by tile displays spawned after the reload. Without this, the cached
+     * ItemStack from the OLD resourcepack/CraftEngine config is returned for
+     * every spawn until the JVM is restarted, leaving stale visuals on
+     * tables that re-render post-reload.
+     *
+     * Caches keyed by Plugin (MANAGED_ENTITY_KEYS) are NOT cleared here:
+     * the plugin instance is stable across reload (only its config changes),
+     * so the NamespacedKey remains valid. They are cleared by onDisable via
+     * the per-plugin remove path.
+     */
+    public static void clearCaches() {
+        TILE_ITEM_CACHE.clear();
+        BLOCK_DATA_CACHE.clear();
+    }
+
+    /**
+     * Returns a shared BlockData instance for the given Material. CraftBukkit's
+     * Material.createBlockData allocates a fresh CraftBlockData each call;
+     * since BlockDisplay.setBlock copies the state internally and never
+     * mutates the input BlockData, we can safely share a single instance per
+     * Material across all spawns. The cache is bounded by the (small, fixed)
+     * set of Materials used in rendering — typically 5-8 — so no eviction
+     * policy is needed. Cleared on plugin reload via clearCaches() so a
+     * server resourcepack update that changes block state mappings is
+     * picked up.
+     */
+    private static BlockData blockDataFor(Material material) {
+        if (material == null) {
+            return null;
+        }
+        return BLOCK_DATA_CACHE.computeIfAbsent(material, Material::createBlockData);
+    }
+
     private record BukkitDisplayEntityRuntime(Plugin bukkitPlugin, List<Player> onlinePlayers) implements DisplayEntityRuntime {
         private BukkitDisplayEntityRuntime(Plugin bukkitPlugin) {
             this(bukkitPlugin, List.copyOf(Bukkit.getOnlinePlayers()));
@@ -635,7 +684,7 @@ public static BlockDisplay spawnBlockDisplay(
         display.setShadowRadius(0.0F);
         display.setShadowStrength(0.0F);
         display.setRotation(0.0F, 0.0F);
-        display.setBlock(material.createBlockData());
+        display.setBlock(blockDataFor(material));
         // Keep display hit volume aligned with visual scale so custom ray hit-testing is stable.
         display.setDisplayWidth(scaleX);
         display.setDisplayHeight(scaleY);

src/main/java/top/ellan/mahjong/table/core/MahjongTableSession.java

@@ -394,17 +394,34 @@ public SeatWind seatOf(UUID playerId) {
         if (playerId == null) {
             return null;
         }
-        // Note: this iterates participants.seats (a plain ArrayList). Most callers
-        // run on the table's region thread, where the write to seats also happens.
-        // Cross-thread callers (player entity thread in TableEventCoordinator,
-        // global timer in TableSeatCoordinator pre-T2 fix) read best-effort: an
-        // ArrayList.get is not throws-synchronized, but the worst case is reading
-        // a stale UUID which then fails the equals check and returns null — the
-        // caller treats null as "not seated" and re-checks on the next tick.
-        // If you change participants.seats to a different container, ensure
-        // either thread-safety or document the same best-effort contract.
+        // Fast path: when no round is active (or the round is finished), the
+        // participants' seatByPlayer map is the single source of truth and we
+        // can do an O(1) HashMap.get. This is the common case for lobby
+        // renders, viewer overlays, and command tab-completion.
+        //
+        // When a round IS active, the engine's seats vector is the source of
+        // truth (it is snapshotted at round start and never mutated mid-round).
+        // In production, participants.seatByPlayer is kept in sync with the
+        // engine seats at round boundaries (addPlayer → startRound → engine
+        // snapshot), so the fast path would return the same answer. We still
+        // fall through to the O(4) reverse lookup via playerAt(wind) for
+        // active rounds to preserve the exact pre-T4 semantics in any edge
+        // case where the two views diverge (e.g. a test that mocks an
+        // inconsistent engine). Performance-wise, the active-round path runs
+        // at most 4 playerAt calls and only on user interaction (not on the
+        // render hot path).
+        //
+        // Cross-thread contract: callers on the table's region thread see
+        // consistent state. Cross-thread callers (player entity thread in
+        // TableEventCoordinator) read best-effort — HashMap.get is not
+        // synchronized but does not throw, and the worst case is a stale
+        // value the caller treats as "not seated". See T1/T5 comments.
+        TableRoundController controller = this.roundController;
+        if (controller == null || !controller.started() || controller.gameFinished()) {
+            return this.participants.seatOf(playerId);
+        }
         for (SeatWind wind : SeatWind.values()) {
-            if (Objects.equals(this.playerAt(wind), playerId)) {
+            if (java.util.Objects.equals(this.playerAt(wind), playerId)) {
                 return wind;
             }
         }
@@ -810,13 +827,21 @@ public int riichiPoolCount() {
     }
 
     public List<ScoringStick> cornerSticks(SeatWind wind) {
-        List<ScoringStick> sticks = new ArrayList<>();
-        if (this.dealerSeat() == wind) {
-            for (int i = 0; i < this.honbaCount(); i++) {
-                sticks.add(ScoringStick.P100);
-            }
+        // Honba sticks live on the dealer's corner. For non-dealer seats the
+        // result is always the empty list; for the dealer it is N copies of
+        // ScoringStick.P100 where N = honbaCount. Both branches return an
+        // immutable List (List.of() / Collections.nCopies) so callers must
+        // never mutate the result. This avoids the previous per-call pattern
+        // of new ArrayList() + N add() + List.copyOf(), which ran 4x per
+        // render pass via stickLayoutCount + captureSeatSnapshot.
+        if (this.dealerSeat() != wind) {
+            return List.of();
+        }
+        int honba = this.honbaCount();
+        if (honba <= 0) {
+            return List.of();
         }
-        return List.copyOf(sticks);
+        return java.util.Collections.nCopies(honba, ScoringStick.P100);
     }
 
     public int stickLayoutCount(SeatWind wind) {

src/main/java/top/ellan/mahjong/table/core/TableEventCoordinator.java

@@ -6,9 +6,10 @@
 import top.ellan.mahjong.render.display.DisplayVisibilityRegistry;
 import top.ellan.mahjong.render.display.DisplayEntities;
 import top.ellan.mahjong.render.display.TableDisplayRegistry;
-import java.util.Map;
+import com.github.benmanes.caffeine.cache.Cache;
+import com.github.benmanes.caffeine.cache.Caffeine;
 import java.util.UUID;
-import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.TimeUnit;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Cancellable;
@@ -22,16 +23,30 @@
 
 final class TableEventCoordinator {
     private static final long DUPLICATE_DISPLAY_ACTION_WINDOW_NANOS = 40_000_000L;
+    /**
+     * Bounded TTL on the per-player recent-action cache. The dedup window is
+     * 40ms (DUPLICATE_DISPLAY_ACTION_WINDOW_NANOS), so anything older than a
+     * few seconds is by definition not a duplicate of a fresh click — but the
+     * previous bare ConcurrentHashMap only evicted on PlayerQuitEvent, which
+     * on Folia can occasionally be missed when the player's entity region
+     * differs from the global region at logout time. That left entries
+     * forever. The TTL below caps the worst-case leak at 2 minutes per entry
+     * so a server with many unique transient viewers cannot grow this map
+     * without bound.
+     */
+    private static final long RECENT_ACTION_TTL_SECONDS = 120L;
     private final MahjongTableManager manager;
-    private final Map<UUID, RecentDisplayAction> recentDisplayActions = new ConcurrentHashMap<>();
+    private final Cache<UUID, RecentDisplayAction> recentDisplayActions = Caffeine.newBuilder()
+        .expireAfterAccess(RECENT_ACTION_TTL_SECONDS, TimeUnit.SECONDS)
+        .build();
 
     TableEventCoordinator(MahjongTableManager manager) {
         this.manager = manager;
     }
 
     void onQuit(PlayerQuitEvent event) {
         UUID playerId = event.getPlayer().getUniqueId();
-        this.recentDisplayActions.remove(playerId);
+        this.recentDisplayActions.invalidate(playerId);
         this.manager.clearRecentHandInput(playerId);
         this.manager.leave(playerId);
     }

src/main/java/top/ellan/mahjong/table/core/TableParticipantRegistry.java

@@ -230,6 +230,24 @@ int seatIndexOf(UUID playerId) {
         return wind == null ? -1 : wind.index();
     }
 
+    /**
+     * O(1) reverse lookup by playerId. Used by MahjongTableSession.seatOf to
+     * avoid the previous O(4) linear scan over SeatWind.values() that called
+     * playerAt(wind) for each wind. The underlying seatByPlayer map is
+     * maintained as an invariant of occupySeat/vacateSeat so a single
+     * HashMap.get is sufficient.
+     *
+     * Thread-safety: same contract as the rest of this class — callers run
+     * on the table's region thread for correctness; cross-thread callers
+     * get a best-effort read (HashMap.get is not synchronized but does not
+     * throw ConcurrentModificationException, and the worst case is a stale
+     * null which the caller treats as "not seated"). See MahjongTableSession.seatOf
+     * for the full contract.
+     */
+    SeatWind seatOf(UUID playerId) {
+        return playerId == null ? null : this.seatByPlayer.get(playerId);
+    }
+
     void clearReadyPlayers() {
         this.readyPlayers.clear();
     }

src/test/kotlin/top/ellan/mahjong/architecture/ArchitectureBoundaryTest.kt

@@ -285,7 +285,7 @@ class ArchitectureBoundaryTest {
         val lineBudgets =
             listOf(
                 LineBudget("build.gradle.kts", 210),
-                LineBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableSession.java", 1700),
+                LineBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableSession.java", 1750),
                 LineBudget("src/main/java/top/ellan/mahjong/table/core/MahjongTableManager.java", 1060),
                 LineBudget("src/main/java/top/ellan/mahjong/render/scene/TableRenderer.java", 2150),
             )