CoreLib Actions

When EmakiItem is enabled, it adds main-hand update, rerender, repair, and durability stages to the CoreLib action registry, along with vanilla Data Component add, modify, and remove stages.

NOTE

This page documents only the stages registered by EmakiItem. CoreLib built-in stages are documented in CoreLib Actions. Current stage IDs use only the canonical names below; historical aliases are no longer registered. The old emakiitem_update is now written item_update, the others follow the same rule, and the old colon form emakiitem:component_add is now item_component_add.

Stage IDs

Stage ID	Purpose	Target requirement	Parameters
item_update	Forces the main-hand item through EmakiItem's update service.	REQUIRED_ENTITY	none
item_rerender	Rebuilds the main-hand item presentation through CoreLib item assembly.	REQUIRED_ENTITY	none
item_repair_amount	Repairs the main-hand item by a damage amount.	REQUIRED_ENTITY	amount
item_damage	Adds damage to the main-hand item.	REQUIRED_ENTITY	amount
item_set_damage	Sets the main-hand item's current damage value.	REQUIRED_ENTITY	value
item_set_durability	Sets the main-hand item's remaining durability value.	REQUIRED_ENTITY	value
item_component_add	Adds one Data Component and fails if it is already present.	OPTIONAL	component, value, optional slot
item_component_modify	Modifies an existing Data Component and fails if it is absent.	OPTIONAL	component, value, optional slot
item_component_remove	Removes one Data Component and idempotently skips if it is absent.	OPTIONAL	component, optional slot
item_state_set	Sets a typed persistent item state.	OPTIONAL	key, type, value, optional slot
item_state_add	Adds to a numeric persistent item state.	OPTIONAL	key, type, amount, optional slot
item_state_remove	Removes a persistent item state.	OPTIONAL	key, type, optional slot
item_state_refresh	Refreshes the target item while preserving its persistent state.	OPTIONAL	optional slot

Gate IDs

Gate ID	Purpose	Parameters	Provided variables
item_state_read	Reads one persistent item state into pipeline variables.	key, type, optional slot	item_state.value, item_state.exists, item_state.key, item_state.type

Parameters

Update and durability stages

Parameter	Type	Required	Default	Description
amount	INTEGER	Yes (item_repair_amount, item_damage)	—	Repair or damage amount. Negative values are treated as 0.
value	INTEGER	Yes (item_set_damage, item_set_durability)	—	Target damage value or target remaining durability value.

item_update and item_rerender read no parameters.

Component stages

Parameter	Type	Required	Default	Description
component	STRING	Yes	—	Data Component ID. IDs without a namespace resolve as minecraft:.
value	STRING	Yes (add / modify)	—	JSON-ish component value: JSON objects and arrays, quoted strings, booleans, numbers, null, and plain strings are supported. A malformed structured value fails the stage.
slot	STRING	No	""	Explicit player inventory slot. When blank, the target is resolved in the order below.

item_component_remove has only component and slot; it has no value.

Item state stages and gate

Parameter	Type	Required	Default	Description
key	STRING	Yes (except item_state_refresh)	—	Item-state field name.
type	STRING	Yes (except item_state_refresh)	—	Item-state type.
value	STRING	Yes (item_state_set)	—	Field value to write.
amount	DOUBLE	Yes (item_state_add)	—	Numeric delta.
slot	STRING	No	""	Explicit player inventory slot; slot names match the Component stages.

item_state_refresh takes only the optional slot. item_state_read is a gate rather than a stage and takes key, type, and an optional slot.

Component target resolution

Component stages resolve the item to patch in this order:

1. An explicit slot argument.
2. The pipeline item (CoreActionKeys.ITEM, published by stages such as create_item).
3. The target player's main hand.

An explicit slot wins over the pipeline item because naming a slot is a deliberate instruction, not a fallback. The pipeline item is patched in place: later stages read the same reference, so replacing it would leave them looking at the unpatched copy.

The three component stages declare OPTIONAL rather than REQUIRED_ENTITY: as long as the pipeline carries an item, they can run without a player target.

Supported slots

Slot names follow CoreLib's shared slot table:

• Main hand: mainhand, main_hand, hand
• Off hand: offhand, off_hand
• Armor: helmet, chestplate / chest, leggings / legs, boots
• Inventory indices: 0 through 35, also written slot_12 or hotbar_0

Examples

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'
  # Patch the pipeline item instead of something in the inventory
  - 'self | create_item item_source=minecraft-diamond_sword | item_component_add component=max_stack_size value=1 | send_item'

Quote values that contain spaces or structured content:

self | item_component_modify component=custom_name value='<gold>Forged Blade</gold>'
self | item_component_add component=custom_data value='{"emaki":{"source":"forge"}}'

Notes

• Update and durability stages operate on the target player's main-hand item and are skipped when the main hand is empty. On success they report changed, damage, and max_damage.
• item_set_durability makes no change when the item has no maximum durability. Damage values are clamped to [0, max_damage], and dropping below the maximum clears the repair disabled flag.
• item_component_add on an existing component and item_component_modify on a missing one both fail with REJECTED instead of silently correcting themselves, because either case means the configuration is wrong. item_component_remove treats a missing component as skipped.
• Component patches are applied through CoreLib ConfiguredItemDefinition, preserving third-party source identity, PDC, and unrelated components.
• On success, component stages report component, target, changed, and existed_before. target is either the slot name or pipeline:item.
• An empty (air) target item is skipped. If none of the three resolution paths finds an item, the stage fails.