New Features

• Player Inventory Placeholders: Added %zmenu_player_empty_slots% to get the number of free slots in the player's inventory, and %zmenu_player_item_count_<MATERIAL>% to count the total amount of a specific item. These placeholders work even when the bottom inventory is hidden with clear-inventory: true, allowing shop menus to check if the player has enough space before purchasing.
• Custom Commands: Add a new field actions-requirements for custom commands, allowing you to specify requirements that must be met for the command's actions to execute. This provides more control over argument conditions and enhances command functionality.
• Anvil Inventory Support: Added a new ANVIL inventory type, with rename-requirements to validate the text entered by the player before running the rename actions. Inventory types are now resolved through a dedicated InventoryType registry (currently ANVIL and CHEST), making it easier to add new container types in the future.
• Item Rules System: Added a flexible item-matching system configurable through a rule section. Built-in rule types: material, material-contains, material-prefix, material-suffix, name, lore, tag, custom-model-data, and the and / or composites to combine several rules. Plugin-specific item rules (match by item id, supporting wildcards and ignore-case) are available for CraftEngine, Denizen, Eco, ExecutableBlocks, ExecutableItems, HeadDatabase, ItemsAdder, MMOItems, Nexo, NextGens, Nova, Oraxen and SlimeFun. The item_drag button now accepts a rule section to validate which items a player is allowed to drop.
• New Action set_item (set_item / set-item): place an item in one or several inventory slots (menu or player inventory via in-player-inventory: true), with dupe-protection enabled by default.
• New Action take_item (take_item / take-item): remove a configurable amount of matching items from the player's inventory, with verification: SIMILAR (default) or MODELID to control how items are matched.
• New Action refresh_slot (refresh_slot / refresh-slot): refresh only the given slots (menu or player inventory) without rebuilding the whole inventory.
• Check Inventory Requirement (check-inventory permissible): verify that a given slot contains a specific item (or that the player owns it), with success and deny actions and a configurable comparison type.
• Denizen Support: Added a new hook for Denizen, allowing Denizen items to be matched through the item rules system (denizen rule type).

Bug Fixes

• Clear Inventory Session Items: Fixed a bug where items given to the player during a menu session (e.g., via shop purchase actions) were lost when closing a menu with clear-inventory: true. Session items are now collected before restoring the original inventory and properly restored afterward.

• ItemGiveAction Inventory Update: Added player.updateInventory() after giving items via the give_item action, ensuring the client inventory display updates immediately.

• Inventory Desync on Item Give: Fixed ItemGiveAction not calling player.updateInventory() after adding items, causing a visual desynchronization where the player's hotbar/inventory wouldn't visually update until the next interaction.

• Multi Dialogs number-of-columns: Fixed multi-action dialogs not supporting the number-of-columns option.

• Nexo Glyphs in Items: Fixed Nexo glyphs not working inside items. Add skip-first-cache: true to the item configuration to use them.

• Animation Listener: Fixed an issue with PacketAnimationListener (#245).

Internal Changes

• New Minecraft version detection system MinecraftVersion over old NMSVersion enum, allowing more flexible version checks and better support for future Minecraft versions without needing to update the plugin.
• New utils annotations
  • @SinceVersion | These annotations can be used to mark classes that should only be loaded for specific Minecraft versions, check in the VersionFilter class for more details.
  • @UntilVersion | These annotations can be used to mark classes that should only be loaded for specific Minecraft versions, check in the VersionFilter class for more details.
  • @PaperOnly | These annotations can be used to mark classes that should only be loaded if the server is a Paper version, check in the VersionFilter class for more details.
  • @SpigotOnly | These annotations can be used to mark classes that should only be loaded if the server is a spigot version, check in the VersionFilter class for more details.
  • @AutoComponentLoader (renamed from @ComponentLoader) | Allow to load dynamically all items component loader without having to register them one by one in the ZComponentManager class for "fr.maxlego08.zmenu" package, filtering by version and server type with the new annotations by the helper of VersionFilter class.
  • @AutoListener | Allow to load dynamically all listeners who take a MenuPlugin in their constructor or no-arg constructor without having to register them one by one in the ZListenerManager class for "fr.maxlego08.zmenu" package, filtering by version and server type with the new annotations by the helper of VersionFilter class.
  • @AutoActionLoader | Allow to load dynamically all action loaders without having to register them one by one, filtering by version and server type via the VersionFilter class.
  • @AutoMaterialLoader | Allow to load dynamically all material loaders without having to register them one by one, filtering by version and server type via the VersionFilter class.
  • @AutoPermissibleLoader | Allow to load dynamically all permissible (requirement) loaders without having to register them one by one, filtering by version and server type via the VersionFilter class.
  • @AutoRuleLoader | Allow to load dynamically all item rule loaders without having to register them one by one in the ZRuleLoaderRegistry, filtering by version and server type via the VersionFilter class.
  • @RequiresPlugin | Mark a class so it is only loaded when a given plugin is present. Now supports a version and a type (Comparison) to only load the class when the plugin version comparison is true, plus a checkMode (EXISTS / EXISTS_AND_ENABLED) to choose between "plugin installed" and "plugin installed and enabled".
• All action, component, listener, material, permissible and rule loaders are now discovered and registered automatically at startup through ClassRegistry and the annotations above, instead of being registered one by one.
• ClassRegistry now logs constructor instantiation failures, making it easier to diagnose why a loader did not register.
• New dedicated NMS modules (NMS/Base, NMS/v1_20_R3, NMS/v1_20_R4, NMS/v1_21_R1) with a versioned NMSHandler abstraction.
• New item packet management classes: NMSMenuPacketListener, PacketQueue and ForceChannelPromise.
• New item components: AttackRange and MaxStackSize (with Spigot and Paper implementations); entity variant loaders refactored onto shared base classes (CollarColor, DyeColor, Enum, Registry variant loaders).
• Standardized string casing using Locale.ROOT across all classes for consistent, locale-independent behavior.
• Migrated the build to a Gradle version catalog (gradle/libs.versions.toml).

New Features

• Bedrock Inventory Support: Added full Bedrock inventory support via Geyser/Floodgate integration. Includes Bedrock-specific actions, buttons, input builders (with placeholders support and legacy color code conversion), drag button, inventory replacement, dialog support, and Bedrock player validation.
• Inventory Replacement: Implemented inventory replacement functionality, allowing inventories to be dynamically replaced across various classes.
• ItemStack Build Context: Added ItemStack support to build context and updated durability handling in menu item stack.
• PaperProfileComponent: Added new PaperProfileComponent for Paper-specific profile handling.

Bug Fixes

• Clear Inventory + BACK Button: Fixed items being restored to the player when clicking a BACK button between two inventories with clear-inventory: true and clear-inventory-type: PACKET_EVENT. Items are now physically cleared from the player inventory during storage, ensuring container content packets don't reveal hidden items. The close handler also uses physical restoration (giveInventory) instead of packet-based restoration.
• Item Pickup with Clear Inventory: Fixed items being picked up by the player when clear-inventory is enabled.
• Lore Metadata Duplication: Fixed "lore" metadata duplication when loading items.
• Color Handling: Fixed and simplified color handling for leather armor and banner patterns in MenuItemStackLoader.
• NPE Fix: Fixed null pointer exception.
• Import Fix: Fixed import for ZBuildContext in ItemEditAction.
• API Errors: Fixed errors and updated API version.

Improvements

• Requirement Configuration Validation: Added validation for click-requirement, view-requirement, and open-requirement configurations. Detects common misconfiguration where users place requirement keys directly under the requirement section instead of using named groups (for click-requirement) or a requirements list (for view/open-requirement). Displays a clear warning message with an example of the correct structure and a link to the documentation.
• Inventory Lookup Optimization: Optimized inventory lookup with a map cache for better performance.
• CraftEngine Compatibility: Updated compatibility with the latest version of CraftEngine.
• Color Parsing: Added color parsing support.

Changes

• Time Placeholders: Changed time_unix_timestamp, time_next_day_unix_timestamp, and time_today_start_unix_timestamp placeholders to return values in seconds instead of milliseconds.

Internal Changes

• Standardized method parameter annotations to use @NonNull across action and button classes.
• Standardized this keyword usage in method return statements for clarity.
• Streamlined item stack creation by consolidating special item stack application.
• Enhanced click handling in Button class and simplified click requirement configuration.
• Updated Nexo dependency version.
• Updated Gradle repositories URL for Floodgate.
• Removed unused library files (FirstCore.jar, zEssentials.jar, zMenu-1.1.0.0.jar).
• Removed debug messages.

New Features

• Pagination Management System: Introduced PaginationManager with PaginationButton, PaginationNextButton, and PaginationPreviousButton classes, allowing a single button to handle pagination. Includes max page tracking and optimized page size handling.
• Pagination Placeholders: Added pagination-related placeholders to MenuPlaceholders for enhanced inventory navigation.
• Reset Pagination Action: New ResetPaginationAction and loader to reset pagination state for button paginations.
• Skip Close Actions on Inventory Switch: Added skip-close-actions-on-switch configuration option to prevent close actions from firing when switching between inventories, fixing issues with back/inventory actions triggering on close.
• PacketManager Interface: Introduced PacketManager API interface and refactored title name handling in packet events for cleaner architecture.
• ClickAction Enum: Added ClickAction enum to streamline action handling in InventoryLoader.

Bug Fixes

• Fixed CustomModelDataComponent data handling (removed Optional) and added Paper-specific implementation (PaperCustomModelDataComponent) for proper Paper compatibility.
• Fixed head cache issue in ZMenuItemStack.
• Fixed unnecessary toLowerCase conversion on dialog names in CommandDialogOpen.
• Fixed item button click handling by removing redundant null check for clickable buttons.

Internal Changes

• Added javadocs.
• API fixes.
• Removed unused class.

Bug Fixes

• Fixed openWithOldInventories method crash on 1.20 by using CompatibilityUtil.getTopInventory() for safe inventory access.
• Fixed trim pattern and material validation: now uses Bukkit Registry instead of the hardcoded TrimHelper, with proper error messages listing all available patterns/materials when a key is not found.
• Fixed null ItemFlag entries causing errors when applying flags to item meta.
• Fixed EnchantmentGlintOverrideComponent not handling false values correctly — previously only true was applied, now both true and false are respected.
• Fixed click requirements defaulting to an empty click list when none are specified — now defaults to all click types.
• Fixed AttributeWrapper to support an optional NamespacedKey instead of always generating a random UUID, preventing attribute duplication on item rebuild.
• Fixed database connection logger initialization order in ZStorageManager.
• Fixed item loading from map (loadItemStack) to use MenuItemStackLoader instead of the removed MenuItemStackFormMap class.

Improvements

• Command Permissions: Added dedicated permissions for CommandMenuEditor (ZMENU_EDITOR), CommandMenuVersion (ZMENU_VERSION), and CommandMenuGiveOpenItem (ZMENU_GIVE_OPEN_ITEM).
• API: Added getClickRequirementKeys() method to MenuPlugin interface, allowing addons to retrieve the supported click requirement configuration keys.
• Default Configs: Updated default configuration files (pro_inventory.yml, playtime_reward.yml) to use kebab-case (view-requirement, click-requirement, open-requirement) matching current conventions.
• Dependencies: Added adventure-text-minimessage as a library dependency in plugin.yml.

Internal Changes

• Removed unused PlayerSkin class.
• Removed unused MenuItemStackFormMap class and associated fromMap static method.
• Cleaned up imports and formatting across multiple files.

New Features

• MMOItems Support: Added material loader for MMOItems plugin integration.
• Enchantments Component: Added enchantments component support for item configuration.

Performance

• Performance improvement for items that will use a player's nickname to be displayed (player-head optimization).

Bug Fixes

• Fixed enchant key parsing in configuration.
• Fixed enchantments component initialization.
• Fixed title parsing before sending to player in PlayerTitleAnimation.
• Fixed dynamic material check in menu item stack caching logic.
• Fixed %player% as a valid player argument in validators.
• Fixed error handling and formatting in various loaders and actions.
• Fixed basehead itemstack rendering.
• Fixed French translations in message strings.
• Fixed wrong format issues.
• Fixed null checks for player in packet listeners.
• Fixed [] display when placeholder returns an empty list.
• Fixed null message handling in getLegacyMessage method.

Internal Changes

• Refactored placeholder package structure and usage.
• Renamed SpigotDyeColorItemComponentLoader to SpigotDyedColorItemComponentLoader.
• Changed item model type from String to NamespacedKey in MenuItemStack classes.
• Updated @Contract annotations in BaseInventory.java for clarity.
• Removed unnecessary whitespace in ComponentMeta.java.
• Removed debug messages.

New Features

• Performance Debug System: Added per-operation performance monitoring for inventory opening. Measures execution time for each step (permission checks, button building, item rendering, etc.) and logs results to console. Configurable via enable-performance-debug, with threshold filtering and whitelist/blacklist support for operation names.

Performance

• ItemStack Build Optimization: Optimized ZMenuItemStack.build() to reduce redundant work on each inventory open:
  • Eliminated duplicate PlaceholderAPI resolution for material strings (was called twice per build)
  • Pre-resolve Material at load time when no placeholders are present, skipping PAPI parsing at runtime
  • Replaced exception-based control flow for numeric material IDs with a simple numeric check
  • Pre-compute NamespacedKey for tooltipStyle, itemModel, and equippedModel in setters instead of splitting/creating on every build
  • Cache the glowing enchantment lookup instead of querying the enchantment registry on every build
  • Pre-split lore lines containing \n at load time instead of splitting on every build
  • Added early exit in Placeholders.parse() when the string contains no % character, avoiding unnecessary iteration over all placeholder entries

Internal Changes

• MiniMessage Color Parsing Refactor: Consolidated color parsing methods into MiniMessageColorUtils class for better maintainability and code reuse.
• Added unit tests to verify preservation of MiniMessage color tags.

Bug Fixes

• Fixed hex color parsing regex to correctly handle edge cases.
• Fixed typo in PlayerCommandLoader constructor parameter list.

New Features

• Dynamic Inventory Title Updates: Added PacketEventChangeTitleName and PacketTitleListener for changing inventory titles dynamically without reopening the inventory. Requires PacketEvents.
• ClearInvType for Inventory Management: Introduced ClearInvType enum and temporary inventory storage system for better inventory state management.
• Per-Inventory Click Limiter: The click limiter now only applies to zMenu inventories and can be configured per inventory with click-limiter-enabled: true/false. It no longer interferes with non-zMenu inventories.
• Enhanced ItemButton Context: ItemButton now includes inventory context for improved button logic and interactions.

Bug Fixes

• Fixed parsing of map structures inside arrays in YAML configuration. #219
• Fixed click limiter applying to all inventories instead of only zMenu inventories. #219
• Fixed inventory restoration on plugin disable. #215
• Fixed PacketEvents warning on plugin disable. #215
• Resolved scheduler compatibility issue with Folia.
• Fixed task registration during plugin shutdown.
• Enhanced variant component initialization with proper error handling and version checks.

New Features

• New Item Component System (1.20.5+) - Complete overhaul with 30+ components (Enchantments, Lore, Trim, Tool, PotionContents, WrittenBook, AttributeModifiers, etc.). Improved error handling and case sensitivity.
• Animated Inventory Titles - Requires PacketEvents.
• Local Placeholders - local-placeholders section in inventory/pattern configs, cached with Guava for better performance.
• Actions Pattern System - Define default actions for all buttons in actions_patterns/ directory.
• New Actions: message-to (send to specific player), open-actions and close-actions for inventories.
• Console Commands - Commands can now be executed from console (console: true).
• LuckPerms - Permission expiration support with time unit configuration.
• MiniMessage support in toasts.
• Multi-line inventory names (useful with zTextGenerator).
• Resin trim material support.

Bug Fixes

• Fixed Avast false positive on VirusTotal.
• Fixed async access block and container component issues.
• Fixed PacketAnimationListener task execution when plugin is disabled.
• Fixed button reference in updatedButtons iteration.
• Various minor fixes.

Internal Changes

• Removed getCustomItemStack(Player player) method. Use getCustomItemStack(Player player, Placeholders placeholders) instead.
• Renamed package zcore → common.
• Moved Component classes to API module.
• Added nullability annotations and new interfaces (BuildContext, MenuItemStackContext).
• Improved JavaDoc documentation.