EmakiItem
EmakiItem 是轻量自定义物品模块，提供稳定物品 ID、基础属性、套装、触发动作、自动更新与 PlaceholderAPI 支持。它适合作为装备成长线的起点：先生成一件有稳定 ID 的装备，再交给 Forge、Strengthen、Gem、Attribute 和 Skills 继续扩展。
基本信息
| 项目 | 值 |
|---|---|
| 模块版本 | 2.8.0 |
| 主命令 | /emakiitem |
| 别名 | /ei |
| 硬依赖 | EmakiCoreLib |
| 软依赖 | EmakiAttribute、EmakiSkills、MythicMobs、PlaceholderAPI |
| 权限节点 | emakiitem.use、emakiitem.give、emakiitem.browse、emakiitem.inspect、emakiitem.update、emakiitem.reload、emakiitem.debug、emakiitem.admin |
功能页面
| 页面 | 内容 |
|---|---|
| 命令与权限 | 列出与发放物品、检查手持物与组件、刷新物品与套装、重载与调试。 |
| 物品定义与套装 | items/*.yml 与 sets/*.yml 的字段、物品 ID 到 ItemStack 的生成规则。 |
| 物品浏览 GUI | /ei browse 的两级浏览界面、pack.yml 物品包元数据与槽位类型。 |
| 触发器 | 交互、攻击、投射物、方块、丢弃等事件中执行动作。 |
| 物品更新策略 | 物品定义变更后把玩家手上的旧物品更新到新版本。 |
| 物品修复系统 | 耐久归零后的禁用状态与材料/货币修复流程。 |
| 跨模块集成 | 被 Attribute、Forge、Strengthen、Gem、Skills、Cooking 引用时的物品来源写法。 |
| MythicMobs 集成 | 在 MythicMobs 的 Drops 中掉落 EmakiItem 物品。 |
| 占位符 | PlaceholderAPI 输出。 |
| CoreLib 动作 | 主手物品更新、重绘、修复、耐久与原版 Data Component 动作。 |
| API | 通过 EmakiItemApi 创建、识别与查询物品。 |
| 事件 API | 物品流程的 Bukkit 事件与拦截点。 |
核心能力
| 能力 | 说明 |
|---|---|
| 稳定物品 ID | 用配置 ID 标识物品，不依赖显示名。 |
| 物品组件 | 配置材质、名称、Lore、模型、附魔、flags、耐久等。 |
| 属性写入 | 可向 Attribute 提供属性 payload。 |
| 技能绑定 | 可让物品提供技能或技能解锁信息。 |
| 套装系统 | 根据装备件数触发属性、技能或 Lore。 |
| 触发器 | 在交互、攻击、投射物、方块、丢弃等事件中执行动作。 |
| 自动更新 | 玩家登录、切换手持、点击背包、拾取等场景刷新物品。 |
| 修复系统 | 耐久归零后进入禁用状态，可用材料或货币修复。 |
| 浏览界面 | 两级 GUI 按物品包浏览全部物品，可直接取出。 |
| ID alias 与迁移 | 支持物品 ID 改名映射，并可批量迁移配置与玩家背包。 |
默认配置目录
text
plugins/EmakiItem/
├── config.yml
├── id_aliases.yml
├── items/
├── sets/
├── gui/
└── lang/items/ 定义物品，sets/ 定义套装，gui/ 存放修复界面与两级浏览界面模板（repair_gui.yml、pack_browser_gui.yml、item_browser_gui.yml），id_aliases.yml 保存物品 ID 改名映射。
items/ 的每个子目录都是一个物品包，可放一份 pack.yml 定义它在浏览界面里的图标，详见物品浏览 GUI。
主配置
config.yml 只包含全局设置，物品行为写在各自的定义文件里。
| 配置键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
version | string | 当前模块版本 | 默认配置结构标识，不建议手动修改。 |
language | string | zh_CN | 语言文件 ID，对应 lang/<language>.yml。 |
release_default_data | boolean | true | 是否释放 items/、sets/ 等默认示例数据。config.yml 与语言文件不受此项控制。 |
data_directories.max_depth | int | 2 | items/ 与 sets/ 的子目录扫描层数上限（含数据目录本身）。1 只读根目录，2 允许一层子目录，3 允许两层。超限子目录会被跳过并输出控制台警告，最小值为 1。 |
set_bonus.enabled | boolean | true | 是否启用套装加成系统。 |
set_bonus.refresh_triggers.join | boolean | true | 玩家进服时刷新套装状态。 |
set_bonus.refresh_triggers.held_change | boolean | true | 切换手持物品时刷新。 |
set_bonus.refresh_triggers.inventory_click | boolean | true | 点击背包时刷新。 |
set_bonus.refresh_triggers.inventory_drag | boolean | true | 拖拽物品时刷新。 |
set_bonus.refresh_triggers.pickup | boolean | true | 拾取物品时刷新。 |
set_bonus.refresh_triggers.interact | boolean | true | 交互时刷新。 |
set_bonus.refresh_triggers.command | boolean | true | 执行相关命令时允许刷新。 |
mythicmobs.enabled | boolean | true | MythicMobs 集成总开关。 |
mythicmobs.drops.enabled | boolean | true | 是否注册 MythicMobs 自定义 Drop。 |
mythicmobs.drops.names | list | emakiitem、ei_item | 可识别的 Drop 名称；为空时回退默认值。 |
item_state.clamp | boolean | true | 是否按 fields 声明的 min/max 钳制写入值。关闭后只保留溢出保护。 |
item_state.fill_defaults | boolean | true | add 操作在字段缺失时是否用 fields 的 default 作为起始值。关闭后字段缺失直接拒绝。 |
item_state.fields | map | {} | 字段声明，键名即状态键名。含 type、default、min、max 与 thresholds；只有数值类型支持 min/max 与阈值。未声明的字段不受钳制、默认值与阈值影响。 |
item_state.migrations | map | {} | 按 schema 版本的迁移步骤，每步声明 from/to，可 rename、retype、drop 字段。留空表示不迁移。 |
item_state.preservation.verify_rebuild | boolean | true | 物品 rebuild 后校验状态是否仍在，缺失时用重建前快照回填。 |
item_state.preservation.repair_on_pickup | boolean | false | 拾取时修复损坏的状态元数据。 |
item_state.preservation.repair_on_drop | boolean | false | 丢弃时修复损坏的状态元数据。 |
item_state.preservation.repair_on_trade | boolean | false | 交易时修复损坏的状态元数据。 |
item_state.preservation.repair_on_container_transfer | boolean | false | 容器转移时修复损坏的状态元数据。 |
item_state.preservation.repair_on_join | boolean | false | 玩家进服时修复损坏的状态元数据。 |
item_state.derivation.enabled | boolean | false | 状态变更驱动派生刷新的总开关。 |
item_state.derivation.refresh_lore | boolean | true | 派生刷新时刷新套装 Lore。 |
item_state.derivation.refresh_attributes | boolean | true | 派生刷新时同步属性。 |
item_state.derivation.scan_holder | boolean | true | 缺少持有者信息时允许扫描在线玩家定位物品。 |
item_state.derivation.max_depth | int | 2 | 派生刷新与阈值奖励的最大递归深度，用于阻断自触发循环。 |
proficiency_guard.dedupe_per_event | boolean | true | 同一物品定义在一次事件中只派发一次。 |
proficiency_guard.max_dispatches_per_event | int | 0 | 单次事件最多派发次数；0 表示不限制。 |
proficiency_guard.same_target_cooldown_seconds | int | 0 | 对同一目标的冷却秒数；0 表示无冷却。 |
proficiency_guard.daily_soft_cap | int | 0 | 每日软上限；0 表示无上限。计数存在内存中，按服务器本地日期跨天重置，不跨重启保留。 |
proficiency_guard.decay_factor | double | 1.0 | 超过软上限后的递减系数，取值 (0, 1]；1.0 表示超限直接拒绝。 |
proficiency_guard.decay_minimum_ratio | double | 0.0 | 递减后的最低通过概率下限，取值 [0, 1]。 |
proficiency_guard.guarded_triggers | list | damage_dealt、kill_entity、kill_player | 受该段约束的触发器名单。 |
set_bonus.refresh_triggers 控制套装状态刷新；物品自动更新由物品定义的 update.triggers 单独控制，二者互不覆盖。
item_state.* 作用于 emaki:item_state PDC 分区，由 item_state_* 动作段与 API 读写，全部为增量配置：不写任何内容时行为与旧版本一致。proficiency_guard.* 作用于 damage_dealt、kill_entity、kill_player 的槽位派发，除 dedupe_per_event 外全部默认关闭或无限。
典型物品生命周期
- 在
items/中定义物品 ID、材质、名称、Lore 和组件。 - 可选写入 Attribute 属性、Skills 技能或 set 信息。
- 管理员通过命令发放物品。
- 玩家使用装备。
- Item 在触发时机自动更新物品状态。
- Forge / Strengthen / Gem 可继续在该物品上写入自己的 layer。
- CoreLib 统一重建最终展示。
与其他模块的关系
| 模块 | 协作方式 |
|---|---|
| EmakiAttribute | Item 写入基础属性或套装属性。 |
| EmakiSkills | Item 写入装备技能 ID 与装备强制触发器；PDC 键由独立协议模块统一持有，不依赖 EmakiSkills 是否启用。 |
| EmakiForge | Forge 可以改造 EmakiItem 生成的装备。 |
| EmakiStrengthen | Strengthen 可以强化 EmakiItem 装备。 |
| EmakiGem | Gem 可以给 EmakiItem 装备开孔和镶嵌。 |
| MythicMobs | MythicMobs 怪物可以通过 Drops 掉落 EmakiItem 物品。 |