📥 安装与部署

环境要求

部署步骤

1. 将 AdventureServer-Proxy-1.6.0.jar 放入 Velocity plugins/
2. 将 AdventureServer-Paper-1.6.0.jar 放入每个子服 plugins/
3. 每个子服配置 config.yml -> server-name，必须与 Velocity 注册名一致
4. 所有子服统一 servers.yml
5. 启动后用 /stp reload（Paper）与 /asadmin reload（Proxy）同步重载

⌨️ 命令总表

玩家命令（Paper）

管理员命令

🔐 权限矩阵

动态权限（按子服配置）

• servers.yml -> servers.<name>.permission：访问该子服的条件权限
• servers.yml -> open-control.bypass-permission：绕过该子服时段限制
• Proxy config.properties -> server-open.<name>.bypass-permission：Proxy 全局拦截绕过

⚙️ 配置详解

config.yml（Paper）

servers.yml（Paper）

servers:
  creative:
    display: "&b创造服"
    permission: "adventureserver.stp.creative"
    cooldown: -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.0

Proxy config.properties

# 连接失败提示（留空=隐藏默认消息）
connection-failed-message=&c[!] &e%server% &c服务器暂时不可用

# 子服关闭/被踢时的自定义提示
shutdown-kick-message=&c[!] 服务器 &e%server% &c已关闭

# 子服关闭后玩家重定向到的备用服务器（留空=不重定向）
shutdown-fallback-server=lobby

# Proxy层开放时间拦截（拦截非 /stp 进服）
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%

# creative 子服规则
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

💬 消息系统 (messages.yml)

支持简写字符串与增强对象。增强对象支持 type + sound + title/bossbar 扩展参数。

占位符

类型字段

• chat — 聊天栏（默认）
• title — 标题+副标题（支持 fade-in/stay/fade-out）
• actionbar — 动作栏
• bossbar — BossBar（支持 bar-color/bar-style/bar-duration）

关键消息键

🔗 PlaceholderAPI

标识符: as（即 %as_xxx%），安装 PlaceholderAPI 后自动注册。

使用示例

# 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 详解

核心通道协议

• 通道: adventureserver:main
• 编码: DataOutputStream / DataInputStream
• 封包: int typeOrdinal + int dataCount + UTF string[dataCount]
• 限制: 最大 32KB, 最大 64 字段; Paper 待发队列上限 50

MessageType 枚举

PLAYER_LOOKUP / PLAYER_LOOKUP_RESPONSE
TP_REQUEST / TPHERE_REQUEST
TP_ACCEPT / TP_DENY / TP_CANCEL / TP_EXECUTE
TP_LOCATION
PLAYER_LIST_REQUEST / PLAYER_LIST_RESPONSE
CONNECT_SERVER / PLAYER_ARRIVED / RELOAD
SERVER_NOT_FOUND

消息字段

Java 类接口

🛠️ 运维与排错

常见问题

推荐运维流程

1. 先在测试服验证 servers.yml + Proxy config.properties 的开放规则
2. 上线前统一分发配置到所有 Paper 子服
3. 执行 /asadmin reload 后，再在任意子服执行 /stp reload
4. 验证：普通进服、/stp 路径、绕过权限三种场景

📝 更新日志

v1.6.0

• NEW RTP 随机传送 — /artp 随机传送到当前世界安全位置，参考 BetterRTP 安全选点算法（圆形/方形均匀分布）
• NEW RTP 权限组范围 — 按 default/plus/vip/mvp/pro/max 分组配置传送范围、冷却、每日次数限制
• NEW RTP 世界规则 — 在 servers.yml 按子服+世界名配置中心点/Y范围/形状，支持下界
• NEW Back 死亡返回 — /aback 返回最近死亡点；多次死亡取最后一次；使用后当前位置成为新 back 点
• NEW Back 权限组 — 按权限组配置不同冷却时间
• NEW 闭服扣血 — servers.yml open-control.enforce.health-drain，每X秒扣Y生命值
• NEW 闭服强制传送 — servers.yml open-control.enforce.force-transfer，延迟后强制传送到指定子服
• CONFIG 新增配置项 — rtp.* 和 back.* 配置区块；servers.yml rtp.* 世界规则
• CONFIG 新增消息键 — rtp.*, back.*, server-open-control.health-drain, server-open-control.force-transfer

v1.5.0

• NEW 关服自定义消息 — Proxy shutdown-kick-message 配置项，替代 Velocity 默认的 "close server" 提示，支持 %server%/%player% 占位符
• NEW 关服自动重定向 — Proxy shutdown-fallback-server 配置项，子服关闭后自动将玩家传送到指定备用服（如 lobby）
• NEW 目标服务器不存在提示 — 当跨服目标不可达时，Proxy 直接通知玩家并通过 SERVER_NOT_FOUND 消息通知 Paper 端
• FIX 玩家断线/闪退报错 — TpManager 所有异步回调增加 null/isOnline 防护，消除 NPE 崩溃日志
• NEW AdventureManage 卡片数据保存 — 跨服传送前自动通过反射调用 AdventureManage 的 FlyCard/ExpCard 保存方法
• CONFIG softdepend 更新 — plugin.yml 新增 AdventureManage 为可选依赖

v1.4.0

• NEW 子服限定开放机制（Paper 时段准入 + 闭服滞留限制）
• NEW Home 功能：/sethome、/home、homes.yml 持久化
• NEW PAPI 占位符：home 状态、开放状态、时间段
• NEW Proxy 层开放时间拦截（全路径入服控制）
• 命令/权限/文档全面同步到 v1.4.0

v1.3.0

• IMPROVED 消息配置自动补全（merge defaults），旧文件缺少 key 自动写入
• 增强启动日志