Right-Click Item Bindings: item_bindings.yml

item_bindings.yml binds a main-hand item interaction to a KaMenu menu. The file is located at plugins/KaMenu/item_bindings.yml. It can be maintained manually and also stores Bindings.Items generated by /km migrate trmenu.

KaMenu treats a missing file as an empty configuration. The migrator creates it only when at least one item binding is generated. /km reload config and /km reload all reload this file.

Basic Format#

item-bindings:
  server_selector:
    enabled: true
    menu: 'example/main_menu'
    require-sneaking: false
    cooldown-ms: 2000
    ignore-case: true
    translate-colors: true
    material: 'COMPASS'
    target-name: '&eServer Selector'
    target-lore: '&7Right-click to open'
    data: 0
    custom-model-data: 1001

Each binding must be enabled, declare menu, and contain at least one item matcher. When a player right-clicks air or a block with the main hand, KaMenu selects the first matching entry in configuration order, cancels the original interaction, and opens the target menu.

Fields#

Field	Description	Default
enabled	Enables this binding	false
menu	KaMenu menu ID to open	none
require-sneaking	Requires the player to be sneaking	false
cooldown-ms	Absolute-time delay before the same player can trigger an item binding again, in milliseconds	0
ignore-case	Ignores case in name and lore substring matching	false
translate-colors	Converts & color codes in configured text to Bukkit color codes before matching	false
material	Vanilla material, or an explicitly prefixed ItemsAdder, Oraxen, or CraftEngine item ID	optional
target-name	Text that the item display name must contain	optional
target-lore	Text that at least one lore line must contain; '', [], or omission disables lore matching	optional
data	Legacy Bukkit item damage/data value	optional
custom-model-data	Integer CustomModelData	optional

External item IDs use forms such as itemsadder:namespace:item, ia:namespace:item, oraxen:item_id, craftengine:namespace:item, or ce:namespace:item. They do not match when the provider plugin is unavailable or cannot identify the item.

KaMenu stores one last-trigger timestamp per player. When another binding matches, its own cooldown-ms is checked against that timestamp. Migrated bindings all use 2000ms, matching TrMenu's global interval behavior. The cooldown uses absolute system time and is independent of server tick rate.

Colors And Text Matching#

Names and lore use substring matching rather than requiring the complete line to be equal. Colors are not stripped from item metadata automatically:

• With translate-colors: true, configured &aMenu is converted to the actual Bukkit color code before matching colored item text.
• With translate-colors: false, configured text is matched literally. This preserves the legacy listeners.item-lore behavior.

Relationship To The Legacy config.yml Listener#

KaMenu continues to load config.yml > listeners.item-lore. A legacy listener requires material; omitting or clearing target-lore makes it match by material only. Legacy listeners load before item_bindings.yml, so they win when the same item matches both sources.

Use the separate file for new bindings to keep the main config compact and prevent migration output from rewriting comments in config.yml.

TrMenu Migration#

/km migrate trmenu merges safely mappable Bindings.Items into this file and points them at the migrated Container menus. Supported traits are material, lore, name, data, and model-data. TrMenu ignores amount while matching bound items, so the migration ignores it as well.

TrMenu's default Bound-Item-Interval is 2000 milliseconds, so generated bindings use cooldown-ms: 2000. The migrator does not read TrMenu's global settings.yml; update the generated value manually if the source server changed that setting.

Opposed traits, skull owner/texture matching, unknown traits, amount-only matchers, and conflicting matcher groups are not migrated automatically. The command emits a WARNING and does not generate a weakened binding that could match arbitrary items.