11 Teleport Safety and Preloading

11 传送安全检查与预加载

中文版本 | English version

这一页集中说明 teleporting.preloadEnabled、teleporting.defaultSafetyCheck 和 <disableSafetyCheck> 之间的关系。

三类传送安全逻辑

当前有三类不同的安全逻辑：

• 已知目标传送：home、sharedhome、warp、back、worldspawn。
• 近距离随机传送：rtp。
• 长距离探索传送：wild。

它们不是同一套规则。

已知目标传送的安全检查是在目标点附近寻找更合适的落点。RTP 在玩家附近的随机范围内检查可站立位置。Wild 则分批加载远处候选区块，只检查地表候选。RTP 与 Wild 都不受 teleporting.defaultSafetyCheck 或目标预加载开关影响。

已知目标传送什么时候做安全检查

已知目标传送要执行安全检查，需要同时满足：

• 本次传送的 safety enabled 为 true。
• teleporting.preloadEnabled=true。

其中 safety enabled 的来源是：

• 命令没有传入 <disableSafetyCheck> 时，使用 teleporting.defaultSafetyCheck。
• 命令传入 <disableSafetyCheck>true 时，跳过安全检查。
• 命令传入 <disableSafetyCheck>false 时，请求执行安全检查。

因此，如果 preloadEnabled=false，即使 defaultSafetyCheck=true，已知目标传送也不会执行安全落点搜索。

为什么安全检查依赖预加载

已知目标传送的安全检查可能读取目标点附近一片区域的方块信息。只检查目标区块是否已加载并不够，因为搜索范围可能跨到相邻区块。

为了避免并发安全检查读取未预加载区域并触发额外区块加载导致死锁，当前设计要求目标预加载开启后才执行这类安全搜索。preloadEnabled=false 时，home、sharedhome、warp、back、worldspawn 的安全落点搜索不会执行。

推荐配置

轻量默认配置：

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

这种模式下，已知目标传送直接使用原目标点，主线程负担更可控。

更偏安全落点的配置：

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

这种模式下，home、sharedhome、warp、back、worldspawn 会默认尝试寻找附近安全落点。

<disableSafetyCheck> 的含义

<disableSafetyCheck> 只影响已知目标传送，不影响 RTP 或 Wild。

例如：

/warp market true

表示传送到 market 时跳过目标安全落点搜索。

/warp market false

表示本次传送请求启用目标安全落点搜索；但如果 preloadEnabled=false，仍然不会实际执行搜索。

RTP 的独立逻辑

RTP 始终使用自己的随机落点安全检查。它会在配置范围内尝试寻找合适落点，失败时返回失败结果，而不是套用已知目标传送的安全搜索规则。

Wild 的独立逻辑

Wild 使用自己管理的区块 ticket、异步区块加载和地表安全判断。每次操作只提交有限批次和候选，找到安全地表位置后再执行传送。它不读取 rtp 半径，也不使用 teleporting.preloadEnabled 或 preloadRadiusChunks。