• 欢迎加入MineBBS QQ讨论群：点击查看所有的官方讨论群
  • 我们将于近期对服务器进行迁移，服务可能中断至多2日。请各位安排好自己的访问计划，造成不便敬请谅解！
  • MineBBS入站考试已经上线！想要成为【正式会员】解锁更多功能吗？快来参与吧！【点我去看】
VelocityPlayerStatus — 跨服玩家状态占位符插件

原创 VelocityPlayerStatus — 跨服玩家状态占位符插件 2026-08-17

请登录后获取
概述 更新 （1） 历史版本 讨论区 已兑换
版权类型
原创
插件中文名称
VelocityPlayerStatus
插件英文名称
VelocityPlayerStatus
原帖地址
#
支持的核心（代理-服务端）
  1. Velocity
  2. PaperSpigot
语言支持
中文（简体）
前置组件
PlaceholderAPI+https://www.minebbs.com/resources/placeholderapi.8229/
适配版本（Java）
  1. 最新版本
  2. 26.x
  3. 1.21
  4. 1.20
  5. 1.19
  6. 1.18
  7. 1.17
  8. 1.16
  9. 1.15
  10. 1.14
  11. 1.13

一、简介​

VelocityPlayerStatus 是一个面向 Velocity 群组服的玩家状态查询插件，由 Velocity 代理端与 Paper/Bukkit 子服端配合工作。子服侧通过 PlaceholderAPI 暴露一组统一前缀的占位符，可在记分板、TAB、菜单、NPC 对话、Join/Quit 提示等任意支持 PAPI 的场景中，实时展示任意玩家或当前玩家的在线状态、所在子服、首次记录时间、最后上线/离线时间，以及全服/单服在线人数。
无论是给管理员做监控面板，还是给玩家做"好友在线状态"展示，都能开箱即用。

二、核心特性​

  • 双端协同：Velocity 端负责统一收集与分发，子服端只负责占位符注册，互不干扰。
  • 任意玩家查询：传入玩家名即可查询历史记录，无需该玩家在线。
  • 持久化存储：玩家状态写入 players.properties，重启不丢失。
  • HTTP + Token 鉴权：内嵌轻量 HTTP 服务，子服通过 token 鉴权拉取，安全可控。
  • 高频抗性：子服端内置 TTL 缓存，记分板/菜单秒级刷新也不会打爆代理端。
  • 零额外依赖：Velocity 端无第三方依赖；子服端仅需 PlaceholderAPI（软依赖）。
  • 全 PAPI 兼容：所有占位符遵循 %vstatus_<...>% 命名，直接被 PAPI 识别。

三、工作原理​

JavaScript： 
┌──────────────── Velocity 代理端 ────────────────┐
│  VelocityPlayerStatus                            │
│   ├─ 监听 PostLogin / ServerConnected / Disconnect│
│   ├─ StatusStore（players.properties 持久化）    │
│   └─ StatusHttpServer（127.0.0.1:8765，token 鉴权）│
└───────────────────────┬─────────────────────────┘
                        │  HTTP + token
                        ▼
┌──────────── Paper / Spigot 子服端 ──────────────┐
│  VelocityStatusPlaceholder                       │
│   ├─ VelocityStatusClient（带 TTL 缓存）         │
│   └─ StatusExpansion → PlaceholderAPI 占位符     │
└──────────────────────────────────────────────────┘

四、占位符一览​

1. 指定玩家变量（需带玩家名）​

代码： 
%vstatus_online_<玩家名>% - 显示指定玩家在线或离线
%vstatus_status_<玩家名>% - 显示指定玩家在线或离线
%vstatus_raw_<玩家名>% - 显示指定玩家原始状态，返回 online、offline、unknown
%vstatus_server_<玩家名>% - 显示指定玩家当前所在子服
%vstatus_name_<玩家名>% - 显示记录里的玩家名
%vstatus_first_seen_<玩家名>% - 显示指定玩家首次被记录的时间
%vstatus_last_online_<玩家名>% - 显示指定玩家最后上线时间
%vstatus_last_offline_<玩家名>% - 显示指定玩家最后离线时间
%vstatus_last_seen_<玩家名>% - 显示指定玩家最后在线时间

2. 当前玩家变量（自动取触发占位符的玩家）​

代码： 
%vstatus_online% - 显示当前玩家在线或离线
%vstatus_status% - 显示当前玩家在线或离线
%vstatus_raw% - 显示当前玩家原始状态，返回 online、offline、unknown
%vstatus_server% - 显示当前玩家所在子服
%vstatus_name% - 显示当前玩家记录名
%vstatus_first_seen% - 显示当前玩家首次被记录的时间
%vstatus_last_online% - 显示当前玩家最后上线时间
%vstatus_last_offline% - 显示当前玩家最后离线时间
%vstatus_last_seen% - 显示当前玩家最后在线时间

3. 全服 / 单服在线人数​

代码： 
%vstatus_total_online% - 显示 Velocity 当前总在线人数
%vstatus_all_servers_online% - 显示所有子服务器加起来的在线人数
%vstatus_servers_online% - 显示所有子服务器加起来的在线人数
%vstatus_servers_total_online% - 显示所有子服务器加起来的在线人数
%vstatus_server_online_<子服名>% - 显示指定子服务器当前在线人数
提示：%vstatus_online% 与 %vstatus_status%、%vstatus_all_servers_online% 与 %vstatus_servers_online%/%vstatus_servers_total_online% 为同义别名，按习惯选用即可。

五、命令与权限​

代码： 
【Velocity 端】
  /vstatus reload   — 重载配置         [权限：velocitystatus.admin]
  /vstatus info     — 查看运行信息     [权限：velocitystatus.admin]
  /vstatus list     — 列出在线玩家     [权限：velocitystatus.admin]
  别名：/vpstatus

【子服端 Paper/Spigot】
  /vstatusbukkit reload    — 重载配置           [权限：vstatusbukkit.admin → 默认 OP]
  /vstatusbukkit list      — 列出占位符清单     [权限：vstatusbukkit.admin → 默认 OP]
  /vstatusbukkit online    — 查询在线人数       [权限：vstatusbukkit.admin → 默认 OP]
  /vstatusbukkit players   — 查看玩家记录       [权限：vstatusbukkit.admin → 默认 OP]

六、配置说明​

Velocity 端​

bind-host=127.0.0.1 # HTTP 服务监听地址，仅本机访问保持默认即可
port=8765 # HTTP 服务监听端口
token=change-me # 鉴权 token，务必修改并同步到所有子服

子服端​

proxy-api:
# Velocity 端 HTTP 查询地址，子服与 Velocity 同机时保持默认
base-url: "http://127.0.0.1:8765"
token: "change-me" # 与 Velocity 端 config.properties 保持一致
connect-timeout-ms: 800
read-timeout-ms: 1200

cache:
# 占位符缓存时间，避免计分板/菜单高频刷新时重复请求代理端
player-status-ms: 3000
total-online-ms: 1000

display:
online: "&a在线"
offline: "&c离线"
unknown: "&7未知"
no-server: "&7无"
time-format: "yyyy-MM-dd HH:mm:ss"
never: "&7从未记录"
]

七、安装步骤​

  1. 确认环境：Velocity 3.4.0+（代理端），Paper/Spigot 1.13+（子服端，需已安装 PlaceholderAPI）。
  2. 部署代理端：将 velocity-status-proxy-1.0.0.jar 放入 Velocity 的 plugins/ 目录，启动一次以生成 config.properties。
  3. 部署子服端：将 velocity-status-bukkit-1.0.1.jar 放入每个子服的 plugins/ 目录，启动一次以生成 config.yml。
  4. 统一 token：修改 Velocity 端 config.properties 中的 token，并保持子服端 config.yml 中的 token 一致（默认 change-me，请务必修改）。
  5. 重启 / reload：执行 /vstatus reload（Velocity 端）与 /vstatusbukkit reload（子服端）即可生效，无需全服重启。

八、典型使用场景​

  • TAB/记分板：%vstatus_server% 显示当前玩家所在子服，%vstatus_total_online% 显示全服在线人数。
  • 好友系统：%vstatus_online_&lt;好友名&gt;% 显示好友在线状态，%vstatus_last_seen_&lt;好友名&gt;% 显示上次在线时间。
  • 管理面板：用 %vstatus_raw_&lt;玩家名&gt;% 拿到原始 online/offline/unknown 三态，配合脚本做条件判断。
  • 欢迎/离线提示：玩家上线显示 %vstatus_first_seen%（首次到访时间）做老玩家回归奖励。

九、兼容性​

  • Velocity API 3.4.0-SNAPSHOT（含旧版兼容层 VelocityCompat，反射兼容老版本 ServerConnection）。
  • Paper / Spigot / Bukkit 1.13+。
  • 需 PlaceholderAPI（软依赖，未安装时占位符不生效但不会崩服）。
反馈与建议欢迎在帖子下方留言。
PixelCloud 一键开服
作者
119
价格
100.00金粒
下载
3
查看
58
首次发布
最后更新

评分

0.00 星 0 次评分
参与讨论

119 的其他资源

分享资源

旋律云高性能云服务器
后退
顶部 底部