原创 付费 [1.20.1] WarZArmorRepairKit| 三角洲护甲修理插件 | |读条修甲 + TacZ互通 + 自定义绑定 1.0.0

---

[MD] # WarZArmorRepairKit v1.0.0 **三角洲护甲修理插件 | Spigot 1.20.1** 复刻端游战术修甲玩法 · 手持修理包读条修理 · 移动/受伤/切物品打断 · TacZ PDC 耐久完全互通 **作者**：Crazy_Jky **版本**：V1.0.0 **开发框架**：Maven **适配服务端**：Spigot 1.20.1（兼容 Paper 同版本） **附属关系**：WarZTacZBullet 子弹插件附属（推荐搭配） --- ## 一、插件简介 **WarZArmorRepairKit** 是 **WarZTacZBullet** 子弹插件的官方附属插件，完美复刻《三角洲行动》护甲修理机制。 玩家手持修理包右键启动读条修理，修理过程中**移动、受伤、切换物品、丢弃道具**都会打断修理，且**不消耗修理包**，极具战术深度。 - 完美对接 TacZ 子弹插件的 PDC 护甲耐久体系（子弹扣甲 + 修理回甲数据完全互通） - 无 TacZ 时自动降级使用原版护甲 - 支持玩家自定义任意物品作为个人专属修理包（`/ar bind`） - 双进度显示（BossBar + ActionBar） - 全参数高度可配置 --- ## 二、插件概述 ### 2.1 插件简介 WarZArmorRepairKit 依托 Spigot 1.20.1 开发，是 WarZTacZBullet 配套附属插件，落地三角洲行动同款护甲修理玩法：玩家使用护甲修理包右键启动修理读条，等待配置时间完成护甲耐久修复；修理过程移动、受伤、切换物品、丢弃道具都会终止修理，道具无损。 ### 2.2 核心设计理念 1. **沉浸式战术**：摒弃瞬时修甲，复刻端游读条修理，营造野外找掩体修甲的生存玩法 2. **风险博弈**：修甲僵直不能移动，玩家需要规划作战点位，提升服务器 PVP 战术深度 3. **数据互通**：共用 TacZ 子弹插件 PDC 耐久键值，子弹扣甲、修理回甲数据完全互通 4. **灵活兼容**：软依赖架构，无 TacZ 时自动降级使用原版护甲耐久规则，单插件可独立运行 ### 2.3 全功能一览 | 功能模块 | 详情说明 | |------------------|--------------------------------------------------------------------------| | 右键快捷修理 | 手持修理包右键修单部位护甲，Shift + 右键一键全修头盔 + 胸甲 | | 指令快捷修理 | `/ar head` / `/ar chest` / `/ar all` | | 指令免道具快速修甲 | 管理员权限可直接使用指令修理，无需消耗修理包 | | 双栏进度展示 | BossBar 顶部进度条 + ActionBar 快捷栏文字双显示，可单独开关 | | 多重中断判定 | 位移超限、受伤、切副手、丢弃物品、玩家离线全场景中断 | | CD 冷却管控 | 修甲成功后进入配置冷却，中断不修 CD、不消耗修理包 | | 自定义修理包 | `/ar bind` 自由绑定任意物品作为专属修理包，支持材质 / 名称 / Lore 多条件匹配 | | 双模式护甲识别 | 联动 TacZ 读取自定义护甲规则；无依赖自动降级原版护甲分级 | | 全参数配置化 | 修甲时长、修复数值、消耗数量、音效、提示文本全部 yml 可配置 | --- ## 三、依赖与兼容性 ### 3.1 软依赖清单 | 依赖插件 | 必要性 | 作用说明 | |-------------------|----------------|--------------------------------------------------------------------------| | WarZTacZBullet | 推荐安装（可选） | 读取 armor.yml 自定义护甲规则、护甲等级、自定义最大耐久，实现全模组护甲适配 | | WarZNaiJiu | 可选 | 检测自定义耐久道具，遇到耐久被奈玖接管的护甲自动跳过修理逻辑 | ### 3.2 PDC 数据互通规则 插件与 WarZTacZBullet 共用同一 PDC 持久化键，实现子弹扣甲、修理回甲数据互通： ```plaintext 命名空间键：warztaczbullet:armor_durability 数据类型：PersistentDataType.INTEGER ``` - **WarZTacZBullet**：子弹命中护甲 → 扣除该 PDC 内耐久数值 - **WarZArmorRepairKit**：修理完成 → 写入恢复该 PDC 耐久，同步原版装备耐久 UI ### 3.3 两种运行模式 **模式 A｜已装载 WarZTacZBullet（完整版，推荐）** 通过 Java 反射桥接 TacZ 配置服务，调用 `matchHelmetRule()` / `matchChestRule()` 读取 armor.yml 内全部自定义护甲配置，精准获取护甲最大耐久、护甲分级。 **模式 B｜未装载 WarZTacZBullet（降级版，独立运行）** 采用原版材质硬编码分级，自动识别原版护甲最大耐久。 | 原版材质 | 护甲等级 | 默认最大耐久来源 | |--------------|----------|------------------------------| | 皮革护甲系列 | 1 级 | Material 原生 MaxDurability | | 铁甲系列 | 3 级 | Material 原生 MaxDurability | | 钻石甲系列 | 4 级 | Material 原生 MaxDurability | | 下界合金甲 | 5 级 | Material 原生 MaxDurability | --- ## 四、安装与配置教程 ### 4.1 安装步骤 1. 服务端环境：Spigot 1.20.1（兼容同版本衍生服务端 Paper） 2. 将 `WarZArmorRepairKit-1.0.0.jar` 放入服务器 `plugins` 文件夹 3. 【可选】放入 `WarZTacZBullet.jar` 实现完整自定义护甲识别 4. 重启服务端生成默认 `config.yml` 配置文件 5. 修改配置后使用 `/ar reload` 热重载配置，无需重启服务器 ### 4.2 config.yml 全注释配置文档 ```yaml #====================修理包全局定义==================== repair_kit: material: NETHER_STAR # 全局修理包基础材质 customModelData: -1 # 自定义模型ID，-1=不校验CMD nameContains: "修理包" # 物品名称包含字符（自动去颜色+小写比对） loreContains: # Lore多条件全匹配列表 - "右键使用" displayName: "&6护甲修理包" # 配置生成修理包默认显示名（仅生成道具用） lore: # 默认道具Lore - "&7右键点击来修理你装备的护甲" - "&7Shift + 右键 可同时修理头盔和胸甲" - "&7在修理过程中请勿移动或受到伤害" #====================修理核心参数==================== repair: head_repair_time: 5 # 单修头盔读条秒数 chest_repair_time: 7 # 单修胸甲读条秒数 all_repair_time: 12 # 头盔+胸甲全修读条秒数 head_repair_amount: "full" # full=修满最大耐久；数字=固定回复耐久值 chest_repair_amount: "full" all_repair_amount: "full" consume_amount: 1 # 单次修理消耗修理包数量 cooldown_seconds: 30 # 修理成功冷却时长，0=关闭冷却 #====================中断规则配置==================== interrupt: on_move: true # 开启移动中断 move_threshold: 0.5 # 位移中断阈值（方块距离），0=任意微小移动即打断 on_damage: true # 受伤打断修理 on_item_swap: true # 主副手切换物品打断 on_item_drop: true # 丢弃手持物品打断 #====================进度条显示配置==================== progress: mode: "both" # 可选bossbar / actionbar / both bossbar_color: "GREEN" # BossBar颜色：BLUE/GREEN/PINK/PURPLE/RED/WHITE/YELLOW bossbar_style: "SOLID" # 进度条样式：SOLID/SEGMENTED_6/SEGMENTED_10/SEGMENTED_12/SEGMENTED_20 actionbar_format: "&a&l▸ &a正在修理 ${partName} &7... &f${percent}% &8| &7剩余 &f${time}s" #可用变量：${percent}百分比、${time}剩余秒数、${partName}护甲部位 #====================音效配置==================== sound: start_enabled: true start_sound: "BLOCK_ANVIL_USE" complete_enabled: true complete_sound: "BLOCK_ANVIL_LAND" interrupt_enabled: true interrupt_sound: "ENTITY_ITEM_BREAK" #====================自定义修理包绑定开关==================== bind: enabled: true # 是否开启玩家自定义绑定修理包功能 #====================全消息配置（支持&颜色码，${prefix}前缀变量）==================== messages: prefix: "&8[&6护甲修理&8] &r" ``` --- ## 五、指令 & 权限 ### 5.1 主指令：`/armorrepair` | 简写别名 `/ar` | 子指令 | 使用格式 | 权限节点 | 功能描述 | |--------|--------------|----------------------------|-----------------------------------| | head | /ar head | warzarmorrepairkit.use | 指令直接修理头盔，无需消耗修理包 | | chest | /ar chest | warzarmorrepairkit.use | 指令直接修理胸甲 | | all | /ar all | warzarmorrepairkit.use | 一键全修头盔 + 胸甲 | | bind | /ar bind | warzarmorrepairkit.use | 手持道具绑定为个人专属修理包 | | unbind | /ar unbind | warzarmorrepairkit.use | 解除当前个人修理包绑定 | | reload | /ar reload | warzarmorrepairkit.admin | 重载插件配置文件（OP 管理员） | ### 5.2 权限表 | 权限节点 | 默认拥有者 | 权限说明 | |-----------------------------|------------|------------------------------| | warzarmorrepairkit.use | 全部玩家 | 使用修理包、绑定道具、修理指令 | | warzarmorrepairkit.admin | OP | 配置重载管理权限 | ### 5.3 Tab 自动补全 输入 `/ar` 按下 Tab 自动补全全部子命令：`head`、`chest`、`all`、`bind`、`unbind`、`reload` --- ## 六、完整修理业务逻辑 ### 6.1 修理全流程状态机 1. **校验阶段** 校验手持 / 绑定道具是否为合法修理包 → 校验身上是否穿戴护甲 → 校验护甲非满血 → 校验无冷却 CD → 校验当前无正在进行的修甲任务；任意校验失败终止修理并弹窗提示。 2. **消耗道具** 校验全部通过后，扣除配置数量修理包。 3. **创建修甲任务** 记录玩家初始坐标（位移判定基准）、生成 RepairState 任务实例、初始化 BossBar 进度条、播放启动音效、开启 Bukkit 定时任务。 4. **Tick 循环倒计时** 逐 Tick 减少剩余修甲时间，循环检测全部中断条件，同步刷新 BossBar + ActionBar 进度文本。 - 触发中断：销毁任务、关闭进度条、播放中断音效、不消耗 CD、修理包不返还 - 倒计时归零：进入修甲完成逻辑 5. **修理收尾** - **完成**：写入 PDC 耐久 + 同步原版装备 Damage 耐久条、播放完成音效、添加配置冷却 CD、推送完成提示 - **中断**：直接结束任务无任何耐久变更 ### 6.2 修理数值计算规则 1. `full` 参数：护甲耐久直接拉满至该护甲配置最大耐久（TacZ 自定义 maxDurability / 原版装备最大耐久） 2. 固定数字（例：50）：当前耐久 + 固定数值，上限不超过护甲最大耐久，不会超修溢出 ### 6.3 耐久双同步逻辑 ```java // 1. 写入 TacZ 共用 PDC 耐久 pdc.set("warztaczbullet:armor_durability", PersistentDataType.INTEGER, newDurability); // 2. 同步原版装备耐久显示条 if (装备实现 Damageable 接口) { int damage数值 = (1 - 当前耐久 / 最大耐久) * 装备原版最大耐久; item.setDamage(damage数值); } ``` 效果：TacZ 子弹插件读取 PDC 做护甲减伤计算，游戏内装备图标耐久条同步变化，双向兼容。 --- ## 七、自定义修理包绑定系统 ### 7.1 绑定功能作用 除配置文件全局修理包外，玩家可使用 `/ar bind` 将任意手持物品设置为个人专属修理包，背包内所有匹配特征道具均可右键修甲。 ### 7.2 绑定特征存储项 绑定时抓取物品四项特征作为匹配依据： 1. 物品 Material 材质 2. CustomModelData 自定义模型（-1 代表忽略该项匹配） 3. 去除颜色代码后的物品名称（全小写比对） 4. 完整 Lore 文本内容 ### 7.3 道具检索优先级 1. 主手手持道具 → 优先匹配个人绑定 > 全局配置修理包 2. 副手手持道具 → 同上规则 3. 背包其余格子道具 → 满足匹配即可消耗使用 > **备注**：绑定数据存储内存，服务器重启后全部绑定失效，需要玩家重新执行 `/ar bind` 绑定。 --- ## 八、中断机制 & 冷却系统详解 ### 8.1 移动中断计算公式 两点空间距离公式：`距离 = √(Δx² + Δy² + Δz²)` 玩家当前坐标与启动修甲坐标距离 > `move_threshold` 配置值 → 判定位移打断 - 阈值 = 0：角色任何微小移动直接打断（转头 / 小幅挪动） - 阈值 = 0.5：角色移动半格以上才触发打断 ### 8.2 全中断触发行为汇总 | 触发条件 | 执行逻辑 | |------------------------|----------------------------------------------------| | 位移超限 / 受伤 / 切物品 / 丢物品 | 取消任务、移除进度条、发送中断消息、播放中断音效、不消耗修理包、不生成冷却 CD | | 玩家离线 | 静默销毁全部修甲任务，无提示消息 | ### 8.3 冷却规则 - 仅修理成功结束才会添加配置冷却时间 - 修理中途中断不触发冷却，可立刻再次开启修理 - `cooldown_seconds: 0` 全局关闭冷却限制 --- ## 九、进度展示效果说明 ### 9.1 三种显示模式 1. `bossbar`：仅屏幕顶部进度条展示修甲进度 2. `actionbar`：仅快捷栏上方浮动文字展示 3. `both`：双显示同时开启（推荐） ### 9.2 展示示例 - **BossBar**：██████████░░░░░ 70% | 剩余 4s - **ActionBar**：▸ 正在修理 胸甲 ... 70% | 剩余 4s - **聊天文本**：插件前缀 + 分段开始 / 进行 / 完成提示消息 --- ## 十、运行控制台日志 插件正常启用打印日志格式： ```plaintext ▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃ [WarZArmorRepairKit] 插件已启用 版本: 1.0.0 作者: Crazy_Jky ✔ 配置文件加载完成 ✔ WarZTacZBullet 护甲等级联动: 已启用（反射桥接） ● WarZNaiJiu 耐久联动: 未检测到 ✔ 耐久管理器已初始化 ✔ 命令处理器已注册 ✔ 事件监听器已注册 插件技术交流群: 398893720 末日类服务器交流群: 1063544727 插件定制开发: QQ 1285988665 支持作者: https://afdian.com/a/sunjood ▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃▃ ``` --- ## 十一、常见问题 FAQ **Q1：修理包右键无任何反应？** 1. 手持物品不满足 `config.yml` 全局修理包匹配规则（材质 / 名称 / Lore 校验） 2. 当前处于修理冷却 CD 中，等待 CD 结束重试 3. 身上已有正在进行的修甲读条任务，无法二次启动 4. 模组自定义护甲未在 WarZTacZBullet 的 `armor.yml` 配置，无 TacZ 插件时仅原版护甲可识别修理 **Q2：修理完成护甲耐久没变化？** 1. 修甲过程被移动 / 受伤意外中断（中断不会执行耐久写入） 2. 修理量配置填写错误，核对 `head_repair_amount` 参数 3. 使用 TacZ 调试指令 `/wtb debugarmor 玩家名` 查看护甲 PDC 原始耐久数据 **Q3：想要自定义道具做修理包？** 手持目标道具执行 `/ar bind` 一键绑定为个人修理包，重启失效。 **Q4：能否关闭读条实现瞬修？** 修甲时间配置最小限制 1 秒，填 0 配置会被插件强制修正为 1，无法完全无读条。 **Q5：搭配 WarZNaiJiu 自定义耐久装备失效？** 插件自动识别奈玖耐久标记，被奈玖接管耐久的护甲跳过本插件修理逻辑，需使用奈玖自带修理功能。 --- --- ## 十三、更新日志 ### V1.0.0（首发正式版） 1. 完成全量三角洲风格读条修甲基础功能 2. 实现 TacZ 子弹插件 PDC 互通、双运行模式降级适配 3. 自定义修理包绑定、全参数 yml 可配置 4. 多重中断判定、冷却系统、双样式进度显示 5. 音效、全自定义消息系统完善 --- **联系方式** - 插件技术交流群：398893720 - 末日类服务器交流群：1063544727 - 插件定制开发：QQ 1285988665 - 支持作者：https://afdian.com/a/sunjood [/MD]