Changelog Notes

This page explains the current documentation sync focus and provides an upgrade checklist. For complete release information, also check the per-module CHANGELOG.md files, default configuration files, and the release package you are using.

CoreLib 4.5.11 / Item 2.5.9: safe legacy configured-item migration

• Shared CoreLib GUI files and EmakiItem items/ definitions now migrate legacy item fields before normal YAML parsing.
• Legacy sources, amounts, names, lore, model data, enchantments, item flags, and hidden components are converted to item.source, item.amount, and item.components, including 1.21.5+ custom_model_data and tooltip_display mappings.
• Canonical values win, components.raw nodes are skipped as a whole, non-target business fields remain unchanged, and repeated starts do not rewrite migrated files.
• Exact original text is backed up before any change. Migrated output is written to a temporary file and parsed again; the source is replaced only after validation, and failures preserve or restore the original.
• Backups are stored under each plugin data directory at migration-backups/configured-item-format/<timestamp>/. A full configuration backup is still recommended before production upgrades.

CoreLib boundary change: domain protocols moved back to business modules

CoreLib no longer owns domain protocols and extension points. Use the current owners:

• The item layer preview SPI (ItemLayerPreviewProvider, ItemLayerPreviewRequest, and related types) was removed from CoreLib and is now owned by EmakiItemApi in emaki.jiuwu.craft.item.api.preview.
• Equipment skill PDC keys and their codec are now owned solely by EmakiSkillsProtocol (EquipmentSkillPdcCodec). CoreLib's SkillPdcGateway is marked @Deprecated(forRemoval = true) and only delegates.
• The attribute PDC and attribute service contract is now authoritative in EmakiAttributeApi (emaki.jiuwu.craft.attribute.api.PdcAttributeApi with the full PdcAttributePayload). CoreLib's PdcAttributeGateway and mirror PdcAttributeApi are @Deprecated(forRemoval = true), and the mirror cannot represent conditions, schema version, or update timestamp.
• These CoreLib adapters are retained for one synchronized release window only; new code should not depend on them.

Current documentation sync focus

This documentation line has been rechecked against the current source tree for commands, permissions, configuration directories, and major runtime capabilities, together with the runtime boundaries and configuration structures below.

Runtime boundary and configuration sync focus

• Platform and scheduling
  • paper-plugin.yml descriptors now declare Paper 1.21.8+ and Folia support. CoreLib provides the Folia scheduler adapter, and business modules route delayed tasks, async work, GUI return-to-main-thread refreshes, and display refreshes through unified scheduling entry points.
  • Requirements now target Paper 1.21.8+ and include the current Folia support declaration.
• GUI and item presentation
  • GUI slots use item as the current structured item-source field. Dynamic information, confirmation, and preview slots prefer template item, display_name, lore, and component settings.
  • EmakiGem inlay/open/upgrade GUIs no longer auto-fill the target item from the player's main hand or inventory when opened. Players must place target equipment and materials manually.
  • EmakiSkills skill panels, trigger selection, and EmakiStrengthen preview/confirmation dynamic slots now follow the same template-first GUI rule.
• Attributes and PDC
  • Attribute supports ranged random values. Lore/PDC parsing can represent percentage and integer ranges, and snapshots keep minimum, maximum, and resolved values for ranged contributions.
  • variables and ea_attributes are separated more strictly: variables are text/placeholder context, while real attribute output should use explicit ea_attributes.
  • Recent cleanup removed ea_attribute_meta logic; materials, gems, items, and strengthen configs should not rely on it as the current attribute metadata entry.
• Cooking recipes
  • Recipe results now use the unified result.<branch>.outputs/actions structure. Success, early, over, undercooked, overcooked, and invalid branches follow the same model.
  • Recipe completion conditions were added, and station interaction keys were adjusted to the current source behavior.
  • Station floating text, display backend, and refresh configuration are part of the current configuration line.
• Level
  • Added the EmakiLevel / EmakiLevelApi module for multiple level types, exp sources, requirements, PDC, PlaceholderAPI, CoreLib actions, MythicMobs drops, and EmakiAttribute contribution bridging.
  • VitePress now includes detailed Level module documentation, and the getting-started, introduction, and architecture pages include the progression module.
• Forge / Gem / Strengthen / Item / Skills
  • Forge material effects show only payload fields for the selected effect type. quality_modify uses tier, and capacity_bonus uses value.
  • Gem items are refreshed from the current gem definition when obtained, after reloads, and when reconstructed inside GUIs.
  • Skills, Strengthen, Forge, Gem, and Item use the es_skills list form for skill effects in current examples and documentation.

Added and expanded

• Attribute
  • Configuration directory documentation for config.yml, attribute_balance.yml, attributes/, damage_types/, conditions/, and lore_formats/.
  • Scaling curve documentation for logarithmic, sqrt, and piecewise_linear rules.
  • Damage documentation now includes synthetic hit feedback when vanilla damage is intercepted.
• Gem
  • Socket opener documentation for socket_openers, opener items, socket type filtering, and failure feedback.
  • Inlay success rate documentation for the current inlay_success structure.
  • Gem resonance documentation now covers min_level, priority, exclusive_group, and the actual effects object structure.
• Skills
  • Action bar documentation for templates, update interval, and cast mode display.
  • Script engine limits, including per-phase action count and per-action target limits.
  • Passive trigger settings and combo_attack behavior.
• Cooking
  • Command and permission documentation for /ec debug, oven, juicer, and fermentation barrel permissions.
  • Station documentation for display entities, display distance, refresh interval, wok animation, and scald damage.
• Forge
  • Forge history documentation for audit records, auto-save, and troubleshooting.
  • Quality documentation keeps quality pools, guarantee counters, quality item metadata, and deterministic algorithm notes.
• Strengthen
  • Branch tree documentation for branch recipe files and transfer design notes.
• Item
  • Command documentation includes /ei debug and emakiitem.debug.

Removed or corrected

• Gem commands
  • Removed old admin entries that are not in the current command router.
  • Current command set: /emakigem gui <inlay|open|upgrade>, reload, inspect, clearstate, and debug.
  • Current permissions: emakigem.use, emakigem.reload, emakigem.admin, and emakigem.debug.
• Skills commands
  • GUI entry is /eskills gui.
  • Old trigger management commands were removed.
  • /eskills clearslot <player> <slot> is documented.
  • castmode is documented as /eskills castmode <on|off|toggle>.
• Cooking permissions
  • Juicer collect permission is emakicooking.station.juicer.collect.
  • Fermentation barrel start permission is emakicooking.station.fermentation_barrel.start.
  • Station permissions use the emakicooking.station.* form.

Module version lines

The current source tree does not use one single version number for every module. Prefer each module's src/main/resources/config.yml and pom.xml when upgrading:

Module	Current default config version
EmakiCoreLib	4.6.0
EmakiAttribute	4.6.0
EmakiForge	4.6.0
EmakiStrengthen	4.6.0
EmakiCooking	4.1.0
EmakiLevel	1.4.0
EmakiCodex	1.0.0
EmakiGem	2.6.0
EmakiSkills	2.6.0
EmakiItem	2.6.0
EmakiStorage	1.0.0

The pure protocol artifact emaki-skills-protocol is currently 2.6.0. It is not a server plugin and has no default configuration of its own; it ships inside the runtime modules.

Different version lines reflect separate release cadence, not feature importance.

Recommended reading order

1. Read the target module overview page to confirm responsibilities and dependencies.
2. Read commands and permissions before configuring permission groups.
3. Read configuration directory or core feature pages to understand default files.
4. Read feature-specific pages such as socket openers, skill triggers, attribute scaling, forge quality, or cooking stations.
5. After editing configuration, verify with the module's reload, inspect, debug, or lint command if available.
6. Before upgrading a live server, test with real equipment and player data on a staging server.

Upgrade checklist

• Back up all plugins/Emaki*/ configuration directories.
• Back up player data, equipment data, Cooking station data, and economy data.
• Do not blindly overwrite old configuration files; compare defaults and merge new fields manually. The CoreLib 4.5.11 / Item 2.5.9 configured-item migration is not a replacement for a full backup.
• Check whether commands and permission nodes match the current documentation.
• Check whether Attribute hard_lock_damage and environmental damage mapping fit your server.
• Check whether Gem has merged socket_openers, inlay_success, and global upgrade configuration.
• Check whether Skills has merged actionbar, script_engine, and passive_trigger_settings.
• Check whether Cooking has merged oven, juicer, fermentation barrel station settings, GUI files, and permissions.
• Check whether Forge quality, history, and condition failure strategies match your gameplay.
• Check whether Item auto-update and repair configuration affect old items.