命令与权限

EmakiItem 的全部命令与权限节点如下, 覆盖常见操作: 发放和检查物品, 刷新状态, 重载配置与排查问题

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

命令列表

命令	权限	说明
/ei help	无	输出命令帮助. 直接执行 /ei 不带参数, 等于执行 help
/ei list [page]	emakiitem.use	分页列出已加载的物品定义, 每页 10 条
/ei browse [page]	emakiitem.browse	打开物品浏览界面, 一级先列出物品包. 只能由玩家执行. 详见物品浏览 GUI
/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 state query|repair|recompute [player]	emakiitem.inspect (query) / emakiitem.admin (repair, recompute)	查询, 修复或重算主手物品的 item state; 省略子命令时按 query 处理
/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.browse	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 browse
/ei browse 2

一级界面列出物品包, 点包图标进入二级界面, 左键取一件, Shift + 左键取一整组. /ei give 得先知道物品 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 输出. 想要能直接粘贴进配置的 YAML, 就写 components 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 改名映射, 即旧 ID 指向新 ID 的对照表) 变更会写回 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, item_state, proficiency

排查建议

• 物品列表里没有目标 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>