YuTeleport Java API

YuTeleport 2.0.1.0 通过 Bukkit ServicesManager 注册 YuTeleportApi。消费插件应把 YuTeleport 写入 depend 或 softdepend，不要强转插件主类，也不要访问内部集合。

获取 API

RegisteredServiceProvider<YuTeleportApi> registration =
    Bukkit.getServicesManager().getRegistration(YuTeleportApi.class);
YuTeleportApi api = registration == null ? null : registration.getProvider();

消费插件的 plugin.yml：

softdepend: [YuTeleport]

请求传送

api.requestTeleport(player, world).thenAccept(result -> {
    if (result.isSuccess()) {
        Location destination = result.getDestination();
    }
});

CompletableFuture<TeleportResult> 不需要阻塞等待。请求会沿用命令相同的权限、世界、冷却、等待、经济和安全策略。在 Folia 上不要假定回调属于某个固定区域，需要操作实体或世界时应重新使用服务端调度器。

API 方法

方法	说明
requestTeleport(Player, World)	按完整策略请求随机传送。
requestWarpTeleport(Player, String)	请求传送到 warp。
requestHomeTeleport(Player, String)	请求传送到自己的 home。
requestHomeTeleport(Player, Player, String)	请求传送到指定在线玩家的 home。
requestBackTeleport(Player)	请求执行与 /back 相同的最近位置返回流程。
sendTeleportRequest(Player, Player, boolean)	发起 /tpa 或 /tpahere 请求，here=true 表示 tpahere。
acceptTeleportRequest(Player, Player)	接受指定请求者的 TPA 请求。
denyTeleportRequest(Player, Player)	拒绝指定请求者的 TPA 请求。
cancelOutgoingTeleportRequest(Player)	取消玩家发出的 TPA 请求。
cancelTeleport(Player, TeleportCancelReason)	取消玩家正在进行的传送请求。
isPending(UUID)	玩家是否处于等待、搜索或执行状态。
getCooldownRemainingMillis(UUID)	随机传送剩余冷却毫秒数。
getCooldownRemainingMillis(UUID, TeleportType)	指定传送类型剩余冷却毫秒数。
getSnapshot(UUID)	获取不可变的最近状态和位置快照。
isModuleEnabled(TeleportType)	指定模块是否启用。
getConfiguredCooldownSeconds(Player, TeleportType)	获取玩家指定类型的有效冷却秒数。
getEffectiveWaitSeconds(Player, TeleportType)	获取玩家指定类型的有效等待秒数。
getConfiguredCost(Player, TeleportType, World)	获取玩家在指定世界和类型下的有效费用。
getSuccessfulTeleports()、getFailedTeleports()、getCancelledTeleports()	获取本次启动以来的全局成功、失败和取消计数。
isFolia()	当前是否运行在 Folia 调度模型。

Warp 与 Home 查询

方法	说明
getWarpNames()	全部 warp 名称。
getVisibleWarpNames(Player)	指定玩家可见 warp 名称。
getPublicWarpNames()	公开 warp 名称。
getWarpCount()、getPublicWarpCount()、getWarpCount(Player)	warp 数量统计。
getMaxWarps(Player)	指定玩家有效 warp 上限。
hasWarp(String)、isWarpRestricted(String)、isWarpPublic(String)	warp 状态查询。
getHomeNames(Player)、getHomeNames(UUID)	指定玩家 home 名称。
getPublicHomeNames()	公开 home 名称。
getHomeCount(Player)、getHomeCount(UUID)、getPublicHomeCount()	home 数量统计。
hasHome(UUID, String)、isHomePublic(Player, String)	home 状态查询。
getMaxHomes(Player)	指定玩家有效 home 上限。
getPendingTeleportRequesters(Player)	指定玩家收到的待处理 TPA 请求者。

返回值与状态

TeleportResult 提供玩家 UUID、TeleportStatus、世界名、克隆后的目标 Location、时间戳和 isSuccess()。

可能的状态：

IDLE, PENDING, SEARCHING, SUCCESS, NO_SAFE_LOCATION,
CANCELLED, REJECTED, TELEPORT_FAILED, PLAYER_OFFLINE, ERROR,
DESTINATION_UNAVAILABLE

TeleportType：

RANDOM, WARP, HOME, TPA, SHARE, BACK

TeleportCancelReason：

MOVEMENT, DAMAGE, INTERACTION, CHAT, COMMAND, DISCONNECT,
API, EVENT, PLUGIN_DISABLE, ECONOMY

事件与 PlaceholderAPI

• 生命周期事件与线程注意事项见 Bukkit 事件。
• %yuteleport_*% 完整变量见 PlaceholderAPI。

其他联动

联动	行为
Vault	可选软依赖；economy.provider: vault 时通过服务注册查找经济服务。
PlayerPoints	可选软依赖；economy.provider: playerpoints 时按点券扣费和退款。
PlaceholderAPI	可选软依赖；只读快照，不主动加载区块。
bStats	Bukkit 统计插件 ID 32443；关闭不会影响传送。
控制台命令钩子	各模块 hooks 由控制台执行，可接任务、广播和日志插件。

文件与网络行为

• 读写 plugins/YuTeleport/config.yml。
• 提取并读取 plugins/YuTeleport/lang/*.yml。
• 维护 warp、home、back、冷却和分享相关数据文件。
• 配置升级时创建 .bak 备份。
• bStats 和更新检查启用时会访问外部服务；核心传送本身不依赖外网。