GroupeZ Docs

Metadata Overview

Configure special item properties with metadata

Metadata allows you to configure special properties for items that go beyond basic materials and enchantments. This includes making items edible, adding potion effects, customizing armor appearance, and more.

How Metadata Works

Metadata is defined in the metadata section of an item configuration:

my_item:
  material: DIAMOND_SWORD
  display-name: "<red>Special Sword</red>"

  metadata:
    # Each metadata type is a separate key
    food:
      nutrition: 5
      saturation: 1.0

    commands:
      commands:
        - sender: CONSOLE
          commands:
            - "give %player% diamond 1"

Available Metadata Types

TypeDescriptionUse Case
foodMake items edibleCustom food items
potionAdd potion effectsCustom potions
leather-armorDye leather armorColored armor
trimAdd armor trimsDecorative armor
bannerAdd banner patternsCustom banners/shields
toolCustom mining propertiesCustom tools
commandsExecute commands on useInteractive items

food

Make any item edible with custom nutrition, effects, and animations.

metadata:
  food:
    # Required: Food value (hunger points restored)
    nutrition: 6

    # Required: Saturation modifier
    saturation: 1.2

    # Optional: Can eat when not hungry (default: false)
    can-always-eat: true

    # Optional: Time to eat in seconds (default: 1.6)
    eat-seconds: 1.0

    # Optional: Eating animation
    animation: EAT  # EAT, DRINK, BLOCK, BOW, SPEAR, CROSSBOW, SPYGLASS, TOOT_HORN, BRUSH

    # Optional: Eating sound
    sound: ENTITY_GENERIC_EAT

    # Optional: Cooldown after eating
    cooldown-seconds: 5.0

    # Optional: Cooldown group (shared cooldown)
    group-cooldown: "my_food_group"

    # Optional: Effects when eaten
    effects:
      - effect: SPEED
        amplifier: 1
        duration: 600  # ticks (600 = 30 seconds)
      - effect: REGENERATION
        amplifier: 2
        duration: 100

Full Food Example

super_apple:
  material: GOLDEN_APPLE
  display-name: "<gradient:#ff69b4:#da70d6>Super Apple</gradient>"
  lore:
    - ""
    - "<gray>A magical fruit!</gray>"
    - ""
    - "<yellow>When eaten:</yellow>"
    - "<gray>+10 Hunger</gray>"
    - "<gray>Speed II (30s)</gray>"
    - "<gray>Strength II (30s)</gray>"

  metadata:
    food:
      nutrition: 10
      saturation: 2.5
      can-always-eat: true
      eat-seconds: 0.5
      animation: EAT
      effects:
        - effect: SPEED
          amplifier: 1
          duration: 600
        - effect: STRENGTH
          amplifier: 1
          duration: 600
        - effect: REGENERATION
          amplifier: 2
          duration: 100

potion

Configure custom potion effects for potions and tipped arrows.

metadata:
  potion:
    # Optional: Potion color (hex or RGB)
    color: "#FF0000"

    # Optional: Base potion type
    base-potion-type: STRENGTH

    # Optional: Custom effects
    custom-effects:
      - effect: STRENGTH
        amplifier: 2
        duration: 1200
      - effect: SPEED
        amplifier: 1
        duration: 1200

Full Potion Example

warrior_potion:
  material: POTION
  display-name: "<red>Warrior's Elixir</red>"
  lore:
    - ""
    - "<gray>Grants combat prowess</gray>"
    - ""
    - "<yellow>Effects:</yellow>"
    - "<gray>Strength III (60s)</gray>"
    - "<gray>Speed II (60s)</gray>"
    - "<gray>Resistance I (60s)</gray>"

  metadata:
    potion:
      color: "#FF4444"
      custom-effects:
        - effect: STRENGTH
          amplifier: 2
          duration: 1200
        - effect: SPEED
          amplifier: 1
          duration: 1200
        - effect: RESISTANCE
          amplifier: 0
          duration: 1200

leather-armor

Set the color of leather armor pieces.

metadata:
  leather-armor:
    # Color in RGB format
    color: "#FF5500"

Full Leather Armor Example

flame_chestplate:
  material: LEATHER_CHESTPLATE
  display-name: "<gradient:#ff4500:#ff8c00>Flame Tunic</gradient>"
  lore:
    - ""
    - "<gray>Burns with inner fire</gray>"

  enchantments:
    - enchantment: FIRE_PROTECTION
      level: 4

  metadata:
    leather-armor:
      color: "#FF4500"

trim

Apply armor trims to armor pieces.

metadata:
  trim:
    # Trim material
    material: GOLD  # QUARTZ, IRON, NETHERITE, REDSTONE, COPPER, GOLD, EMERALD, DIAMOND, LAPIS, AMETHYST

    # Trim pattern
    pattern: SENTRY  # SENTRY, DUNE, COAST, WILD, WARD, EYE, VEX, TIDE, SNOUT, RIB, SPIRE, WAYFINDER, SHAPER, SILENCE, RAISER, HOST, FLOW, BOLT

Full Trim Example

royal_helmet:
  material: DIAMOND_HELMET
  display-name: "<gradient:#ffd700:#daa520>Royal Crown</gradient>"
  lore:
    - ""
    - "<gray>Fit for a king</gray>"

  enchantments:
    - enchantment: PROTECTION
      level: 4
    - enchantment: UNBREAKING
      level: 3

  metadata:
    trim:
      material: GOLD
      pattern: SENTRY

Add patterns to banners and shields.

metadata:
  banner:
    patterns:
      - pattern: STRIPE_BOTTOM
        color: WHITE
      - pattern: STRIPE_TOP
        color: BLUE
      - pattern: CROSS
        color: RED

Common patterns: BASE, STRIPE_BOTTOM, STRIPE_TOP, STRIPE_LEFT, STRIPE_RIGHT, STRIPE_CENTER, STRIPE_MIDDLE, STRIPE_DOWNRIGHT, STRIPE_DOWNLEFT, CROSS, STRAIGHT_CROSS, DIAGONAL_LEFT, DIAGONAL_RIGHT, DIAGONAL_UP_LEFT, DIAGONAL_UP_RIGHT, HALF_VERTICAL, HALF_HORIZONTAL, CIRCLE, RHOMBUS, TRIANGLE_BOTTOM, TRIANGLE_TOP, GRADIENT, GRADIENT_UP, BRICKS, SKULL, CREEPER, FLOWER, MOJANG, GLOBE, PIGLIN, FLOW, GUSTER

Full Banner Example

guild_banner:
  material: BLUE_BANNER
  display-name: "<blue>Guild Banner</blue>"
  lore:
    - ""
    - "<gray>The banner of our guild</gray>"

  metadata:
    banner:
      patterns:
        - pattern: GRADIENT
          color: LIGHT_BLUE
        - pattern: CROSS
          color: YELLOW
        - pattern: BORDER
          color: WHITE

tool

Configure custom mining properties for tools.

metadata:
  tool:
    # Damage per block mined
    damage-per-block: 1

    # Default mining speed
    default-mining-speed: 1.0

    # Tag-based rules
    rules:
      - tag: MINEABLE_PICKAXE
        speed: 8.0
        correct-for-drops: true

    # Material-based rules
    material-rules:
      - materials:
          - STONE
          - COBBLESTONE
        speed: 10.0
        correct-for-drops: true

Full Tool Example

multitool:
  material: NETHERITE_PICKAXE
  display-name: "<gradient:#ff6b6b:#feca57>Multi-Tool</gradient>"
  lore:
    - ""
    - "<gray>Works on everything!</gray>"

  metadata:
    tool:
      damage-per-block: 1
      default-mining-speed: 8.0
      rules:
        - tag: MINEABLE_PICKAXE
          speed: 12.0
          correct-for-drops: true
        - tag: MINEABLE_SHOVEL
          speed: 12.0
          correct-for-drops: true
        - tag: MINEABLE_AXE
          speed: 12.0
          correct-for-drops: true

commands

Execute commands when the item is used.

metadata:
  commands:
    # Optional: Require confirmation
    need-confirmation: false

    commands:
      - sender: PLAYER  # PLAYER or CONSOLE
        action: RIGHT_CLICK  # LEFT_CLICK, RIGHT_CLICK, SHIFT_LEFT_CLICK, SHIFT_RIGHT_CLICK
        commands:
          - "spawn"
        messages:
          - "<green>Teleported to spawn!</green>"
        cooldown: 300  # seconds
        damage:
          type: AMOUNT  # AMOUNT or DURABILITY
          quantity: 1

Full Commands Example

teleport_wand:
  material: BLAZE_ROD
  display-name: "<gradient:#00ffff:#00aaff>Teleport Wand</gradient>"
  lore:
    - ""
    - "<gray>Right-click to teleport to spawn!</gray>"
    - ""
    - "<yellow>Cooldown: <white>5 minutes</white></yellow>"

  max-damage: 10

  metadata:
    commands:
      commands:
        - sender: PLAYER
          action: RIGHT_CLICK
          commands:
            - "spawn"
          messages:
            - "<green>Whoosh! Teleported to spawn!</green>"
          cooldown: 300
          damage:
            type: AMOUNT
            quantity: 1

Complete Multi-Metadata Example

legendary_artifact:
  material: GOLDEN_APPLE
  display-name: "<gradient:#ffd700:#ff8c00>Legendary Artifact</gradient>"
  lore:
    - ""
    - "<gray>An ancient artifact with</gray>"
    - "<gray>mysterious powers.</gray>"
    - ""
    - "<yellow>When eaten:</yellow>"
    - "<gray>- Full hunger restoration</gray>"
    - "<gray>- All positive effects</gray>"
    - ""
    - "<yellow>When used:</yellow>"
    - "<gray>- Teleports to spawn</gray>"

  metadata:
    food:
      nutrition: 20
      saturation: 5.0
      can-always-eat: true
      eat-seconds: 0.5
      effects:
        - effect: SPEED
          amplifier: 2
          duration: 2400
        - effect: STRENGTH
          amplifier: 2
          duration: 2400
        - effect: REGENERATION
          amplifier: 2
          duration: 600
        - effect: RESISTANCE
          amplifier: 1
          duration: 2400
        - effect: FIRE_RESISTANCE
          amplifier: 0
          duration: 2400

    commands:
      commands:
        - sender: PLAYER
          action: SHIFT_RIGHT_CLICK
          commands:
            - "spawn"
          messages:
            - "<gold>The artifact's power teleports you!</gold>"

Next Steps

Attributes Applicator

Add or modify item attributes

Runes (Legacy)

Next Page

On this page

How Metadata WorksAvailable Metadata TypesfoodFull Food ExamplepotionFull Potion Exampleleather-armorFull Leather Armor ExampletrimFull Trim ExamplebannerBanner PatternsFull Banner ExampletoolFull Tool ExamplecommandsFull Commands ExampleComplete Multi-Metadata ExampleNext Steps
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.