Item Source

CoreLib Item Source provides a stable way to identify items from Vanilla and external item ecosystems. It is better than relying on display names or lore.

Supported sources

ItemSourceKind is a record rather than an enum, written namespace:id. A blank namespace becomes emaki. That design is deliberate: it lets a third-party plugin mint its own source kind. Whoever supplies the ItemSourceProvider declares the kind and its dash-shorthand prefixes in the same registration, using its own namespace.

The eight built-in constants CoreLib implements itself all live in the emaki namespace:

Constant	Kind key	Aliases
VANILLA	emaki:vanilla	vanilla, minecraft, v
CRAFTENGINE	emaki:craftengine	craftengine, ce
ITEMSADDER	emaki:itemsadder	itemsadder, ia
NEIGEITEMS	emaki:neigeitems	neigeitems, ni
MMOITEMS	emaki:mmoitems	mmoitems, mi
NEXO	emaki:nexo	nexo, no
ORAXEN	emaki:oraxen	oraxen, ox
ECOITEMS	emaki:ecoitems	ecoitems, eco, eci

There is deliberately no EMAKIITEM constant: its resolver lives in the EmakiItem module, so its kind and prefixes are declared there as ItemSourceKind.of("emakiitem:emakiitem"), with emakiitem and ei as config aliases.

Type names are case-insensitive. The available sources at runtime depend on which plugins are installed.

Type aliases and dash-shorthand prefixes are not identical: the type: field accepts every alias above, while the dash shorthand accepts minecraft-, mc-, v-, craftengine-, ce-, itemsadder-, ia-, neigeitems-, ni-, mmoitems-, mi-, emakiitem-, ei-, nexo-, no-, oraxen-, ox-, ecoitems-, and eci- (there is no eco- shorthand).

Object format

The object format uses type plus identifier; both must be non-blank:

item:
  type: vanilla
  identifier: diamond

MMOItems requires a <type>:<item> identifier:

item:
  type: mmoitems
  identifier: SWORD:FLAME_SWORD

When resolving an object node, CoreLib checks item_sources first, then the string field item (parsed as dash shorthand), then a nested source, and only then falls back to type + identifier.

Vanilla identifiers are normalised to lowercase and may only contain lowercase letters, digits, and underscores; a minecraft: namespace prefix is rejected.

Resolution priority

When several plugins can identify the same item, CoreLib tries resolvers in descending priority, breaking ties by resolver ID:

Resolver	priority
NeigeItems	102
CraftEngine	101
MMOItems	100
EmakiItem (registered by EmakiItem)	100
ItemsAdder	98
Nexo	97
Oraxen	96
EcoItems	95
Vanilla (fallback)	0

Unified item definitions

CoreLib GUI slots and EmakiItem base items share ConfiguredItemDefinition. In YAML the source lives at item.source:

item:
  source: itemsadder-custom_items:ruby_sword
  amount: 1
  components:
    custom_name: '<red>Ruby Sword</red>'

item.source accepts every ItemSource shorthand currently registered in CoreLib. EmakiItem validates that the resolver is available and can create the base item before caching a definition. For third-party sources, component application preserves source identity, PDC, and unknown components, and transfers only patches that the current Paper runtime can safely handle.

Finding the ID for each source

Vanilla

Use the Bukkit Material enum name with underscores. Identifiers are normalised to lowercase, so either case is accepted as input:

diamond_sword, iron_chestplate, golden_apple, netherite_axe

The dash shorthand accepts minecraft-, mc-, and v-. See the Spigot Material docs for the full list.

EmakiItem

Use the id field defined in plugins/EmakiItem/items/*.yml:

# items/flame_blade.yml
id: flame_blade

Reference it as the shorthand emakiitem-flame_blade, or in object form as type: emakiitem plus identifier: flame_blade.

CraftEngine

Use the item ID registered with CraftEngine, which its own commands can list.

ItemsAdder

Use the ItemsAdder namespaced ID, usually namespace:item_id:

item:
  type: itemsadder
  identifier: custom_items:ruby_sword

Nexo

Use the item ID registered with Nexo.

MMOItems

Give both the item type and the ID in identifier, separated by a colon:

item:
  type: mmoitems
  identifier: SWORD:FLAME_SWORD

NeigeItems

Use the item ID from the NeigeItems configuration.

Why not to rely on display names

• A display name can be changed by an anvil, a plugin, or the language system.
• Lore may be rebuilt by the Attribute, Forge, Strengthen, or Gem modules.
• Colour codes, MiniMessage, and legacy colour symbols make text inconsistent.
• Players may obtain a similarly named item some other way.
• A display name can change on update while the ID stays stable.

Advice

Use stable IDs for recipe materials, rewards, conditions, and station matching. Avoid judging items by display name or lore because they may be modified by other plugins or rebuilt by CoreLib Assembly.

CraftEngine, ItemsAdder, and Nexo item sources can also be passed to the place_block action when the source represents a custom block.