Item Mechanics
Give custom items behaviour with mechanics such as itemjoin and on-click
Custom items defined in the plugins/zMenu/items/ folder can be given mechanics — reusable behaviours attached to the item. Each item is identified by an id (its YAML key), which zMenu stores on the item so the mechanic can recognise it later.
Item File Structure
# plugins/zMenu/items/default-items.yml
<item-id>:
name: "&aMy Item" # standard zMenu item format (see Item Configuration)
lore:
- "&7A special item"
mechanics:
<mechanic-id>:
# options depend on the mechanicitemjoin
The itemjoin mechanic controls when the item is granted and how it is protected in the player's inventory. It is registered by default, so it works out of the box.
server-guide:
material: FILLED_MAP
name: "&eServer Guide"
lore:
- "&7Everything you need to get started."
mechanics:
itemjoin:
give-first-join: true
fixed-slot: 8
prevent-inventory-modification: trueOptions
| Option | Type | Default | Description |
|---|---|---|---|
give-first-join | Boolean | false | Give the item automatically the first time a player ever joins the server. |
fixed-slot | Integer | -1 | Force the item into this inventory slot when given, and lock it there. -1 disables it; valid range is 0–36. |
prevent-inventory-modification | Boolean | true | Prevent the item from being dropped, moved, dragged, swapped to the off-hand or placed in an item frame. |
prevent-inventory-modification only takes effect when a fixed-slot is set — the protection is tied to the locked slot. Without a fixed-slot, the item can be moved freely even if this option is true.
Use give-first-join together with a fixed-slot to hand every new player a guide/menu item that stays pinned to their hotbar.
on-click
The on-click mechanic runs zMenu actions when the player left- or right-clicks while holding the item in their main hand.
on-click is not registered by default in the current build. It only works if an addon registers it through the API (ItemManager#registerMechanicFactory); otherwise an on-click block logs a "No MechanicFactory found" warning. The default built-in mechanic is itemjoin.
magic-wand:
name: "&dMagic Wand"
material: BLAZE_ROD
mechanics:
on-click:
cooldown: 3
cancel-event: true
click-target: both
click-types:
- RIGHT
- SHIFT_RIGHT
click-requirements:
1:
requirements:
- type: permission
permission: "server.wand"
deny:
- type: message
messages:
- "&cYou can't use this wand."
actions:
- type: message
messages:
- "&dPoof! ✨"
- type: player-command
commands:
- "spawn"Options
| Option | Type | Default | Description |
|---|---|---|---|
cooldown | Integer | 0 | Seconds between activations, per player (0 = no cooldown) |
cancel-event | Boolean | false | Cancel the interaction (e.g. to stop block placement / item use) |
click-target | String | both | Where the click must happen: air, block, or both |
click-types | List | — | Which clicks trigger it: LEFT, RIGHT, SHIFT_LEFT, SHIFT_RIGHT (sneaking uses the SHIFT variants) |
click-requirements | Section | — | Standard zMenu requirements checked on click |
actions | List | — | Standard zMenu actions run on click |
on-click fires from a PlayerInteractEvent on the main-hand item. Because no inventory is open, inventory-specific placeholders are not available inside the requirements/actions.
Next Steps
- Learn how items are defined and given in Custom Items
- Configure the item itself with Item Configuration
- Learn about Actions you can run
- Set up Requirements for conditional behaviour