284 lines
11 KiB
Markdown
284 lines
11 KiB
Markdown
# OpenSourceTools
|
||
|
||
开源 Minecraft 服务器工具包插件（Spigot / Paper），提供传送、称号、隐身、禁言、踢人 GUI、公告等常用服务器管理功能。
|
||
|
||
- **当前版本**：`2.1.0`
|
||
- **支持版本**：Minecraft **1.21.11**（Bukkit API `1.21.11-R0.1-SNAPSHOT`，`api-version: 1.21`）
|
||
- **协议**：[Apache License 2.0](LICENSE)
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [功能特性](#功能特性)
|
||
- [环境要求](#环境要求)
|
||
- [安装](#安装)
|
||
- [命令列表](#命令列表)
|
||
- [权限](#权限)
|
||
- [PlaceholderAPI 变量](#placeholderapi-变量)
|
||
- [配置文件](#配置文件)
|
||
- [构建](#构建)
|
||
- [自动化测试](#自动化测试)
|
||
- [版本历史](#版本历史)
|
||
- [已知问题与限制](#已知问题与限制)
|
||
- [安全提醒](#安全提醒)
|
||
|
||
---
|
||
|
||
## 功能特性
|
||
|
||
### 命令系统（21 个注册命令）
|
||
|
||
| 功能分类 | 说明 |
|
||
|---|---|
|
||
| 基础恢复 | `/feed`（别名 `/eat`）恢复饱食度；`/heal` 恢复状态 |
|
||
| 出生点 | `/spawn` 返回主城；`/setspawn` 设置主城坐标 |
|
||
| 传送系统 | `/tpa` 发起传送请求（可点击同意/拒绝，60 秒超时）；`/tpaaccept` 接受；`/tpadefuse` 拒绝 |
|
||
| 死亡回溯 | `/back` 返回死亡地点 |
|
||
| 游戏模式 | `/gamemode`（别名 `/gm`）切换创造/生存/冒险/旁观，支持数字与中文参数、Tab 补全、指定目标玩家 |
|
||
| 世界控制 | `/day` 一键天亮；`/sun` 一键晴天 |
|
||
| 玩家管理 | `/vanish`（别名 `/v`）隐身；`/fly` 飞行；`/mute` 禁言；`/unmute` 解除禁言；`/kick` 踢出（无参数时打开玩家头像踢人 GUI） |
|
||
| 服务器管理 | `/list`（别名 `/tps`）查看内存/TPS/在线列表；`/OSTReload` 重载插件；`/stop` 关闭服务器（支持自定义提示语） |
|
||
| 称号系统 | `/PlayerTitle`（别名 `/plt`）添加/删除玩家称号与后缀 |
|
||
| 内部命令 | `/testGUI`（插件作者测试用） |
|
||
|
||
### 事件系统（8 个监听器）
|
||
|
||
- **进服/退服公告**：区分管理员与普通玩家模板，支持 `%PlayerName%` 与 PlaceholderAPI 变量
|
||
- **彩色聊天**：按管理员/玩家开关控制，支持白名单；**彩色告示牌**：编辑时自动转换颜色代码
|
||
- **聊天管理**：聊天冷却（默认 3 秒）、重复消息防刷屏、屏蔽词拦截（拦截时通知在线管理员）
|
||
- **死亡记录**：死亡点自动记录，供 `/back` 使用
|
||
- **跨世界飞行保持**：切换世界后自动恢复飞行状态
|
||
|
||
### 定时任务（3 个）
|
||
|
||
- **TPA 超时检测**：每秒倒计时，60 秒未处理自动取消
|
||
- **TPA 执行检测**：定期执行已接受的传送请求
|
||
- **定时公告**：按配置间隔循环广播公告内容
|
||
|
||
### PlaceholderAPI 扩展
|
||
|
||
自动注册内部扩展，标识符 `OpenSourceTools`，提供 3 个变量（详见 [PlaceholderAPI 变量](#placeholderapi-变量)）。
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
| 项目 | 要求 |
|
||
|---|---|
|
||
| 服务器 | Spigot / Paper **1.21.11**（其他 1.21.x 版本理论可用，未测试） |
|
||
| Java | **21+**（本项目在 JDK 25 下编译与运行测试通过） |
|
||
| 前置插件 | **PlaceholderAPI**（硬依赖，缺失时插件无法启动） |
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
1. 安装 [PlaceholderAPI](https://hangar.papermc.io/HelpChat/PlaceholderAPI) 前置插件。
|
||
2. 将构建产物 `OpenSourceTools-2.1.0.jar` 放入服务器 `plugins/` 目录。
|
||
3. 重启服务器，插件会自动生成 `plugins/OpenSourceTools/config.yml`。
|
||
4. 按需修改配置文件后使用 `/OSTReload` 重载。
|
||
|
||
> ⚠️ 插件在 `plugin.yml` 中声明了 `depend: [PlaceholderAPI]`，请确保 PAPI 已安装，否则插件不会加载。
|
||
|
||
---
|
||
|
||
## 命令列表
|
||
|
||
| 命令 | 别名 | 用法 | 权限 | 默认 |
|
||
|---|---|---|---|---|
|
||
| `/feed` | `/eat` | `/feed` | `OpenTools.default` | 所有人 |
|
||
| `/heal` | - | `/heal` | `OpenTools.default` | 所有人 |
|
||
| `/spawn` | - | `/spawn` | `OpenTools.default` | 所有人 |
|
||
| `/tpa` | - | `/tpa <玩家ID>` | `OpenTools.default` | 所有人 |
|
||
| `/back` | - | `/back` | `OpenTools.default` | 所有人 |
|
||
| `/tpaaccept` | - | `/tpaaccept <玩家ID>` | `OpenTools.default` | 所有人 |
|
||
| `/tpadefuse` | - | `/tpadefuse <玩家ID>` | `OpenTools.default` | 所有人 |
|
||
| `/PlayerTitle` | `/plt` | `/PlayerTitle help` | `OpenTools.default` | 所有人 |
|
||
| `/testGUI` | - | `/testGUI KickGUI` | `OpenTools.testGUI` | OP |
|
||
| `/OSTReload` | - | `/OSTReload` | `OpenTools.reload` | OP |
|
||
| `/stop` | - | `/stop [提示语]` | `OpenTools.stop` | OP |
|
||
| `/gamemode` | `/gm` | `/gamemode <模式> [玩家ID]` | `OpenTools.gamemode` | OP |
|
||
| `/sun` | - | `/sun` | `OpenTools.sun` | OP |
|
||
| `/setspawn` | - | `/setspawn` | `OpenTools.setspawn` | OP |
|
||
| `/day` | - | `/day` | `OpenTools.day` | OP |
|
||
| `/vanish` | `/v` | `/vanish [玩家ID]` | `OpenTools.vanish` | OP |
|
||
| `/fly` | - | `/fly [玩家ID]` | `OpenTools.fly` | OP |
|
||
| `/mute` | - | `/mute <玩家ID>` | `OpenTools.mute` | OP |
|
||
| `/unmute` | - | `/unmute <玩家ID>` | `OpenTools.unmute` | OP |
|
||
| `/kick` | - | `/kick [玩家ID] [理由]` | `OpenTools.kick` | OP |
|
||
| `/list` | `/tps` | `/list` | `OpenTools.list` | OP |
|
||
|
||
`/PlayerTitle` 子命令：
|
||
|
||
```
|
||
/PlayerTitle help
|
||
/PlayerTitle addTitle <玩家ID> <称号>
|
||
/PlayerTitle addSuffix <玩家ID> <后缀>
|
||
/PlayerTitle delTitle <玩家ID>
|
||
/PlayerTitle delSuffix <玩家ID>
|
||
```
|
||
|
||
`/gamemode` 模式参数支持：`0/生存/survival`、`1/创造/creative`、`2/冒险/adventure`、`3/旁观/spectator`。
|
||
|
||
---
|
||
|
||
## 权限
|
||
|
||
| 权限节点 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `OpenTools.default` | 所有人 | 默认命令权限（feed/heal/spawn/tpa/back/称号等） |
|
||
| `OpenTools.kick` | OP | /kick |
|
||
| `OpenTools.mute` | OP | /mute |
|
||
| `OpenTools.unmute` | OP | /unmute |
|
||
| `OpenTools.fly` | OP | /fly |
|
||
| `OpenTools.vanish` | OP | /vanish |
|
||
| `OpenTools.ostreload` | OP | /OSTReload |
|
||
| `OpenTools.sun` | OP | /sun |
|
||
| `OpenTools.stop` | OP | /stop |
|
||
| `OpenTools.gamemode` | OP | /gamemode |
|
||
| `OpenTools.setspawn` | OP | /setspawn |
|
||
| `OpenTools.list` | OP | /list |
|
||
| `OpenTools.testGUI` | OP | /testGUI |
|
||
|
||
---
|
||
|
||
## PlaceholderAPI 变量
|
||
|
||
| 变量 | 说明 | 示例输出 |
|
||
|---|---|---|
|
||
| `%OpenSourceTools_Nick%` | 玩家昵称（未设置时显示游戏 ID） | `Steve` |
|
||
| `%OpenSourceTools_Title%` | 玩家称号（未设置时为空） | `§7[管理员§7]§f` |
|
||
| `%OpenSourceTools_Suffix%` | 玩家后缀（未设置时为空） | `§7[后缀§7]` |
|
||
|
||
---
|
||
|
||
## 配置文件
|
||
|
||
首次启动自动生成 `plugins/OpenSourceTools/config.yml`，关键配置项：
|
||
|
||
```yaml
|
||
ServerName: "ServerName" # 服务器名字
|
||
DefaultStopMessage: "StopServerText" # 默认关服提示
|
||
|
||
PlayerJoinServerMessage: "&7[&f&l玩家&7]&e%PlayerName%&a进入了服务器" # 进服公告
|
||
AdminJoinServerMessage: "&7[&d&l管理员&7]&e%PlayerName%&a进入了服务器" # 管理员进服公告
|
||
|
||
ColorChatSetting:
|
||
AllowAdminUsedColorChat: true # 允许管理员彩色聊天
|
||
AllowPlayerUsedColorChat: true # 允许玩家彩色聊天
|
||
AllowPlayers: [] # 无视开关的白名单
|
||
|
||
ColorSignSetting:
|
||
AllowAdminUsedColorSign: true # 允许管理员彩色告示牌
|
||
AllowPlayerUsedColorSign: true # 允许玩家彩色告示牌
|
||
|
||
SpawnSetting: # 主城坐标（/setspawn 自动写入）
|
||
WorldName: world
|
||
locationX: 0.5
|
||
locationY: 80.0
|
||
locationZ: 0.5
|
||
|
||
TimeMessageSetting: # 定时公告
|
||
TimeMessage: true # 是否启用
|
||
TimeMessageTime: 60 # 间隔（秒）
|
||
Message:
|
||
- "Text-1"
|
||
|
||
FeedCommandSetting: # /feed 开关
|
||
AllowAdminUsedFeedCommand: true
|
||
AllowPlayerUsedFeedCommand: false
|
||
|
||
ChatSetting:
|
||
ChatTime: 3 # 聊天冷却（秒）
|
||
|
||
AntiKeyWords: # 屏蔽词列表（精确匹配整句）
|
||
- xxx1
|
||
```
|
||
|
||
---
|
||
|
||
## 构建
|
||
|
||
### 环境
|
||
|
||
- JDK 8+（编译目标为 Java 8 字节码；本仓库使用 JDK 25 验证）
|
||
- Maven 3.8+
|
||
|
||
### 构建命令
|
||
|
||
```bash
|
||
mvn clean package
|
||
```
|
||
|
||
构建产物：`target/OpenSourceTools-2.1.0.jar`（shade 打包，含 JetBrains Annotations）。
|
||
|
||
> 网络提示：若访问 Maven Central 缓慢，可使用项目自带的阿里云镜像设置：
|
||
>
|
||
> ```bash
|
||
> mvn -s tools/smoke-test/maven-settings.xml clean package
|
||
> ```
|
||
|
||
---
|
||
|
||
## 自动化测试
|
||
|
||
项目内置了基于 **Paper 1.21.11** 实机启动的自动化测试设施（`tools/smoke-test/`）：
|
||
|
||
| 脚本 | 用途 |
|
||
|---|---|
|
||
| `run-smoke-test.ps1` | 全自动冒烟测试：临时启动服务器 → 校验插件加载/PAPI 扩展注册 → 优雅停止 → 断言日志，输出 PASS/FAIL |
|
||
| `start-test-server.ps1` | 启动一个**持续运行**的交互式测试服务器（端口 25565、离线模式），在独立控制台窗口等待玩家连接 |
|
||
|
||
使用前需将测试制品放入缓存目录 `%USERPROFILE%\.ost-smoke-cache\`：
|
||
|
||
- `paper-1.21.11-132.jar`（[PaperMC Fill API](https://fill.papermc.io/) 下载，SHA256 `5ffef465eeeb5f2a3c23a24419d97c51afd7dbb4923ff42df9a3f58bba1ccfba`）
|
||
- `PlaceholderAPI-2.12.3.jar`（官方发行版，[Modrinth](https://modrinth.com/plugin/placeholderapi) 下载）
|
||
|
||
```powershell
|
||
# 一键冒烟测试（自动启停）
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File tools/smoke-test/run-smoke-test.ps1
|
||
|
||
# 启动交互式测试服务器（等待玩家连接，手动关闭）
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File tools/smoke-test/start-test-server.ps1
|
||
```
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 变更 |
|
||
|---|---|---|
|
||
| `2.1.0` | 2026-11-09 | 升级 Bukkit API 至 **1.21.11**；`api-version` 提升至 `1.21`；声明 `depend: [PlaceholderAPI]` 保证加载顺序；补充自动化冒烟测试设施 |
|
||
| `2.0` | 2025 | 初版（Spigot API 1.20） |
|
||
|
||
---
|
||
|
||
## 已知问题与限制
|
||
|
||
> 以下问题为代码现状记录，不影响插件基本使用，欢迎提交 PR 修复。
|
||
|
||
1. **禁言不生效**：`/mute` 仅将玩家写入配置 `MutePlayerList`，聊天事件未检查该列表。
|
||
2. **`/heal` 实际恢复的是饱食度**（与 `/feed` 相同），且配置键大小写不匹配（`healCommandSetting` vs `HealCommandSetting`），导致默认被禁用。
|
||
3. **`/kick` 无法阻止踢出自己**：自我检查逻辑失效（`player.getName().equals(player.getName())` 恒为真）。
|
||
4. **控制台执行 `/unmute` 无效**：解禁分支误用 `add` 而非 `remove`。
|
||
5. **`/tpaback` 未注册**：类存在但未在 plugin.yml 与主类中注册。
|
||
6. **空指针风险**：玩家未死亡时使用 `/back` 或重生事件、未使用过 TPA 时执行 `/tpaback`、跨世界飞行检查，均可能抛出 NPE。
|
||
7. **状态仅存内存**：TPA 请求、聊天冷却、死亡点、隐身/飞行状态存于静态 HashMap，服务器重启即丢失。
|
||
8. **权限声明不一致**：`/OSTReload` 使用 `OpenTools.reload` 而权限节定义为 `OpenTools.ostreload`；`/day` 的 `OpenTools.day` 未在权限节声明。
|
||
9. **硬依赖退出方式激进**：缺失 PlaceholderAPI 时插件会 `System.exit(0)` 直接结束整个 JVM（现已通过 `depend` 声明保证加载顺序规避）。
|
||
10. **屏蔽词精确匹配**：仅拦截与关键词完全相同的整句消息。
|
||
|
||
---
|
||
|
||
## 安全提醒
|
||
|
||
- 仓库根目录的 `build.txt` 内含 Jenkins 构建服务器 Token，属于**敏感信息泄露**，建议立即吊销该 Token 并将文件从仓库移除。
|
||
- 玩家加入时其 IP 地址会输出到服务器控制台日志，如介意请自行移除 `PlayerJoin_Event.java` 中的相关代码。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目采用 [Apache License 2.0](LICENSE)。
|