LsLiveTime是一款B站直播在线计时插件，适用于KCauldron 1.7.10以及Spigot、PaperSpigot 1.8至1.12.2等Bukkit系服务端[注:1.8-1.12.2未测试，理论支持]。
玩家可通过指令绑定自己的B站UID，当玩家保持游戏在线且对应直播间处于开播状态时，插件会每分钟自动检查一次。首次满足条件只记录状态，不增加时间；从第二次连续满足条件开始，每次累计一分钟。玩家退出服务器、直播结束、解绑或更换UID后，将重新进行首次判定。插件支持绑定、解绑、累计时间查询、管理员查询、手动检查[注：增加一次时间]、时间设置和配置重载等功能，所有网络请求均异步执行，避免阻塞服务器主线程。数据自动保存至YAML文件，并提供重复UID限制、连接超时、失败重试及异常保护。插件没有强制前置，安装PlaceholderAPI后可使用累计分钟、小时、格式化时间、绑定UID和直播状态等变量，同时提供Bukkit服务API与计时事件，方便其他插件进行排行榜、称号、任务及奖励系统开发。项目采用MIT许可证开源，支持Windows和Linux，配置文件统一使用UTF-8编码。
玩家可通过指令绑定自己的B站UID，当玩家保持游戏在线且对应直播间处于开播状态时，插件会每分钟自动检查一次。首次满足条件只记录状态，不增加时间；从第二次连续满足条件开始，每次累计一分钟。玩家退出服务器、直播结束、解绑或更换UID后，将重新进行首次判定。插件支持绑定、解绑、累计时间查询、管理员查询、手动检查[注：增加一次时间]、时间设置和配置重载等功能，所有网络请求均异步执行，避免阻塞服务器主线程。数据自动保存至YAML文件，并提供重复UID限制、连接超时、失败重试及异常保护。插件没有强制前置，安装PlaceholderAPI后可使用累计分钟、小时、格式化时间、绑定UID和直播状态等变量，同时提供Bukkit服务API与计时事件，方便其他插件进行排行榜、称号、任务及奖励系统开发。项目采用MIT许可证开源，支持Windows和Linux，配置文件统一使用UTF-8编码。
# LsLiveTime 使用者文档
## 1. 环境与安装
支持目标：
- KCauldron 1.7.10 + Java 8
- PaperSpigot/Spigot 1.12.2 + Java 8
支持 Windows 和 Linux。插件不依赖操作系统命令、本地动态库或固定盘符，同一个 JAR 可以在两个系统上使用。
### 文件编码
插件源码、`config.yml`、`players.yml` 和 B 站接口 JSON 统一使用 **UTF-8**。用记事本、Notepad++、VS Code 或服务器面板修改 YAML 时，请选择“UTF-8”保存，不要转换成 ANSI、GBK 或 UTF-16，否则中文消息可能乱码，严重时 YAML 会无法读取。
Windows 控制台本身的中文显示可能受终端代码页影响；如果只有控制台乱码而游戏内消息和配置文件正常，一般不是插件数据损坏。Linux 环境建议保持系统 locale 为 UTF-8。
把 `LsLiveTime-1.0.0.jar` 放进服务端 `plugins` 目录，然后**完整重启**服务器。首次启动会生成：
- `plugins/LsLiveTime/config.yml`：配置与消息。
- `plugins/LsLiveTime/players.yml`：绑定和累计时间；不要在服务器运行时手工编辑。
PlaceholderAPI 为可选插件。不安装时，绑定、查询和计时仍正常，只是不提供 `%lslivetime_...%` 变量。
## 2. 玩家命令
| 命令 | 说明 | 权限 |
|---|---|---|
| `/lsl bind <UID>` | 校验直播间并绑定 B 站 UID | `lslivetime.use` |
| `/lsl unbind` | 解除绑定 | `lslivetime.use` |
| `/lsl info` | 查询自己的绑定、分钟与最近直播状态 | `lslivetime.use` |
| `/lsl help` | 显示帮助 | 无 |
`/lslivetime`、`/lsl`、`/livetime` 是同一个命令。
### 怎样找到 UID
打开 B 站用户空间，网址通常类似 `https://space.bilibili.com/123456`，末尾的 `123456` 就是 UID。插件绑定时会确认该 UID 有直播间；昵称不能代替 UID。
注意：绑定过程只校验 UID 和直播间存在，不证明操作者拥有该 B 站账号。默认禁止同一个 UID 被多个 Minecraft 账号绑定。
## 3. 管理员命令
以下命令需要 `lslivetime.admin`，默认仅 OP 拥有：
| 命令 | 说明 |
|---|---|
| `/lsl info <玩家>` | 查询已产生数据的玩家 |
| `/lsl reload` | 重载配置，并重新开始“首次判定”状态 |
| `/lsl check` | 立即发起检查；若上一轮未结束则不会重叠请求 |
| `/lsl set <玩家> <分钟>` | 设置累计分钟 |
| `/lsl add <玩家> <分钟>` | 增加累计分钟 |
离线玩家必须至少进入过一次服务器，才能按名字被管理员命令找到。玩家改名后，下次上线会自动更新保存的名字。
## 4. PlaceholderAPI 变量
| 变量 | 示例 | 含义 |
|---|---:|---|
| `%lslivetime_minutes%` | `125` | 累计分钟整数 |
| `%lslivetime_hours%` | `2` | 累计完整小时数 |
| `%lslivetime_hours_decimal%` | `2.08` | 两位小数小时数 |
| `%lslivetime_formatted%` | `2小时5分钟` | 中文格式 |
| `%lslivetime_uid%` | `123456` | 绑定 UID；未绑定为空 |
| `%lslivetime_name%` | `主播名` | 最近获取到的 B 站昵称 |
| `%lslivetime_bound%` | `true` | 是否已绑定 |
| `%lslivetime_live%` | `true`/`false`/`unknown` | 最近一次成功查询的状态 |
`unknown` 表示服务器启动或绑定后尚未完成一次成功查询，不等同于未开播。
## 5. 计时示例
假设检查发生在 12:01、12:02、12:03：
| 时间 | 玩家在线 | 直播中 | 结果 |
|---|---|---|---|
| 12:01 | 是 | 是 | 首次判定，+0 |
| 12:02 | 是 | 是 | +1 分钟 |
| 12:03 | 是 | 是 | +1 分钟 |
玩家在两个检查点之间离开过服务器时，退出事件会立即清除连续状态，即使很快重新登录，下一次也按首次判定处理。
## 6. 常用配置
配置文件内有完整中文注释。常用项：
- `binding.allow-duplicate-uid`：是否允许多人绑定同一 UID，默认 `false`。
- `binding.reset-minutes-on-unbind`：解绑是否清零，默认 `false`。
- `counting.first-check-delay-seconds`：启动/重载后第一次检查的延迟。
- `counting.autosave-minutes`：自动保存周期。
- `counting.notify-on-increment`：每次 +1 是否提示玩家，默认关闭以免刷屏。
- `bilibili.*`：接口地址、超时、重试与批量数量。
修改后运行 `/lsl reload`。检查间隔固定为 60 秒，以保证每次增加恰好代表 1 分钟。
## 7. 故障排查
### 绑定失败
- 确认输入的是 UID，而不是房间号或昵称。
- 确认该账号已经开通直播间。
- 查看控制台是否出现“B 站直播状态查询失败”。
- 检查服务器能否访问 `api.live.bilibili.com`，以及防火墙/代理是否允许 HTTPS。
### 时间没有增加
- 第一次成功判断按设计不会增加，要等下一次一分钟检查。
- 玩家必须在检查发生时在线，且 B 站返回 `live_status = 1`；轮播状态不计入直播。
- `/lsl info` 中 `unknown` 通常表示请求还未成功完成。
- 检查 PlaceholderAPI 显示缓存；以 `/lsl info` 和 `players.yml` 数据为准。
### 旧服务端报 TLS/HTTPS 错误
KCauldron 1.7.10 应使用维护到较新根证书与 TLS 的 Java 8 更新版本。过旧 Java 8 可能无法连接现代 HTTPS 站点。
## 8. 备份与升级
定期备份整个 `plugins/LsLiveTime` 文件夹。升级时保留 `players.yml`；替换 JAR 后完整重启。`players.yml` 首行包含数据结构版本，未来版本可据此迁移。
## 1. 环境与安装
支持目标：
- KCauldron 1.7.10 + Java 8
- PaperSpigot/Spigot 1.12.2 + Java 8
支持 Windows 和 Linux。插件不依赖操作系统命令、本地动态库或固定盘符，同一个 JAR 可以在两个系统上使用。
### 文件编码
插件源码、`config.yml`、`players.yml` 和 B 站接口 JSON 统一使用 **UTF-8**。用记事本、Notepad++、VS Code 或服务器面板修改 YAML 时，请选择“UTF-8”保存，不要转换成 ANSI、GBK 或 UTF-16，否则中文消息可能乱码，严重时 YAML 会无法读取。
Windows 控制台本身的中文显示可能受终端代码页影响；如果只有控制台乱码而游戏内消息和配置文件正常，一般不是插件数据损坏。Linux 环境建议保持系统 locale 为 UTF-8。
把 `LsLiveTime-1.0.0.jar` 放进服务端 `plugins` 目录，然后**完整重启**服务器。首次启动会生成：
- `plugins/LsLiveTime/config.yml`：配置与消息。
- `plugins/LsLiveTime/players.yml`：绑定和累计时间；不要在服务器运行时手工编辑。
PlaceholderAPI 为可选插件。不安装时，绑定、查询和计时仍正常，只是不提供 `%lslivetime_...%` 变量。
## 2. 玩家命令
| 命令 | 说明 | 权限 |
|---|---|---|
| `/lsl bind <UID>` | 校验直播间并绑定 B 站 UID | `lslivetime.use` |
| `/lsl unbind` | 解除绑定 | `lslivetime.use` |
| `/lsl info` | 查询自己的绑定、分钟与最近直播状态 | `lslivetime.use` |
| `/lsl help` | 显示帮助 | 无 |
`/lslivetime`、`/lsl`、`/livetime` 是同一个命令。
### 怎样找到 UID
打开 B 站用户空间，网址通常类似 `https://space.bilibili.com/123456`，末尾的 `123456` 就是 UID。插件绑定时会确认该 UID 有直播间；昵称不能代替 UID。
注意：绑定过程只校验 UID 和直播间存在，不证明操作者拥有该 B 站账号。默认禁止同一个 UID 被多个 Minecraft 账号绑定。
## 3. 管理员命令
以下命令需要 `lslivetime.admin`，默认仅 OP 拥有：
| 命令 | 说明 |
|---|---|
| `/lsl info <玩家>` | 查询已产生数据的玩家 |
| `/lsl reload` | 重载配置，并重新开始“首次判定”状态 |
| `/lsl check` | 立即发起检查；若上一轮未结束则不会重叠请求 |
| `/lsl set <玩家> <分钟>` | 设置累计分钟 |
| `/lsl add <玩家> <分钟>` | 增加累计分钟 |
离线玩家必须至少进入过一次服务器，才能按名字被管理员命令找到。玩家改名后，下次上线会自动更新保存的名字。
## 4. PlaceholderAPI 变量
| 变量 | 示例 | 含义 |
|---|---:|---|
| `%lslivetime_minutes%` | `125` | 累计分钟整数 |
| `%lslivetime_hours%` | `2` | 累计完整小时数 |
| `%lslivetime_hours_decimal%` | `2.08` | 两位小数小时数 |
| `%lslivetime_formatted%` | `2小时5分钟` | 中文格式 |
| `%lslivetime_uid%` | `123456` | 绑定 UID；未绑定为空 |
| `%lslivetime_name%` | `主播名` | 最近获取到的 B 站昵称 |
| `%lslivetime_bound%` | `true` | 是否已绑定 |
| `%lslivetime_live%` | `true`/`false`/`unknown` | 最近一次成功查询的状态 |
`unknown` 表示服务器启动或绑定后尚未完成一次成功查询，不等同于未开播。
## 5. 计时示例
假设检查发生在 12:01、12:02、12:03：
| 时间 | 玩家在线 | 直播中 | 结果 |
|---|---|---|---|
| 12:01 | 是 | 是 | 首次判定，+0 |
| 12:02 | 是 | 是 | +1 分钟 |
| 12:03 | 是 | 是 | +1 分钟 |
玩家在两个检查点之间离开过服务器时，退出事件会立即清除连续状态，即使很快重新登录，下一次也按首次判定处理。
## 6. 常用配置
配置文件内有完整中文注释。常用项：
- `binding.allow-duplicate-uid`：是否允许多人绑定同一 UID，默认 `false`。
- `binding.reset-minutes-on-unbind`：解绑是否清零，默认 `false`。
- `counting.first-check-delay-seconds`：启动/重载后第一次检查的延迟。
- `counting.autosave-minutes`：自动保存周期。
- `counting.notify-on-increment`：每次 +1 是否提示玩家，默认关闭以免刷屏。
- `bilibili.*`：接口地址、超时、重试与批量数量。
修改后运行 `/lsl reload`。检查间隔固定为 60 秒，以保证每次增加恰好代表 1 分钟。
## 7. 故障排查
### 绑定失败
- 确认输入的是 UID，而不是房间号或昵称。
- 确认该账号已经开通直播间。
- 查看控制台是否出现“B 站直播状态查询失败”。
- 检查服务器能否访问 `api.live.bilibili.com`，以及防火墙/代理是否允许 HTTPS。
### 时间没有增加
- 第一次成功判断按设计不会增加，要等下一次一分钟检查。
- 玩家必须在检查发生时在线，且 B 站返回 `live_status = 1`；轮播状态不计入直播。
- `/lsl info` 中 `unknown` 通常表示请求还未成功完成。
- 检查 PlaceholderAPI 显示缓存；以 `/lsl info` 和 `players.yml` 数据为准。
### 旧服务端报 TLS/HTTPS 错误
KCauldron 1.7.10 应使用维护到较新根证书与 TLS 的 Java 8 更新版本。过旧 Java 8 可能无法连接现代 HTTPS 站点。
## 8. 备份与升级
定期备份整个 `plugins/LsLiveTime` 文件夹。升级时保留 `players.yml`；替换 JAR 后完整重启。`players.yml` 首行包含数据结构版本，未来版本可据此迁移。
