Commands and Permissions

The main command of EmakiItem is /emakiitem, with /ei as an alias. Commands list item definitions, give items, inspect held items, inspect Minecraft item components, refresh player items and set state, reload configuration, and print debug output.

Commands

Command	Permission	Description
/ei help	None	Print command help. Running /ei without arguments is equivalent to help.
/ei list [page]	emakiitem.use	List loaded item definitions, 10 per page.
/ei give <player> <id> [amount]	emakiitem.give	Give an EmakiItem item to a player.
/ei inspect [player]	emakiitem.inspect	Inspect the target player's main-hand item, including item id, versions, attributes, skills, and set PDC state.
/ei components [yaml] [player] [component_id]	emakiitem.inspect	Inspect Minecraft item components. JSON remains the default; YAML is produced only when yaml is explicit. /ei component is also accepted.
/ei repair	emakiitem.use	Open the equipment repair interface for yourself. Players only.
/ei update [player]	emakiitem.update	Refresh EmakiItem items in the player's inventory and recalculate set state.
/ei alias list|add|remove	emakiitem.admin	List, add, or remove item ID aliases.
/ei migrate id|inventory	emakiitem.admin	Preview or apply an item ID migration, or migrate player inventories.
/ei reload	emakiitem.reload	Reload items, sets, config, and language.
/ei debug [stats|player|module|on|off]	emakiitem.debug or emakiitem.admin	Print runtime debug information; stats prints refresh metrics.

Permissions

Permission	Default	Description
emakiitem.use	true	Allows basic command usage and item listing.
emakiitem.give	op	Allows giving custom items.
emakiitem.inspect	op	Allows inspecting item state and Minecraft components.
emakiitem.update	op	Allows refreshing player item and set state.
emakiitem.reload	op	Allows reloading configuration.
emakiitem.debug	op	Allows debug output.
emakiitem.admin	op	Allows alias and migration commands, and acts as the administrative fallback for debug access.

The root /emakiitem command itself requires emakiitem.use, which the repair subcommand also uses.

Common operations

List items

/ei list
/ei list 2

Use this to confirm that files under plugins/EmakiItem/items/ loaded successfully. The list shows config ids and display names.

Give an item

/ei give Steve example_item 1

After giving the item, the plugin runs the item's actions.give, refreshes the player's EmakiItem items and set state, and schedules Attribute equipment sync. If giving fails, confirm that the item id exists.

Inspect the held item

/ei inspect
/ei inspect Steve

inspect reads the target player's main-hand item and prints:

• EmakiItem id;
• schema / update versions;
• whether the item definition still exists;
• Attribute PDC written under the emakiitem namespace (attributes and attribute_meta);
• skill ids and forced equipment skill triggers;
• definition signature;
• set id, set piece, active count, total count, and active thresholds.

When debugging missing attributes, set bonuses, or skills, inspect real PDC state instead of relying on lore only.

Inspect Minecraft item components

/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

Without a format argument, components preserves the existing JSON output. Only components yaml ... emits structured YAML. YAML export is based on the stable vanilla component string and never treats String.valueOf(DataComponentValue) as a persistence format. Command arguments may omit minecraft:, and YAML export uses short IDs for vanilla components while preserving explicit non-Minecraft namespaces. Component id lines can be clicked to copy the id. This is useful for Minecraft 1.21+ components such as:

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

If the player name is omitted and the sender is a player, the command inspects the sender's main-hand item. If the second argument is not an online player name, it is treated as a component id.

Refresh items and sets

/ei update
/ei update Steve

Use this after changing item definitions, set definitions, update rules, or equipment state. The command refreshes EmakiItem items in the player's inventory and recalculates equipped set state. If anything changes, Attribute equipment sync is scheduled.

Open the repair interface

/ei repair

Players only; opens the repair interface defined by gui/repair_gui.yml for the sender. If the template is missing, the command reports that opening failed.

Manage ID aliases

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

add requires the target item ID to be loaded, otherwise it reports that the item does not exist. Alias changes are written back to id_aliases.yml and clear the item factory cache.

Migrate item IDs and inventories

/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 requires an explicit --dry-run or --apply. --dry-run only reports the replacement count and affected files; --apply performs the replacement and keeps an alias. migrate inventory rewrites legacy IDs in the target player's inventory (or all online players) and also refreshes sets and Attribute equipment sync.

Reload configuration

/ei reload

This reloads items, sets, config, and language. On production servers, validate new config on a test server first, then run /ei update for online players when needed.

Inspect refresh metrics

/ei debug stats

Prints item/set refresh event counts, batches, coalesced batches, requested versus actual refresh scope, cache hits, scanned slots, changes, conflicts, and elapsed time. Available debug modules are create, update, identify, set, item_operation, and pdc.

Troubleshooting

• Item id is missing from the list: check items/*.yml, id, YAML indentation, and console load errors.
• Attributes do not apply after giving: use /ei inspect to check attributes and attribute_meta, then confirm EmakiAttribute is installed.
• Set bonuses do not trigger: use /ei inspect to check set_id, set_piece, set_active_count, and set_active_thresholds.
• Components look wrong: use /ei components to inspect actual Bukkit components, then fix the item.components section in the item definition.
• Old items did not update: confirm update.enabled, update.version, and update triggers in the item definition, then run /ei update <player>.