database-mysql/OpenSourceTools

0 Fork 0

Files

T

database-mysql 6c7d7fedcb feat: OpenSourceTools v2.1.0 - 升级 Bukkit 1.21.11, 补充 README 与自动化测试设施

2026-11-09 07:57:59 +08:00

11 KiB

Raw Blame History

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

功能特性

命令系统（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 变量）。

环境要求

项目	要求
服务器	Spigot / Paper 1.21.11（其他 1.21.x 版本理论可用，未测试）
Java	21+（本项目在 JDK 25 下编译与运行测试通过）
前置插件	PlaceholderAPI（硬依赖，缺失时插件无法启动）

安装

安装 PlaceholderAPI 前置插件。
将构建产物 OpenSourceTools-2.1.0.jar 放入服务器 plugins/ 目录。
重启服务器，插件会自动生成 plugins/OpenSourceTools/config.yml。
按需修改配置文件后使用 /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，关键配置项：

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+

构建命令

mvn clean package

构建产物：target/OpenSourceTools-2.1.0.jar（shade 打包，含 JetBrains Annotations）。

网络提示：若访问 Maven Central 缓慢，可使用项目自带的阿里云镜像设置：
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 下载，SHA256 5ffef465eeeb5f2a3c23a24419d97c51afd7dbb4923ff42df9a3f58bba1ccfba）
PlaceholderAPI-2.12.3.jar（官方发行版，Modrinth 下载）

# 一键冒烟测试（自动启停）
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 修复。

禁言不生效：/mute 仅将玩家写入配置 MutePlayerList，聊天事件未检查该列表。
/heal 实际恢复的是饱食度（与 /feed 相同），且配置键大小写不匹配（healCommandSetting vs HealCommandSetting），导致默认被禁用。
/kick 无法阻止踢出自己：自我检查逻辑失效（player.getName().equals(player.getName()) 恒为真）。
控制台执行 /unmute 无效：解禁分支误用 add 而非 remove。
/tpaback 未注册：类存在但未在 plugin.yml 与主类中注册。
空指针风险：玩家未死亡时使用 /back 或重生事件、未使用过 TPA 时执行 /tpaback、跨世界飞行检查，均可能抛出 NPE。
状态仅存内存：TPA 请求、聊天冷却、死亡点、隐身/飞行状态存于静态 HashMap，服务器重启即丢失。
权限声明不一致：/OSTReload 使用 OpenTools.reload 而权限节定义为 OpenTools.ostreload；/day 的 OpenTools.day 未在权限节声明。
硬依赖退出方式激进：缺失 PlaceholderAPI 时插件会 System.exit(0) 直接结束整个 JVM（现已通过 depend 声明保证加载顺序规避）。
屏蔽词精确匹配：仅拦截与关键词完全相同的整句消息。

安全提醒

仓库根目录的 build.txt 内含 Jenkins 构建服务器 Token，属于敏感信息泄露，建议立即吊销该 Token 并将文件从仓库移除。
玩家加入时其 IP 地址会输出到服务器控制台日志，如介意请自行移除 PlayerJoin_Event.java 中的相关代码。

许可证

本项目采用 Apache License 2.0。

11 KiB Raw Blame History Unescape Escape