ZaKoStrengthen (Equipment Enhancement Plugin)

A Paper 1.21.10 plugin: Enhance equipment via a custom GUI, adding extra attribute bonuses to weapons/armor/shields. Supports 3-tier failure penalties, protection scrolls, mineral/mystery potions to boost success rate, and chest/fishing item acquisition.

I. Gameplay Overview

II. Core Mechanics

1. Enhancement Stages & Failure Penalties

• Each enhancement consumes 1 Enhancement Template.
• Success rate is read from level-success-rate config, using the largest configured value <= current level.
• Mineral Potion and Mystery Potion bonuses are directly added as percentages to the base success rate (stackable).

2. Attribute Bonus System (Stacking)

Enhancement appends additional Minecraft attribute modifiers to equipment, without overwriting original attributes (vanilla default attributes + existing custom attributes + enhancement attributes merged together).

Each equipment type can have multiple attributes configured, each with an independent base-value (per-level bonus) and slot (active slot).

Final Bonus Formula: Bonus = base-value × Enhancement Level

Example: Diamond Sword enhanced to +20, config generic.attack_damage base-value=0.5:

Bonus = 0.5 × 20 = +10 Attack Damage

3. Enhancement GUI Layout (45 Slots)

Row 0: [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass]
Row 1: [Gray Glass] [Template Label] [Template Slot] [Gray Glass] [Gray Glass] [Equipment Label] [Equipment Slot] [Gray Glass] [Gray Glass]
Row 2: [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass]
Row 3: [Gray Glass] [Gray Glass] [Confirm] [Gray Glass] [Status Indicator] [Gray Glass] [Cancel/Close] [Gray Glass] [Gray Glass]
Row 4: [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass] [Gray Glass]

• Clicking non-interactive slots will be cancelled. Player inventory (>=45 slots) is unrestricted and items can be freely taken.

4. Potion System

Mineral Potions (Crafting Table):

Crafting Layout (3x3 Crafting Table):

[Empty] [Mineral] [Empty]
[Empty] [Awkward Potion] [Empty]
[Empty] [Gunpowder] [Empty]

Mystery Potion: +25%, stackable with Mineral Potions, cannot stack with itself.

5. Chest Loot

When opening normal chests/trapped chests/barrels/shulker boxes, items are automatically inserted based on probability:

Each chest block is evaluated only once; all items are independently evaluated (a single chest can yield multiple items).

6. Fishing Acquisition

Fishing has an 8% chance to replace the caught item with an Enhancement Template.

III. Items

IV. Commands

V. Configuration File Parameters (config.yml)

Message Text

messages:
  prefix: "&8[&6Strengthen System&8] &r"
  success: "&aEnhancement successful! Current level: &e%level%"
  fail-safe: "&cEnhancement failed, but your equipment was not affected."
  fail-level-down: "&cEnhancement failed! Equipment level dropped to &e%level%"
  fail-destroy: "&cEnhancement failed! Equipment has been destroyed!"
  protect-level: "&eLevel Protection Scroll activated, equipment level preserved."
  protect-destroy: "&eDestroy Protection Scroll activated, equipment preserved. Scroll consumed."
  potion-active: "&aMystery Potion effect activated, success rate +%bonus%%"
  invalid-slot: "&cThis equipment cannot be enhanced!"
  max-level: "&cThis equipment has reached the maximum enhancement level!"
  give-received: "&aYou received %item%"
  set-level-success: "&aSet %item% enhancement level to &e%level%"
  reload-success: "&aConfiguration reloaded!"
  no-permission: "&cYou do not have permission to perform this action."

Placeholders: %level% = Enhancement Level / %item% = Item Name / %bonus% = Bonus Percentage

Success Rate & Stages

level-success-rate:
  1: 100.0    # Level 1 success rate 100%
  10: 91.0    # Level 10 success rate 91%
  20: 70.0    # Level 20 success rate 70%
  25: 55.0    # Level 25 success rate 55%
  50: 11.0    # Level 50 success rate 11%
  100: 0.3    # Level 100 success rate 0.3%
  # Format: level: percentage, uses largest configured value <= current level

max-level: 100

stages:
  stage1-max: 10   # Levels 1-10: no failure penalty
  stage2-max: 20   # Levels 11-20: failure causes level down
  stage3-max: 100  # Levels 21+: failure causes destruction

Enhanceable Equipment Types

Three config sections (equipment-types / intensify-attributes / slot-config) must use identical type names. Default provides 3 types, extendable as needed.

Default Type Names:

Custom Type Example (e.g., distinguishing bows from melee weapons):

equipment-types:
  weapon:
    - "minecraft:netherite_sword"
    - "minecraft:diamond_sword"
  bow:
    - "minecraft:bow"
    - "minecraft:crossbow"
  tool:
    - "minecraft:netherite_pickaxe"
    - "minecraft:diamond_pickaxe"

intensify-attributes:
  weapon:
    - attribute: "generic.attack_damage"
      base-value: 0.5
      slot: "HAND"
  bow:
    - attribute: "generic.attack_damage"
      base-value: 0.3
      slot: "HAND"
  tool:
    - attribute: "generic.mining_efficiency"
      base-value: 0.5
      slot: "HAND"

slot-config:
  weapon: "HAND"
  bow: "HAND"
  tool: "HAND"

The type names across all three sections must be identical, otherwise that type's attribute bonuses and slot config will not take effect.

Custom Attribute Bonuses (Core Config)

intensify-attributes:
  weapon:
    - attribute: "generic.attack_damage"  # Attribute ID
      base-value: 0.5                     # Per-level bonus value
      slot: "HAND"                        # Active slot
    - attribute: "generic.attack_speed"
      base-value: 0.1
      slot: "HAND"
  armor:
    - attribute: "generic.armor"
      base-value: 0.3
      slot: "ANY"  # Applies to helmet/chestplate/leggings/boots
    - attribute: "generic.armor_toughness"
      base-value: 0.15
      slot: "ANY"
  shield:
    - attribute: "generic.max_health"
      base-value: 0.2
      slot: "OFF_HAND"
    - attribute: "player.reach"
      base-value: 0.05
      slot: "OFF_HAND"

Field Descriptions:

Common Attribute IDs:

Slot Options:

When the slot field is omitted in attribute config, it automatically falls back to the default slot in slot-config for that type. For armor types, set slot: "ANY" to make bonuses apply across all armor pieces.

Potions & Loot

mineral-potion-bonus:
  iron: 3.0        # Success rate bonus for each mineral potion
  diamond: 15.0
  netherite: 20.0
  # ...

mineral-potion:
  duration: 30     # Mineral potion duration in seconds

mystery-potion:
  bonus-rate: 25.0 # Mystery potion bonus

template-drop:
  fishing-chance: 0.08  # Chance to obtain Enhancement Template from fishing

chest-loot:
  enabled: true
  strengthen-core: 0.05
  level-protect-scroll: 0.04
  destroy-protect-scroll: 0.03

Custom Item Appearance

custom-items:
  strengthen-core:
    material: "nether_star"       # Item material
    name: "&6Enhancement Core"    # Display name (supports & color codes)
    lore:                         # Item description
      - "&7Right-click to open enhancement interface"
    custom-model-data: 10000      # Custom model data (for resource pack)
  # ...other items follow the same format

Item identification relies on internal PDC tags; material/name/lore can be freely modified without affecting functionality.

Mineral Potion Crafting Recipes

mineral-potion-recipes:
  iron:
    mineral: "RAW_IRON"          # Crafting material (material ID)
    name: "&7Iron Ore Potion"
    lore:
      - "&7Drink to gain"
      - "&7enhancement success rate &a+3%"
    bonus-rate: 3.0              # Must match mineral-potion-bonus
    custom-model-data: 10010
  # ...other minerals follow the same format

config.yml is only auto-generated on plugin first run. After modification, use /sh reload for hot-reload; if the server already has an older config version, manually add new parameters or delete the file to regenerate.

VI. Technical Notes (Admin Reference)

• Supports Paper 1.21.10 only (API 1.21), Java 21.
• Attribute merging implemented via NMS: reads DataComponents.ATTRIBUTE_MODIFIERS (MC 1.21.10 stores default attribute values in this component), merges vanilla default attributes + player custom attributes + enhancement attributes, then writes back to ItemMeta.
• Enhancement modifiers use deterministic NamespacedKeys (zakostrengthen:strengthen_<attribute>_<slot>), ensuring no identification loss during NMS round-trips.
• All custom items identified via PDC (PersistentDataContainer) tags, not dependent on item name or lore comparison.
• Potion effects use PDC tags to prevent same-type stacking; effects auto-remove upon expiration.
• Chest loot uses TileState PDC tags to prevent duplicate evaluation; each chest block triggers only once.

ZaKoStrengthen (装备强化插件)

一款 Paper 1.21.10 插件：通过自定义 GUI 界面强化装备，为武器/盔甲/盾牌添加额外属性加成。支持 3 阶段失败惩罚、保护卷轴、矿物药水/神秘药水提升成功率，以及宝箱/钓鱼获取道具。

一、玩法总览

二、核心机制说明

1. 强化阶段与失败惩罚

• 每次强化消耗 1 个强化模板。
• 成功率从 level-success-rate 配置读取，取 <= 当前等级的最大已配置值。
• 矿物药水和神秘药水的加成在基础成功率上直接加百分比（可叠加）。

2. 属性加成系统（叠加式）

强化为装备追加额外的 Minecraft 属性修饰符，不会覆盖装备原有属性（原版默认属性 + 已有自定义属性 + 强化属性三层合并）。

每个装备类型可配置多个属性，每个属性有独立的 base-value（每级加成）和 slot（生效槽位）。

最终加成公式：加成值 = base-value × 强化等级

示例：钻石剑强化到 +20，配置 generic.attack_damage base-value=0.5：

加成 = 0.5 × 20 = +10 攻击伤害

3. 强化 GUI 布局（45 格）

第0行: [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃]
第1行: [灰玻璃] [强化模板标签] [模板槽位] [灰玻璃] [灰玻璃] [装备标签] [装备槽位] [灰玻璃] [灰玻璃]
第2行: [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃]
第3行: [灰玻璃] [灰玻璃] [确认执行] [灰玻璃] [状态指示] [灰玻璃] [取消关闭] [灰玻璃] [灰玻璃]
第4行: [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃] [灰玻璃]

• 点击非交互槽位会被取消，玩家背包（>=45 格）不受限制，可自由拿取物品。

4. 药水系统

矿物药水（工作台合成）：

合成摆放（工作台 3x3）：

[空] [矿物] [空]
[空] [粗制药水] [空]
[空] [火药] [空]

神秘药水：+25%，可与矿物药水叠加，不可与自身叠加。

5. 宝箱战利品

打开普通箱子/陷阱箱/木桶/潜影盒时，按概率自动放入物品：

每个箱子方块只判定一次，所有物品独立判定（一个箱子可同时开出多个）。

6. 钓鱼获取

钓鱼时有 8% 概率将钓到的物品替换为强化模板。

三、物品道具

四、命令

五、配置文件参数（config.yml）

消息文本

messages:
  prefix: "&8[&6强化系统&8] &r"       # 消息前缀
  success: "&a强化成功！当前强化等级: &e%level%"
  fail-safe: "&c强化失败，但你的装备没有受到任何影响。"
  fail-level-down: "&c强化失败！装备强化等级下降至 &e%level%"
  fail-destroy: "&c强化失败！装备已被销毁！"
  protect-level: "&e掉级保护卷生效，装备未掉级。"
  protect-destroy: "&e强化保护卷生效，装备未被销毁，保护卷已消耗。"
  potion-active: "&a神秘药水效果已激活，成功率 +%bonus%%"
  invalid-slot: "&c该装备无法进行强化！"
  max-level: "&c该装备已达到最大强化等级！"
  give-received: "&a你获得了 %item%"
  set-level-success: "&a已将 %item% 强化等级设置为 &e%level%"
  reload-success: "&a配置已重载！"
  no-permission: "&c你没有权限执行此操作。"

占位符：%level% = 强化等级 / %item% = 物品名 / %bonus% = 加成百分比

成功率与阶段

level-success-rate:
  1: 100.0    # 1级成功率 100%
  10: 91.0    # 10级成功率 91%
  20: 70.0    # 20级成功率 70%
  25: 55.0    # 25级成功率 55%
  50: 11.0    # 50级成功率 11%
  100: 0.3    # 100级成功率 0.3%
  # 格式: 等级: 百分比，取 <= 当前等级的最大已配置值

max-level: 100

stages:
  stage1-max: 10   # 1-10级 失败无惩罚
  stage2-max: 20   # 11-20级 失败掉级
  stage3-max: 100  # 21级+ 失败销毁

可强化装备类型

三个配置节（equipment-types / intensify-attributes / slot-config）必须使用相同的类型名。默认提供 3 种类型，可自行扩展。

默认类型名：

自定义类型示例（如需区分弓和近战武器）：

equipment-types:
  weapon:
    - "minecraft:netherite_sword"
    - "minecraft:diamond_sword"
  bow:
    - "minecraft:bow"
    - "minecraft:crossbow"
  tool:
    - "minecraft:netherite_pickaxe"
    - "minecraft:diamond_pickaxe"

intensify-attributes:
  weapon:
    - attribute: "generic.attack_damage"
      base-value: 0.5
      slot: "HAND"
  bow:
    - attribute: "generic.attack_damage"
      base-value: 0.3
      slot: "HAND"
  tool:
    - attribute: "generic.mining_efficiency"
      base-value: 0.5
      slot: "HAND"

slot-config:
  weapon: "HAND"
  bow: "HAND"
  tool: "HAND"

三个节的类型名必须完全一致，否则该类型的属性加成和槽位配置不会生效。

自定义属性加成（核心配置）

intensify-attributes:
  weapon:
    - attribute: "generic.attack_damage"  # 属性ID
      base-value: 0.5                     # 每级加成值
      slot: "HAND"                        # 生效槽位
    - attribute: "generic.attack_speed"
      base-value: 0.1
      slot: "HAND"
  armor:
    - attribute: "generic.armor"
      base-value: 0.3
      slot: "ANY"  # 头盔/胸甲/护腿/靴子都生效
    - attribute: "generic.armor_toughness"
      base-value: 0.15
      slot: "ANY"
  shield:
    - attribute: "generic.max_health"
      base-value: 0.2
      slot: "OFF_HAND"
    - attribute: "player.reach"
      base-value: 0.05
      slot: "OFF_HAND"

字段说明：

常用属性 ID：

槽位可选值：

属性配置中省略 slot 字段时，自动回退到 slot-config 中该类型的默认槽位。盔甲类建议设为 slot: "ANY" 使加成覆盖所有护甲部位。

药水与战利品

mineral-potion-bonus:
  iron: 3.0        # 各矿物药水的成功率加成
  diamond: 15.0
  netherite: 20.0
  # ...

mineral-potion:
  duration: 30     # 矿物药水持续秒数

mystery-potion:
  bonus-rate: 25.0 # 神秘药水加成

template-drop:
  fishing-chance: 0.08  # 钓鱼获得强化模板概率

chest-loot:
  enabled: true
  strengthen-core: 0.05
  level-protect-scroll: 0.04
  destroy-protect-scroll: 0.03

自定义物品外观

custom-items:
  strengthen-core:
    material: "nether_star"       # 物品材质
    name: "&6强化核心"            # 显示名称（支持 & 颜色）
    lore:                         # 物品描述
      - "&7右键打开强化界面"
    custom-model-data: 10000      # 自定义模型数据（配合资源包）
  # ...其他物品同理

物品识别靠内部 PDC 标记，material/name/lore 可自由修改不影响功能。

矿物药水合成配方

mineral-potion-recipes:
  iron:
    mineral: "RAW_IRON"          # 合成材料（材质ID）
    name: "&7铁矿药水"
    lore:
      - "&7饮用后30秒内"
      - "&7强化成功率 &a+3%"
    bonus-rate: 3.0              # 需与 mineral-potion-bonus 一致
    custom-model-data: 10010
  # ...其他矿物同理

config.yml 仅在插件首次运行时自动生成。修改后用 /sh reload 热重载；若服务端已存在旧版配置，需手动添加新参数或删除该文件重新生成。

六、技术说明（管理员参考）

• 仅支持 Paper 1.21.10（API 1.21），Java 21。
• 属性合并通过 NMS 实现：读取 DataComponents.ATTRIBUTE_MODIFIERS（MC 1.21.10 属性默认值存储在该组件中），合并原版默认属性 + 玩家自定义属性 + 强化属性，再写回 ItemMeta。
• 强化修饰符使用确定性 NamespacedKey（zakostrengthen:strengthen_<属性>_<槽位>），确保 NMS 往返不丢失识别。
• 所有自定义物品通过 PDC（PersistentDataContainer）标记识别，不依赖物品名称或 lore 比对。
• 药水效果通过 PDC 标记防止同类叠加，过期自动移除。
• 宝箱战利品通过 TileState PDC 标记防止重复判定，每个箱子方块只触发一次。