AdventureServer
一、简介
AdventureServer —— 一款 Velocity + Paper 跨服传送管理插件
AdventureServer 为您的服务器群组提供完整的跨服传送解决方案。支持跨服传送(STP)、跨服玩家传送请求(ATP)、Home系统、随机传送(RTP)、死亡返回(Back)和服务器限定开放等功能。基于 Plugin Message 协议实现高性能跨服通信。
AdventureServer 支持 Velocity 3.4+ 代理端和 Paper 1.21.4+ 子服，并且会第一时间支持未来版本。
AdventureServer
- STP跨服传送 > 独立权限/冷却/消耗，一键传送指定服务器
- ATP/ATPHere > 跨服玩家传送请求，支持接受/拒绝
- Home系统 > sethome + home 持久化，支持多个家
- RTP随机传送 > 权限组范围/冷却/每日次数限制
- Back返回 > 死亡返回 + 往返切换
- 限定开放 > 时段准入 + 闭服滞留处理
- Proxy+Paper双端 > 代理端和子服协同工作
- Plugin Message > 高性能跨服通信协议
- 高自定义 > 消息文本、冷却、费用全部可配置
二、插件前置说明
都是非必须
- PlaceholderAPI — PAPI变量支持（Paper端）
下一篇安装与部署 →
安装与部署
环境要求
| 项目 | 要求 |
|---|---|
| Java | 21+ |
| Proxy | Velocity 3.4.0+ |
| Backend | Paper 1.21.4+ |
| 外部依赖 | 无（PlaceholderAPI 可选） |
部署步骤
- 将
AdventureServer-Proxy-1.6.0.jar放入 Velocityplugins/ - 将
AdventureServer-Paper-1.6.0.jar放入每个子服plugins/ - 每个子服
config.yml → server-name必须与 Velocity 注册名一致 - 所有子服统一
servers.yml /stp reload（Paper）+/asadmin reload（Proxy）
⚠️ 重点
子服名不一致会导致跨服消息正确但传送失败。校验 config.yml: server-name 与 Velocity 配置名完全一致（含大小写）。
上一篇← 概览
下一篇命令总表 →
命令总表
玩家命令 (Paper)
| 命令 | 别名 | 权限 | 说明 |
|---|---|---|---|
/stp [server] | /servertp /ast | adventureserver.stp | 列出子服或跳转 |
/atp <player> | /crosstp | adventureserver.tp | 请求跨服传送到目标 |
/atphere <player> | /crosstphere | adventureserver.tphere | 邀请目标传送到自己 |
/atpyes | /atpaccept | — | 接受请求 |
/atpno | /atpdeny | — | 拒绝请求 |
/sethome | /ashome /homeset | adventureserver.home.set | 设置家点 |
/home | /h | adventureserver.home.use | 回家 (倒计时+移动取消) |
/artp | /rtp /randomtp | adventureserver.rtp | 随机传送安全位置 |
/aback | /back | adventureserver.back | 返回死亡点 |
管理命令
| 命令 | 端 | 权限 | 说明 |
|---|---|---|---|
/stp reload | Paper | adventureserver.admin | 重载 Paper 配置 |
/asadmin status | Proxy | adventureserver.admin | 代理状态/玩家分布 |
/asadmin reload | Proxy | adventureserver.admin | 重载 Proxy + 广播 RELOAD |
上一篇← 安装与部署
下一篇权限矩阵 →
权限矩阵
| 权限 | 默认 | 用途 |
|---|---|---|
adventureserver.stp | true | /stp |
adventureserver.stp.bypass.cooldown | OP | 绕过 STP 冷却 |
adventureserver.stp.bypass.cost | OP | 绕过 STP 消耗 |
adventureserver.tp | true | /atp |
adventureserver.tp.bypass.cooldown | OP | 绕过 TP 冷却 |
adventureserver.tp.bypass.cost | OP | 绕过 TP 消耗 |
adventureserver.tphere | OP | /atphere |
adventureserver.tphere.bypass.cooldown | OP | 绕过 TPHere 冷却 |
adventureserver.tphere.bypass.cost | OP | 绕过 TPHere 消耗 |
adventureserver.home.use | true | /home |
adventureserver.home.set | true | /sethome |
adventureserver.home.bypass.cooldown | OP | 绕过 home 冷却 |
adventureserver.rtp | true | /artp |
adventureserver.rtp.bypass.cooldown | OP | 绕过 RTP 冷却 |
adventureserver.rtp.bypass.limit | OP | 绕过每日次数 |
adventureserver.rtp.group.* | — | RTP 权限组 |
adventureserver.back | true | /aback |
adventureserver.back.bypass.cooldown | OP | 绕过 back 冷却 |
adventureserver.back.group.* | — | Back 权限组 |
adventureserver.serveropen.bypass | OP | 绕过时段限制 |
adventureserver.serveropen.enforce.bypass | OP | 绕过闭服滞留 |
adventureserver.admin | OP | 管理命令 |
动态权限 (按子服)
servers.yml → servers.<name>.permission— 访问条件权限servers.yml → open-control.bypass-permission— 该服时段绕过Proxy config.properties → server-open.<name>.bypass-permission— 全局拦截绕过
上一篇← 命令总表
下一篇配置详解 →
配置详解
config.yml (Paper)
| 路径 | 默认 | 说明 |
|---|---|---|
server-name | lobby | 当前子服名 (必须匹配 Velocity) |
stp.cooldown | 3 | STP 冷却秒 |
stp.countdown | 3 | STP 倒计时秒 |
stp.cancel-on-move | true | 移动取消 |
stp.move-tolerance | 0.5 | 容差 (格) |
tp.enabled | true | 启用 ATP |
tp.request-timeout | 60 | TP 请求超时秒 |
tphere.enabled | true | 启用 ATPHere |
home.enabled | true | 启用 home |
home.cooldown | 20 | /home 冷却秒 |
home.countdown | 3 | /home 倒计时秒 |
rtp.enabled | true | 启用 RTP |
rtp.max-attempts | 30 | 安全选点尝试次数 |
rtp.countdown | 3 | RTP 倒计时秒 |
rtp.groups.<name>.* | — | 权限组 (min/max-radius, cooldown, daily-limit) |
back.enabled | true | 启用 /aback |
back.cooldown | 30 | 默认冷却秒 |
back.countdown | 3 | 倒计时秒 |
back.groups.<name>.cooldown | — | 权限组冷却 |
security.max-requests-per-second | 3 | 限流 |
security.log-teleports | true | 传送日志 |
debug | false | 调试 |
闭服控制
| 路径 | 默认 | 说明 |
|---|---|---|
server-open-control.check-interval-seconds | 5 | 检测周期 |
server-open-control.enforce.enabled | true | 闭服滞留处理 |
server-open-control.enforce.block-move | true | 禁移 |
server-open-control.enforce.force-gamemode.* | — | 强制模式 |
server-open-control.enforce.darkness.* | — | 黑暗效果 |
servers.yml (Paper)
servers:
creative:
display: "&b创造服"
permission: "adventureserver.stp.creative"
cooldown: -1 # -1 表示用全局
cost:
money: -1
exp-level: -1
order: 2
open-control:
enabled: true
timezone: "Asia/Shanghai"
time-ranges:
- "19:00-23:30"
bypass-permission: "adventureserver.serveropen.bypass.creative"homes.yml (自动生成)
homes:
550e8400-e29b-41d4-a716-446655440000:
world: "world"
x: 100.5
y: 64.0
z: -32.5
yaw: 90.0
pitch: 0.0Proxy config.properties
connection-failed-message=
shutdown-kick-message=&c[!] 服务器 &e%server% &c已关闭
shutdown-fallback-server=lobby
server-open-control-enabled=true
server-open-bypass-permission=adventureserver.serveropen.bypass
server-open-default-timezone=Asia/Shanghai
server-open-deny-message=&c[!] &e%server% &c当前未开放，开放时段: &e%ranges%
server-open.creative.enabled=true
server-open.creative.timezone=Asia/Shanghai
server-open.creative.time-ranges=19:00-23:30,00:00-01:00
server-open.creative.bypass-permission=adventureserver.serveropen.bypass.creativeℹ️ 建议
Paper 负责功能层限制 (STP/闭服措施)，Proxy 负责入口层拦截 (任何进服路径)，建议都配。
上一篇← 权限矩阵
下一篇消息系统 →
消息系统
支持简写字符串与增强对象两种格式。增强对象支持 type + sound 扩展。
占位符
| 占位符 | 含义 |
|---|---|
%player% | 玩家名 |
%server% / %display% | 服务器名/显示名 |
%time% / %timeout% | 时间秒数 |
%cost% / %amount% / %item% | 消耗相关 |
%world% %x% %y% %z% | 位置 |
%time_ranges% | 开放时段 |
消息类型
chat— 聊天栏 (默认)title— 标题+副标题 (fade-in/stay/fade-out)actionbar— 动作栏bossbar— BossBar (bar-color/bar-style/bar-duration)
消息键分组
| 分组 | 关键键 |
|---|---|
common | player-only, no-permission, cooldown, reload-success 等 |
stp | server-not-found, countdown-*, teleporting, server-entry |
tp | request-sent/received, accepted*, denied*, arrived |
tphere | request-sent/received, accepted*, teleporting |
home | not-set, set-success, countdown-*, teleported |
rtp | daily-limit-reached, searching, failed, success |
back | no-location, success, countdown-* |
server-open-control | closed-enforce, move-blocked, force-transfer |
上一篇← 配置详解
下一篇PlaceholderAPI →
PlaceholderAPI
标识符：as（即 %as_xxx%）
| 占位符 | 返回 | 说明 |
|---|---|---|
%as_home_set% | true/false | 是否设置 home |
%as_home_world% | world 名 | home 世界 |
%as_home_x% / y / z | 坐标 | home 坐标 |
%as_home_cooldown% | 整数秒 | home 剩余冷却 |
%as_server_current% | 子服名 | 当前子服 |
%as_server_open% | true/false | 当前服开放状态 |
%as_current_server_open% | true/false | 同上 (别名) |
%as_server_open_<server>% | true/false | 目标服开放状态 |
%as_server_ranges_<server>% | 19:00-23:30 | 目标服开放时段 |
使用示例
# TAB 示例
&7当前服: &f%as_server_current%
&7是否开放: &f%as_server_open%
&7Home状态: &f%as_home_set%
&7Home冷却: &f%as_home_cooldown%s
# 查询目标服
&7PVP开放: &f%as_server_open_pvp%
&7PVP时段: &f%as_server_ranges_pvp%上一篇← 消息系统
下一篇开发 API →
开发 API
Plugin Message 协议
- 通道：
adventureserver:main - 编码：
DataOutputStream / DataInputStream - 封包：
int typeOrdinal+int dataCount+UTF string[dataCount] - 限制：最大 32KB / 64 字段；Paper 待发队列上限 50
MessageType 枚举
PLAYER_LOOKUP # Paper→Proxy [lookupId, targetName]
PLAYER_LOOKUP_RESPONSE # Proxy→Paper [lookupId, name, uuid, server]
TP_REQUEST # Paper→Proxy→Paper [senderUuid, name, targetUuid, timeout]
TPHERE_REQUEST # Paper→Proxy→Paper [senderUuid, name, targetUuid, timeout]
TP_ACCEPT # Paper→Proxy→Paper [senderUuid, accepterName, uuid, type, ...]
TP_DENY # Paper→Proxy→Paper [senderUuid, denierName, type]
TP_CANCEL # Paper→Proxy→Paper [targetUuid]
TP_EXECUTE # Proxy→Paper [arrivedUuid, targetUuid, targetName]
TP_LOCATION # Paper→Proxy→Paper [uuid, world, x, y, z, yaw, pitch]
PLAYER_LIST_REQUEST # Paper→Proxy []
PLAYER_LIST_RESPONSE # Proxy→Paper [server, playersCsv, ...]
CONNECT_SERVER # Paper→Proxy [uuid, targetServer, (targetPlayerUuid)]
PLAYER_ARRIVED # Proxy→Paper [uuid, name]
RELOAD # Proxy→Paper []
SERVER_NOT_FOUND # Proxy→Paper [uuid, targetServerName]Java 类接口
| 类 | 关键方法 |
|---|---|
AdventureServerPaper | getConfigManager(), getTpManager(), getHomeManager(), getServerOpenManager(), getRtpManager(), getBackManager(), reloadAll() |
ProxyMessageManager | onMessage(type, handler), sendToProxy(type, data...), connectServer(...) |
ConfigManager | sendMessage(player, key, replacements...) |
HomeManager | setHome(), teleportHome(), getHome(), getRemainingCooldown() |
ServerOpenManager | canEnterServer(), isServerOpenNow(), getTimeRangesDisplay() |
RtpManager | executeRtp(), getPlayerGroup(), cancelRtp(), reload() |
BackManager | executeBack(), recordDeath(), cancelBack() |
⚠️ 注意
MessageType 枚举顺序是协议的一部分，Proxy/Paper 任一侧变化都会导致消息错读。
上一篇← PlaceholderAPI
下一篇运维排错 →
运维与排错
常见问题
| 现象 | 排查点 |
|---|---|
/stp 服务器不存在 | 检查所有子服 servers.yml 一致 + 目标名拼写 |
| 请求发了传送不执行 | Proxy 插件是否在线、通道是否注册、目标在线 |
| 时段限制不生效 | open-control.enabled + 时区 + 格式 H:mm-H:mm |
| 玩家被错误拦截 | 缺少绕过权限 (全局或子服 bypass) |
| PAPI 空值 | 确认 PAPI 已装 + 启动日志有「占位符已注册」 |
推荐运维流程
- 测试服验证
servers.yml+ Proxyconfig.properties - 上线前统一分发配置到所有子服
/asadmin reload→/stp reload确认- 管理员验证：普通进服 / /stp 路径 / 绕过权限 三种场景
上一篇← 开发 API
下一篇更新日志 →
更新日志
v1.6.0 最新
- NEW RTP 随机传送 — /artp 安全选点，权限组范围/冷却/每日次数
- NEW RTP 世界规则 — servers.yml 按子服+世界配置中心点/Y范围/形状
- NEW Back 死亡返回 — /aback 返回死亡点，连续往返
- NEW Back 权限组 — 按组配冷却
- NEW 闭服扣血 — health-drain 每X秒扣Y HP
- NEW 闭服强制传送 — force-transfer 延迟后传到指定子服
v1.5.0
- NEW 关服自定义消息 (shutdown-kick-message + %server%/%player%)
- NEW 关服自动重定向 (shutdown-fallback-server)
- NEW 目标服不存在提示 (SERVER_NOT_FOUND)
- FIX TpManager 异步回调 null/isOnline 防护
- NEW AdventureManage FlyCard/ExpCard 跨服保存
v1.4.0
- NEW 子服限定开放机制 (Paper 时段准入 + 闭服滞留)
- NEW Home 功能 (/sethome + /home + homes.yml)
- NEW PAPI 占位符 (home/开放状态/时段)
- NEW Proxy 层开放时间拦截
v1.3.0
- NEW 消息配置自动补全 (merge defaults)
上一篇← 运维排错