GUI System

CoreLib provides GUI templates, open requests, session management, slot control, and click handling. Business modules reuse this infrastructure instead of implementing inventory events from scratch.

Used by

Module	Usage
EmakiForge	Forge GUI, recipe book.
EmakiStrengthen	Strengthening GUI, material slots, protection slots.
EmakiGem	Inlay, extraction, socket opening, and upgrade GUI.
EmakiSkills	Skill panel and trigger-selection GUI.
EmakiCooking	Steamer, oven, juicer, and fermentation-barrel GUI.
EmakiAttribute	Attribute point allocation GUI.
EmakiItem	Item repair GUI.
EmakiLevel	Level panel and leaderboard GUI.
EmakiStorage	Paged warehouse GUI.

Menu rendering backend

gui.backend in plugins/EmakiCoreLib/config.yml decides how every Emaki menu is presented:

Value	Description
bukkit	Default. Opens a real server-side container and needs no extra plugin.
packet	CoreLib's built-in packet-based virtual menu. It reuses the same window when the row count changes, so the cursor is not reset. Requires PacketEvents; falls back to bukkit when it is missing.
auto	Uses packet when PacketEvents is installed, otherwise bukkit.

The default stays bukkit, so upgrading CoreLib does not change existing menu behaviour.

Template fields

Field	Type	Required	Description
id	string	Yes	Template id used by the module.
title	string/object	Yes	Inventory title. MiniMessage strings and TextConfig objects are supported.
rows	integer	Yes	Inventory rows, usually 1 to 6.
slots	map	Yes	Slot definitions keyed by slot name.

Slot fields

Field	Type	Description
key	string	Slot key used by business code.
slots	list<number>	Inventory indexes covered by this slot definition.
type	string	Business type label, such as input, output, button, or decoration.
item	object	Shared item definition containing source, amount, and components. Without source, it can act as a pure patch for a runtime item.
sounds	map	Click sounds keyed by click type.

Unified item structure

New configs and bundled defaults only write the nested canonical structure:

item:
  source: minecraft-anvil
  amount: 1
  components:
    custom_name: '<green>Confirm</green>'
    lore:
      - '<gray>Click to execute</gray>'
    item_model: emaki:confirm
    enchantment_glint_override: true
    $unset:
      - repairable
    $reset:
      - attribute_modifiers

• source accepts every ItemSource shorthand registered in CoreLib; availability depends on the corresponding resolver/plugin.
• A normal component value means SET; $unset removes a component and $reset restores the material prototype default.
• Component IDs must be valid namespaced keys. IDs without a namespace default to minecraft:, while explicit namespaces are preserved; the same rule applies to $unset / $reset entries. Unknown IDs and invalid values for supported components are configuration errors.
• Known components introduced after the current server version are skipped with a warning without linking newer typed classes.
• Third-party sources are cloned first so source identity, PDC, and unknown components survive; only patches that Paper can safely transfer are applied.
• Legacy item: <source> plus top-level components, display_name, and lore are still readable compatibility inputs. When both forms exist, nested item wins.
• Real player-provided targets, materials, and business outputs remain controlled by session state and are not overwritten by template display items.

Automatic migration of legacy GUI item fields

Starting with CoreLib 4.5.11, shared gui/*.{yml,yaml} files undergo a pure structural migration before normal YamlDocument loading and GuiTemplateParser parsing. The migration walks candidate configured-item nodes throughout the document, including regular slots and module-specific containers such as pages/buttons and virtual_items.

The mapping follows the runtime LegacyConfiguredItemConverter contract:

• Legacy material, item_source / item_sources, and scalar item sources move to item.source; amount moves to item.amount.
• Legacy display_name, item_name, lore, custom_model_data, enchantments, item_flags, hidden_components, unbreakable, and related display fields move to item.components.
• Existing canonical item.source, item.amount, and component values win. Legacy values never overwrite modern values in mixed files.
• A candidate containing components.raw or item.components.raw is skipped as a whole so opaque raw component payloads are not rewritten.
• Slot layout, sounds, actions, pagination rules, and other non-target business fields remain unchanged. Running the migration again produces no further changes.

Before a changed batch is committed, every original file is backed up under the relevant plugin data directory at migration-backups/configured-item-format/<timestamp>/, preserving its path relative to the gui/ source directory. The migrated YAML is written to a sibling temporary file and parsed again before replacement. If writing, validation, or replacement fails, the original remains intact or is restored from the batch backup, and GUI loading does not continue with an unverified migrated result. BoostedYAML preserves comments on untouched business nodes where its comment model allows, but a full configuration backup is still recommended before production upgrades.

This compatibility layer does not read version values from config.yml, language files, or plugin descriptors, and it is not version-gated. It runs solely when legacy fields are present. The implementation is contained in CoreLib's item.migration.configureditem package, with GuiTemplateLoader as the only GUI production bridge, so it can be removed as a unit after the compatibility window without leaving legacy rules in YamlFiles, YamlDirectoryLoader, or canonical parsers.

Editing advice

1. Change display text first.
2. Then move decorative slots.
3. Adjust functional slots only after confirming the layout.
4. Test shift-click, drag, double-click, close handling, and full-inventory cases after each GUI change.