装备来源与物品数据

六槽来源

内置读取器只扫描：主手、副手、头、胸、腿、脚，来源固定为：

sealattributes:equipment/main_hand
sealattributes:equipment/off_hand
sealattributes:equipment/head
sealattributes:equipment/chest
sealattributes:equipment/legs
sealattributes:equipment/feet

每个槽是一份完整快照；换装整体替换，卸下整体撤销。插件不会扫描饰品、背包、自定义槽或套装共鸣。

规范 JSON PDC

键固定为 sealattributes:item_attributes，值为 UTF-8 JSON，schema 1：

{
  "schema": 1,
  "attributes": [
    {
      "id": "sealattributes:physical_attack",
      "operation": "ADD",
      "value": 25.0
    },
    {
      "id": "sealattributes:max_health",
      "operation": "TOTAL_PERCENT",
      "value": 20.0
    }
  ]
}

物品输入中 20.0 表示 20%，运行时变为 0.20。限制：JSON 最多 16,384 字节、最多 64 项原始属性、最大嵌套深度 3；同一 ID+operation 会被确定性合并求和，数值必须有限，TOTAL_PERCENT 仅适用于支持它的 AMOUNT 属性。

Paper 写入示例（Java）

package example.items;

import org.bukkit.NamespacedKey;
import org.bukkit.inventory.ItemStack;
import org.bukkit.persistence.PersistentDataType;
import org.bukkit.plugin.java.JavaPlugin;

public final class AttributeItemWriter {
    private final NamespacedKey key;

    public AttributeItemWriter(JavaPlugin plugin) {
        this.key = new NamespacedKey("sealattributes", "item_attributes");
    }

    public void writeSword(ItemStack item) {
        String json = """
            {"schema":1,"attributes":[
              {"id":"sealattributes:physical_attack","operation":"ADD","value":25.0},
              {"id":"sealattributes:max_health","operation":"TOTAL_PERCENT","value":20.0}
            ]}
            """;
        item.editPersistentDataContainer(pdc ->
            pdc.set(key, PersistentDataType.STRING, json)
        );
    }
}

预期：持主手后 /sa item inspect <玩家> 显示有效，/sa sources <玩家> 出现主手来源。典型错误是用创建方插件自己的 namespace 构造键；必须写固定的 sealattributes:item_attributes。

扁平 PDC 兼容写法

MythicMobs 结构化物品可写 22 项内置属性的 DOUBLE：

sealattributes:physical_attack = 25.0
sealattributes:total_percent/max_health = 20.0

第一种为 ADD；total_percent/<path> 为 TOTAL_PERCENT。只接受内置属性、DOUBLE 值。自定义扩展属性必须写规范 JSON。

不要混用

同一物品同时存在规范 JSON 和扁平 PDC 会被视为歧义，整个物品输入无效。未知属性可作为“休眠项”保留；已知项仍可应用，但任何结构/语义错误会让整件物品无效。

Lore 兼容模式

item-mode: LORE 时只读取配置的精确文本模板，不读 PDC。Lore 适合旧服迁移，不适合作为高价值物品真实性凭据，因为玩家可见文本通常会被其他插件复制或改写。

lore:
  formats:
    number: ["{name}: {value}"]
    percent: ["{name}: {value}%"]
  aliases:
    sealattributes:physical_attack: [物攻]
  templates:
    - attribute: sealattributes:max_health
      operation: TOTAL_PERCENT
      template: "总生命 +{value}%"

可匹配：

物攻: +25
总生命 +20%

何时刷新

正常装备事件会重建相关槽。怀疑其他插件绕过事件修改物品时，管理员执行 /sa refresh <玩家>，它只请求内置读取器在下一合法线程时机重读，不刷新 SealItems 自有来源。用 item inspect 先检查输入，再用 sources 检查发布，最后用 inspect 检查聚合，可快速定位三层问题。

避免重复来源

• 只让一个系统拥有装备来源；
• 使用 SealItems 时关闭内置读取器并重启；
• 自定义槽由插件自己的 provider 发布，不要伪装 sealattributes；
• 套装/共鸣单独用稳定键，如 sealitems:equipment/resonance；
• 每槽发布完整安全组件，不按玩法拆成大量来源，也不要超过单快照 512 项和单主体 256 来源。