镶嵌流程

Gem 镶嵌流程负责校验目标装备、插槽物品配置、宝石物品、插槽状态和费用，然后把宝石数据写入装备并重建展示。排查时先确认装备是否匹配 items/*.yml，再看宝石兼容性和插槽状态。

流程步骤

1. 玩家打开宝石 GUI 或执行宝石相关命令。镶嵌、开孔、升级界面打开时目标槽为空，不会自动从玩家主手或背包克隆/转移装备。
2. 模块读取目标装备，并通过 items/*.yml 中的 match 规则确定适用的插槽物品配置。
3. 读取 slots，过滤未开放、已占用或不允许当前操作的槽位。
4. 读取宝石定义，检查宝石 socket_compatibility 是否兼容 slots[].type。
5. 检查插槽物品级限制，例如 allowed_gem_types、max_same_type、max_same_id。
6. 检查条件与费用，例如 inlay_cost、extract_cost、开孔器或升级材料。
7. 写入装备 PDC，记录宝石 ID、当前等级、槽位索引和 gem layer 数据。
8. 调用 CoreLib 装配/展示逻辑重建名称、Lore、属性 payload 和技能 payload。
9. 重新评估宝石共鸣，并应用或撤销共鸣效果。
10. 执行动作并刷新玩家背包。

关键校验字段

配置位置	字段	说明
items/*.yml	match.item_sources	哪些物品会获得这套插槽配置。
items/*.yml	slots[].type	插槽类型，例如 attack、defense、universal。
items/*.yml	default_open_slots	初始开放的插槽索引。未列出的插槽需要开孔。
items/*.yml	allowed_gem_types	装备允许镶嵌的宝石类型白名单。
items/*.yml	max_same_type	同类型宝石最大数量，0 表示不限制。
items/*.yml	max_same_id	同 ID 宝石最大数量。
gems/*.yml	gem_type	宝石自身类型。
gems/*.yml	socket_compatibility	宝石可放入哪些插槽类型。
gems/*.yml	inlay_cost / extract_cost	镶嵌与提取费用。

旧文档中出现过 slot_types，当前源码使用的是 socket_compatibility 与 slots[].type。

排查入口

现象	先检查
装备不支持宝石	items/*.yml > match.item_sources 是否匹配目标装备。
找不到可用插槽	slots、default_open_slots、插槽是否已占用。
宝石无法放入	gems/*.yml > socket_compatibility 与 slots[].type 是否一致。
同类宝石超限	allowed_gem_types、max_same_type、max_same_id。
属性不生效	EmakiAttribute 是否安装，宝石效果是否写入 ea_attribute。

边界情况

• 装备没有匹配的插槽物品配置：提示该装备不支持宝石。
• 插槽未开放：需要先通过开孔器解锁。
• 插槽已占用：禁止覆盖，除非进入提取或替换相关流程。
• 宝石物品堆叠：通常只消耗 1 个，剩余数量保留。
• 背包满：提取宝石时应放入背包或安全掉落。
• GUI 打开：目标装备和材料必须由玩家手动放入；模块不会自动读取主手作为初始槽位，避免误吞或误移动物品。
• 配置重载：已镶嵌旧宝石会尽量保留 ID，并在展示重建时做兜底处理。宝石本体在获取、重载和 GUI 复刻时会按当前定义刷新名称、Lore、模型与等级展示。