Menu Items | Astral Realms Documentation

Each entry under items: in a menu YAML defines a MenuItem — a slot configuration that controls what appears where and what happens when a player interacts with it.

Field Reference

Field	Type	Required	Description
`slot`	int	No*	Single fixed slot index (0-based).
`slots`	List	No*	Multiple fixed slot indices or placeholder strings.
`placeholder`	String	No*	A placeholder expression resolving to an integer slot at runtime.
`priority`	int	No	Render priority when multiple items target the same slot. Higher wins. Default `0`.
`item-stack`	ItemStackWrapper	No	Item appearance definition (see item-stack).
`taints`	`List<String>`	No	Tags used by layouts to filter which items they render.
`can-be-picked-up`	boolean	No	Allow the player to move this item with their cursor. Default `false`.
`view-requirements`	`List<Requirement>`	No	All must pass for the item to be visible.
`clicks-requirements`	`Map<ClickType, List<Requirement>>`	No	Requirements per click type before actions fire.
`actions`	`Map<ClickType, List<Action>>`	No	Actions to execute on click, keyed by click type.
`refresh`	object	No	Timer that re-renders this item's slot on an interval (see Auto-refresh).

*At least one of slot, slots, or placeholder should be provided.

Slot Types

Single slot

profile-button:
  slot: 22

Multiple fixed slots

border:
  slots:
    - 0
    - 8
    - 45
    - 53

Slots can also be quoted strings — useful when the value comes from a YAML anchor:

  slots:
    - "0"
    - "8"

Placeholder slot

The placeholder is resolved at compute-time via PlaceholderAPI or internal processors and must evaluate to an integer:

cursor:
  placeholder: "%variables_selected_slot%"

item-stack

The item-stack block describes how the item looks. It is parsed into an ItemStackWrapper — a placeholder-aware template that is re-resolved every time the slot is rendered.

Top-level fields

Field	Type	Description
`material`	String / placeholder	Bukkit `Material` name (e.g. `DIAMOND_SWORD`), a custom item provider id (see Custom item providers), or a `%placeholder%` that resolves to a `Material`. Required unless `copy-from` is set.
`copy-from`	Placeholder	A `%placeholder%` resolving to another `ItemStack` to clone as the base. The other fields below override fields on the cloned item.
`name`	String (MiniMessage)	Item display name. Supports all menu placeholders, `$e(...)` math, click/hover events.
`lore`	`List<String>`	Lore lines (each is a MiniMessage component).
`append-lore`	boolean	When `true` and `copy-from` is set, the new lore is appended after the copied item's existing lore instead of replacing it. Default `false`.
`amount`	int / placeholder	Stack size. Accepts a literal integer or a `%placeholder%` resolving to one.
`enchantments`	`Map<String, int>`	Enchantments to apply, keyed by lowercase Minecraft enchantment name.
`item-flags`	`List<String>`	List of `ItemFlag` names to set (e.g. `HIDE_ENCHANTS`, `HIDE_ATTRIBUTES`). Replaces all existing flags.

Basic example

item-stack:
  material: "DIAMOND_SWORD"
  name: "<gold>Heroic Blade"
  lore:
    - "<gray>Forged in starlight."
    - "<gray>Damage: <red>%player_attack_damage_rounded%"
  amount: 1
  item-flags:
    - HIDE_ATTRIBUTES
    - HIDE_ENCHANTS
  enchantments:
    sharpness: 5
    unbreaking: 3

Custom item providers

When the material value contains a -, the substring before the first dash is treated as an ItemStackSupplier namespace and the rest as the provider-specific key.

item-stack:
  material: "hdb-12345"   # namespace "hdb", key "12345"

Built-in namespaces:

Namespace	Provider	Always registered?	Example
(none)	Vanilla Minecraft material	yes	`DIAMOND_SWORD`
`vanilla`	Vanilla Minecraft material (explicit)	yes	`vanilla-diamond_sword`
`hdb`	HeadDatabase	when the HeadDatabase plugin is present	`hdb-12345`
`ce`	CraftEngine	when the CraftEngine plugin is present	`ce-my_item` or `ce-mypack:my_item`

Additional namespaces can be registered by plugins — see Item Stack Suppliers.

copy-from

copy-from clones the resolved item from another ItemStack placeholder and uses it as the base. Useful for preview menus that display an item the player is interacting with:

item-stack:
  copy-from: "%parameters_item%"
  append-lore: true
  lore:
    - ""
    - "<gray>Right-click to sell."

Item Components

Beyond the top-level fields, the item-stack block accepts any number of component keys that mirror Minecraft 1.21+ data components. Each key is independent — set only the components you need.

Key	Type	Description
`armor-trim`	object	Sets armor trim pattern + material.
`attributes`	map	Adds attribute modifiers (damage, speed, …).
`durability`	int / placeholder	Overrides the item's max damage.
`equippable`	object	Configures the equippable component (slot, sound, model, …).
`food`	object	Configures nutrition / saturation / always-eat.
`glow`	boolean / placeholder	Forces an enchantment glint without enchanting the item.
`hidden-components`	`List<DataComponentType>`	Hides specific vanilla data components from the tooltip (keeps the rest).
`hide-tooltip`	boolean / placeholder	Hides the entire vanilla tooltip.
`instrument`	string / key	Sets a goat horn's instrument.
`item-model`	string	Sets the item model key (`namespace:path`).
`leather-armor-color`	color	Sets the dye color on leather armor.
`model-data`	object	Sets the custom model data component (colors / flags / floats / strings).
`potion-effect`	object	Adds a custom potion effect to a `PotionMeta`.
`potion-color`	color	Sets the liquid color on a potion.
`repair-cost`	int / placeholder	Sets the anvil repair cost.
`skull`	string / placeholder	Sets a player skull's owner name or base64 texture.
`tool`	object	Configures the tool component (mining speed, rules, …).
`tooltip`	string / placeholder	Sets the tooltip style (`namespace:key`).
`tropical-fish-bucket`	object	Configures a tropical fish bucket.

armor-trim

armor-trim:
  pattern: "minecraft:eye"
  material: "minecraft:diamond"

Only takes effect on items whose meta is an ArmorMeta.

attributes

A map of Attribute → numeric value (or placeholder). Each entry becomes an AttributeModifier with the ADD_NUMBER operation, registered under the core:attributes namespaced key. Negative values are ignored.

attributes:
  generic.attack_damage: 12.0
  generic.movement_speed: "%player_speed_bonus%"

durability

Sets the item's max damage via Damageable#setMaxDamage. Accepts an integer or a placeholder.

durability: 250

equippable

Configures the vanilla equippable component. All fields except slot are optional.

equippable:
  slot: HEAD                              # EquipmentSlot — HEAD / CHEST / LEGS / FEET / OFF_HAND
  sound: "minecraft:item.armor.equip_iron"
  asset-id: "myplugin:helmet"             # Adventure key for the equipment asset
  camera-overlay: "myplugin:helm_overlay"
  dispensable: true
  swappable: true
  damage-on-hurt: true
  equip-on-interact: false
  can-be-sheared: false
  shear-sound: "minecraft:entity.sheep.shear"

food

food:
  nutrition: 6
  saturation: 7.2
  can-always-eat: false

Values of 0 or below for nutrition/saturation are skipped (the vanilla defaults remain).

glow

Toggles the enchantmentGlintOverride flag.

glow: true

A value of false clears any existing override. The value can be a %placeholder%.

hidden-components

Hides a specific subset of the item's data components from the tooltip via the vanilla minecraft:tooltip_display data component (Minecraft 1.21.5+). Unlike hide-tooltip, the tooltip is still shown — only the listed components are suppressed. Replaces any previously-set tooltip_display value.

Each entry is a DataComponentType resolved against Minecraft's component registry — supply the namespaced key form.

hidden-components:
  - "minecraft:enchantments"
  - "minecraft:attribute_modifiers"
  - "minecraft:unbreakable"
  - "minecraft:dyed_color"

Use this to clean up tooltips on display items in menus — hide the attribute_modifiers line on weapon previews, hide enchantments on showcase pieces, etc. — without losing the rest of the tooltip the way hide-tooltip: true does.

Hides the entire vanilla tooltip when the player hovers the item.

hide-tooltip: true

instrument

Sets the instrument played by a goat horn. The value is a namespaced key from Minecraft's instrument registry. Only applied when the item's meta is a MusicInstrumentMeta (i.e. a GOAT_HORN) — ignored otherwise.

item-stack:
  material: "GOAT_HORN"
  instrument: "minecraft:ponder_goat_horn"

Valid vanilla values: minecraft:ponder_goat_horn, minecraft:sing_goat_horn, minecraft:seek_goat_horn, minecraft:feel_goat_horn, minecraft:admire_goat_horn, minecraft:call_goat_horn, minecraft:yearn_goat_horn, minecraft:dream_goat_horn.

item-model

Sets the item model component (Minecraft 1.21.4+). Accepts an Adventure key.

item-model: "myplugin:custom_helmet"

leather-armor-color

Sets the dye color on leather armor. Accepts any Color form recognised by Configurate (hex string, named color, or RGB map).

leather-armor-color: "#7A2B8E"

model-data

Sets the four lists of the CustomModelDataComponent. Any combination of the four lists is allowed.

model-data:
  colors:
    - "#FF0000"
    - "#00FF00"
  flags:
    - true
    - false
  floats:
    - 1.0
    - 2.5
  strings:
    - "variant-a"

Every list supports placeholder resolution as a whole.

potion-effect

Adds a custom PotionEffect to a PotionMeta. The serializer accepts any Configurate-recognised PotionEffect payload.

potion-effect:
  type: "minecraft:speed"
  duration: 6000     # ticks
  amplifier: 1
  ambient: false
  particles: true
  icon: true

Applying this clears the base potion type so the custom effect is the only one shown.

potion-color

Sets the liquid color on a POTION/SPLASH_POTION/LINGERING_POTION.

potion-color: "#00FFAA"

repair-cost

Sets the anvil repair cost.

repair-cost: 5

skull

Sets a SkullMeta's skin. The value can be either a player username, a %placeholder%, or a base64-encoded texture property string. A value that begins with ey and is longer than 20 characters is treated as a base64 texture; otherwise it is treated as a username.

# Player username
skull: "%player_name%"

# Base64 texture
skull: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly..."

tool

Configures the tool component: default mining speed, damage per block, and per-block / per-tag rules.

tool:
  mining-speed: 6.0       # only applied if > 0
  damage-per-block: 1     # only applied if > 0
  rules:
    fast-on-stone:
      tag: "minecraft:mineable/pickaxe"
      speed: 12.0
      correct-for-drops: true
    extra-fast-on-iron:
      blocks:
        - "minecraft:iron_ore"
        - "minecraft:deepslate_iron_ore"
      speed: 20.0
      correct-for-drops: true
    single-block:
      block: "minecraft:obsidian"
      speed: 8.0
      correct-for-drops: true

A rule must provide exactly one of blocks (list of materials), tag (a Bukkit tag — see the format below), or block (single material). correct-for-drops makes the tool count as the correct tool for the block.

Sets the item's tooltip style key. The value must be in the form namespace:key.

tooltip: "myplugin:fancy"

tropical-fish-bucket

Only applied if all three fields are set.

tropical-fish-bucket:
  pattern-color: "WHITE"
  body-color: "ORANGE"
  pattern: "KOB"

Auto-refresh

An item can re-render its own slot on a repeating timer via a refresh: block — useful for live values (balances, cooldowns, online counts) that change without any click.

items:
  live-balance:
    slot: 22
    item-stack:
      material: "GOLD_INGOT"
      name: "<gold>%vault_eco_balance%"
    refresh:
      delay: 1.0            # seconds — required to activate
      requirements: []      # optional
      actions: []           # optional

Field	Type	Description
`delay`	double (seconds)	Interval between refreshes, in seconds (`1.0` = 1 s, `0.5` = 10 ticks). Accepts a placeholder / `$e(...)`. The block is inactive if `delay` is absent or resolves to `<= 0`.
`requirements`	`List<Requirement>`	Optional. Evaluated every tick; if any fails, that tick is skipped (the timer keeps running).
`actions`	`List<Action>`	Optional. Run every tick that requirements pass, immediately before the slot is re-rendered.

Only the item's own slot is recomputed each tick — this is the timer-driven equivalent of a refresh-slot action. Layouts have an analogous block, see Layout auto-refresh.

Click Types

Standard Bukkit ClickType values used as keys in actions and clicks-requirements:

Key	Description
`LEFT`	Left mouse button
`RIGHT`	Right mouse button
`SHIFT_LEFT`	Shift + left click
`SHIFT_RIGHT`	Shift + right click
`MIDDLE`	Middle mouse button
`DROP`	Drop key (Q)
`CONTROL_DROP`	Ctrl + drop
`DOUBLE_CLICK`	Double left click
`UNKNOWN`	Fallback — matches any click type not explicitly listed

The UNKNOWN key acts as a wildcard fallback. If a player clicks with a type that has no dedicated entry, the UNKNOWN entry is used instead.

Priority

When two items target the same slot, the one with the higher priority value wins. View requirements are evaluated before priority comparison — an item that fails its view-requirements is treated as absent.

default-item:
  slot: 4
  priority: 0
  item-stack:
    material: GRAY_STAINED_GLASS_PANE

active-item:
  slot: 4
  priority: 10
  view-requirements:
    - "[permission] myplugin.vip"
  item-stack:
    material: DIAMOND

Taints

Taints are string tags that link items to layouts. A layout with taint: "shop-item" will only populate its slots with items that have "shop-item" in their taints list.

shop-item:
  taints:
    - "shop-item"
  item-stack:
    material: STONE

Last modified: 25 July 2026