原创 开源 工具 [1.7~26.X] Guild | 公会插件-功能完善 | GUI支持 | Fotia支持 3.0.8

【修复】​

• Paper 26.2 启动崩溃（ShopConfig 空指针） ： ShopConfig 字段初始化器在父类 SimpleFileConfig 构造函数调用可覆写的 onLoad() 时尚未执行，导致 items 为 null，插件在 26.2 服务端 onEnable 直接 NPE 崩溃。现将 items 的创建移入 onLoad 内部，消除模板方法初始化顺序陷阱
• 公会事件双发与漏发 ： GuildAPI 与 GuildManager 两层各自触发事件，第三方通过 API 操作时事件被触发两次；而命令/GUI 路径则完全不触发（创建/加入/离开/踢出/解散/升级六类事件均存在遗漏）。现将事件触发统一下沉至 GuildManager，所有路径恰好触发一次，API 层不再重复触发
• 批准入会申请必然崩溃 ： acceptRequest 在 CopyOnWriteArrayList 的迭代器上调用 iter.remove()，必抛 UnsupportedOperationException，玩家批准申请即报错且申请无法移除。现改为列表直接 remove 元素，空列表同步移除键
• GUI 重命名实际修改公告 ： 管理 GUI「重命名」按钮注册的挂起动作是 guild_motd，玩家输入新名称后修改的是公告而非公会名。现新增独立的 guild_rename 动作与完整校验处理
• 铁砧创建公会双重扣费 ： 3.0.7 仅修复了命令路径的预扣费，GUI 铁砧创建路径仍然先预扣创建费、createGuild 内部再扣一次（失败时还退款）。现删除铁砧路径预扣/退款逻辑，统一由 createGuild 单次扣费
• 被踢/退会成员重启后复活 ： saveGuild 对成员表只 upsert 不删除，离会成员的数据库行永久残留，重启后被踢玩家重新出现在成员列表。现同一事务内先清空该公会成员行再批量插入
• 公会频道命令空指针 ： /guildchat 直接调用 getMember(...).isMuted()，成员记录缺失时 NPE；且未检查聊天权限、使用硬编码格式与 /guild chat 不一致。现补齐判空与权限校验，格式统一读取 guild.yml chat.format
• 升级循环防护缺失 ： 经验公式配置为 0（或 /guild clxplev 清零后 level=0）时 checkLevelUp 的 required 恒为 0，轻则一次加经验瞬间刷满级，重则循环空转。现 required ≤ 0 时直接跳出升级循环
• GUI 升级等级上限硬编码 ： 升级按钮仍写死 100 级上限，max-level 配置大于 100 时无法继续升级。现改用 guild.getMaxLevel()
• 异步线程触发同步事件 ： 聊天挂起输入运行于 AsyncPlayerChatEvent 异步线程，其中创建/离开/解散流程会在异步线程 callEvent 并直接操作 Bukkit API，存在线程安全异常风险。现统一切回主线程执行管理器操作
• 玩家下线状态残留吞消息 ： 挂起聊天输入、铁砧待确认状态、成员设置目标三项静态映射从不清理，玩家下线前挂起的操作会吞掉其下次上线的第一条聊天消息且映射长期泄漏。现于 PlayerQuit 统一清理
• 踢出/升降级防护缺失 ： kickMember 无操作者判空（API 传 null 直接 NPE），可踢出自己、踢出会长、同级互踢；promote/demote 已到顶/底时仍返回成功导致调用方误报。现补齐全部角色保护校验，职位无变化时返回失败
• 重复入会与幽灵成员 ： joinGuild/批准申请/接受邀请均不检查玩家是否已在其他公会，可制造同时在多个公会的幽灵成员记录。现统一增加 playerGuilds 占用校验
• 改名/解散遗留脏数据 ： 重命名后旧名称下的待处理入会申请直接丢失；解散公会后指向它的待处理邀请残留内存。现改名同步迁移申请、解散同步清理相关邀请
• GUI 操作重启丢失 ： GUI 中的晋升/降级/踢出/昵称修改仅改内存不落库，重启后全部还原。现操作后立即进入异步保存队列
• API 解散空指针 ： disbandGuildAsync(name) 内部以 null 作为解散者调用 disbandGuild，直接 disbander.getUniqueId() NPE。现 disbander 为 null 时自动回退为公会会长
• 禁言缺少保护与校验 ： /guild mute 管理员可禁言会长、可同级互禁，且允许传入 0 或负数分钟。现禁止禁言会长及同级/更高级成员，分钟数必须大于 0
• 命令改名校验不全 ： /guild rename 注释声称"与创建时一致"但缺少正则与黑名单校验，可改名成非法字符或违禁名称。现补齐 name-regex / banned-names 校验

【优化】​

• 主线程数据库 I/O 全面移除 ： 命令层 10 处（标签/标签颜色/公告/设置/权限/gexp/slevel/clxplev/mute/unmute）同步 saveGuild 与解散公会的数据库删除全部改为异步：GUI/命令写操作走 scheduleSavePublic 异步保存队列，deleteGuild 改 runTaskAsynchronously（关闭时刻自动回退同步），大公会操作不再卡顿 TPS
• 玩家名查询缓存化 ： 成员列表、排行榜、GUI 头部点击、升降级/踢出/昵称提示等高频路径的 Bukkit.getOfflinePlayer(uuid).getName() 主线程磁盘查询统一改走 GuildManager.getPlayerNameCached 缓存
• 银行历史记录限容 ： 存取款历史 Map 每人无上限增长，长期运行占用内存。现每人仅保留最近 50 条记录

【新增】​

• 重命名聊天输入处理 ： ChatInputListener 新增 guild_rename 挂起动作，支持取消、长度/正则/黑名单/重名校验，校验通过后走 renameGuild 原地迁移
• 事件层 API 完善 ： GuildCreateEvent 监听器修改的名称与标签现对所有创建路径（命令/GUI/API）生效；GuildAPI.createGuild(name, tag, owner) 的标签参数在事件未被监听器改动时正常应用

【其他】​

• 代码格式化 ： 修复均保持原有反编译风格文件的局部最小改动，未涉及整体重排
• 编译产物修复 ： 构建通过，输出 target/Guild-3.0.8.jar
• 版本号更新 ： 插件版本更新至 3.0.8（pom.xml / plugin.yml）；配置文件版本保持 1.3 不变，无需迁移任何配置文件

【修复】​

• 创建公会双重扣费 ： handleCreate 先按 Vault→PlayerPoints 回退链预扣创建费， GuildManager.createGuild 又按 currency.yml 配置的货币类型再扣一次，玩家实际被扣两次费用。现统一由 createGuild 按配置货币类型单次扣费并提示所需金额
• 创建费用货币类型错误 ： 旧版 handleCreate 的扣费/退款完全忽略 currency.yml 的 type 配置（固定走 Vault→点数回退链）。现删除命令层扣费逻辑，全部走配置化货币类型
• 重命名公会丢失全部数据 ： handleRename 通过「解散公会 + 重新创建」实现改名，导致所有成员、等级、经验、银行余额、权限全部丢失，且会再次扣取创建费。现新增 GuildManager.renameGuild 原地迁移内存索引，并配套 DatabaseManager.migrateGuildName 在数据库端迁移 guild_members/guild_permissions/guild_banks/guilds 关联记录（事务执行）
• 强制删除公会永远无法执行 ： handleDelete 的确认逻辑反转—— pendingDeleteConfirm.remove() 返回 true（即玩家确实先发起了删除）时反而提示"请重新发起删除"。现改为记录待删除公会名，确认时执行删除
• MySQL 配置完全被忽略 ： config.yml 中 database.type/host/port/pool-size 等配置项形同虚设， DatabaseManager.initialize 强制使用 SQLite。现完整实现 MySQL 支持：按 config.yml 建立连接池，MySQL 方言建表（VARCHAR 主键、InnoDB、utf8mb4），upsert 自动切换 INSERT OR REPLACE / ON DUPLICATE KEY UPDATE，pool-size 与 connection-timeout 均已生效
• 公会币余额重启即丢失 ： 玩家公会币（GUILD_COIN）仅存于内存 Map，服务器重启后全部清零。现新增 player_currency 数据库表：启动时全量加载、余额变动异步落库、玩家首次进服自动建户
• 公会权限表从不保存 ： saveGuild 只保存公会/成员/银行三类表，GUI 中修改的权限等级重启后全部还原为默认值。现 saveGuild 事务内同步 upsert guild_permissions 表
• 禁言到期时间丢失 ： saveGuild 保存 muted_until 时写入"当前时间 + 24小时"而非成员真实到期时间，重启后禁言时长错乱。现新增 GuildMember.getMutedUntil()，保存真实时间戳，加载时按剩余时长恢复
• settings public 子命令失效 ： switch 分支 case " public" 带前导空格， /guild settings public true 永远提示"未知属性"。现修正为 case "public"
• 多处命令参数解析未捕获异常 ： /guild top、log、requests、mute、gexp、slevel 等命令直接 Integer.parseInt / Long.parseLong，传入非数字直接抛 NumberFormatException。现统一捕获并提示"无效的数字"，slevel 增加等级范围校验（0 ~ max-level）
• 公会/管理频道空指针 ： handleChat 与 handleOfficerChat 在成员记录缺失时直接调用 member.isMuted() / getRole() 触发 NPE。现增加判空保护
• 语言文件 en_US 永不释放 ： saveLanguageFiles 中路径字符串 " en_US" 带前导空格，导致英文语言文件从未被释放到插件目录。现修正为 "en_US"
• 入会请求并发安全与重复提交 ： requests 使用 ArrayList 挂载在 ConcurrentHashMap 上仍非线程安全；同一玩家可无限重复提交申请。现改用 CopyOnWriteArrayList 并拒绝重复申请
• 幽灵申请长期堆积 ： 入会请求从不过期清理。现随邀请清理任务每分钟扫描，超时（10分钟）自动移除，空列表同步移除
• createGuild 缺少"已在公会"校验 ： 旧版仅命令层拦截，直接调用 API 可让已在公会的玩家重复创建。现管理器层补齐 playerGuilds 校验

【优化】​

• 银行系统与玩家钱包打通 ： 旧版 depositToBank / withdrawFromBank 只是银行数字增减，玩家钱包分文未动。现按 currency.yml 配置的货币类型：存款先从玩家钱包扣款、取款后向玩家钱包入账，失败自动退还，杜绝"凭空造币"
• 银行限额与税收全面生效 ： 接入 bank.yml 的 max-deposit / max-withdraw / max-balance / min-balance / deposit-tax / withdraw-tax / daily-deposit-limit / daily-withdraw-limit，税收按比例折算实际入账/到账金额，每日限额跨天自动重置
• 经验系统接入配置 ： addExperience 现应用 experience.yml 的 weekend-multiplier（周末加成）、holiday-multiplier（节假日加成）、daily-exp-limit（每日经验上限）、daily-contribution-limit（每日贡献上限），上限计为增量截断而非整单拒绝
• 等级/成员上限配置化 ： Guild.getMaxMembers 改为 base-members + level × members-per-level（guild.yml）；等级上限 100 硬编码改为 max-level 配置（升级、checkLevelUp、setlevel 校验三处同步）
• 经验公式配置化 ： Guild.getRequiredExperience 改用 experience.yml level-formula（base / growth-rate / max-required），保留旧公式作为未配置时的回退默认值
• 名称校验配置化 ： /guild create 增加正则与黑名单校验（guild.yml name-regex / banned-names），ChatInputListener 的硬编码正则同步改为读取配置，创建与聊天输入规则一致
• 升级事件补发 ： 自然经验升级从未触发 GuildLevelUpEvent（仅付费升级路径触发）。现 Guild.checkLevelUp 升级时触发事件，付费升级路径不重复触发
• 每日重置任务落地 ： clearAllDailyData 一直无人调用。现 GuildPlugin 启动每分钟检测日期变更，跨天自动重置日常经验/贡献与银行每日限额（受 features.yml daily-reset 开关控制）
• initial-balance 生效 ： currency.yml 的初始余额从未发放。现玩家首次进服异步建户并发放初始余额（通过数据库行存在性保证终生一次，不会刷初始资金）
• 公会币上限生效 ： depositPlayerGuildCurrency 接入 currency.yml max-balance（0 = 无限制），超出部分截断至上限
• 银行功能开关 ： /guild deposit、withdraw 命令接入 features.yml 银行开关，关闭时直接拒绝并提示

【新增】​

• 聊天格式配置 ： guild.yml 新增 chat.format / chat.officer-format，公会频道与管理频道格式完全可自定义（占位符 {tag_color} {tag} {player} {message}），替代旧版硬编码格式
• 公会币持久化 API ： DatabaseManager 新增 loadPlayerCurrencies / ensurePlayerCurrency / savePlayerCurrency 方法；GuildManager 新增 loadPlayerCurrencyBalances / ensurePlayerCurrencyRow / setPlayerGuildCurrency 持久化方法
• 公会重命名 API ： GuildManager 新增 renameGuild(oldName, newName, operator) 方法，供命令与第三方插件安全调用

【其他】​

• 代码格式化 ： GuildPlugin、PlayerListener、DatabaseManager 整体重写为规范缩进，消除反编译遗留的级联缩进与 }} 链式结构
• 编译产物修复 ： 构建通过（Release 配置），输出 target/Guild-3.0.7.jar
• 配置文件注释更新 ： guild.yml 新增聊天格式段落说明；数据库配置项（config.yml database 段）现已真实生效
• 版本号更新 ： 插件版本更新至 3.0.7；配置文件版本更新至 1.3（config.yml config-version 与插件内检测常量同步，旧配置首次启动将提示配置版本较旧，新配置项自动使用默认值）

【修复】​

• /guild reload 命令不完整，原仅调用plugin.reloadConfig()，导致CurrencyConfig、GUIConfig、语言文件、货币系统、玩家服务器等子系统均不更新，需重启服务器才生效
• 公会商店购买依赖硬编码 player.performCommand("menu shop ...") ，委托给外部菜单插件执行，本身不处理扣款也不检查货币，且仅支持6个固定商品
• CurrencyConfig 与 FeatureConfig 存在重复的 isBankEnabled() 方法

【优化】​

• 新增 GuildPlugin.reloadAll() ，完整重载：主配置、语言文件、FeatureConfig、CurrencyConfig、GuildConfig、ExperienceConfig、BankConfig、GUIConfig、ShopConfig、Vault/PlayerPoints货币系统、玩家名称缓存
• 新增 DatabaseManager.reload() ，先关闭旧连接池重新重新初始化
• reload命令支持控制台执行（原仅游戏内可用）
• 公会商店完全重构为配置驱动：
  • 新增独立配置文件shop.yml，支持无限自定义商品
  • 每个商品 11 项可配置字段： slot（位置）、material（材质）、name（名称）、lore（描述）、required-level（等级要求）、price（价格）、currency-type（独立货币类型）、action（动作类型）、action-value（动作内容）、buy-message（购买提示）、permission（权限要求）
  • 支持5种动作类型：COMMAND（玩家执行）、CONSOLE（控制台执行，支持%player%）、GIVE_ITEM（直接给予物品）、GUILD_EXP（给予公会经验）、GUILD_COIN（给予玩家公会币）
  • 商品数量从6个起 9个亚马逊（新增钻石礼包、金苹果礼包、下界合金包、经验加成卷）
  • 商店购买流程内部化：等级检查 → 权限检查 → 扣款 → 执行动作 → 发送提示，不再依赖外部插件

【重构】​

• 配置文件从 1 个分割为 7 个独立文件：
  文件路径内容 config.yml config.yml 仅保留核心（语言、数据库、调试），原 120 行专业至 39 行 features.yml features.yml 功能开关（原 features 块 + 新增 6 个开关）currency.ymlcurrency.yml 货币系统（原currency块 + 新增 8 项）guild.yml guild.yml公会规则（原行会块+新增15项）experience.yml experience.yml经验获取（原经验+新增18项）bank.ymlbank.yml银行系统（原bank块+新增15项）gui.yml gui.yml GUI界面（原gui块，独立共享）shop.yml shop.yml 公会商店（新系统，10项商品全局设置+商品列表）
• 新增公共基类 SimpleFileConfig.java ，所有配置类统一继承，自动处理文件保存、Yaml加载、热重载
• 7个配置类（FeatureConfig、CurrencyConfig、GuildConfig、ExperienceConfig、BankConfig、GUIConfig、ShopConfig）全部重构为继承SimpleFileConfig

【新增配置选项】（约60+项）​

features.yml（+6个开关）：自动保存自动保存、自动解散无人自动解散、daily-reset每日重置、战斗标签战斗锁定、cooldown-bar冷却进度条、shop商店开关

currency.yml（+8项）：initial-balance 初始公会币、 max-balance 公会币上限、 create.cost 创建费用独立配置、 create.requires-money 创建开关独立配置、upgrade-formula.growth-rate 升级、upgrade-formula.max-cost 升级费用上限、 format.thousands-separator 千分位、 format.decimal-places 小数位

guild.yml（+15项）：base-members成员基础数、name-regex名称正则过滤、banned-names取消名称列表、allowed-tag-colors标签颜色白名单、7种冷却时间（invite/join/promote/demote/kick/rename/tag-change）、max-officers最大库存数、allow-self-demote会长自降、auto-kick-inactive-days自动踢脚不激活、自动休眠天数 自动休眠

experience.yml（+18项） ：
9种新增经验事件（钓鱼/饲养/交易/附魔/制作/酿造/熔炼/驯服/进阶）、daily-exp-limit每日经验上限、daily-contribution-limit每日贡献上限、周末倍率、周末倍率、节日倍率、节假日倍率、level-formula.*等级公式参数、no-exp-blocks无经验方块、 no-exp-mobs 无经验实体、cumulative-contribution 历史贡献累计、weekly-reward.* 周贡献排行奖励

Bank.yml（+15项） ： min-balance 最低保留余额、存款税提款限额、提款税提款限额、提款权限存款权限权限、存款权限权限、daily-deposit-limit 每日存款限额、 daily-withdraw-limit 每日存款限额、利息* 利息系统（enabled/rate/time/max-interest）、 max-history-records 记录条数、 log-large-transactions 大额日志开关、 large-transaction-threshold 大额阈值

【修复】​

• 修复 17 处旧代码直接读取 plugin.getConfig().getXxx("guild.xxx") / getXxx("experience.xxx") 的过时引用（涉及 PlayerListener.java 、 InventoryListener.java 、 ChatInputListener.java 、 GuildCommand.java 、 GuildManager.java ），全部改用对应配置类的 getter
• plugin.yml 新增 PlayerPoints 软依赖、 guild.shop 独立权限节点

【其他】​

• 配置文件版本号：1.1 → 1.2
• 插件版本号：3.0.5 → 3.0.6

【修复】​

• PAPI 变量无法使用的核心问题 ： GuildPAPIExpansion 现在同时覆写 onRequest(OfflinePlayer, String) 和 onPlaceholderRequest(Player, String) 两个方法，全面兼容 PAPI 2.11+ 的新版 API（旧版仅覆写了已废弃的 onPlaceholderRequest ，导致部分用户变量不生效）
• Vault 经济初始化失败 ：原代码通过反射从 Vault 插件对象调用 getServicesManager() ，但该方法属于 Bukkit 而非 Vault 插件类，导致 Vault 经济系统始终初始化失败。现直接使用 Bukkit.getServicesManager().getRegistration() 修复
• GuildBank 并发安全问题 ：余额使用 long 基本类型，存取操作非原子性，多线程下可能出现数据不一致。现改用 AtomicLong 和 ConcurrentHashMap 保证线程安全
• 公会货币提现竞态条件 ： withdrawPlayerGuildCurrency 使用非原子的 get + put 操作，并发提现可能导致余额错算。现改用 CAS（ compareAndSet ）原子操作
• 解散公会未清理入会请求 ： disbandGuild 未清理 requests 中的残留数据，可能导致幽灵请求
• acceptRequest 并发修改异常 ：使用 Iterator.remove() 替代 List.remove() 避免 ConcurrentModificationException
• transferOwnership 空指针 ：当原会长不在成员列表中时 ownerMember 为 null 未判空
• addExperienceWithCurrency 未记录贡献 ：购买经验时未给玩家添加个人贡献值
• 升级费用显示不准确 ：GUI 和命令中显示的升级费用为固定基础值，与实际扣除不符

【优化】​

• 经济平衡性调整 ：升级费用从固定值改为按等级递增公式 baseCost × (1 + level × 0.08) ，低等级时门槛合理，高等级时费用递增，避免后期经济膨胀（例：Lv1→2 需 10.8万，Lv50→51 需 50万，Lv99→100 需 89.2万）
• PAPI 注册重试机制 ：首次注册失败时自动在 3 秒后重试，解决 PAPI 延迟加载导致的注册失败
• PAPI V2 备选注册路径 ：当标准 register() 返回 false 时，自动尝试通过反射调用 PlaceholderAPI.registerExpansion() 备选方案
• 新增 PAPI 变量 ： %guild_max_members% 、 %guild_exp% 、 %guild_required_exp% 、 %guild_created_time% 、 %guild_level_% （查询指定等级所需经验）
• GuildManager 新增 getUpgradeCost() 方法 ：方便其他模块查询升级费用
• GuildManager 新增 clearAllDailyData() 方法 ：用于每日重置日常经验/贡献
• 代码格式化 ：修复 Guild、GuildManager、GuildCurrency、GuildBank、CurrencyConfig 等核心文件的级联缩进问题
• 清理临时文件 ：删除 SimpleFix.java 及其编译产物

【其他】​

• 版本号更新至 3.0.5
• PAPI Expansion 版本号同步更新至 3.0.5
• 配置文件注释更新，说明升级费用动态计算公式

【修复】​

• 等级显示格式修改：经验显示为 当前经验/升级所需经验 格式，修复创建公会默认等级为0的问题，改为默认等级1
• 完善成员设置功能：添加设置昵称、设为管理员、降为成员、踢出公会的完整功能实现
• 完善成员列表功能：点击成员头像后正确打开玩家设置页面
• 修复离开公会逻辑：普通成员点击后需二次确认（输入confirm），会长点击后提示解散公会并要求二次确认，修复之前点击离开但实际未离开的问题
• 修复PAPI变量无法使用：将动态代理方式改为直接继承PlaceholderExpansion抽象类，兼容不同版本PAPI
• 修复语言文件占位符格式：统一将 {placeholder} 改为 %placeholder%

【新增】​

• 创建公会权限控制：guild.create 权限默认改为仅OP拥有，普通玩家需通过权限插件分配
• 创建公会金钱消耗：配置文件新增 create-requires-money 开关和 create-cost 金额设置，支持 Vault、PlayerPoints、公会币三种货币
• 成员昵称设置功能：管理员可通过GUI设置成员公会内昵称
• 创建配置文件版本号

【其他】​

• 版本号更新：3.0.3 → 3.0.4
• 配置文件更新：1.0 → 1.1

注意：从3.0.4版本开始，默认配置文件发生改动，请手动添加/替换旧版配置文件！

【修复】​

• Spigot 1.12 版本兼容性问题：InventoryView 在 1.12 中是类而非接口，直接调用 event.getView() 导致 IncompatibleClassChangeError，修改事件处理方法改用 event.getInventory() 获取物品栏
• GUI 物品可拖拽问题：在 onInventoryDrag 和 onInventoryInteract 事件中通过 isGuildInventory() 判断公会 GUI，取消拖拽事件并更新物品栏
• 变量无法替换问题：消息配置文件中混合使用 {placeholder} 和 %placeholder% 两种格式，统一为百分号格式，修复 zh_cn.yml、GUIConfig.java 等文件中的占位符
• PrepareAnvilEvent 兼容性：旧版本 Bukkit API 中没有 getWhoClicked() 方法，改用反射获取玩家对象
• PAPI 变量空指针保护：为 %guild_owner%、%guild_role%、%guild_role_level%、%guild_is_owner%、%guild_is_officer%、%guild_bank_balance% 等变量添加空值检查，统一布尔值返回格式为小写 "true"/"false"

【其他】​

• 版本号更新：3.0.2 → 3.0.3

紧急更新！！​

【修复】​

• 最小化 JAR 时删除了未使用的类，导致类结构不完整，ART 重映射时产生重复方法签名 $oe$()V
• 签名文件和 module-info 可能干扰 ART 的重映射过程

【其他】​

• dumps:版本号改动

【修复】​

• 修复了铁砧GUI创建公会时报错的问题
• 修复了铁砧GUI创建公会时一直循环的问题
• 修复了GUI中部分物品点击报错或无法点击的问题
• 修复了经济“通货膨胀”过大的问题

【优化】​

• 升级了整体架构
• 优化了插件性能
• 优化了内部经济平衡性
• 美化了GUI的布局

【删除与新增】​

• 删除了铁砧GUI创建公会，改为聊天输入+GUI的模式

【其他】​

• dumps: 版本号改动