CoreLib 动作

EmakiItem 启用后会向 CoreLib 动作注册表追加主手物品更新、重绘、修复、耐久操作，以及原版 Data Component 新增、修改和删除动作。

本页只记录 EmakiItem 注册的 CoreLib 动作；CoreLib 自带通用动作见 CoreLib 动作系统。当前 Action ID 只使用下表中的规范名，不再提供历史别名入口。

动作 ID

动作 ID	用途	参数
emakiitem_update	强制按 EmakiItem 更新服务刷新主手物品。	无
emakiitem_rerender	通过 CoreLib 物品装配服务重建主手物品展示。	无
emakiitem_repair_amount	修复主手物品指定耐久损伤值。	amount
emakiitem_damage	增加主手物品指定损伤值。	amount
emakiitem_set_damage	设置主手物品当前损伤值。	value
emakiitem_set_durability	设置主手物品剩余耐久值。	value
emakiitem:component_add	新增一个 Data Component；目标已存在该组件时失败。	component、value、可选 slot
emakiitem:component_modify	修改一个已存在的 Data Component；目标缺少该组件时失败。	component、value、可选 slot
emakiitem:component_remove	删除一个 Data Component；目标缺少该组件时幂等跳过。	component、可选 slot

参数

参数	类型	必填	默认值	说明
amount	INTEGER	修复/损伤动作必填	0	修复或增加损伤的数量；负数会按 0 处理。
value	INTEGER	耐久设置动作必填	0	目标损伤值或目标剩余耐久值。
component	STRING	component 动作必填	无	Data Component ID；省略命名空间时按 minecraft: 解析。
value	STRING	add/modify 必填	无	JSON-ish component 值，支持 JSON 对象/数组、引号字符串、布尔值、数字、null 和普通字符串。结构化值格式错误时动作失败。
slot	STRING	否	自动解析目标	指定玩家背包槽位；显式传入但非法时动作失败，不会静默回退。

Component 目标解析

Component 动作按以下顺序解析目标：

1. 动作参数中的显式 slot。
2. Action 上下文中的标准可变 holder：item_target（CoreActionItemTarget）。
3. Action 上下文中的兼容物品键：item、itemStack、item_stack、resultItem、result_item、targetItem、target_item。
4. 当前玩家主手。

Forge 与 Strengthen 的结果动作会传入 item_target。Component 动作修改 holder 后，调用模块会在动作链完成后读取最终物品并交付；动作本身不会提前把结果物品塞入玩家背包。

支持的槽位

• 主手：main、mainhand、main_hand、hand、held、held_item、selected
• 副手：offhand、off_hand
• 护甲：head / helmet / armor_head、chest / chestplate / armor_chest、legs / leggings / armor_legs、feet / boots / armor_feet
• 数字槽位：0 到 40，也可写成 slot_12、inventory_12
• 快捷栏：hotbar_0 到 hotbar_8

示例

actions:
  - 'emakiitem_update'
  - 'emakiitem_repair_amount amount=25'
  - 'emakiitem:component_add component=max_stack_size value=16'
  - 'emakiitem:component_modify component=enchantment_glint_override value=true slot=mainhand'
  - 'emakiitem:component_remove component=custom_name slot=offhand'

带空格或结构化内容的 value 应使用 Action 引号语法，例如：

emakiitem:component_modify component=custom_name value='<gold>锻造之刃</gold>'
emakiitem:component_add component=custom_data value='{"emaki":{"source":"forge"}}'

使用提示

• 更新/耐久动作需要玩家上下文，且作用于玩家主手物品；主手为空时返回 skipped。
• 更新/耐久动作返回 changed、damage 和 max_damage 数据。
• emakiitem_set_durability 在物品没有最大耐久时不做修改；损伤值会被钳制到 [0, max_damage]，降到上限以下时自动清除修复禁用标记。
• Component 动作可以作用于显式槽位、跨模块结果 holder 或上下文 ItemStack；没有任何可用目标时返回失败。
• 组件修改通过 CoreLib ConfiguredItemDefinition patch 应用，会保留第三方物品来源身份、PDC 和未涉及的组件。
• Component 动作返回 operation、component、target、changed、existed_before、warnings 和 issues 数据，供后续动作链与调试读取。