Cross-module Integration

The Item module is a shared source for equipment, materials, consumables, and display items. Other modules can reference EmakiItem ids through CoreLib item sources. The recommended shorthand format is emakiitem-item_id.

Common integration points

Scenario	Recommended approach
Recipe material	Reference the EmakiItem id in item_sources.
Equipment base	Store attributes, components, set data, triggers, and PDC in the item definition.
Skill consumable	Check item source in skill conditions or actions.
Gem or strengthen material	Use stable ids instead of display name or lore matching.

Forge example

materials:
  - item_sources:
      - "emakiitem-shadow_ingot"
    amount: 3
    capacity_cost: 5

Gem example

Gem definitions use item_sources to identify gem items:

id: "ruby_t1"
display_name: "<red>Ruby I</red>"
gem_type: "attack"
item_sources:
  - "emakiitem-ruby_t1"
socket_compatibility:
  - "attack"
  - "universal"

Socket item definitions use match.item_sources to decide which equipment can have sockets:

match:
  item_sources:
    - "emakiitem-shadow_blade"
  slot_groups:
    - "weapon"

Strengthen example

stars:
  1:
    materials:
      - item_sources:
          - "emakiitem-strengthen_stone"
        amount: 1

Item layer preview providers

The item layer preview SPI is owned by EmakiItemApi. Third parties register through EmakiItemApi.registerLayerPreview(plugin, provider), and the returned handle implements AutoCloseable. See API for the interfaces and registry semantics.

The built-in layer ids are strengthen and gem, registered by EmakiStrengthen and EmakiGem from their conditionally loaded integration packages. Those lifecycles listen for PluginEnableEvent / PluginDisableEvent and reflectively register the provider only while EmakiItem is enabled, degrading to a no-op when EmakiItem is absent so no hard dependency is introduced. When a module is not loaded, its layer appears as an unavailable placeholder while the other layers still compute.

Skill PDC and the protocol module

Item does not check whether EmakiSkills is enabled when writing equipment skill ids and forced equipment triggers. Those PDC keys are owned by the standalone EmakiSkillsProtocol module through EquipmentSkillPdcCodec, so the skill payload is still written and cleared even when EmakiSkills is not installed; EmakiSkills reads it once equipped.

PDC and lore

Use PDC as the real data layer and lore as presentation only. This prevents language, color, or external lore changes from breaking gameplay logic.

Troubleshooting

• If an item is not recognized, confirm the EmakiItem stable ID was written to PDC.
• If recipe materials cannot be submitted, check that item_sources uses the correct source prefix.
• Items created by external plugins are not equivalent to EmakiItem items unless they carry the matching PDC identity.