原创 开源 工具 世界管理 PhantomControl - 幻翼生成控制插件 | 支持folia | 支持GUI v2.1.1

[MD] - 优化配置热重载并修复命令管理修复重载配置时出现的 UnsupportedOperationException: remove - 增加 YAML 校验、失败回滚、按需数据库切换和自动保存任务刷新 - 修复管理员 server 与 batch 子命令，并更新中英文提示和配置版本 [/MD]

[MD] # v2.1.0版本更新日志 ## 一、平台与版本适配优化 本次更新完成插件核心架构适配迭代，全面转向 Paper/Folia 服务端核心，彻底摒弃 Spigot 适配思路及兼容降级方案，聚焦高版本服务端性能与特性支持。 - 升级 Paper API 至 1.20.1-R0.1-SNAPSHOT 版本 - 升级 PlaceholderAPI 依赖至 2.11.7 正式版本 - 优化插件配置标识，在 plugin.yml 中声明 api-version: 1.20、folia-supported: true，原生适配对应服务端 ## 二、幻翼拦截机制重构升级 废弃旧版通过生成事件、位置推断的拦截逻辑，全面改用 Paper 原生 **PhantomPreSpawnEvent** 事件实现幻翼生成拦截，逻辑更精准、稳定性更强。 - 通过 `event.getSpawningEntity()` 直接获取触发幻翼生成的目标玩家，告别间接推断，数据精准无误 - 优化禁用逻辑：关闭幻翼生成功能时，同步执行 `event.setCancelled(true)` 与`event.setShouldAbortSpawn(true)`，彻底阻断生成流程 - 将事件监听优先级提升至 HIGHEST，优先拦截幻翼生成事件，规避其他插件干扰，提升拦截稳定性 - 新增玩家登录保护机制：玩家数据加载期间默认启用幻翼禁用规则，解决进服初期数据库未加载完成导致的短暂放行问题 ## 三、数据库与性能深度优化 针对数据读写、加载、保存全流程进行性能重构，大幅降低主线程IO占用，修复数据异常问题，提升插件运行稳定性。 - 玩家数据加载逻辑改为异步执行，避免阻塞服务端主线程 - 幻翼生成事件全程使用只读缓存，不再触发数据库IO操作，极致优化事件响应性能 - 新增数据加载中状态保护机制，杜绝异步加载结果覆盖玩家实时修改的状态，保证数据一致性 - 优化插件保存、重载、关闭全场景的数据处理流程，减少数据丢失、错乱风险 - 完善异常处理：MySQL初始化失败时，主动输出明确报错信息并自动禁用插件，避免异常运行 - 清理冗余代码，移除无用的数据库重载接口，精简插件内核 ## 四、Folia/Paper 调度体系重构 全面重写调度工具类 SchedulerUtil，适配新版服务端调度机制，移除老旧兼容逻辑，调度效率与兼容性大幅提升。 - 废弃传统调度方式，直接对接 Paper 原生异步调度器 - 彻底移除反射调度、Bukkit 降级方案及 Spigot 兼容冗余逻辑，代码更轻量化 ## 五、命令系统优化迭代 - 移除 PluginCommand 反射构造器调用，规避反射报错、兼容失效问题 - 采用 DynamicPluginCommand 实现动态命令注册，命令注册更规范、运行更稳定 - 保留热重载功能的核心能力，支持重载时自动清理旧命令及别名，避免命令冗余冲突 - 修正文档错误，将 README 中的重载命令统一更正为 `/phantomcontrolreload` ## 六、开发者 API 全面拓展 新增全套公开开发者 API 与自定义事件，标准化对外调用接口，支持开发者深度二次开发与功能拓展。 ### 1. 新增核心API类 - 新增 **PhantomControlAPI**、**DefaultPhantomControlAPI**、**PhantomStatusChangeSource** 核心接口类 - 通过 Bukkit ServicesManager 统一注册管理API，调用方式标准化 - 支持在线玩家幻翼状态实时查询、修改，支持玩家UUID异步查询与数据写入 ### 2. 新增自定义事件 - **PhantomStatusPreChangeEvent**：幻翼状态变更前触发，支持取消变更操作 - **PhantomStatusChangeEvent**：状态变更完成后触发，携带旧状态、新状态、变更来源完整参数 - **PhantomSpawnBlockedEvent**：幻翼生成被成功拦截时触发，便于拓展拦截后置逻辑 ### 3. 全场景溯源机制 所有状态变更场景（命令操作、GUI设置、管理员后台操作、API调用、权限强制恢复）均记录变更来源，实现操作全溯源。 ## 七、文档内容更新完善 - 更新适配说明，明确标注 Paper/Folia 1.20.1+ 专属支持范围 - 补充幻翼禁止生成的核心原理说明，方便用户与开发者理解机制逻辑 - 全面更新开发者API文档，完善接口功能、参数、使用场景介绍 - 新增 ServicesManager 获取API、异步UUID API 完整调用示例 - 补充全部新增自定义事件的使用说明与拓展场景 [/MD]

[MD] - 此插件项目开源到GitHub，地址 https://github.com/Chun2919089965/PhantomControl - 大量功能和代码重构以及优化 - 修复所有已知的历史遗留的代码问题 - 架构重构 - GUI优化 [/MD]

[MD] - 修复config.yml 世界白名单/黑名单 YAML 层级错误和bstats 配置层级错误的问题（需要重新生成config文件） - GUI添加权限检测 - 重构了部分代码进行了优化 [/MD]

[MD] - 添加/phantomcontrol toggle或者/phantomcontrol switch命令，来进行当前幻翼生成状态的切换 [/MD]

[MD] - 新增，玩家没有phantomcontrol.use权限时，强制为启用幻翼生成 [/MD]

[MD] - 使用独立线程池进行异步保存，不依赖 Bukkit 调度器 - 修复调度器异常的处理 - 修复定时任务，让定时任务可以正确取消 [/MD]

[MD] - 优化玩家退出时，插件的文件写入，改为异步线程，防止个别情况下文件I/O操作和数据库操作在主线程中同步执行，导致服务器主线程被阻塞 [/MD]

[MD] - 注：如果要从之前的版本更新到此版本，请删除原本的配置文件夹，重新生成本插件的配置文件夹 - 增加GUI界面 - 消息文本优化和美化，确保了所有状态消息都明确说明幻翼是否会生成，减少之前玩家使用插件对于是否生效的困惑 - 新增英文语言支持以及插件消息文本全自定义，并且消息文本配置转移为单独的消息文本配置文件 - 新增自动语音检测，根据玩家客户端语言自动调整语言的功能 - 集成bStats统计（如果不需要，可在配置文件中关闭） [/MD]

[MD] - 修复命令重复注册的bug - 修复部分条件判断错误的bug - 修复无用补全的问题 - 修复消息文本颜色代码显示问题 [/MD]