? YuTeleport / YuTP – 跨版本安全传送插件
?️ 安全着陆 | ? 随机传送 | ? 战点 | ? 家 | ? TPA | ? 返回 | ? 坐标共享 | ? Folia 支持
? 担心随机传送会把玩家掉进岩浆、水中、方块内、虚空边缘,或是下界的危险平台上?
? 想要在一个插件中管理资源世界的分散点、公共战点、玩家家园、TPA、/back 以及坐标共享?
? 不想让传统的传送插件在搜索区块时卡顿主线程,也不想分别维护冷却时间、费用、权限和消息提示?
? 不想让多个插件争夺 /warp、/home、/tpa、/back 的控制权,并逐一调试冲突问题?
YuTeleport (YuTP) 是一款适用于 Minecraft Java 服务器的跨版本安全传送套件。
它不仅仅是一个 RTP 工具,而是一个完整的传送系统:包含随机传送、公共战点、玩家家园、基于 TPA 的互相传送、/back 返回、坐标共享、经济集成、权限组、PlaceholderAPI、公共 Java API、Folia/Paper 兼容性——所有功能均通过统一的传送管线处理。
当前版本:2.0.1.2
配置版本:config‑version 20
? 核心特性
- ? 随机传送 (RTP):支持按世界配置半径、高度范围、中心点、方形/圆形分布、方块规则及生物群系过滤。
- ? 战点 (Public Waypoints):支持公共、私有和受限类型;包含描述、重命名、删除、最大数量限制及细粒度权限控制。
- ? 家园 (Player Homes):每位玩家独立保存家园;支持多家园、公共家园、跨玩家访问、描述信息及数量扩展。
- ? TPA (玩家间传送):支持
/tpa、/tpahere、接受、拒绝、取消、忽略请求及全局 tpahere。
- ? 返回 (Return System):记录死亡地点、插件传送前的位置及外部传送原点;支持
/back、/back death、/back list、/back clear。
- ? 坐标共享:成功传送后,玩家可将当前位置分享给所有在线玩家;其他人可点击进行传送。
- ? 统一传送管线:所有处理——等待、中断、冷却、扣除费用、退款、安全检查、事件、状态跟踪及钩子——均统一处理。
- ⚡ 异步安全点搜索:在 Paper 1.13+ 上可使用异步区块加载以减轻主线程压力;在不支持时自动回退到同步模式。
- ? 着陆点预缓存:后台预先准备安全着陆点;命中缓存时,减少在线搜索的等待时间。
- ? 生物群系过滤:支持黑白名单、
* 通配符及单次使用的 biome:<pattern> 指定。
- ? Vault / PlayerPoints 经济:可按传送类型、世界及权限组设置价格;失败、取消或 Folia 回收等场景会自动退款。
- ? 权限组覆盖:使用
yuteleport.group.<group> 为不同组配置不同的冷却时间、费用、战点上限及家园上限。
- ⏳ 多渠道倒计时:聊天栏、BossBar、ActionBar 或静默等待——可自由组合;移动、受伤、交互、聊天及命令中断均可单独切换。
- ? 完整视听反馈:倒计时音效、成功琶音、失败/取消/扣费/退款音效、标题、粒子效果、点击重试及悬停显示坐标。
- ? PlaceholderAPI 扩展:提供模块状态、冷却时间、费用、家园/战点数量、传送统计及返回状态。
- ?? Java API & 事件:外部插件可发起传送、读取模块数据、监听及取消传送生命周期事件。
- ? Folia 调度适配:使用 Region / Entity / Global Schedulers 避免跨区域实体访问问题。
? 设计理念
YuTeleport 的目标不仅仅是“移动玩家”,而是让每一次传送请求都可控、可回滚且可观测——从请求到抵达的全过程。
- 玩家是否有权限?
- 目标世界是否允许?
- 冷却时间是否生效?
- 是否需要等待倒计时?
- 在倒计时期间,玩家是否移动、受伤、聊天或执行了命令?
- 是否需要费用?如何处理等待期间的余额变化?
- 目标点是否安全?目标世界是否仍已加载?
- 失败、取消或实体被回收时,费用是否应退还?
- 第三方插件是否可以监听、取消或读取结果?
- 玩家是否可以返回到死亡地点或传送前的位置?
这些逻辑片段不再分散在多个插件或模块中;它们由统一的传送管线处理。服务器管理员可将其作为生产服务器的基础传送系统使用,而不仅仅是一个临时的分散工具。
? 功能模块
? 随机传送 (RTP)
适用于资源世界、荒野探索、新玩家出生点、活动地图以及需要减少出生点拥挤的服务器。
- 每个世界拥有独立的半径、费用、高度范围、安全规则和搜索策略。
- 可自定义随机中心点,不固定于
(0, 0)。
- 支持按面积分布的方形环或圆形环。
- 世界黑白名单,支持
* 通配符。
- 方块黑白名单——排除岩浆、火焰、仙人掌、甜浆果丛、蜘蛛网等。
- 生物群系黑白名单——例如
*OCEAN*、*FOREST*。
- 支持 Paper 异步区块加载、Folia 区域调度及同步回退。
- 后台安全着陆点预缓存,以减少高频传送的在线搜索开销。
常用命令:
/yuteleport
/ytp
/rtp
/yuteleport biome:*FOREST*
/yuteleport <player>
/yuteleport <player> <world> biome:*PLAINS*
? 战点 (Public Waypoints)
适用于出生点、资源世界入口、活动场地、商业区、副本入口及玩家建造的公共地点。
/setwarp <name> 用于创建或更新传送点。
public(公开)传送点对所有玩家可见且可使用。
private(私有)传送点仅由创建者和管理员管理。
restricted(受限)传送点需要拥有 yuteleport.warps.<name> 权限才能查看和使用。
- 支持描述、重命名、公开/取消公开以及删除功能。
- 默认限制、基于权限的限制,以及通过
groups.<group>.warp.max‑warps 进行扩展。
- 权限过期后超出限制时,传送点将被暂时锁定;重新授予权限即可恢复访问。
- 创建公开传送点、使用公开传送点以及普通传送点的费用可以分别设置。
常用命令:
/warp
/warp <name>
/warp public
/warp public <name> true
/warp rename <old> <new>
/warp desc <name> <description>
/setwarp <name> [restricted|public|private] [description]
/delwarp <name>
? 家园(玩家家园)
适用于生存、养老、RPG、空岛以及需要玩家自行管理返回点的服务器。
/sethome [name] 设置个人家园;默认名称为 home。
/homes 列出您自己的家园。
- 玩家可以使家园公开;其他在线玩家可以查看并传送至这些家园。
- 每个家园都可以添加描述。
- 支持重命名、修改描述、公开/取消公开以及删除功能。
- 管理员可以查看或使用在线玩家的家园。
- 默认家园数量限制、基于权限的限制,以及通过
groups.<group>.home.max‑homes 进行扩展。
- 权限过期后超出的家园将被暂时锁定。
- 可配置禁止设置家园的世界(例如活动世界、挖矿世界)。
- 每位玩家的家园数据保存在单独的文件中;加入服务器时加载,退出服务器时卸载。
常用命令:
/home
/home <name>
/home list
/home public
/home public <name> true
/home rename <old> <new>
/home desc <name> <description>
/home <player>:<name>
/homes
/homes <player>
/sethome [name] [public|private] [description]
/delhome <name>
/delhome <player>:<name>
? TPA(玩家间传送)
适合玩家拜访、团队探索、活动集会以及常规生存服务器。
/tpa <player> – 请求传送到该玩家处。
/tpahere <player> – 请求该玩家传送到你这里。
/tpaccept [player] – 接受请求。
/tpdeny [player] – 拒绝请求。
/tpacancel – 取消你发出的请求。
/tpaignore – 暂时忽略收到的 TPA 请求。
/tpaall 或 /tpahere all – 向所有在线玩家发送 tpahere 请求。
- 请求会自动过期;如果过期请重新发送。
- 新请求会替换你上一次发出的请求,以避免请求堆积。
- 目标玩家会收到可点击的“接受”和“拒绝”按钮。
- 在
tpahere 模式下,被请求者移动,但费用和冷却时间归属于请求者。
常用命令:
/tpa <player>
/tpahere <player>
/tpahere all
/tpaccept [player]
/tpdeny [player]
/tpacancel
/tpaignore
/tpaall
? 返回系统
/back 适用于死亡复活、意外传送后的回退,以及跨插件传送后返回原始位置。
/back – 返回到最近可用的位置。
/back death – 返回到上次死亡的位置。
/back list – 显示返回历史;启用交互式聊天后,点击任意记录即可传送。
/back clear – 清除你自己的返回历史。
- 记录来自内部插件传送前的位置、玩家死亡位置以及外部插件传送前的位置。
- 按距离过滤——移动距离小于阈值(默认 3 格)的位置不会被记录,以防止垃圾信息。
- 可配置最大历史记录数量(默认 5)。
- 可配置过期时间(默认 1800 秒)。
- 持久化存储——返回历史保存至
data/back。
- 独立的预热、冷却、费用、安全救援、世界黑白名单以及挂钩功能。
- 优先级配置——默认优先选择死亡点,其次是插件传送前位置,最后是外部插件传送前位置。
常用命令:
/back
/back death
/back list
/back clear
核心配置:
teleports:
back:
enabled: true
commands:
back: [back]
warmup-seconds: 5
cooldown-seconds: 10
cost: 0.0
safety-rescue: true
max-history: 5
expire-seconds: 1800
persist: true
capture:
plugin-teleports: true
death: true
external-teleports: true
include-types: [random, warp, home, tpa, share, back]
min-distance: 3.0
priority: [death, teleport, external]
? 坐标分享
适合临时集结点、资源发现、活动坐标、团队聚会以及探索分享。
成功传送后,成功消息中可以包含一个“分享当前位置”按钮。点击它会将坐标分享给所有在线玩家,他们可以点击进行传送。
- 分享具有过期时间;过期后自动失效。
- 分享拥有独立的冷却时间。
- 内存中保留的最大活跃分享数量,以防止长期堆积。
- 分享和通过分享进行传送的费用可以分别设置。
- 坐标分享继承或单独配置世界黑白名单。
常用命令:
/yuteleport share
/yuteleport join <share_id>
?️ 安全着陆与救援
YuTeleport 在进行随机传送前会检查以下内容:
- 玩家脚下的方块是否足够坚固?
- 是否有足够的空间容纳玩家的身体和头部?
- 头顶上方的额外空间是否符合配置要求?
- 危险方块:水、熔岩、火、仙人掌、蜘蛛网、岩浆块等。
- 虚空、世界最低/最高高度、世界边界。
- 生物群系黑白名单。
- 在地狱等复杂维度中的垂直候选位置。
这可以降低以下风险:
- 玩家卡在方块或墙壁内。
- 落入熔岩、水下或危险方块中。
- 传送出世界边界或正好落在边界上。
- 落在虚空边缘或悬浮在空中。
- 在地狱随机着陆时没有稳固立足点的平台上。
固定点模块(传送点、家、TPA、分享、返回)默认尊重已存储的坐标,不会强制进行新的随机安全点搜索。如果你担心坐标失效,可以针对该模块启用 safety-rescue(安全救援),在到达后执行卡住救援。
? 世界访问与模块配置
YuTeleport 支持全局默认的世界访问规则,并允许在每个模块中覆盖该规则:
teleports.defaults.world-access
teleports.rtp.world-access
teleports.warp.world-access
teleports.home.world-access
teleports.tpa.world-access
teleports.share.world-access
teleports.back.world-access
世界列表支持 * 通配符:
lobby
resource_*
*_nether
*event*
*
典型用例:
- 主世界:中等半径,低成本,排除海洋。
- 资源世界:超大半径,高成本,启用异步搜索和预缓存。
- 下界:限制高度,增加尝试次数,设置允许方块白名单。
- 事件世界:仅允许特定模块或完全禁止。
- 大厅世界:禁用
/back 或所有玩家发起的传送。
⚡ 异步搜索与预缓存
传统的 RTP 同步加载会在传送期间加载新区块,导致高峰期卡顿。YuTeleport 提供了两种优化方案。
异步安全点搜索
teleports:
rtp:
search-mode: async
在 Paper 1.13+ 及兼容核心上,插件使用异步区块加载来寻找随机落点。如果当前服务器不支持此功能,它将自动回退到同步模式并记录提示。在 Folia 上,插件遵循区域调度模型,不依赖传统的主线程假设。
落点预缓存
teleports:
rtp:
precache:
enabled: true
size: 3
插件可以在后台为每个世界预生成 1–16 个安全落点。当玩家请求随机传送且命中缓存时,将跳过在线搜索阶段——仅执行最终验证和剩余流程。
⏳ 倒计时、中断与反馈
所有传送模块均可使用统一的等待倒计时。
teleports:
defaults:
warmup-seconds: 5
countdown-display: actionbar
cancel-on-move: true
cancel-triggers:
move: true
damage: true
interact: true
chat: true
command: true
显示渠道:
- Chat(聊天栏)
- BossBar(Boss 血条)
- ActionBar(动作栏)
- Silent wait(静默等待)
中断条件:
- Move(移动)
- Damage(受到伤害)
- Interact(交互)
- Chat(聊天)
- Execute command(执行命令)
拥有 yuteleport.bypass.wait 权限的玩家可跳过等待。
拥有 yuteleport.bypass.cooldown 权限的玩家可跳过冷却时间。
拥有 yuteleport.bypass.cost 权限的玩家可跳过费用。
? 经济系统
economy:
enabled: true
provider: vault # vault or playerpoints
功能特性:
- Vault 货币经济支持。
- PlayerPoints 货币经济支持。
- RTP 按世界定价。
- Warp / Home / TPA / Share / Back 按模块定价。
- 权限组费用覆盖。
- 余额不足通知。
- 等待结束后进行第二次余额检查。
- 失败、取消或 Folia 回收时自动退款。
- 重复传送保护,避免重复收费。
PlayerPoints 使用整数货币;费用向上取整,退款遵循相同的取整逻辑。
? 权限组覆盖
groups:
vip:
rtp:
cooldown-seconds: 10
cost: 5.0
warp:
cooldown-seconds: 2
max-warps: 40
home:
cooldown-seconds: 2
max-homes: 20
tpa:
cooldown-seconds: 5
cost: 0.25
mvp:
rtp:
cooldown-seconds: 0
cost: 0.0
warp:
cooldown-seconds: 0
cost: 0.0
max-warps: 100
home:
cooldown-seconds: 0
cost: 0.0
max-homes: 50
tpa:
cooldown-seconds: 0
cost: 0.0
拥有权限 yuteleport.group.vip 或 yuteleport.group.mvp 的玩家将自动获得相应的配置。如果匹配多个组,则应用配置文件中靠前的那个。
示例:
- 默认玩家获得标准冷却时间和费用。
- VIP 玩家获得更短的冷却时间和更多的家/传送点数量。
- MVP 玩家无冷却时间且免费传送。
- 活动期间对特定组的临时折扣。
? 命令概览
RTP
/yuteleport
/ytp
/rtp
/yuteleport biome:<pattern>
/yuteleport <player>
/yuteleport <player> <world>
/yuteleport <player> <world> biome:<pattern>
/yuteleport reload
/yuteleport help
Warp
/warp
/warp <name>
/warp public
/warp public <name> true
/warp rename <old> <new>
/warp desc <name> <description>
/setwarp <name> [restricted|public|private] [description]
/delwarp <name>
Home
/home
/home <name>
/home list
/home public
/home public <name> true
/home rename <old> <new>
/home desc <name> <description>
/home <player>:<name>
/homes
/homes <player>
/sethome [name] [public|private] [description]
/delhome <name>
/delhome <player>:<name>
TPA
/tpa <player>
/tpahere <player>
/tpahere all
/tpaccept [player]
/tpdeny [player]
/tpacancel
/tpaignore
/tpaall
Back
/back
/back death
/back list
/back clear
坐标分享
/yuteleport share
/yuteleport join <share_id>
命令名称和别名可在配置中更改。当某个模块被禁用时,其命令不会被注册,从而避免与 EssentialsX 或 CMI 等插件产生不必要的冲突。
? 权限快速参考
| 权限 |
描述 |
默认值 |
yuteleport.use |
使用随机传送 |
所有人 |
yuteleport.biome |
使用 biome:<pattern> 指定目标生物群系 |
OP |
yuteleport.teleport.others |
通过主命令传送其他玩家 |
OP |
yuteleport.reload |
重载配置 |
OP |
yuteleport.warp.use |
使用传送点 |
所有人 |
yuteleport.warp.set |
创建或更新传送点 |
所有人 |
yuteleport.warp.delete |
删除自己的传送点 |
所有人 |
yuteleport.warp.public |
将你的传送点设为公开或私有 |
所有人 |
yuteleport.warp.admin |
编辑/删除所有玩家的传送点 |
OP |
yuteleport.warp.limit.<number> |
动态增加传送点上限 |
由权限插件分配 |
yuteleport.warp.limit.unlimited |
无限制的传送点数量 |
由权限插件分配 |
yuteleport.warp.limit.bypass |
忽略传送点上限过期锁定 |
OP |
yuteleport.warps.<name> |
使用指定的受限传送点 |
OP |
yuteleport.home.use |
使用家园并查看自己的家园 |
所有人 |
yuteleport.home.set |
创建或更新家园 |
所有人 |
yuteleport.home.delete |
删除家园 |
所有人 |
yuteleport.home.others |
查看或使用在线玩家的家園 |
OP |
yuteleport.home.public |
将你的家园设为公开或私有 |
所有人 |
yuteleport.home.limit.<number> |
动态增加家园上限 |
由权限插件分配 |
yuteleport.home.limit.unlimited |
无限制的家園数量 |
由权限插件分配 |
yuteleport.home.limit.bypass |
忽略家园上限过期锁定 |
OP |
yuteleport.tpa.use |
使用 tpa、tpaccept、tpdeny、tpacancel |
所有人 |
yuteleport.tpa.here |
使用 tpahere |
所有人 |
yuteleport.tpa.ignore |
忽略传入的 TPA 请求 |
所有人 |
yuteleport.tpa.all |
向所有在线玩家发送 tpahere |
OP |
yuteleport.share |
成功传送后分享当前位置 |
所有人 |
yuteleport.back.use |
使用 /back |
所有人 |
yuteleport.back.death |
使用 /back death |
所有人 |
yuteleport.back.clear |
清除自己的返回历史 |
所有人 |
yuteleport.back.admin |
保留用于返回功能的管理员权限 |
OP |
yuteleport.bypass.cooldown |
跳过传送冷却时间 |
OP |
yuteleport.bypass.cooldown.others |
在管理员传送他人时忽略目标的冷却时间 |
OP |
yuteleport.bypass.cost |
跳过传送费用 |
OP |
yuteleport.bypass.wait |
跳过等待倒计时 |
OP |
yuteleport.group.<group> |
应用相应的组配置 |
由权限插件分配 |
? PlaceholderAPI, Java API & Events
安装 PlaceholderAPI 后,你可以使用 %yuteleport_*% 占位符。
常见示例:
%yuteleport_version%
%yuteleport_platform%
%yuteleport_search_mode%
%yuteleport_random_enabled%
%yuteleport_warp_enabled%
%yuteleport_home_enabled%
%yuteleport_tpa_enabled%
%yuteleport_share_enabled%
%yuteleport_back_enabled%
%yuteleport_cooldown_random%
%yuteleport_cooldown_warp%
%yuteleport_cooldown_home%
%yuteleport_cooldown_tpa%
%yuteleport_cooldown_share%
%yuteleport_cooldown_back%
%yuteleport_cost_random%
%yuteleport_cost_warp%
%yuteleport_cost_home%
%yuteleport_cost_tpa%
%yuteleport_cost_share%
%yuteleport_cost_back%
%yuteleport_home_count%
%yuteleport_home_max%
%yuteleport_visible_warp_count%
%yuteleport_tpa_pending_count%
%yuteleport_success_rate%
可用于:
- 记分板
- TAB 列表
- 菜单插件
- 任务插件
- 成就系统
- 统计面板
开发者可以通过 Bukkit 的 ServicesManager 获取公共 Java API:
RegisteredServiceProvider<YuTeleportApi> registration =
Bukkit.getServicesManager().getRegistration(YuTeleportApi.class);
YuTeleportApi api = registration == null ? null : registration.getProvider();
该 API 可以发起随机传送、传送点传送、家园传送、返回传送以及 TPA 请求;读取模块启用状态、冷却时间、费用、传送点/家园列表以及传送统计数据。
生命周期事件:
PlayerTeleportStartEvent
PlayerTeleportDestinationEvent
PlayerTeleportCancelEvent
PlayerTeleportCompleteEvent
命令和 API 共享相同的入口点,因此第三方插件无法绕过权限、世界访问控制、冷却时间、等待机制、经济系统或安全规则。
? Compatibility
Minecraft Versions
本插件旨在实现 Minecraft 1.8.x – 1.26.x Bukkit / Spigot / Paper 生态系统的跨版本兼容。
不同功能会自动检测并降级:
- BossBar:支持 1.9+;否则回退到其他倒计时通道。
- ActionBar / Title:在支持时启用;旧版本会自动跳过或降级。
- 粒子效果:支持 1.9+;如果不可用,不影响传送功能。
&#RRGGBB 十六进制颜色:1.16+ 原生显示;旧版本降级为传统颜色。
- Paper 异步区块加载:可用时用于异步搜索和预缓存;否则回退到同步搜索。
- 1.18+ 世界高度:自动读取最小/最大高度,兼容负高度世界。
Server Softwares
- CraftBukkit / Spigot
- Paper / Purpur / Leaves 及大多数 Paper 分支
- Folia
- Youer / Arclight / Mohist / CatServer 及其他混合服务器
- 任何遵循 Bukkit / Spigot / Paper API 的服务器
Soft Dependencies
- Vault: 当启用金币经济时使用。
- PlayerPoints: 当启用积分经济时使用。
- PlaceholderAPI: 安装后自动注册
%yuteleport_*% 占位符。
如果缺少任何软依赖项,插件仍会独立运行;相应功能将被跳过,并在日志中提供清晰提示。
⚙️ Configuration Example
language:
default: zh_CN
use-player-locale: true
economy:
enabled: true
provider: vault
cooldowns:
persist: true
teleports:
defaults:
warmup-seconds: 5
countdown-display: actionbar
cancel-on-move: true
cancel-triggers:
move: true
damage: true
interact: true
chat: true
command: true
world-access:
blacklist:
- lobby
- "playerworld*"
whitelist: []
rtp:
enabled: true
warmup-seconds: -1
cooldown-seconds: 5
search-mode: async
precache:
enabled: true
size: 3
worlds:
default:
cost: 15.0
shape: circle
center:
x: 0
z: 0
radius:
min: 500
max: 10000
safety:
check: true
allow-void: false
allow-water: false
allow-lava: false
max-attempts: 32
min-air-above: 8
blocked-materials:
- "MAGMA*"
- "CACTUS"
- "SWEET_BERRY_BUSH"
- "COBWEB"
- "FIRE"
allowed-materials: []
blocked-biomes:
- "OCEAN"
allowed-biomes: []
warp:
enabled: true
warmup-seconds: 5
cooldown-seconds: 3
cost: 0.0
max-warps: 1
public:
enabled: true
publish-cost: 0.0
teleport-cost: 0.0
home:
enabled: true
warmup-seconds: 5
cooldown-seconds: 3
cost: 0.0
max-homes: 2
world-blacklist: []
public:
enabled: true
publish-cost: 0.0
teleport-cost: 0.0
tpa:
enabled: true
request-timeout-seconds: 60
warmup-seconds: 5
cooldown-seconds: 10
cost: 0.0
share:
enabled: true
cooldown-seconds: 60
expire-seconds: 120
max-active: 256
cost: 0.0
teleport-cost: 0.0
back:
enabled: true
warmup-seconds: 5
cooldown-seconds: 10
cost: 0.0
safety-rescue: true
max-history: 5
expire-seconds: 1800
persist: true
effects:
sounds:
enabled: true
titles:
enabled: true
particles:
enabled: true
smooth-bossbar: true
interactive-chat: true
---
# ? 适用于以下服务器
- 生存服务器
- 退休/社区服务器
- 资源世界服务器
- RPG 大型地图服务器
- 带有额外维度的 Skyblock(天空岛)
- 科技 / Slimefun 服务器
- 拥有大量商店、出生点和公共设施的服务器
- 活动世界服务器
- 硬核 / 大逃杀风格服务器
- 高性能 Paper / Purpur 服务器
- Folia 多线程服务器
- Bukkit 混合服务器
- 需要统一传送系统和玩家分布的服务器
---
# ? 官方链接
- 文档:https://vicuna-main.github.io/YuPluginHub/plugins/items/yu-teleport/
- Modrinth:https://modrinth.com/plugin/yuteleport
- 问题追踪:https://github.com/vicuna-main/YuTeleportIssueReport
- 官方 QQ 群:https://qm.qq.com/q/xiwJYBYdh0
- 支持作者:https://afdian.com/a/vicuna
---
# ? YuTeleport
**不仅仅是一个随机坐标生成器,也不是零散命令的拼凑——而是一个专为生产环境服务器设计的安全传送系统。**
? 随机传送,? 传送点,? 家,? TPA,? 返回,? 坐标共享,? 经济集成,? 组权限,⏳ 统一倒计时,?️ 安全着陆,? Folia 调度,? PAPI 占位符,以及 ?? Java API —— 全部集成于 YuTeleport。
**将服务器的传送功能从“可用”升级为“统一、可控且易于维护”。**
? YuTeleport / YuTP – Cross-Version Safe Teleport Plugin
?️ Safe Landing | ? Random Teleport | ? Warp | ? Home | ? TPA | ? Back | ? Coordinate Sharing | ? Folia Support
? Worried that random teleport might drop players into lava, underwater, inside blocks, at the void edge, or onto dangerous platforms in the Nether?
? Want to manage resource‑world scatter points, public waypoints, player homes, TPA, /back, and coordinate sharing all in one plugin?
? Don't want traditional teleport plugins to lag the main thread while searching for chunks, nor maintain cooldowns, costs, permissions, and messages separately?
? Don't want multiple plugins fighting over /warp, /home, /tpa, /back, and having to debug conflicts one by one?
YuTeleport (YuTP) is a cross‑version, safe teleport suite for Minecraft Java servers.
It is not just a single RTP tool, but a complete teleport system: random teleport, public warps, player homes, TPA‑based mutual teleport, /back return, coordinate sharing, economy integration, permission groups, PlaceholderAPI, a public Java API, Folia/Paper compatibility – all processed through the same teleport pipeline.
Current version: 2.0.1.2
Config version: config‑version 20
? Core Features
- ? Random Teleport (RTP): Per‑world configuration for radius, height range, center point, square/circle distribution, block rules, and biome filtering.
- ? Warp (Public Waypoints): Supports public, private, and restricted types; includes description, rename, delete, max amount limits, and fine‑grained permissions.
- ? Home (Player Homes): Each player saves homes independently; supports multiple homes, public homes, cross‑player access, descriptions, and quantity expansion.
- ? TPA (Player‑to‑Player Teleport): Supports
/tpa, /tpahere, accept, deny, cancel, ignore requests, and global tpahere.
- ? Back (Return System): Records death points, pre‑teleport locations from plugin teleports, and external teleport origins; supports
/back, /back death, /back list, /back clear.
- ? Coordinate Sharing: After a successful teleport, players can share their current location to all online players; others can click to teleport.
- ? Unified Teleport Pipeline: All handling – wait, interrupt, cooldown, cost deduction, refund, safety re‑check, events, status tracking, and hooks – is processed uniformly.
- ⚡ Asynchronous Safe‑Point Search: On Paper 1.13+ can use async chunk loading to reduce main‑thread stress; falls back to sync mode automatically when unsupported.
- ? Landing‑Point Pre‑caching: Background preparation of safe landing points; when cache is hit, online search wait time is reduced.
- ? Biome Filtering: Supports black/whitelists,
* wildcards, and single‑use biome:<pattern> specification.
- ? Vault / PlayerPoints Economy: Prices are set per teleport type, per world, and per permission group; failed, cancelled, or Folia‑retired scenarios automatically refund.
- ? Permission Group Overrides: Use
yuteleport.group.<group> to configure different cooldowns, costs, warp limits, and home limits per group.
- ⏳ Multi‑Channel Countdown: Chat, BossBar, ActionBar, or silent wait – freely combinable; move, damage, interact, chat, and command interruptions can be toggled individually.
- ? Full Audio‑Visual Feedback: Countdown sounds, success arpeggios, fail/cancel/cost/refund sounds, titles, particles, click‑to‑retry, and hover coordinates.
- ? PlaceholderAPI Extension: Provides module states, cooldowns, costs, home/warp counts, teleport stats, and back status.
- ?? Java API & Events: External plugins can initiate teleports, read module data, listen to and cancel teleport lifecycle events.
- ? Folia Scheduling Adaptation: Uses Region / Entity / Global Schedulers to avoid cross‑region entity access issues.
? Design Philosophy
YuTeleport's goal is not merely to "move a player", but to make every teleport request controllable, rollback‑able, and observable – from request to arrival.
- Does the player have permission?
- Is the target world allowed?
- Is the cooldown active?
- Does a countdown need to be waited?
- During the countdown, did the player move, take damage, chat, or execute commands?
- Is a cost required? How to handle balance changes during the wait?
- Is the target point safe? Is the target world still loaded?
- Should the cost be refunded on failure, cancellation, or entity retirement?
- Can third‑party plugins listen to, cancel, or read the result?
- Can the player return to their death point or previous location before teleport?
These logic pieces are no longer scattered across multiple plugins or modules; they are handled by the unified teleport pipeline. Server owners can use it as the foundational teleport system for production servers, not just a temporary scatter tool.
? Feature Modules
? Random Teleport (RTP)
Ideal for resource worlds, wilderness exploration, new player spawning, event maps, and servers that need to reduce spawn crowding.
- Each world has independent radius, cost, height range, safety rules, and search strategy.
- Customizable random center, not fixed to
(0, 0).
- Supports square ring or circular ring distributed by area.
- World black/whitelist with
* wildcard support.
- Block black/whitelist – exclude lava, fire, cactus, sweet berry bushes, cobwebs, etc.
- Biome black/whitelist – e.g.,
*OCEAN*, *FOREST*.
- Supports Paper async chunk loading, Folia region scheduling, and sync fallback.
- Background safe‑landing pre‑caching to reduce online search overhead for high‑frequency teleports.
Common commands:
/yuteleport
/ytp
/rtp
/yuteleport biome:*FOREST*
/yuteleport <player>
/yuteleport <player> <world> biome:*PLAINS*
? Warp (Public Waypoints)
Suitable for spawns, resource world entrances, event venues, shopping districts, dungeon entrances, and player‑built public points.
/setwarp <name> to create or update a warp.
public warps are visible and usable by all players.
private warps are manageable only by the creator and admins.
restricted warps require yuteleport.warps.<name> to be visible and usable.
- Supports description, rename, public/unpublic, and deletion.
- Default limit, permission‑based limit, and
groups.<group>.warp.max‑warps for expansion.
- Exceeding the limit after permission expiry locks the warp temporarily; re‑granting permission restores access.
- Create‑public, use‑public, and normal warp teleports can each have separate costs.
Common commands:
/warp
/warp <name>
/warp public
/warp public <name> true
/warp rename <old> <new>
/warp desc <name> <description>
/setwarp <name> [restricted|public|private] [description]
/delwarp <name>
? Home (Player Homes)
Suitable for survival, retirement, RPG, skyblock, and servers where players need to manage their own return points.
/sethome [name] sets a personal home; default name is home.
/homes lists your own homes.
- Players can make homes public; other online players can view and teleport to them.
- Each home can have a description.
- Supports rename, description change, public/unpublic, and deletion.
- Admins can view or use online players' homes.
- Default home limit, permission‑based limit, and
groups.<group>.home.max‑homes for expansion.
- Excess homes after permission expiry are locked temporarily.
- Worlds where home setting is forbidden can be configured (e.g., event worlds, mining worlds).
- Each player's homes are saved in individual files; loaded on join, unloaded on quit.
Common commands:
/home
/home <name>
/home list
/home public
/home public <name> true
/home rename <old> <new>
/home desc <name> <description>
/home <player>:<name>
/homes
/homes <player>
/sethome [name] [public|private] [description]
/delhome <name>
/delhome <player>:<name>
? TPA (Player‑to‑Player Teleport)
Ideal for player visits, team exploration, event gatherings, and regular survival servers.
/tpa <player> – request to teleport to that player.
/tpahere <player> – request that player to teleport to you.
/tpaccept [player] – accept a request.
/tpdeny [player] – deny a request.
/tpacancel – cancel your outgoing request.
/tpaignore – temporarily ignore incoming TPA requests.
/tpaall or /tpahere all – send a tpahere request to all online players.
- Requests expire automatically; send again if expired.
- New request replaces your last outgoing request to avoid an endless request book.
- Target player receives clickable accept/deny buttons.
- In
tpahere, the receiver is moved, but cost and cooldown belong to the requester.
Common commands:
/tpa <player>
/tpahere <player>
/tpahere all
/tpaccept [player]
/tpdeny [player]
/tpacancel
/tpaignore
/tpaall
? Back Return System
/back is suitable for death recovery, rollback after accidental teleport, and returning to the original location after cross‑plugin teleportation.
/back – returns to the most recent available location.
/back death – returns to the last death point.
/back list – shows the return history; with interactive chat enabled, click any record to teleport.
/back clear – clears your own back history.
- Records pre‑teleport positions from internal plugin teleports, player death points, and pre‑teleport positions from external plugins.
- Filters by distance – moves less than the threshold (default 3 blocks) are not recorded to prevent spam.
- Configurable maximum history size (default 5).
- Configurable expiry time (default 1800 seconds).
- Persistent storage – back history saved to
data/back.
- Independent warm‑up, cooldown, cost, safety rescue, world black/whitelist, and hooks.
- Priority configuration – default prefers death points first, then plugin pre‑teleport, then external pre‑teleport.
Common commands:
/back
/back death
/back list
/back clear
Core configuration:
teleports:
back:
enabled: true
commands:
back: [back]
warmup-seconds: 5
cooldown-seconds: 10
cost: 0.0
safety-rescue: true
max-history: 5
expire-seconds: 1800
persist: true
capture:
plugin-teleports: true
death: true
external-teleports: true
include-types: [random, warp, home, tpa, share, back]
min-distance: 3.0
priority: [death, teleport, external]
? Coordinate Sharing
Ideal for temporary rally points, resource discoveries, event coordinates, team gatherings, and exploration sharing.
After a successful teleport, the success message can include a "Share Current Location" button. Clicking it broadcasts the coordinate share to all online players, who can click to teleport.
- Shares have an expiry time; they are automatically invalid after expiry.
- Shares have their own cooldown.
- Maximum number of active shares in memory to prevent long‑term buildup.
- Sharing and teleporting via share can be separately charged.
- Coordinate sharing inherits or individually configures world black/whitelist.
Common commands:
/yuteleport share
/yuteleport join <share_id>
?️ Safe Landing & Rescue
YuTeleport checks the following before a random teleport:
- Is the block below the player solid enough?
- Is there enough space for the player's body and head?
- Is the extra headroom above meeting the configuration?
- Dangerous blocks: water, lava, fire, cactus, cobwebs, magma blocks, etc.
- Void, world min/max height, world border.
- Biome black/whitelist.
- Vertical candidate positions in complex dimensions like the Nether.
This reduces the risk of:
- Players stuck inside blocks or walls.
- Landing in lava, underwater, or hazardous blocks.
- Teleporting outside the world border or exactly on the border.
- Landing at the void edge or floating in the air.
- Nether random landing on a platform without a solid foothold.
Fixed‑point modules (warp, home, tpa, share, back) respect the stored coordinates by default and do not force a new random safe‑point search. If you worry about points being broken, enable safety-rescue for that module to perform a stuck‑rescue after arrival.
? World Access & Per‑Module Configuration
YuTeleport supports a global default world‑access rule, which can be overridden per module:
teleports.defaults.world-access
teleports.rtp.world-access
teleports.warp.world-access
teleports.home.world-access
teleports.tpa.world-access
teleports.share.world-access
teleports.back.world-access
World lists support * wildcards:
lobby
resource_*
*_nether
*event*
*
Typical use cases:
- Overworld: moderate radius, low cost, exclude oceans.
- Resource world: huge radius, high cost, enable async search and pre‑caching.
- Nether: restrict height, increase attempts, set allowed‑block whitelist.
- Event worlds: allow only specific modules or block entirely.
- Lobby world: disable
/back or all player‑initiated teleports.
⚡ Async Search & Pre‑caching
Traditional RTP sync‑loads new chunks during teleport, causing lag during peak times. YuTeleport offers two optimizations.
Asynchronous Safe‑Point Search
teleports:
rtp:
search-mode: async
On Paper 1.13+ and compatible cores, the plugin uses async chunk loading to find random landing points. If the current server does not support it, it automatically falls back to sync mode and logs a hint. On Folia, the plugin respects the region‑scheduling model and does not rely on traditional main‑thread assumptions.
Landing‑Point Pre‑caching
teleports:
rtp:
precache:
enabled: true
size: 3
The plugin can pre‑generate 1–16 safe landing points per world in the background. When a player requests random teleport and the cache is hit, the online search phase is skipped – only final verification and the remaining pipeline are executed.
⏳ Countdown, Interruptions & Feedback
All teleport modules can use the unified wait countdown.
teleports:
defaults:
warmup-seconds: 5
countdown-display: actionbar
cancel-on-move: true
cancel-triggers:
move: true
damage: true
interact: true
chat: true
command: true
Display channels:
- Chat
- BossBar
- ActionBar
- Silent wait
Interruption conditions:
- Move
- Damage
- Interact
- Chat
- Execute command
Players with yuteleport.bypass.wait skip the wait.
Players with yuteleport.bypass.cooldown skip cooldowns.
Players with yuteleport.bypass.cost skip costs.
? Economy System
economy:
enabled: true
provider: vault # vault or playerpoints
Features:
- Vault coin economy.
- PlayerPoints currency economy.
- RTP priced per world.
- Warp / Home / TPA / Share / Back priced per module.
- Permission‑group cost overrides.
- Insufficient balance notification.
- Second balance check after the wait ends.
- Automatic refund on failure, cancellation, or Folia retirement.
- Duplicate teleport protection to avoid double charges.
PlayerPoints uses integer currency; costs are rounded up, and refunds follow the same rounding logic.
? Permission Group Overrides
groups:
vip:
rtp:
cooldown-seconds: 10
cost: 5.0
warp:
cooldown-seconds: 2
max-warps: 40
home:
cooldown-seconds: 2
max-homes: 20
tpa:
cooldown-seconds: 5
cost: 0.25
mvp:
rtp:
cooldown-seconds: 0
cost: 0.0
warp:
cooldown-seconds: 0
cost: 0.0
max-warps: 100
home:
cooldown-seconds: 0
cost: 0.0
max-homes: 50
tpa:
cooldown-seconds: 0
cost: 0.0
Players with the permission yuteleport.group.vip or yuteleport.group.mvp automatically receive the corresponding configuration. If multiple groups match, the first one in the config file order is applied.
Examples:
- Default players get standard cooldowns and costs.
- VIP players get reduced cooldowns and more homes/warps.
- MVP players have no cooldowns and free teleports.
- Temporary discounts for a group during events.
? Command Overview
RTP
/yuteleport
/ytp
/rtp
/yuteleport biome:<pattern>
/yuteleport <player>
/yuteleport <player> <world>
/yuteleport <player> <world> biome:<pattern>
/yuteleport reload
/yuteleport help
Warp
/warp
/warp <name>
/warp public
/warp public <name> true
/warp rename <old> <new>
/warp desc <name> <description>
/setwarp <name> [restricted|public|private] [description]
/delwarp <name>
Home
/home
/home <name>
/home list
/home public
/home public <name> true
/home rename <old> <new>
/home desc <name> <description>
/home <player>:<name>
/homes
/homes <player>
/sethome [name] [public|private] [description]
/delhome <name>
/delhome <player>:<name>
TPA
/tpa <player>
/tpahere <player>
/tpahere all
/tpaccept [player]
/tpdeny [player]
/tpacancel
/tpaignore
/tpaall
Back
/back
/back death
/back list
/back clear
Coordinate Sharing
/yuteleport share
/yuteleport join <share_id>
Command names and aliases can be changed in the configuration. When a module is disabled, its commands are not registered, avoiding unnecessary conflicts with plugins like EssentialsX or CMI.
? Permission Quick Reference
| Permission |
Description |
Default |
yuteleport.use |
Use random teleport |
Everyone |
yuteleport.biome |
Use biome:<pattern> to specify target biome |
OP |
yuteleport.teleport.others |
Teleport other players via main command |
OP |
yuteleport.reload |
Reload configuration |
OP |
yuteleport.warp.use |
Use warps |
Everyone |
yuteleport.warp.set |
Create or update a warp |
Everyone |
yuteleport.warp.delete |
Delete your own warp |
Everyone |
yuteleport.warp.public |
Make your warp public or unpublic |
Everyone |
yuteleport.warp.admin |
Edit/delete all players' warps |
OP |
yuteleport.warp.limit.<number> |
Increase warp limit dynamically |
Assigned by permission plugin |
yuteleport.warp.limit.unlimited |
Unlimited warp count |
Assigned by permission plugin |
yuteleport.warp.limit.bypass |
Ignore warp limit expiry lock |
OP |
yuteleport.warps.<name> |
Use the specified restricted warp |
OP |
yuteleport.home.use |
Use homes and view your own homes |
Everyone |
yuteleport.home.set |
Create or update a home |
Everyone |
yuteleport.home.delete |
Delete a home |
Everyone |
yuteleport.home.others |
View or use online players' homes |
OP |
yuteleport.home.public |
Make your home public or unpublic |
Everyone |
yuteleport.home.limit.<number> |
Increase home limit dynamically |
Assigned by permission plugin |
yuteleport.home.limit.unlimited |
Unlimited home count |
Assigned by permission plugin |
yuteleport.home.limit.bypass |
Ignore home limit expiry lock |
OP |
yuteleport.tpa.use |
Use tpa, tpaccept, tpdeny, tpacancel |
Everyone |
yuteleport.tpa.here |
Use tpahere |
Everyone |
yuteleport.tpa.ignore |
Ignore incoming TPA requests |
Everyone |
yuteleport.tpa.all |
Send tpahere to all online players |
OP |
yuteleport.share |
Share current location after successful teleport |
Everyone |
yuteleport.back.use |
Use /back |
Everyone |
yuteleport.back.death |
Use /back death |
Everyone |
yuteleport.back.clear |
Clear your own back history |
Everyone |
yuteleport.back.admin |
Reserved admin permission for back |
OP |
yuteleport.bypass.cooldown |
Skip teleport cooldowns |
OP |
yuteleport.bypass.cooldown.others |
Ignore target cooldown when admin‑teleporting others |
OP |
yuteleport.bypass.cost |
Skip teleport costs |
OP |
yuteleport.bypass.wait |
Skip wait countdown |
OP |
yuteleport.group.<group> |
Apply the corresponding group configuration |
Assigned by permission plugin |
? PlaceholderAPI, Java API & Events
After PlaceholderAPI is installed, you can use %yuteleport_*% placeholders.
Common examples:
%yuteleport_version%
%yuteleport_platform%
%yuteleport_search_mode%
%yuteleport_random_enabled%
%yuteleport_warp_enabled%
%yuteleport_home_enabled%
%yuteleport_tpa_enabled%
%yuteleport_share_enabled%
%yuteleport_back_enabled%
%yuteleport_cooldown_random%
%yuteleport_cooldown_warp%
%yuteleport_cooldown_home%
%yuteleport_cooldown_tpa%
%yuteleport_cooldown_share%
%yuteleport_cooldown_back%
%yuteleport_cost_random%
%yuteleport_cost_warp%
%yuteleport_cost_home%
%yuteleport_cost_tpa%
%yuteleport_cost_share%
%yuteleport_cost_back%
%yuteleport_home_count%
%yuteleport_home_max%
%yuteleport_visible_warp_count%
%yuteleport_tpa_pending_count%
%yuteleport_success_rate%
Useful for:
- Scoreboards
- TAB lists
- Menu plugins
- Quest plugins
- Achievement systems
- Statistics panels
Developers can obtain the public Java API via Bukkit's ServicesManager:
RegisteredServiceProvider<YuTeleportApi> registration =
Bukkit.getServicesManager().getRegistration(YuTeleportApi.class);
YuTeleportApi api = registration == null ? null : registration.getProvider();
The API can initiate random teleports, warp teleports, home teleports, back teleports, and TPA requests; read module enable states, cooldowns, costs, warp/home lists, and teleport statistics.
Lifecycle events:
PlayerTeleportStartEvent
PlayerTeleportDestinationEvent
PlayerTeleportCancelEvent
PlayerTeleportCompleteEvent
Commands and the API share the same entry points, so third‑party plugins cannot bypass permissions, world access, cooldowns, waiting, economy, or safety rules.
? Compatibility
Minecraft Versions
The plugin targets cross‑version compatibility for Minecraft 1.8.x – 1.26.x Bukkit / Spigot / Paper ecosystems.
Different features are auto‑detected and downgraded:
- BossBar: 1.9+ supported; falls back to other countdown channels otherwise.
- ActionBar / Title: enabled when supported; older versions skip or downgrade automatically.
- Particle effects: 1.9+ supported; does not affect teleport if unavailable.
&#RRGGBB hex colors: natively displayed on 1.16+; older versions downgrade to legacy colours.
- Paper async chunk loading: used for async search and pre‑caching when available; falls back to sync search otherwise.
- 1.18+ world heights: reads min/max heights automatically, compatible with negative‑height worlds.
Server Softwares
- CraftBukkit / Spigot
- Paper / Purpur / Leaves and most Paper forks
- Folia
- Youer / Arclight / Mohist / CatServer and other hybrid servers
- Any server that follows the Bukkit / Spigot / Paper API
Soft Dependencies
- Vault: used when coin economy is enabled.
- PlayerPoints: used when points economy is enabled.
- PlaceholderAPI: automatically registers
%yuteleport_*% placeholders when installed.
If any soft dependency is missing, the plugin still runs independently; the corresponding features are skipped with clear log hints.
⚙️ Configuration Example
language:
default: zh_CN
use-player-locale: true
economy:
enabled: true
provider: vault
cooldowns:
persist: true
teleports:
defaults:
warmup-seconds: 5
countdown-display: actionbar
cancel-on-move: true
cancel-triggers:
move: true
damage: true
interact: true
chat: true
command: true
world-access:
blacklist:
- lobby
- "playerworld*"
whitelist: []
rtp:
enabled: true
warmup-seconds: -1
cooldown-seconds: 5
search-mode: async
precache:
enabled: true
size: 3
worlds:
default:
cost: 15.0
shape: circle
center:
x: 0
z: 0
radius:
min: 500
max: 10000
safety:
check: true
allow-void: false
allow-water: false
allow-lava: false
max-attempts: 32
min-air-above: 8
blocked-materials:
- "MAGMA*"
- "CACTUS"
- "SWEET_BERRY_BUSH"
- "COBWEB"
- "*FIRE*"
allowed-materials: []
blocked-biomes:
- "*OCEAN*"
allowed-biomes: []
warp:
enabled: true
warmup-seconds: 5
cooldown-seconds: 3
cost: 0.0
max-warps: 1
public:
enabled: true
publish-cost: 0.0
teleport-cost: 0.0
home:
enabled: true
warmup-seconds: 5
cooldown-seconds: 3
cost: 0.0
max-homes: 2
world-blacklist: []
public:
enabled: true
publish-cost: 0.0
teleport-cost: 0.0
tpa:
enabled: true
request-timeout-seconds: 60
warmup-seconds: 5
cooldown-seconds: 10
cost: 0.0
share:
enabled: true
cooldown-seconds: 60
expire-seconds: 120
max-active: 256
cost: 0.0
teleport-cost: 0.0
back:
enabled: true
warmup-seconds: 5
cooldown-seconds: 10
cost: 0.0
safety-rescue: true
max-history: 5
expire-seconds: 1800
persist: true
effects:
sounds:
enabled: true
titles:
enabled: true
particles:
enabled: true
smooth-bossbar: true
interactive-chat: true
? Suitable for These Servers
- Survival servers
- Retirement/community servers
- Resource‑world servers
- RPG large‑map servers
- Skyblock with extra dimensions
- Tech / Slimefun servers
- Servers with many shops, spawns, and public facilities
- Event‑world servers
- Hardcore / Battle‑Royale style servers
- High‑performance Paper / Purpur servers
- Folia multithreaded servers
- Bukkit hybrid servers
- Servers needing a unified teleport system and player distribution
? Official Links
- Documentation:
- Modrinth:
- Issue Tracker:
- Official QQ Group:
- Support the Author:
? YuTeleport
Not just a random coordinate generator, nor a patchwork of scattered commands – but a safe teleport system designed for production servers.
? Random Teleport, ? Warp, ? Home, ? TPA, ? Back, ? Coordinate Sharing, ? Economy integration, ? Group Permissions, ⏳ Unified Countdown, ?️ Safe Landing, ? Folia Scheduling, ? PAPI placeholders, and ?? Java API – all integrated into YuTeleport.
Upgrade your server's teleport from "functional" to "unified, controllable, and maintainable".
评论 0
登录后参与评分
还没有评论,来抢沙发吧