EmakiItem lets you define complete custom items through clean YAML configuration, with a set system, automatic updating, and repair mechanics. Once defined, items are ready to use in-game. When you iterate on item configs, outdated items in player inventories automatically sync to the latest version — no manual recall needed.

Core Features

YAML Item Definition

Define all item properties through configuration files. Each .yml file in plugins/EmakiItem/items/ represents one item, with the filename serving as the item ID.

Base Fields:

• id — Unique item identifier (required)
• material — Base material type (e.g. diamond_sword, netherite_helmet)
• display_name — Display name with MiniMessage formatting and {variable} placeholders
• item_name — Vanilla item_name component for stack identity (no variables)
• lore — Description lines with MiniMessage and variable support

Component Fields:

• custom_model_data — Custom model data (1.21.4+ multi-field format: floats/flags/strings/colors)
• item_model — Item model path (1.21.4+ item_model component)
• tooltip_style — Tooltip style identifier
• enchantments — Enchantment list as name: level
• item_flags — Item flags (HIDE_ENCHANTS, HIDE_ATTRIBUTES, etc.)
• unbreakable — Whether the item is unbreakable
• enchantment_glint_override — Force enchantment glint on/off
• max_stack_size — Maximum stack size
• rarity — Rarity tier (common/uncommon/rare/epic)
• damage / max_damage — Initial damage and max durability
• enchantable — Enchantability level
• hide_tooltip — Hide the entire tooltip
• attribute_modifiers — Vanilla attribute modifiers (attribute/amount/operation/slot/name)
• raw — Raw item component string (advanced, passed directly to Bukkit)

Effect System

Items can carry multiple effect types, unified under the effects list with a type discriminator:

• variables — Expression engine variables for {placeholder} rendering in display_name and lore
• ea_attribute — EmakiAttribute PDC attributes written to item PDC, read by EmakiAttribute when equipped. Supports ea_attribute_meta for additional metadata tags
• es_skill — EmakiSkills skill binding; player gains listed skills when the item is equipped

Set System

Define equipment sets in plugins/EmakiItem/sets/, one file per set.

Set Pieces:
Each piece specifies an item ID, equipment slot (main_hand/off_hand/helmet/chestplate/leggings/boots), and display name. Items declare their set membership via set.id and set.piece fields.

Threshold Effects:
Different effects activate at different equipped piece counts. For example, 2-piece grants attack bonus, 4-piece unlocks an aura skill. Each threshold has its own effects list and lore description.

Dynamic Lore Display:

• Set header showing equipped/total count
• Equipped pieces marked with green checkmarks, missing pieces with gray crosses
• Active thresholds highlighted in green, inactive in gray
• All formats customizable in the set config's lore section

Refresh Triggers:
Set status auto-refreshes on: join, held change, inventory click, inventory drag, pickup, interact, and command. Each trigger can be toggled independently in config.yml.

Automatic Item Updating

When you modify item configs and increment the update.version field, outdated items in player inventories automatically update:

• version field — Increment after each config change; the plugin compares versions to determine update necessity
• triggers list — Configure when to check: join, held_change, inventory_click, inventory_drag, pickup, interact, command
• Preservation — Player-added enchantments and durability are preserved; only config-defined properties (name, lore, model) are updated
• No restart needed, no manual recall, seamless iteration

Item Repair System

Configure complete repair solutions for items:

• Repair materials — Multiple materials with independent consume amounts and repair values (repair_amount)
• Economy repair — Vault-compatible currency costs with formula support ({base_cost}, {damage_percent} variables)
• Disabled state — When durability reaches zero, item enters disabled state and attributes stop working
• Appearance changes — Auto-adds name prefix (e.g. [Broken]) and lore warning when disabled
• Action triggers — Execute configured actions (messages, sounds) on disable and repair events

Equipment Conditions

Items can require conditions to activate their attributes:

• entries — Condition expressions supporting {player_level}, {player_class}, etc.
• type — Combination mode: all_of (all must pass) or any_of (any one passes)
• required_count — Minimum conditions that must be satisfied
• deny_message / deny_actions — Feedback when conditions are not met

Trigger Actions

Items can execute actions on specific events:

• give — When the item is given to a player
• interact — When the player interacts with the item
• Supports sendmessage, sendactionbar, playsound and more

Commands

• /ei help — Display help information (emakiitem.use)
• /ei list [page] — List all registered item IDs with pagination (emakiitem.use)
• /ei give <player> <item_id> [amount] — Give a custom item to a player (emakiitem.give)
• /ei inspect [player] — Inspect detailed info of target's held item (emakiitem.inspect)
• /ei update [player] — Manually refresh item updates and set lore (emakiitem.update)
• /ei reload — Reload all configs and item definitions (emakiitem.reload)

Command aliases: /emakiitem, /ei

Permissions

• emakiitem.use — Basic commands (help/list) — Default: all players
• emakiitem.give — Give items — Default: OP
• emakiitem.inspect — Inspect item info — Default: OP
• emakiitem.update — Manual item update — Default: OP
• emakiitem.reload — Reload configuration — Default: OP

PAPI Placeholders

• %emakiitem_held_id% — EmakiItem ID of the player's main hand item
• %emakiitem_held_name% — Display name of the held item (plain text)
• %emakiitem_loaded_count% — Total number of loaded item definitions

Requirements

• Server: Spigot / Paper 1.21+
• Java: 21+
• Hard Dependencies: EmakiCoreLib
• Soft Dependencies: EmakiAttribute (stat system), EmakiSkills (skill system), PlaceholderAPI (placeholders)