BetterWaystones

BetterWaystones (version 1.2.15) is an enterprise-grade waystone teleportation infrastructure engineered for Paper, Folia, Velocity, and BungeeCord networks under package namespace com.itskua.betterwaystones. The plugin decouples waystone data models, virtual block rendering, condition evaluation pipelines, economy services, and cross-server routing into dedicated, independent subsystems.

Performance Benchmarks

Technical Specifications

System Architecture and Subsystems

The plugin operates across modular layers to prevent single points of failure and main-thread stalls:

BetterWaystonesPlugin (lifecycle, scheduler wiring, late-hook injection)
└── WaystoneManager (central in-memory registry, chunk lookup maps, player sessions)
    ├── WaystoneStorage (storage routing)
    │   ├── FileWaystoneStorage (partitioned YAML per world/chunk)
    │   └── MySQLWaystoneStorage (asynchronous HikariCP connection pool)
    ├── DataHandler (binary and byte-level serialization for waystones and player data)
    ├── WaystoneData (waystone entity state, permissions, block components, warmup)
    │   └── Component* (furniture, block display, and custom model components)
    ├── condition/Condition (pluggable access, permission, cost, and visibility pipeline)
    ├── economy/ (Cost, CostList, and multi-currency EconomyService)
    ├── gui/GUIManager (dynamic inventory menus, pagination, and transitions)
    ├── protocol/ (ProtocolLib virtual packet displays with JOML Vector3fc/Quaternionfc)
    ├── structure/ (world-generation structure placement with serialVersionUID templates)
    ├── task/ (warmup counters, damage/movement cancellation, and destination safety)
    ├── hook/ (WorldGuard, Lands, BlueMap, Dynmap, Nexo, ItemsAdder, ModelEngine, PAPI)
    └── proxy/ProxyWaystoneBridge (binary cluster messaging over Velocity and BungeeCord)

How It Works

1. Placement and Registration Lifecycle

When a player places a waystone block or structure:

• listener/WaystoneListener intercepts the block placement event.
• WaystoneManager instantiates a new WaystoneData object assigned an immutable UUID.
• Block components, model archetypes (configured in waystone_types/*.yml), and custom furniture bounds are associated with the location coordinates.
• The state is written asynchronously to the persistence layer via WaystoneStorage (writeWaystoneData), preventing any disk I/O on the server tick thread.

2. Virtual Packet Display Engine

BetterWaystones avoids spawning real entity objects in the world, which would otherwise incur pathfinding and physics overhead. Instead:

• ProtocolLib packet builders construct virtual client-side display entities (BlockDisplay, TextDisplay, ItemDisplay).
• Display packets are streamed only to players within the configured view distance (Waystone Hologram View Distance).
• In Minecraft 26.2/26.3, NMS entity serializers require JOML read-only interfaces (Vector3fc and Quaternionfc). The packet pipeline handles these interfaces with fallback to concrete classes, resolving packet serialization errors.
• Dynamic per-player state swapping: when an unactivated waystone is right-clicked, the packet engine sends a metadata update transforming the visual pillar material (for example, andesite to emerald or netherite) exclusively for that player without affecting other viewers.

3. Interactive GUI and AnvilGUI Text Processing

• Interacting with an activated waystone opens the main directory menu managed by GUIManager.
• Custom player input (such as renaming waystones, entering password codes, searching directory entries, and managing access lists) is powered by an in-tree shaded AnvilGUI (1.10.13-SNAPSHOT).
• Employs Wrapper26_R1 to interface with the modern Minecraft Menu API on Paper 26.x.
• Fully compatible with Geyser and Bedrock clients: AnvilGUI captures server-side NMS rename text forwarded from Bedrock dialog packets.

4. Gating, Conditions, and Economy Pipeline

Before executing a teleportation request:

• The Condition pipeline evaluates permission nodes (such as betterwaystones.activate.<n>, betterwaystones.vip, or betterwaystones.admin), regional claim permissions (WorldGuard / Lands), and proximity limits.
• Travel costs are calculated dynamically via 3D Euclidean geometry: $$\text{Distance} = \sqrt{(x_2 - x_1)^2 + (y_2 - y_1)^2 + (z_2 - z_1)^2}$$
• Dimension multipliers are applied for inter-world transfers (Overworld, Nether, and The End).
• The economy/ subsystem supports multi-currency settlement via Vault, Treasury, custom item ingredients, and player experience points.

5. Teleportation Warmup and Destination Safety

• Teleport requests initialize an asynchronous warmup task (task/warmup/).
• Movements beyond configured thresholds or incoming player damage cancel the warmup sequence unless the player holds the bypass permission (betterwaystones.skip.warmup).
• task/safety/ verifies destination blocks: detects air cavities, safe floor structures, and liquid hazards, auto-correcting target coordinates to prevent suffocation or void falls.

6. Zero-Latency Proxy Synchronization

For multi-server networks:

• ProxyWaystoneBridge connects Paper instances through BetterWaystonesVelocity and BetterWaystonesBungeeCord.
• Eliminates database polling by using lightweight plugin messaging channels.
• When a waystone is registered or unlocked on Server A, a binary packet is broadcasted across the proxy network to all downstream Paper servers. Remote instances update their in-memory discovery registries in under 1 millisecond.

7. Concurrency and Folia Regional Threading

• Supports four configurable scheduler models in config.yml: NativeScheduler, BukkitScheduler, AsyncBukkitScheduler, and SyncBukkitScheduler.
• Prevents thread exhaustion on shared CPU environments.
• On Folia servers, tasks are routed through regional schedulers to respect chunk-thread boundaries and prevent global thread locks.

Core Features

• Multi-Platform Support: Native operation across Paper 26.2/26.3, Folia, Velocity, and BungeeCord.
• Component-Driven Visuals: Supports custom block components, display entities, furniture models, and particle animations.
• Pluggable Conditions: Dynamic rule definitions controlling access restrictions, activation requirements, and VIP bypasses.
• Natural World Generation: Automatically spawns structures in overworld, nether, and end biomes using pre-compiled .bin templates.
• Warpstones and Waypoints: Handheld portable warpstones with durability/cooldown counters and player-owned personal waypoints.
• Broad Hook Registry: Native bindings for WorldGuard, Lands, BlueMap, Dynmap, ItemsAdder, Nexo, MythicMobs, ModelEngine, and PlaceholderAPI.

Technical FAQ

How does cross-server synchronization operate without SQL lag?

The plugin uses dedicated plugin messaging channels between Paper and the proxy (Velocity-Plugin / BungeeCord). When waystone state changes, a compact binary packet synchronizes in-memory caches across all connected nodes in sub-millisecond time.

Does teleport calculation impact main-thread TPS?

No. All distance math, condition parsing, database queries, and permission lookups execute asynchronously on worker threads. The main server thread is touched only for the final location transform.

How does the display engine avoid entity lag?

ProtocolLib packet entities are strictly virtual client-side packets. The server never instantiates ticking entities in the world, keeping tick overhead at zero.