孔位、宝石与共鸣

孔位系统由设置、孔型、profile、操作、限制、宝石、共鸣和迁移共同组成。所有部分会一起编译、一起原子发布；任一引用错误都不会发布半套规则。

1. 总开关与未鉴定策略

gameplay/sockets/settings.yml：

enabled: true
unidentified:
  reveal-sockets: false
  allow-operations: false
equipped-conflicts:
  fallback: disable-excess
  priority: [main-hand, off-hand, helmet, chestplate, leggings, boots]
legacy-items:
  policy: preserve

• 隐藏孔位不会删除状态。
• 禁止操作会阻止未鉴定装备进入工作台提交。
• 全身限制超额时 disable-excess 只停用低优先级超额宝石，不摧毁、不弹出。
• priority 必须是这六个装备槽的明确顺序。
• preserve 让启用系统前的旧装备保持无孔，不给存量装备偷偷重抽。

2. 定义孔型

socket-types.yml：

types:
  attack:
    display-name: '<red>攻击孔'
    accepts: [fire]
    arcartx-icon: 'sealitems:socket/attack'
  universal:
    display-name: '<light_purple>通用孔'
    accepts: [fire, elemental]
    arcartx-icon: 'sealitems:socket/universal'

宝石任一 category 命中 accepts 即可嵌入。arcartx-icon 只是 UI 资源身份，不参与业务匹配。

3. 定义 profile 与物品匹配

profiles.yml：

profiles:
  standard-weapon:
    context: weapon
    potential:
      weights: { 1: 80, 2: 20 }
    initially-open: 1
    socket-type-weights: { attack: 80, universal: 20 }
    operations:
      unlock: [unlock-standard]
      insert: [insert-standard]
      convert: [convert-standard]
      remove: [remove-safe]
      replace: [replace-standard]

assignments:
  - priority: 100
    match-tags: [equipment, weapon]
    profile: standard-weapon

overrides:
  example_leather_chestplate: disabled

• potential.weights 抽总孔位潜力。
• initially-open 不能超过抽到的总潜力。
• 新孔按 socket-type-weights 抽孔型。
• profile 只允许列出的操作 ID。
• assignment 按 priority 从高到低匹配 tags；同优先级冲突会拒绝。
• 精确 override 优先于标签匹配，可指定 profile 或 disabled。

4. 五类操作

operations.yml 的完整可运行结构：

operations:
  unlock-standard:
    action: unlock
    result: random
    allowed-types: [attack, universal]
    costs:
      sealitems: { gem_dust: 2 }
      vanilla: { AMETHYST_SHARD: 4 }
      currency: { type: vault, amount: '100.00' }
    success: { chance: '60%', guarantee-on-attempt: 4 }
    failure: { consume-items: true, consume-currency: true }

  insert-standard:
    action: insert
    costs: { sealitems: { gem_dust: 1 } }
    success: { chance: '100%' }
    failure: { consume-items: true, consume-input-gem: true }

  convert-standard:
    action: convert
    result: selected
    allowed-types: [attack, universal]
    costs: { sealitems: { gem_dust: 3 } }
    success: { chance: '100%' }
    failure: { consume-items: true }

  remove-safe:
    action: remove
    result: return-gem
    costs: { sealitems: { gem_dust: 1 } }
    success: { chance: '100%' }
    failure: { consume-items: true, destroy-existing-gem: false }

  replace-standard:
    action: replace
    result: return-old-gem
    costs: { sealitems: { gem_dust: 2 } }
    success: { chance: '100%' }
    failure: { consume-items: true, consume-input-gem: true }

费用可同时包含 SealItems 材料、原版材质和一种外部货币。失败块明确决定失败时是否消耗物品、货币、输入宝石或摧毁旧宝石；不要只看成功概率就假设失败无损。

5. 宝石物品与效果

先在 items/*.yml 定义可堆叠宝石物品：

ruby_t1:
  item:
    material: RED_DYE
    name: '<red>Ⅰ阶红宝石'
    lore: ['<gray>可镶嵌到攻击孔或通用孔']
    custom-model-data: 11001
  instance: stackable
  tags: [gem, fire]

再在 gameplay/sockets/gems/ruby.yml 定义业务效果：

gems:
  ruby_t1:
    categories: [fire, elemental]
    limit-profile: core-unique
    exclusive-group: elemental-core
    effects:
      default:
        sealattributes:max_health: { add: 20 }
      contexts:
        weapon:
          sealattributes:physical_attack: { add: 12, total-percent: 0.10 }

宝石 ID 与 SealItems 物品 ID 相同。default 总是贡献；contexts.weapon 只在装备 profile 的 context 为 weapon 时叠加。

6. 限制模板

limit-profiles.yml：

profiles:
  core-unique:
    same-gem: { per-item: 1, equipped: 1 }
    exclusive-group: { per-item: 1, equipped: 1 }

• per-item 限制单件装备。
• equipped 限制玩家全身已穿戴装备。
• 超额宝石状态仍保存，只暂停属性和共鸣贡献。

7. 共鸣

resonances/flame.yml：

id: flame-path
display-name: '<red>烈焰之路'
points:
  categories: { fire: 1 }
  items: { ruby_t1: 2 }
thresholds:
  3:
    sealattributes:physical_attack: { add: 5 }
  6:
    sealattributes:physical_attack: { add: 10 }

一颗 ruby 同时可因 fire category 得 1 分、因精确 ID 得 2 分。只有当前“生效”的宝石参与计分；被全身限制停用的宝石不贡献。达到阈值后发布对应档位属性。

8. 稳定 ID 迁移

migrations.yml：

gems: { old_ruby: ruby_t1 }
socket-types: { old_attack: attack }
profiles: { old_weapon: standard-weapon }

仅在真实重命名稳定 ID 时写映射。链必须无环且最终目标存在。迁移只改 ID，不重抽孔位、宝石、保底或属性值。没有迁移时保留空映射。

9. 启用顺序

1. 定义材料与宝石物品。
2. 定义孔型。
3. 定义操作。
4. 定义限制和宝石。
5. 定义 profile/assignment。
6. 可选定义共鸣和迁移。
7. 打开 settings.yml。
8. 执行 /si reload sockets 和 /si reload socket-ui。
9. /si health 后用新生成装备实测五种操作。