- ◆ 游戏版本
- 1.20.1
- ◆ 服务端核心
- mohist
一、插件能做什么
给每一把 TACZ 枪械赋予独立的耐久度:开枪掉耐久、耐久归零损坏或销毁、可用修理包 / 金币修复。 所有数据跟随物品本身保存,跨重启、跨存储完全保留。二、核心特性详解
1. 基于 GunId 的枪械识别(支持全部扩展包)
- 通过读取物品 NBT 中的 GunId 标签识别枪械(如 tacz:ak47),不依赖不稳定的物品类型 / ItemMeta 判断
- TACZ 官方枪械 + 一切扩展包枪械自动兼容,无需逐个适配
- NBT 读取采用 NMS 反射直读,并针对 Mohist 1.20.1 的 SRG 混淆映射做了适配(getTag = m_41783_ 等);反射失败时自动回退到 Bukkit SNBT 正则解析,保证任何核心上都能工作
- 全程只读 TACZ 原生 NBT,绝不写入、不覆盖
2. 耐久数据存储于 PersistentDataContainer(PDC)
- 耐久、最大耐久、损坏标记、修理次数、累计发射子弹数全部存放在 Bukkit PDC(独立命名空间)
- 不污染、不覆盖 TACZ 原生 NBT(GunId、弹药数等原样保留)
- PDC 随物品持久化,跨重启、跨存档完全保留
3. 射击检测原理(天然支持全自动 / 半自动 / 点射)
TACZ 每开一枪会将枪械 NBT 中的 GunCurrentAmmoCount 减少 1。 插件每 1 tick 对玩家手中枪械做快照比对:弹药减少量 = 射击次数 = 应扣耐久
弹药增加 = 换弹,不扣耐久
- 通过物品 PDC 中的唯一 UID 判定"是不是同一把枪"(不能用 ItemStack.isSimilar —— TACZ 每次射击都会改弹药 NBT,导致快照永远不相等)
- 扣耐久前校验手上物品仍是这把枪,防止同 tick 切枪误扣
- 自动记录这把枪累计发射子弹数,HUD 可实时显示
4. 三种耐久归零模式(可配置)
| 模式 | 行为 |
|---|---|
| DESTROY | 耐久归零直接销毁枪械(播放破损音效 + 提示),贴近原版工具体验 |
| DISABLE | 枪械不消失,但强制禁用 —— 见下方"四重禁射防线" |
| CHANCE | 概率模式:归零时有 destroy-chance(0~1 可配)概率直接销毁,否则变为损坏 |
5. 损坏枪械的四重禁射防线(DISABLE / CHANCE 模式)
Mohist 上单纯取消 Bukkit 事件对 Forge 侧 TACZ 不完全生效,因此采用物理隔离 + 事件拦截双保险:- 切枪拦截:玩家选中损坏枪械的瞬间,先回退到原槽位,再把枪从手上转移到背包其他空位
- 子弹发射拦截:TACZ 子弹继承 Projectile,开枪必触发 ProjectileLaunchEvent —— 在子弹发射瞬间取消,无论单击 / 全自动都拦得住
- 右键拦截:损坏枪械右键交互直接取消(LOWEST 优先级,赶在 TACZ 处理前)
- 背包保护:禁止把损坏枪械点击 / 数字键放回当前手持槽位,杜绝绕过切枪检查
6. 耐久 HUD(ActionBar 常显)
手持枪械时屏幕下方显示:- 进度条为 十六进制真彩色平滑渐变(每格独立插值),支持 2~8 个 #RRGGBB 色标自由配色
- 默认可爱粉紫青渐变,也可一键改成经典的"绿→黄→红警示"或彩虹渐变
- 进度条字符可换(❤ / ❚ / ▌ / ■…),长度、刷新间隔、显示格式均可配置
- 占位符:{bar} {current} {max} {percent} {shots}(累计发射子弹数)
- 无限耐久显示专用格式
- 玩家可用 /gundur hud 自行开关
7. 低耐久智能提醒
- 耐久比例低于阈值(默认 30%)时触发
- 提醒方式可独立开关:ActionBar / Title / 音效(音效类型、音量、音调可配)
- 内置冷却时间防刷屏,提醒文本支持 & 颜色代码与 {percent} 占位符
8. 修理包系统(铁砧修理)
- 管理员手持任意物品执行 /gundur kit 即可将其转换为修理包(再次执行恢复原状;仅转换当前这一件,创造模式可复制)
- 修理包外观完全自定义(材质默认紫水晶碎片、名称、Lore)
- 枪械 + 修理包 放入铁砧 → 预览修理结果,取出时消耗修理包 + 经验等级,耐久修满
- 经验消耗可配置(xp-cost,0 = 免费),经验不足时拒绝修理并提示
- 针对 Mohist 做了经验确定性校正:扣经验后下一 tick 强制校验等级,防止个别核心重复扣经验甚至清零
9. 金币修理(/gundur repair)
- 玩家手持枪械花费金币直接修满,价格可配置(money-cost,≤0 禁用)
- Vault 反射桥接:不引入编译期依赖,无 Vault / 无经济插件时优雅降级(金币修理不可用,铁砧修理不受影响),状态日志清晰区分三种情况:READY / NO_VAULT / NO_PROVIDER
- 启动时 + 延迟 5 秒各检测一次(经济插件可能加载较晚),状态变化才输出日志
- 扣款失败(余额不足)有明确提示,扣款写入控制台日志
- 可配置管理员是否免费(admin-free-repair,默认管理员同样扣费)
- 金币修理是否计入修理次数上限可配置
10. 修理次数上限(枪械寿命机制)
- 每把枪可修理次数有上限(repair-limit,-1 不限),数据存于物品 PDC
- 剩余次数达到提醒阈值(warn-remaining)时黄色警告
- 达到上限的最后一次修理不会立即失效:枪照常可用,但耐久耗尽时必定销毁(不受 break-mode 影响),修理前也有醒目预告
- 已达上限的枪无法再修理,提示"请购买新枪"—— 天然的枪械经济回收机制
11. Lore 耐久显示
- 物品说明中显示耐久行,三种格式独立配置:正常 / 已损坏 / 无限耐久
- 更新时按格式前缀精准匹配移除旧耐久行,不碰 TACZ 和其他插件的 Lore
12. 其他细节
- per-gun 按枪械类型自定义最大耐久,per-gun-cost 按枪械自定义每发耐久消耗(如 AWP 一枪掉 3 点),-1 = 无限耐久
- /gundur set <耐久> 可仅设置手中这一把枪(写入物品自身 PDC,不影响同类其他枪)
- 可选监听副手枪械(check-offhand)
- 所有游戏内消息文本可在 config.yml 自定义,统一配色风格,控制台带启动 Banner
- 损坏提示带 3 秒冷却防刷屏;玩家退出自动清理缓存;离线玩家快照自动回收
三、命令与权限
| 命令 | 说明 | 权限 |
|---|---|---|
| /gundur help | 帮助菜单(普通玩家 3 条,管理员额外 3 条) | 所有人 |
| /gundur info | 查看手持枪械 GunId / 耐久 / 弹药 / 状态;非枪械时自动输出物品 NBT 到控制台辅助排查 | 所有人 |
| /gundur hud | 开关个人耐久 HUD | 所有人 |
| /gundur repair | 花金币修复手持枪械 | 所有人 |
| /gundur kit | 手持物品 ⇋ 修理包 转换 | 管理员 |
| /gundur set <耐久> | 设置手持枪械耐久(-1 无限;也支持旧用法 set <GunId> <耐久> 写入全局配置) | 管理员 |
| /gundur reload | 重载配置(自动重启周期任务) | 管理员 |
四、完整配置文件(默认值)
放入插件启动查看五、技术实现亮点(给同好)
| 设计 | 说明 |
|---|---|
| NMS 反射 + SNBT 双方案 | 优先 Mojang 映射,其次 SRG 混淆映射(Mohist 1.20.1),失败回退纯 Bukkit SNBT 正则解析,任何核心都能跑 |
| PDC 存储 | 耐久体系完全走 Bukkit PDC,与 TACZ 原生 NBT 物理隔离,互不干扰 |
| UID 快照机制 | 物品唯一 UID 判枪,解决了"弹药 NBT 每枪都变导致 isSimilar 失效"的经典坑 |
| 事件拦截 + 物理转移 | 损坏枪械禁射不赌核心事件行为,"枪不在手上"才是硬保证 |
| Vault 反射桥接 | 零编译期依赖接入经济系统,三态状态日志 |
| 经验确定性校正 | 下一 tick 强制校验等级,根治 Mohist 铁砧重复扣经验问题 |
| Lore 前缀精准维护 | 只增删自己的耐久行,与其他插件 Lore 和平共处 |