EmakiItem
EmakiItem provides lightweight custom items, stable item IDs, sets, trigger actions, auto update, and PlaceholderAPI support. It is often the starting point for equipment progression.
Module facts
| Item | Value |
|---|---|
| Module version | 2.8.0 |
| Main command | /emakiitem |
| Alias | /ei |
| Hard dependency | EmakiCoreLib |
| Soft dependencies | EmakiAttribute, EmakiSkills, MythicMobs, PlaceholderAPI |
| Permissions | emakiitem.use, emakiitem.give, emakiitem.browse, emakiitem.inspect, emakiitem.update, emakiitem.reload, emakiitem.debug, emakiitem.admin |
Pages
| Page | Contents |
|---|---|
| Commands | Listing and giving items, inspecting the held item and its components, refreshing items and sets, reload and debug. |
| Definitions and Sets | The fields of items/*.yml and sets/*.yml, and how an item ID produces an ItemStack. |
| Browser GUI | The two-level browser opened by /ei browse, pack.yml pack metadata, and slot types. |
| Triggers | Running actions on interact, attack, projectile, block, and drop events. |
| Update Strategy | Bringing items players already hold up to a changed definition. |
| Repair System | The disabled state at zero durability and the material/currency repair flow. |
| Cross-Module Integration | Item source syntax when Attribute, Forge, Strengthen, Gem, Skills, or Cooking reference an item. |
| MythicMobs Integration | Dropping EmakiItem items from MythicMobs Drops. |
| Placeholders | PlaceholderAPI output. |
| CoreLib Actions | Main-hand update, redraw, repair, durability, and vanilla data component actions. |
| API | Creating, identifying, and querying items through EmakiItemApi. |
| Event API | Bukkit events and interception points across the item flow. |
Core capabilities
| Capability | Description |
|---|---|
| Stable item ID | Uses config IDs instead of display names. |
| Item components | Configures material, name, lore, model, enchants, flags, durability, and more. |
| Attribute output | Can provide attribute payloads to Attribute. |
| Skill binding | Can expose skills or skill unlock data. |
| Set system | Grants attributes, skills, or lore based on equipped piece count. |
| Triggers | Runs actions on interaction, combat, projectile, block, drop, and other events. |
| Auto update | Refreshes item state on login, hand switch, inventory click, pickup, and similar cases. |
| Repair system | Items enter a disabled state at zero durability and can be repaired with materials or currency. |
| Browser GUI | A two-level GUI browses every item by pack and takes pieces directly. |
| ID aliases and migration | Maps renamed item IDs and can migrate configs and player inventories in bulk. |
Default runtime folder
text
plugins/EmakiItem/
├── config.yml
├── id_aliases.yml
├── items/
├── sets/
├── gui/
└── lang/items/ defines items, sets/ defines item sets, gui/ holds the repair and two browser templates (repair_gui.yml, pack_browser_gui.yml, item_browser_gui.yml), and id_aliases.yml stores renamed item ID mappings.
Every subdirectory of items/ is an item pack and may carry a pack.yml defining its icon in the browser; see Browser GUI.
Main configuration
config.yml contains only global settings; item behavior lives in the individual definition files.
| Key | Type | Default | Description |
|---|---|---|---|
version | string | Current module version | Marks the default config structure; manual edits are discouraged. |
language | string | zh_CN | Language file ID, matching lang/<language>.yml. |
release_default_data | boolean | true | Whether to release default sample data such as items/ and sets/. This does not control config.yml or language files. |
data_directories.max_depth | int | 2 | Maximum subdirectory scan depth for items/ and sets/, counting the data directory itself. 1 reads only the root, 2 allows one level of subdirectories, 3 allows two. Directories beyond the limit are skipped with a console warning; the minimum value is 1. |
set_bonus.enabled | boolean | true | Whether the set bonus system is enabled. |
set_bonus.refresh_triggers.join | boolean | true | Refresh set state when a player joins. |
set_bonus.refresh_triggers.held_change | boolean | true | Refresh when the held item changes. |
set_bonus.refresh_triggers.inventory_click | boolean | true | Refresh on inventory click. |
set_bonus.refresh_triggers.inventory_drag | boolean | true | Refresh on inventory drag. |
set_bonus.refresh_triggers.pickup | boolean | true | Refresh on item pickup. |
set_bonus.refresh_triggers.interact | boolean | true | Refresh on interaction. |
set_bonus.refresh_triggers.command | boolean | true | Allow refresh when related commands run. |
mythicmobs.enabled | boolean | true | Master switch for the MythicMobs integration. |
mythicmobs.drops.enabled | boolean | true | Whether the MythicMobs custom drop is registered. |
mythicmobs.drops.names | list | emakiitem, ei_item | Recognized drop names; falls back to the defaults when empty. |
item_state.clamp | boolean | true | Whether written values are clamped to the min/max declared in fields. Only overflow protection remains when disabled. |
item_state.fill_defaults | boolean | true | Whether add uses the fields default as the starting value when the field is absent. A missing field is rejected outright when disabled. |
item_state.fields | map | {} | Field declarations keyed by state key name, carrying type, default, min, max, and thresholds. Only numeric types support min/max and thresholds; undeclared fields are unaffected by clamping, defaults, and thresholds. |
item_state.migrations | map | {} | Migration steps per schema version. Each step declares from/to and may rename, retype, or drop fields. Empty means no migration. |
item_state.preservation.verify_rebuild | boolean | true | Verify state survives an item rebuild and backfill from the pre-rebuild snapshot when it is missing. |
item_state.preservation.repair_on_pickup | boolean | false | Repair damaged state metadata on pickup. |
item_state.preservation.repair_on_drop | boolean | false | Repair damaged state metadata on drop. |
item_state.preservation.repair_on_trade | boolean | false | Repair damaged state metadata on trade. |
item_state.preservation.repair_on_container_transfer | boolean | false | Repair damaged state metadata on container transfer. |
item_state.preservation.repair_on_join | boolean | false | Repair damaged state metadata when a player joins. |
item_state.derivation.enabled | boolean | false | Master switch for state-change-driven derived refreshes. |
item_state.derivation.refresh_lore | boolean | true | Refresh set lore during a derived refresh. |
item_state.derivation.refresh_attributes | boolean | true | Sync attributes during a derived refresh. |
item_state.derivation.scan_holder | boolean | true | Allow scanning online players to locate the item when holder information is missing. |
item_state.derivation.max_depth | int | 2 | Maximum recursion depth for derived refreshes and threshold rewards, blocking self-triggering loops. |
proficiency_guard.dedupe_per_event | boolean | true | Dispatch one item definition at most once per event. |
proficiency_guard.max_dispatches_per_event | int | 0 | Maximum dispatches per event; 0 means unlimited. |
proficiency_guard.same_target_cooldown_seconds | int | 0 | Cooldown in seconds against the same target; 0 means no cooldown. |
proficiency_guard.daily_soft_cap | int | 0 | Daily soft cap; 0 means no cap. Counts live in memory, reset on the server's local date change, and do not survive a restart. |
proficiency_guard.decay_factor | double | 1.0 | Decay factor once the soft cap is exceeded, in (0, 1]; 1.0 rejects outright past the cap. |
proficiency_guard.decay_minimum_ratio | double | 0.0 | Lower bound for the decayed pass probability, in [0, 1]. |
proficiency_guard.guarded_triggers | list | damage_dealt, kill_entity, kill_player | Triggers governed by this section. |
set_bonus.refresh_triggers controls set state refreshing, while item auto-update is controlled separately by update.triggers in an item definition; neither overrides the other.
item_state.* applies to the emaki:item_state PDC partition and is read and written by the item_state_* action stages and the API. The whole section is additive: leaving it untouched keeps the previous behavior. proficiency_guard.* applies to slot dispatch for damage_dealt, kill_entity, and kill_player; everything except dedupe_per_event defaults to disabled or unlimited.
Typical item lifecycle
- Define item IDs, material, name, lore, and components in
items/. - Optionally add Attribute stats, Skills, or set info.
- An administrator gives out the item.
- A player uses the item.
- Item automatically refreshes its state when triggered.
- Forge / Strengthen / Gem can continue writing their own layers on top.
- CoreLib rebuilds the final presentation.
Relations with other modules
| Module | Integration |
|---|---|
| EmakiAttribute | Item writes base or set attributes. |
| EmakiSkills | Item writes equipment skill IDs and forced equipment triggers. The PDC keys are owned by a standalone protocol module and do not depend on EmakiSkills being enabled. |
| EmakiForge | Forge can modify items created by EmakiItem. |
| EmakiStrengthen | Strengthen can strengthen EmakiItem equipment. |
| EmakiGem | Gem can add sockets and inlay gems onto EmakiItem equipment. |
| MythicMobs | MythicMobs mobs can drop EmakiItem items through Drops. |