Assembly and Structured Presentation

Assembly rebuilds final item display from structured module layers. This prevents modules from overwriting each other's lore.

Core concepts

Concept	Meaning
namespace layer	One module's data layer on an item, holding all state that module writes.
order	The layer's sort weight, deciding where that module appears in the final lore.
snapshot	A snapshot of layer data, used for encoding, decoding, and persistence.
contribution	What a layer contributes to the final presentation: lore sections, name decoration, and attribute totals.
renderer	Merges every contribution into the final ItemMeta.

Common layers

Namespace	Order	Meaning
forge	100	Forge layer: quality, material contribution, forge recipe info.
strengthen	200	Strengthening layer: stars, forge mark, protection state, strengthen attributes.
gem	300	Gem layer: sockets, gems, levels, gem attributes.
cooking	10000	Cooking display layer or special presentation.

Lower order appears earlier. CoreLib reads all registered layers and renders the final name and lore.

Assembly flow

1. A module finishes an operation (strengthen success, gem inlay, ...)
       ↓
2. The module writes real state into PDC (layer snapshot)
       ↓
3. The module runs name_actions / lore_actions through ItemOperationLedger
       ↓
4. The ledger records the operation into PDC (emaki:item_operations) for precise reverts
       ↓
5. The updated ItemStack is returned

Reverting an operation, such as gem extraction or a strengthening downgrade:

1. The module calls Ledger.revert(operationId) or Ledger.revertAll(sourceNamespace)
       ↓
2. The reverter undoes exactly the recorded name / lore changes
       ↓
3. Other modules' results are left untouched

Key services

Service	Description
EmakiItemAssemblyService	Assembly entry point; accepts rebuild requests and coordinates layers.
ItemOperationLedger	Unified name/lore operation ledger supporting precise reverts.
ItemOperationExecutor	Runs name_actions / lore_actions and records the changes.
ItemOperationReverter	Reverts operations from the ledger records.
EmakiNamespaceRegistry	Namespace registration and ordering for every registered layer.
EmakiItemLayerCodecRegistry	Layer encoding, decoding, and version migration.

Namespace IDs are normalised on registration: trimmed, lowercased, spaces replaced with underscores, and a blank ID becomes unknown.

Name contributions

Layers may also decorate the item name. The position enum values are PREFIX and POSTFIX (there is no SUFFIX); an unknown or blank value falls back to POSTFIX.

Lore operation ledger

Each name_actions / lore_actions execution is recorded under the item PDC key emaki:item_operations with an operationId and a sourceNamespace, so a single module's changes can be reverted precisely:

Method	Description
apply(itemStack, operationId, sourceNamespace, nameActions, loreActions, variables)	Execute the operations and record them into PDC.
revert(itemStack, operationId)	Revert one specific operation.
revertAll(itemStack, sourceNamespace)	Revert every operation from one namespace.

Insert anchor behaviour

An empty anchor and an anchor that matches nothing do not behave the same way:

Operation	Empty anchor	anchor matches nothing
insert_below	Insert at the end of the lore.	Insert at the end of the lore.
insert_above	Insert at the start of the lore.	Insert at the end of the lore.

Anchors use contains matching and stop at the first matching line.

When assembly is triggered

These operations rebuild an item:

Operation	Triggering module
Strengthen success or failure	EmakiStrengthen
Forge completion	EmakiForge
Gem inlay / extraction / upgrade	EmakiGem
Automatic item update	EmakiItem
Manual refresh command	Any module
Attribute sync	EmakiAttribute

What operators can change

Operators rarely touch the assembly service directly, but several settings shape its result.

Lore templates usually live in each module's own config:

# EmakiStrengthen example
lore:
  template:
    - '<gray>Strengthen level: <yellow>+%star%'
    - '<gray>Strengthen bonus: <green>+%bonus_attack% attack'

Attribute display format is defined in EmakiAttribute's lore_formats/:

# lore_formats/default_flat.yml
format: '<gray>%display_name%: <white>+%value%'

Some modules expose display toggles:

display:
  show_quality: true
  show_material_info: false
  show_star_level: true
  show_gem_slots: true

Existing gear does not update its presentation automatically after a config change. Use the module's refresh command to refresh one item, refresh online players in bulk, or rely on login-time refresh where the module supports it.

Presentation design advice

• Keep real values in PDC or the attribute payload, not only in lore. Lore is the presentation layer; PDC is the data layer.
• Show only what players need. Internal debug data does not belong in lore.
• Keep each module's lore block clearly bounded. Forge, strengthen, and gem sections should not interleave.
• Do not let two modules print the same attribute. Show attack power in one place so players do not misread it.
• Sample-refresh old gear on a test server first when upgrading templates, to confirm old data still renders.
• Keep name decoration short. +10 Flame Blade [Epic] reads better than [+10][Epic][Forged][Gem x3] Flame Blade.

Advice

Store real state in PDC or payloads. Use lore only as presentation. When a module changes item state, request a proper refresh.