EN 11 Teleport Safety and Preloading

11 Teleport Safety and Preloading

中文版本 | English version

This page explains how teleporting.preloadEnabled, teleporting.defaultSafetyCheck, and <disableSafetyCheck> interact.

Three Safety Paths

There are three different safety paths:

• Known-target teleports: home, sharedhome, warp, back, worldspawn.
• Nearby random teleport: rtp.
• Long-range exploration teleport: wild.

They do not use the same rule set.

Known-target safety searches for a better landing point near the target. RTP checks standable candidates in a nearby random range. Wild loads distant candidate chunks in batches and checks surface positions only. RTP and Wild are not affected by teleporting.defaultSafetyCheck or target preloading.

When Known-Target Safety Runs

Known-target safety requires both:

• This teleport request has safety enabled.
• teleporting.preloadEnabled=true.

Safety enabled is resolved as follows:

• If <disableSafetyCheck> is omitted, use teleporting.defaultSafetyCheck.
• If <disableSafetyCheck>true is passed, skip safety search.
• If <disableSafetyCheck>false is passed, request safety search.

So if preloadEnabled=false, known-target teleports do not perform nearby safe-landing search even when defaultSafetyCheck=true.

Why Safety Depends on Preloading

Known-target safety may read blocks around the target area. Checking only the target chunk is not sufficient because the search area may cross neighboring chunk boundaries.

To avoid concurrent safety checks reading non-preloaded areas and triggering extra chunk loading that may cause deadlock, this safety path only runs when target preloading is enabled. When preloadEnabled=false, safe-landing search for home, sharedhome, warp, back, and worldspawn does not run.

Recommended Configurations

Lightweight default:

"teleporting": {
  "preloadEnabled": false,
  "defaultSafetyCheck": false
}

Known-target teleports use the original target directly, keeping main-thread cost predictable.

Safer known-target landing behavior:

/tpc config teleporting preload true
/tpc config teleporting defaultSafetyCheck true

With this setup, home, sharedhome, warp, back, and worldspawn try to find nearby safe landing points by default.

What <disableSafetyCheck> Means

<disableSafetyCheck> only affects known-target teleports. It does not affect RTP or Wild.

Example:

/warp market true

This skips known-target safe-landing search for market.

/warp market false

This requests known-target safety search for this teleport. If preloadEnabled=false, the search still does not run.

RTP Is Independent

RTP always uses its own random-destination safety logic. It searches for a valid destination inside the configured range and fails if none is found, instead of using known-target safety behavior.

Wild Is Independent

Wild manages its own chunk tickets, asynchronous chunk loading, and surface safety validation. Each operation submits a bounded number of batches and candidates, then teleports only after a valid surface destination is ready. It does not read RTP radii and does not use teleporting.preloadEnabled or preloadRadiusChunks.