CoreLib 动作

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

NOTE

本页只记录 EmakiItem 注册的段；CoreLib 自带通用段见 CoreLib 动作系统。当前段 ID 只使用下表中的规范名，不再提供历史别名入口。旧的 emakiitem_update 现在写作 item_update，其余同理；旧的冒号写法 emakiitem:component_add 现在写作 item_component_add。

段 ID

段 ID	用途	目标要求	参数
item_update	强制按 EmakiItem 更新服务刷新主手物品。	REQUIRED_ENTITY	无
item_rerender	通过 CoreLib 物品装配服务重建主手物品展示。	REQUIRED_ENTITY	无
item_repair_amount	修复主手物品指定耐久损伤值。	REQUIRED_ENTITY	amount
item_damage	增加主手物品指定损伤值。	REQUIRED_ENTITY	amount
item_set_damage	设置主手物品当前损伤值。	REQUIRED_ENTITY	value
item_set_durability	设置主手物品剩余耐久值。	REQUIRED_ENTITY	value
item_component_add	新增一个 Data Component；目标已存在该组件时失败。	OPTIONAL	component、value、可选 slot
item_component_modify	修改一个已存在的 Data Component；目标缺少该组件时失败。	OPTIONAL	component、value、可选 slot
item_component_remove	删除一个 Data Component；目标缺少该组件时幂等跳过。	OPTIONAL	component、可选 slot
item_state_set	设置一个类型化持久 item state。	OPTIONAL	key、type、value、可选 slot
item_state_add	对数值型持久 item state 增量。	OPTIONAL	key、type、amount、可选 slot
item_state_remove	删除一个持久 item state。	OPTIONAL	key、type、可选 slot
item_state_refresh	刷新目标物品并保留其持久 state。	OPTIONAL	可选 slot

门控 ID

门控 ID	用途	参数	提供变量
item_state_read	读取一个持久 item state 并写入管道变量。	key、type、可选 slot	item_state.value、item_state.exists、item_state.key、item_state.type

参数

耐久与更新段

参数	类型	必填	默认值	说明
amount	INTEGER	是（item_repair_amount、item_damage）	—	修复或增加损伤的数量；负数按 0 处理。
value	INTEGER	是（item_set_damage、item_set_durability）	—	目标损伤值或目标剩余耐久值。

item_update 与 item_rerender 不读取参数。

Component 段

参数	类型	必填	默认值	说明
component	STRING	是	—	Data Component ID；省略命名空间时按 minecraft: 解析。
value	STRING	是（add / modify）	—	JSON-ish component 值，支持 JSON 对象/数组、引号字符串、布尔值、数字、null 和普通字符串。结构化值格式错误时该段失败。
slot	STRING	否	""	指定玩家背包槽位；留空时按下面的顺序解析目标。

item_component_remove 只有 component 与 slot，没有 value。

item state 段与门控

参数	类型	必填	默认值	说明
key	STRING	是（除 item_state_refresh）	—	item state 字段名。
type	STRING	是（除 item_state_refresh）	—	item state 类型。
value	STRING	是（item_state_set）	—	要写入的字段值。
amount	DOUBLE	是（item_state_add）	—	数值增量。
slot	STRING	否	""	指定玩家背包槽位；槽位名与 Component 段一致。

item_state_refresh 只有可选 slot。item_state_read 是门控而不是段，参数为 key、type 与可选 slot。

Component 目标解析

Component 段按以下顺序解析要改的物品：

1. 参数中显式给出的 slot。
2. 管道物品（由 create_item 等段发布的 CoreActionKeys.ITEM）。
3. 目标玩家的主手。

显式 slot 优先于管道物品：写出槽位是明确指令，不是回退。管道物品会被原地修改，因为后续段读的是同一个引用，替换成新对象会让它们看到未修改的副本。

三个 Component 段的目标要求是 OPTIONAL 而不是 REQUIRED_ENTITY：只要管道里有物品，没有玩家目标也能改。

支持的槽位

槽位名沿用 CoreLib 的统一槽位表：

• 主手：mainhand、main_hand、hand
• 副手：offhand、off_hand
• 护甲：helmet、chestplate / chest、leggings / legs、boots
• 背包索引：0 到 35，也可写成 slot_12、hotbar_0

示例

actions:
  - 'self | item_update'
  - 'self | item_repair_amount amount=25'
  - 'self | item_damage amount=10'
  - 'self | item_set_durability value=100'
  - 'self | item_component_add component=max_stack_size value=16'
  - 'self | item_component_modify component=enchantment_glint_override value=true slot=mainhand'
  - 'self | item_component_remove component=custom_name slot=offhand'
  # 改管道物品而不是背包里的物品
  - 'self | create_item item_source=minecraft-diamond_sword | item_component_add component=max_stack_size value=1 | send_item'

带空格或结构化内容的 value 要加引号：

self | item_component_modify component=custom_name value='<gold>锻造之刃</gold>'
self | item_component_add component=custom_data value='{"emaki":{"source":"forge"}}'

使用提示

• 更新与耐久段作用于目标玩家主手物品，主手为空时跳过；成功时输出 changed、damage、max_damage。
• item_set_durability 在物品没有最大耐久时不做修改；损伤值会被钳制到 [0, max_damage]，降到上限以下时自动清除修复禁用标记。
• item_component_add 遇到已存在的组件、item_component_modify 遇到缺失的组件都会以 REJECTED 失败而不是静默纠正，这两种情况都是配置写错了。item_component_remove 遇到缺失组件则按跳过处理。
• 组件修改通过 CoreLib ConfiguredItemDefinition patch 应用，会保留第三方物品来源身份、PDC 和未涉及的组件。
• Component 段成功时输出 component、target、changed、existed_before；target 是槽位名或 pipeline:item。
• 目标物品为空气时跳过；三种解析路径都没找到物品时该段失败。