Assembly and Structured Presentation

Assembly merges the state several modules write into one item into the final name and lore you see, so modules never overwrite 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: use it to control where each module shows up in the final lore. 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

You 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

After a config change, your existing gear does not update its presentation automatically. 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