原创 前置/API BCOnlineStats 在线时长统计 1.0.0

一、概述​

BCOnlineStats 是一款运行于 BungeeCord 的跨服在线时长统计插件，专为多服务器网络环境设计。


插件采用集中式架构，在代理层统一统计玩家在线时间，并根据配置规则自动完成任务判定、数据同步与奖励提示，从而实现高一致性、高性能的在线统计系统。

---

二、引言​

在传统的多服务器架构中（例如大厅 + 子服 + 小游戏），玩家在线时间通常分散记录在各个 Spigot 服务器中，这会带来一系列问题：

• 统计数据不一致
• 玩家切换服务器时可能丢失在线时间
• 无法实现跨服统一任务
• 每个子服都需要重复部署统计逻辑

BCOnlineStats 的设计目标是将所有统计逻辑统一集中在 BungeeCord 层，从根本上解决跨服统计问题。


通过这一架构，玩家无论处于哪个子服务器，其在线时间都由代理层统一计算，并参与全局任务系统。

---

三、功能实现​

1. 全局在线时长统计​

插件自动记录玩家的上线、切服和下线行为，支持多种统计范围：

• 全服统计（all）
• 单服务器统计
• 多子服聚合统计（适用于小游戏房间）

---

2. 多周期任务系统​

支持多种任务周期类型：

• once：一次性任务，仅触发一次
• daily：每日任务，按自然日重置
• week：周任务，按 7 天周期重置
• month：月任务，按自然月重置

---

3. 智能规则判定​

• 自动检测玩家是否达成目标在线时间
• 内置防重复触发机制
• 支持周期性自动重置
• 达成后自动发送提示消息

---

4. 服务器组统计（核心特性）​

支持将多个子服务器合并为一个统计组，例如：



server-groups:
bedwars:
- bedwarsroom1
- bedwarsroom2
- bedwarsroom3


玩家在这些服务器中的在线时间将统一累计，用于任务判定与统计。

---

5. 跨服数据同步​

• 内置 TCP 通信（默认端口 13000）
• 实时向 Spigot 端插件同步数据
• 支持多子服务器同时接入

---

6. Placeholder 数据输出​

BungeeCord 端负责生成变量数据，由 Spigot 端通过 PlaceholderAPI 进行调用与展示（配合 Spigot-online-stats-bridge 插件使用）。

---

四、config.yml 讲解​

配置文件路径：




plugins/BCOnlineStats/config.yml

---

1. 网络配置​

network:
bind-host: 0.0.0.0
bind-port: 13000
auth-token: "change_this_token"



说明：

• bind-host：监听地址
• bind-port：通信端口
• auth-token：通信鉴权密钥（必须与 Spigot 端一致）

---

2. 系统参数​

settings:
tick-seconds: 30
sync-seconds: 15
save-seconds: 60



说明：

• tick-seconds：计时周期（建议 30 秒）
• sync-seconds：数据同步频率
• save-seconds：数据保存周期

---

3. 服务器组配置​

server-groups:
bedwars:
- bedwarsroom1
- bedwarsroom2



说明：


用于将多个子服务器合并为一个统计单位，常用于小游戏房间。

---

4. 规则配置（核心）​

示例：




rules:
bc_daily_30m:
enabled: true
status: daily
server: all
target-minutes: 30

message:
- "&e[奖励系统] 您已完成每日在线30分钟"

papi: "bc_onlinetime_daily"
papitype: "addup"



字段说明：


status（任务类型）

• once：一次性任务
• daily：每日任务
• week：每 7 天重置
• month：每月重置

server（统计范围）

• all：全服务器
• irontown：指定单服务器
• bedwars：服务器组

papitype（变量类型）

• once：返回 0 / 1 状态
• addup：返回累计分钟数

---

五、权限节点配置​

插件权限设计简洁，主要用于管理操作：

• bconlinestats.admin：管理员权限
• bconlinestats.reload：允许重载配置
• bconlinestats.query：允许查询玩家数据

指令权限示例：

• /bcstats reload 需要 reload 权限
• /bcstats player <玩家> 需要 query 权限

---

六、配置优势​

1. 完全中心化​

所有统计逻辑运行于 BungeeCord 层，避免多服务器数据不一致的问题。

2. 高扩展性​

• 支持任意规则组合
• 支持自定义变量名称
• 可扩展复杂玩法逻辑

3. 适配小游戏网络​

• 支持房间聚合统计
• 支持跨服累计在线时间

4. 无侵入式设计​

Spigot 端仅负责展示数据，不影响现有插件体系。

5. 高性能​

• 采用定时批处理机制，避免高频计算
• 使用内存缓存提升效率
• 网络通信开销低

---

七、适用场景​

小游戏服务器​

• BedWars
• SkyWars
• PvP 房间

用于多房间统一在线时长统计。

---

大型群组服务器​

• 大厅 + 多子服架构
• RPG / 生存 / 创造服务器

用于构建全服活跃度系统。

---

奖励系统​

• 每日在线奖励
• 周常任务
• 月度活动

---

玩家成长系统​

• 在线时长等级
• 活跃度积分
• 成就系统

---

八、总结​

BCOnlineStats 的核心优势在于，将“统计”与“展示”彻底分离，通过 BungeeCord 实现统一计算，从根本上解决跨服在线时长统计问题。