命令与权限

EmakiItem 的主命令是 /emakiitem，别名 /ei。命令用于列出物品、发放物品、检查手持物、查看 Minecraft 物品组件、刷新玩家物品和套装状态、重载配置与输出调试信息。

命令列表

命令	权限	说明
/ei help	无	输出命令帮助。不带参数执行 /ei 等价于 help。
/ei list [page]	emakiitem.use	分页列出已加载的物品定义，每页 10 条。
/ei give <player> <id> [amount]	emakiitem.give	给指定玩家发放 EmakiItem 物品。
/ei inspect [player]	emakiitem.inspect	检查指定玩家或自己的主手物品，输出物品 ID、版本、属性、技能、套装等 PDC 状态。
/ei components [yaml] [player] [component_id]	emakiitem.inspect	查看主手物品的 Minecraft 组件；默认保持 JSON，只有显式写 yaml 时输出可复制到 item.components 的 YAML。也可用 /ei component。
/ei repair	emakiitem.use	为自己打开装备修复界面，仅玩家可用。
/ei update [player]	emakiitem.update	刷新玩家背包中的 EmakiItem 物品，并重新计算套装状态。
/ei alias list|add|remove	emakiitem.admin	查看、添加或删除物品 ID alias。
/ei migrate id|inventory	emakiitem.admin	预览或执行物品 ID 迁移，或迁移玩家背包。
/ei reload	emakiitem.reload	重载物品、套装、配置和语言。
/ei debug [stats|player|module|on|off]	emakiitem.debug 或 emakiitem.admin	输出运行时调试信息；stats 输出刷新统计。

权限节点

权限	默认	说明
emakiitem.use	true	使用基础命令和物品列表。
emakiitem.give	op	发放自定义物品。
emakiitem.inspect	op	检查物品状态和 Minecraft 组件。
emakiitem.update	op	刷新玩家物品或套装状态。
emakiitem.reload	op	重载配置。
emakiitem.debug	op	输出调试信息。
emakiitem.admin	op	管理 alias 与迁移命令，同时作为调试命令的管理员兜底权限。

主命令 /emakiitem 本身要求 emakiitem.use；repair 子命令也使用该权限。

常见操作

查看物品列表

/ei list
/ei list 2

用于确认 plugins/EmakiItem/items/ 目录中的物品是否成功加载。列表会显示配置 ID 和显示名。

发放物品

/ei give Steve example_item 1

发放后模块会执行该物品的 actions.give，刷新玩家已有 EmakiItem 物品、套装状态，并触发 Attribute 装备同步。发放失败时先确认物品 ID 是否存在。

检查主手物品

/ei inspect
/ei inspect Steve

inspect 会读取目标玩家主手物品，并输出：

• EmakiItem ID；
• schema / update 版本；
• 物品定义是否仍存在；
• emakiitem 命名空间写入的 Attribute PDC（attributes 与 attribute_meta）；
• 技能 ID 与装备强制技能触发器；
• definition signature；
• 套装 ID、部件、当前激活数量、总件数和已激活阈值。

排查“属性没生效”“套装不触发”“技能没出现”时，优先看这里，而不是只看 Lore。

查看 Minecraft 物品组件

/ei components
/ei components Steve
/ei components Steve custom_model_data
/ei components yaml
/ei components yaml Steve custom_model_data
/ei component custom_model_data

components 无格式参数时保持既有 JSON 输出。只有 components yaml ... 才输出结构化 YAML；YAML 只基于可稳定解析的原版组件字符串生成，不把 String.valueOf(DataComponentValue) 当作持久化格式。命令参数可省略 minecraft:，YAML 导出也会对原版组件使用短 ID；显式的其他命名空间保持不变。组件 ID 行支持点击复制，适合排查 1.21+ 物品组件，例如：

• minecraft:custom_model_data
• minecraft:item_model
• minecraft:tooltip_style
• minecraft:enchantments
• minecraft:attribute_modifiers

如果省略玩家名且命令发送者是玩家，则检查自己的主手物品。如果第二个参数不是在线玩家名，会被当作组件 ID。

刷新物品与套装

/ei update
/ei update Steve

修改物品定义、套装定义、自动更新规则或装备状态后使用。命令会刷新玩家背包中的 EmakiItem 物品，并重新计算已装备套装；若有变化，会触发 Attribute 装备同步。

打开修复界面

/ei repair

只能由玩家执行，为自己打开 gui/repair_gui.yml 定义的修复界面。模板缺失时会提示打开失败。

管理 ID alias

/ei alias list
/ei alias add old_sword flame_sword
/ei alias remove old_sword

add 要求目标物品 ID 已加载，否则报告物品不存在。alias 变更会写回 id_aliases.yml 并清理物品工厂缓存。

迁移物品 ID 与背包

/ei migrate id old_sword flame_sword --dry-run
/ei migrate id old_sword flame_sword --apply
/ei migrate inventory Steve
/ei migrate inventory all

migrate id 必须显式带 --dry-run 或 --apply：--dry-run 只输出替换数量与涉及文件，--apply 执行替换并保留 alias。migrate inventory 重写目标玩家（或全部在线玩家）背包中的旧 ID，并顺带刷新套装与 Attribute 装备同步。

重载配置

/ei reload

重载后会重新读取物品、套装、配置和语言。正式服建议先在测试服确认新配置能加载，再对在线玩家执行必要的 /ei update。

查看刷新统计

/ei debug stats

输出物品/套装刷新的事件数、批次数、合并次数、请求与实际刷新范围、缓存命中、扫描槽位数、变更数、冲突数和耗时。可用调试模块为 create、update、identify、set、item_operation、pdc。

排查建议

• 物品列表没有目标 ID：检查 items/*.yml 文件名、id、YAML 缩进和控制台加载错误。
• 发放后属性不生效：用 /ei inspect 查看 attributes 与 attribute_meta，再确认 EmakiAttribute 是否安装。
• 套装不触发：用 /ei inspect 查看 set_id、set_piece、set_active_count 和 set_active_thresholds。
• 组件显示异常：用 /ei components 查看实际 Bukkit 组件，再回到物品定义的 item.components 节点修正。
• 更新后旧物品没变化：确认物品定义中的 update.enabled、update.version 和触发器配置，然后执行 /ei update <player>。