Refactor visualizer state management and enhance concurrency handling

[twisti-dev]

This pull request introduces several new features and improvements to the Bukkit API, focusing on thread safety, visualizer enhancements, and packet handling robustness. The most significant changes are the addition of the TickThreadGuard API for tick thread safety, enhancements to the SurfVisualizer interface, and improved concurrency and error handling in utility and packet listener code.

Thread Safety and Concurrency Improvements:

• Introduced the TickThreadGuard API, including its interface, implementation, and service loader integration, to ensure operations are executed on the correct server tick thread. This includes multiple overloads for different world, entity, and region types. (TickThreadGuard.kt, TickThreadGuardImpl.kt, API file updates) [1] [2] [3]
• Refactored computeHighestYBlock to use ConcurrentHashMap and LongOpenHashSet for thread-safe chunk snapshot collection and improved concurrency control with a semaphore, limiting chunk loads to prevent server overload. (bukkit-util.kt)

Visualizer API Enhancements:

• Extended the SurfVisualizer interface to implement AutoCloseable, added close() and isClosed() methods, and introduced a new viewerUuids property (with viewers now deprecated). (SurfVisualizer.kt, API file updates) [1] [2] [3] [4]
• Updated the SurfVisualizerArea interface to use the correct @Unmodifiable annotation for cornerLocations. (SurfVisualizerArea.kt)

Packet Handling Robustness:

• Changed default behavior in NMS packet listeners to return PacketListenerResult.CONTINUE instead of throwing exceptions when a player is not available, improving resilience during early connection phases. (NmsClientboundPacketListener.java, NmsServerboundPacketListener.java) [1] [2]
• Enhanced error logging in SurfBukkitNmsBridgeImpl to include more context about failed packet handling. (SurfBukkitNmsBridgeImpl.kt) [1] [2]
• Allowed the ListenerResultConverter to accept nullable results for improved flexibility. (SurfBukkitPacketListenerApiImpl.kt)

General Improvements:

• Changed Caffeine cache configuration for visualizers to use weakValues() instead of softValues() and introduced a playerToVisualizers map for better memory management and tracking. (SurfBukkitVisualizerApiImpl.kt)
• Bumped the project version to 1.21.11-2.70.0. (gradle.properties)

These changes collectively strengthen the API's thread safety, usability, and reliability, especially for plugin developers working with region operations and visualizers.

---

Download Build‑JARs for this PR: pr-built-jars.zip

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 857e29b4fc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Refactors Bukkit visualizer state management to be more thread-safe and lifecycle-aware (closeable), introduces a tick-thread guard service API, and improves robustness in packet listener handling and concurrent utility code.

Changes:

• Added TickThreadGuard API + ServiceLoader-backed implementation for validating tick-thread/region ownership.
• Refactored visualizer internals to track viewer UUIDs, support close()/isClosed(), and improve concurrency handling across visualizer implementations.
• Improved utility and packet-listener behavior for concurrency/resilience (async chunk snapshot collection, early packet handling defaults, richer error logs).

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/collection/TransformingSet2ObjectSet.kt	Adds a new transforming adapter to expose a Set as a fastutil ObjectSet.
surf-api-core/surf-api-core-api/api/surf-api-core-api.api	Updates core API surface to include TransformingSet2ObjectSet.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/nms/nms-extensions.kt	Adjusts Bukkit→NMS entity handle access (handleRaw).
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/visualizer/visualizer/SurfVisualizerSingleLocationImpl.kt	Adds closed-state checks + Cleaner-based cleanup and migrates viewer handling to UUIDs.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/visualizer/visualizer/SurfVisualizerMultipleLocationsImpl.kt	Major refactor: locking, per-viewer sent-state tracking, Cleaner cleanup, and tick-thread enforcement on chunk callbacks.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/visualizer/visualizer/SurfVisualizerAreaImpl.kt	Refactors area recomputation scheduling to use a conflated channel + dedicated scope; adds close/stop behavior.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/visualizer/visualizer/AbstractSurfVisualizerImpl.kt	Introduces viewerUuids, atomic visualizing/closed flags, versioning, and a new close lifecycle.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/visualizer/SurfBukkitVisualizerApiImpl.kt	Switches caches to weak values and adds player↔visualizer index for faster event dispatch.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/region/TickThreadGuardImpl.kt	Implements TickThreadGuard using Moonrise/Paper tick-thread checks and ServiceLoader registration.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/packet/listener/SurfBukkitPacketListenerApiImpl.kt	Allows nullable listener results via ListenerResultConverter.
surf-api-bukkit/surf-api-bukkit-server/src/main/kotlin/dev/slne/surf/surfapi/bukkit/server/impl/nms/SurfBukkitNmsBridgeImpl.kt	Improves error logs with packet/listener context.
surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/visualizer/visualizer/SurfVisualizerArea.kt	Corrects cornerLocations annotation to @Unmodifiable.
surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/visualizer/visualizer/SurfVisualizer.kt	Extends API with AutoCloseable, viewerUuids, and isClosed().
surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/util/bukkit-util.kt	Refactors computeHighestYBlock for safer concurrent chunk snapshot collection with throttling.
surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/region/TickThreadGuard.kt	Adds public API interface + required-service accessor for tick-thread guarding.
surf-api-bukkit/surf-api-bukkit-api/src/main/java/dev/slne/surf/surfapi/bukkit/api/nms/listener/NmsServerboundPacketListener.java	Changes default early-packet behavior to CONTINUE instead of throwing.
surf-api-bukkit/surf-api-bukkit-api/src/main/java/dev/slne/surf/surfapi/bukkit/api/nms/listener/NmsClientboundPacketListener.java	Changes default early-packet behavior to CONTINUE instead of throwing.
surf-api-bukkit/surf-api-bukkit-api/api/surf-api-bukkit-api.api	Updates Bukkit API surface to include TickThreadGuard and updated SurfVisualizer signatures.
gradle.properties	Bumps project version to 1.21.11-2.70.0.

[Copilot]

@twisti-dev I've opened a new pull request, #258, to work on those changes. Once the pull request is ready, I'll request review from you.