Item Source System

The item source system provides a cross-plugin item retrieval abstraction layer for EmakiCoreLib. Through a unified shorthand format, any module can reference vanilla or third-party plugin items without directly depending on those plugins.

ItemSourceType Enum

Type Enum	Aliases	Plugin	Description
VANILLA	vanilla, minecraft, mc	Minecraft Vanilla	Vanilla items using Material names
CRAFTENGINE	craftengine, ce	CraftEngine	CraftEngine custom items
ITEMSADDER	itemsadder, ia	ItemsAdder	ItemsAdder custom items
NEIGEITEMS	neigeitems, ni	NeigeItems	NeigeItems custom items
MMOITEMS	mmoitems, mi	MMOItems	MMOItems custom items
NEXO	nexo	Nexo	Nexo custom items

Shorthand Format

Item sources use the type-itemId shorthand format with - (hyphen) as the separator.

<sourceType>-<itemId>

Examples by Type

Type	Shorthand Example	Description
VANILLA	vanilla-diamond_sword	Vanilla diamond sword
VANILLA	minecraft-golden_apple	Vanilla golden apple (using alias)
VANILLA	mc-netherite_ingot	Vanilla netherite ingot (using alias)
CRAFTENGINE	craftengine-custom_pickaxe	CraftEngine custom pickaxe
CRAFTENGINE	ce-magic_wand	CraftEngine magic wand (using alias)
ITEMSADDER	itemsadder-emaki:fire_sword	ItemsAdder item (namespace:ID)
ITEMSADDER	ia-emaki:ice_shield	ItemsAdder item (using alias)
NEIGEITEMS	neigeitems-legendary_bow	NeigeItems item
NEIGEITEMS	ni-epic_armor	NeigeItems item (using alias)
MMOITEMS	mmoitems-SWORD.fire_blade	MMOItems item (type.ID)
MMOITEMS	mi-BOW.thunder_bow	MMOItems item (using alias)
NEXO	nexo-crystal_staff	Nexo item

Important

Item sources use the minecraft-xxx format, not minecraft:xxx. The separator is a hyphen -, not a colon :.

# ✅ Correct
source: "vanilla-diamond_sword"
source: "minecraft-diamond_sword"

# ❌ Wrong
source: "minecraft:diamond_sword"
source: "vanilla:diamond_sword"

The colon : only appears inside third-party plugin item IDs (e.g., ItemsAdder's namespace:id), not as a separator between the source type and item ID.

Usage Scenarios

The item source system is widely used by multiple CoreLib subsystems and other modules:

GUI Item Fields

Specify the item source in the item.source field of GUI templates:

slots:
  reward_display:
    slots: "13"
    type: DISPLAY
    item:
      source: "vanilla-diamond"
      name: "<aqua>钻石奖励"
      amount: 5

Assembly System baseSource

In the assembly system, baseSource specifies the base item's source:

assembly:
  baseSource: "craftengine-iron_longsword"
  namespace: "forge"

Action createitem / senditem

Reference items via the source parameter in the action system:

actions:
  - "createitem source=vanilla-diamond amount=10"
  - "senditem source=itemsadder-emaki:rare_gem amount=1"
  - "clearitem source=vanilla-dirt"

Integration Mechanism

The item source system uses a soft-dependency integration strategy, automatically detecting installed item plugins at runtime. The CraftEngine resolver directly calls the CraftEngine API and listens to its reload event to automatically refresh the item table. Other plugin resolvers are dynamically registered or unregistered when plugins are enabled/disabled:

Server Startup
  ├─ Detect CraftEngine  → Installed → Register CRAFTENGINE provider
  ├─ Detect ItemsAdder   → Installed → Register ITEMSADDER provider
  ├─ Detect NeigeItems   → Not installed → Skip
  ├─ Detect MMOItems     → Not installed → Skip
  └─ Detect Nexo         → Not installed → Skip

Tip

Soft-dependency integration means CoreLib does not hard-depend on any third-party item plugin. Even if a plugin is not installed, CoreLib starts normally — only the corresponding item source type becomes unavailable. When attempting to use an item source from an uninstalled plugin, the system returns an ITEM_SOURCE_NOT_FOUND error.

Programming Interface

ItemSourceService itemSourceService = EmakiServiceRegistry.get(ItemSourceService.class);

// Resolve an item source
Optional<ItemStack> item = itemSourceService.resolve("vanilla-diamond_sword", 1);

// Check if a source type is available
boolean available = itemSourceService.isAvailable(ItemSourceType.ITEMSADDER);

// Get all registered source types
Set<ItemSourceType> registered = itemSourceService.getRegisteredTypes();

Warning

The resolve method returns Optional<ItemStack>. It returns Optional.empty() when the item source is unavailable or the item ID is invalid. Callers should always handle the empty case.