ServerTeleport

面向 Velocity 的切服别名插件：在 config.yml 中把短命令（如 /zf）映射到后端服务器，效果等价于玩家执行 /server <服务器ID>。游戏内提示与代理日志支持中文 / 英文（默认中文）。

English: Registers configurable shortcuts that connect players via Velocity’s connection API (not by re-invoking the built-in /server parser). Supports zh / en / auto locale for messages and console logs.

赞助： 爱发电

---

功能一览

能力	说明
别名映射	aliases：命令名 → velocity.toml 中的服务器 ID；键可写 zf 或 /zf
默认全员可用	servertp_permissions 默认 false，不校验 servertp.*
细粒度权限	servertp_permissions: true 时需 servertp.use 或 servertp.alias.<命令>
按当前服限命令	可选 server_commands：非空时为后端白名单；未列出的服不能用别名；可写 */true 表示该服允许全部
管理命令	/servertp、/stp、/serverteleport：help、list（可用别名）、reload 热重载
体验	可选冷却与切换前提示；连接进行中防重复点击；已在目标服时直接提示；启动时校验 aliases 目标与 server_commands 键是否在代理已注册
双语	language: zh / en / auto；全部玩家提示与控制台日志文案在 lang.yml 中按 zh / en 配置，可与 jar 内默认合并覆盖

---

快速上手

1. 将构建或下载的 JAR 放入 Velocity 的 plugins/ 目录。
2. 启动代理一次，确认 plugins/serverteleport/config.yml 已生成。
3. 在 velocity.toml 的 [servers] 中配置好后端名称，使与 aliases 里的值一致。
4. 编辑 aliases（以及可选的 server_commands），执行 /servertp reload（或 /stp reload）。
5. 玩家在游戏内直接输入注册的别名（如 /hub），无需带 /server 前缀。

热重载会同时读取 config.yml 与 lang.yml，一般无需重启代理。

---

环境要求

• Java 17+
• Velocity 3.x（构建依赖 API 3.3.0-SNAPSHOT；生产环境请使用与代理发行版匹配的 API / 插件版本，避免 SNAPSHOT 漂移）

构建与产物

mvn clean package

生成：target/serverteleport-<version>.jar（版本见 pom.xml）。

安装

1. 将 JAR 放入 Velocity plugins/。
2. 启动代理后，数据目录会生成 plugins/serverteleport/config.yml 与 lang.yml（首次从插件内复制默认文件）。
3. 修改 config.yml 或 lang.yml 后执行 /servertp reload（或 /stp reload / /serverteleport reload）即可生效，无需重启 Velocity。玩家可执行 /servertp help 或 /servertp list 查看说明与可用别名。

从旧版迁移： 若曾使用插件 ID servertpalias，请将原目录 plugins/servertpalias/（含 config.yml）移动或合并到 plugins/serverteleport/。若曾使用 extra_permission / permission 键，请改在权限插件中单独配置等价限制（本插件已不再读取这两项）。

自定义 lang.yml：若覆盖了 log_startup_summary，请改为 4 个占位符 {0}…{3}（已去掉原「额外权限」段）。

---

配置文件

路径： plugins/serverteleport/config.yml

键	说明
language	zh / en / auto（auto 时客户端语言以 en 开头则用英文，否则中文）
servertp_permissions	false（默认）：不要求 servertp.*。true：需 servertp.use 或 servertp.alias.<命令>
aliases	切服别名 → 目标服务器 ID（须与代理中已注册后端一致，见 Velocity 文档 · 配置服务器）
server_commands	（可选）后端服 ID → 允许的别名；映射非空时仅列出的服可用切服别名，未列出的服不可用；不写或 {} 则不按服限制。某服写 *、all、true 或列表含 */all 表示该服允许全部已注册别名；[] 或 YAML 布尔 false 表示该服禁止全部
debug	true 时，因 server_commands 拒绝使用别名时向代理日志输出 DEBUG（玩家、UUID、当前服、命令）
teleport_cooldown_millis	同一玩家两次发起切换的最小间隔（毫秒），0 表示不限制；仅限制发起频率，不保证连接一定成功
connecting_message	发起连接前向玩家发送该纯文本（灰色）。jar 内默认有一句中文提示；设为空字符串 "" 则关闭

lang.yml

路径： plugins/serverteleport/lang.yml

• 顶层为 zh:、en: 两段；其下为字符串键（如 players_only）与可选列表键（如 admin_help_lines，多行帮助）。
• 玩家体验：connection_success（{0} 为目标服 ID，留空字符串则不发送成功提示）、connect_in_progress（已有连接进行中时再点别名）、already_on_target_server、teleport_cooldown、connection_failed 等。
• /servertp help 中的 server_commands 摘要：help_sc_off / help_sc_on、help_sc_line（{0} 后端名、{1} 规则说明）、sc_rule_none / sc_rule_all（规则后缀文案）。
• 占位符使用 Java MessageFormat：{0}、{1} …（文案中需要字面量单引号时用 ''）。
• 磁盘文件与 jar 内默认 按键合并：只写需要覆盖的键即可；若文件损坏或 YAML 无效，回退为 jar 内默认英文/中文包。
• /servertp reload 会同时重新加载 config.yml 与 lang.yml。

server_commands 行为摘要

• 未配置或 server_commands: {}：不按当前服限制（仍受 aliases、servertp_permissions 等约束）。
• 配置了至少一个服：形成白名单——只有键中的后端可以使用切服别名；不在表中的后端一律不能使用。
• 玩家在已列出的后端上：若值为 *、all、true（或列表里出现 * / all），则允许全部已注册别名；若为 [] 或 YAML 布尔 false，则该服上不能用任何别名；若为列表或逗号分隔字符串，则仅允许其中的别名（名称小写、去前导 /）。

配置陷阱： 若写成引号字符串 "false"，YAML 会当作普通字符串而非布尔值，可能被解析成名为 false 的别名而不是「全禁」。禁止某服上的全部别名请使用 YAML 布尔 false、空列表 []，或不要列出允许项。

配置示例

language: zh
servertp_permissions: false
teleport_cooldown_millis: 3000
connecting_message: "正在切换服务器，请稍候…"

aliases:
  zf: survival-main
  hub: lobby

# 白名单示例：仅 lobby、survival-main 可用别名；其它后端不能用
# server_commands:
#   lobby:
#     - zf
#     - hub
#   survival-main: '*'   # 或 true / all，表示该服允许全部别名

---

管理命令

主命令 servertp，等价别名 stp、serverteleport。

子命令	作用	玩家权限
help	显示插件说明（配置路径、reload 权限说明等），末尾附带当前 server_commands 规则摘要	无（所有玩家可用）
list	列出切服别名：玩家仅见当前有权限且所在服允许的项；控制台列出全部已注册项	无
reload	从磁盘重新加载 config.yml 与 lang.yml，并刷新切服别名注册	servertp.reload（ServerTeleportPlugin.PERMISSION_RELOAD）；控制台无需权限

示例：/servertp help、/servertp list、/stp reload。

Tab 补全： 管理命令的首个子命令（help / list / reload）支持补全；无 servertp.reload 权限的玩家不会看到 reload。个别 Velocity 版本在「命令 + 空格」时参数数组可能为空，插件已按兼容方式处理。

重载时先读取 config.yml 与 lang.yml，再完整解析并注销旧别名、注册新别名，避免读盘失败导致别名被清空。

---

权限节点（LuckPerms 等）

节点	何时生效
servertp.reload	使用管理命令的 reload（不含 help / list）
servertp.use	仅当 servertp_permissions: true 时，允许使用全部切服别名
servertp.alias.<命令>	仅当 servertp_permissions: true 时，允许使用单个别名（小写、无 /，如 servertp.alias.zf）

默认（servertp_permissions: false）下不要求上述 servertp.use / servertp.alias.*。

代码常量：ServerTeleportPlugin.PLUGIN_NAME、PERMISSION_USE_ALL、PERMISSION_ALIAS_PREFIX、PERMISSION_RELOAD。

---

玩家侧行为

场景	行为
非玩家执行别名（如控制台）	提示仅玩家可用（文案见 lang.yml players_only）
当前所在后端不在 server_commands 白名单内（且白名单已启用）	拒绝并提示；debug: true 时代理打 DEBUG
servertp_permissions: true 且无对应权限	命令不可见/不可用（与 Velocity 权限检查一致）
已在目标后端	提示已在该服，不发起新连接
上一次连接尚未完成（异步回调未结束）	提示「连接进行中」，避免重复请求
冷却未结束	提示剩余秒数；冷却在发起连接时更新，与最终是否连上无关
目标服务器在代理未注册	提示未找到服务器
连接失败或结果非成功	优先展示 Velocity 返回的 ReasonComponent，否则展示失败原因字符串

别名命令的 Tab 补全在玩家无权限或当前服不允许时通常返回空列表；补全目标服 ID 一项主要用于与配置的 ID 一致。

---

日志与调试

日志与玩家消息的具体句子来自 lang.yml；选用 zh 还是 en 段由 language（及玩家的 auto）决定，规则与此前一致。

级别	内容
INFO	启动： 开始加载（版本、数据目录）、配置路径、权限模式、server_commands、已注册别名数量、启动摘要（language / 别名数 / servertp. / server_commands）、插件启用、管理命令注册、热重载前后别名数量
WARN	未配置任何别名、无效别名项、规范化后重复的别名、与管理命令冲突的别名、aliases 目标或 server_commands 键在代理上不存在、server_commands 引用了未成功注册的别名
ERROR	配置加载失败、别名或管理命令注册失败、热重载异常
DEBUG	每个成功注册的 别名 → 目标服；各服务器的允许别名列表；debug: true 时还包括按服拒绝别名的详情

---

注意事项

1. 勿占用管理命令名：servertp、stp、serverteleport 已用于 help / reload；若写入 aliases 会在加载时 WARN 并跳过。规范化后重复的别名（如同时写 Zf 与 zf）仅保留先出现的一条，其余会 WARN。
2. server_commands 的键须与 Velocity 里该后端在代理侧显示的服务器名称一致（与 velocity.toml 中 [servers] 名称对应）。
3. 插件 ID 为 serverteleport，数据目录为 plugins/serverteleport/，与游戏内命令名无关。
4. 玩家断开与代理的连接时，会清理该玩家的冷却时间戳与「连接进行中」标记；代理关闭时仍会整表清空。重连后冷却重新计数（不再沿用断线前的间隔）。

---

English quick reference

What it does: Maps shortcut commands to backend servers on Velocity (same effect as /server <id> for players).

Site: npucraft.com · Maven: com.npucraft:serverteleport

Config: plugins/serverteleport/config.yml · Strings: plugins/serverteleport/lang.yml

Key	Notes
language	zh (default), en, auto (non-English clients → Chinese)
servertp_permissions	default false (no servertp.* checks). true → need servertp.use or servertp.alias.<name>
aliases	alias → registered server ID
server_commands	Optional whitelist: when non-empty, only listed backends may use aliases; unlisted backends cannot. Omit or {} for no per-server rule. Use *, all, or true (or list with */all) for all aliases on that backend; [] or YAML boolean false blocks all there. Do not use quoted "false" if you mean “deny all” — that may be parsed as a literal alias name.

Admin: help (everyone) and reload (console or servertp.reload) on /servertp, /stp, /serverteleport.

Permissions: With servertp_permissions: true, nodes are servertp.use, servertp.alias.<name>; servertp.reload only for the reload subcommand.

Build: mvn package → target/serverteleport-<version>.jar.

Do not use servertp, stp, or serverteleport as entries in aliases.