EN 12 Performance and Concurrency

12 Performance and Concurrency

中文版本 | English version

This page explains how the current version behaves under high teleport load. It is not a tuning manual, but it helps administrators understand which settings affect server cost.

Basic Principle

Minecraft server world logic is centered around the main thread. This mod moves suitable work off the main thread where practical, but actual teleport execution, key world-state access, and player-facing result delivery still need to respect Minecraft threading rules.

The performance goal is not “make everything async”. It is:

• Smooth out bursty teleport load.
• Avoid unnecessary chunk loading.
• Handle high-concurrency RTP separately.
• Load long-range Wild candidates in bounded global batches.
• Bound shared-home broadcast delivery per tick.
• Keep extra logs disabled by default.

Known-Target Teleports

home, sharedhome, warp, back, and worldspawn are known-target teleports.

They share delay, cooldown, pending-operation management, and batching. When many players trigger teleports at once, work is batched instead of being fully processed in one tick.

If target safety checks are enabled, they read blocks around the target area, so they only run when target preloading is enabled. By default, both target preloading and default target safety checks are disabled.

RTP

RTP has different performance characteristics from known-target teleports. It needs to search for a random safe destination, so most cost comes from candidate generation and safety checks.

Current RTP handling chooses a suitable path based on request volume:

• Normal load is processed in controlled batches.
• Large ready backlogs use parallel workers for safe-position search.

RTP uses its own safety logic and is not affected by known-target defaultSafetyCheck or target preloading.

Wild

Wild's main cost is preparing distant chunks rather than scanning many candidates in already-loaded terrain. To prevent one player or a burst of requests from concentrating too much chunk work in one tick, Wild splits each search into bounded batches and limits how many ready batches are processed per tick.

Each batch samples a small number of chunks and checks a fixed number of random surface columns in each chunk. Wild owns its chunk tickets, incomplete loads, and cancellation state; resources are cleaned when the player disconnects, changes dimension, cancels, or the server stops. Increasing Wild radius changes how far candidate chunks may be, but does not increase batches or candidates per operation.

Shared Homes

Shared-home publication and subscription state is lightweight in-memory data. Publication messages are not sent to an unlimited number of online players in one tick; a bounded queue spreads delivery over ticks and drops stale work. Re-broadcasting the same publication is coalesced with its existing pending item.

TPA

TPA requests are relatively lightweight. Once accepted, execution follows accepted-request order and still respects shared delay/cooldown rules where applicable.

Expired TPA requests do not require manual cleanup; they are cleaned automatically.

Preload Radius

teleporting.preloadRadiusChunks controls target preload radius and is limited to 0 through 3. A larger radius means more target chunks may be held for one teleport.

Recommendations:

• Small servers can usually keep the default.
• Enable preloading only when smoother landing around destinations is needed.
• Avoid unnecessarily large preload radius values.

Debug Logs

debugEnabled=false is the default. Extra debug logs are intended for troubleshooting and should not be left on permanently.

Enable while debugging:

/tpc debug true

Disable after debugging:

/tpc debug false

Admin Checklist

If teleport spikes create server pressure, check:

1. Whether target preloading is enabled.
2. Whether preloadRadiusChunks is too large.
3. Whether default target safety checks are enabled.
4. Whether RTP radius is too small, making valid destinations rare.
5. Whether Wild is repeatedly targeting many distant, not-yet-generated chunks.
6. Whether shared-home broadcast cooldown is set too low.
7. Whether debug logs were left enabled.