Katacr
Enter at least two characters

hasItem and hasStockItem Condition Methods

Docs version: v2.1.0

hasItem - Regular Item Check#

Checks whether the player inventory contains items matching the given criteria and totals their quantity.

Format#

hasItem.[mats=material;amount=quantity;lore=description;name=display-name;model=item-model;custom_model_id=integer-ID]

Parameters#

Parameter Description Required
mats Minecraft material name (supports multiple formats), or an external plugin item ID ❌
amount Required quantity; defaults to 1 when omitted ❌
lore Text that must be contained in item description (case-insensitive) ❌
name Text that must be contained in the item display name (case-insensitive, color codes stripped) ❌
model / item_model ItemModel (format: namespace:key) ❌
cmd / custom_model_data / custom_model_id Integer CustomModelData ❌

Matching Rules#

  • At least one matching dimension (mats / lore / name / model / cmd) must be given, otherwise the result is always unsatisfied
  • Multiple specified dimensions are combined with AND: the same item must satisfy all of them
  • Total quantity of all matching items must be greater than or equal to amount (defaults to 1)
  • If mats is specified, the material must match; when mats is an external plugin item ID, matching is by plugin item ID
  • If lore is specified, the item's description must contain that string (case-insensitive)
  • If name is specified, the item's display name with color codes stripped must contain that string (case-insensitive)
  • If model is specified, the item's item_model must match exactly (format: namespace:key, case-insensitive)
  • If custom_model_id is specified, the integer CustomModelData must match exactly

Material Name Format Support#

KaMenu supports multiple material name formats, and the system automatically normalizes and matches the corresponding Material enum:

  • Standard format: DIAMOND_SWORD
  • Lowercase: diamond_sword
  • Mixed case: DiAMond swORd
  • Hyphens: Diamond-Sword
  • Spaces: diamond sword

Examples:

# All formats below match DIAMOND_SWORD
- condition: "hasItem.[mats=DIAMOND_SWORD;amount=1]"
- condition: "hasItem.[mats=diamond_sword;amount=1]"
- condition: "hasItem.[mats=Diamond-Sword;amount=1]"
- condition: "hasItem.[mats=diamond sword;amount=1]"

Examples#

Check if player has 10 diamonds:

- condition: "hasItem.[mats=DIAMOND;amount=10]"
  allow:
    - 'tell: &aYou have enough diamonds!'
  deny:
    - 'tell: &cYou need 10 diamonds!'

Check if player has 1 diamond with "Forging Material" in the description:

- condition: 'hasItem.[mats=DIAMOND;amount=1;lore=Forging Material]'
  allow:
    - 'tell: &aYou have Forging Material diamonds!'
  deny:
    - 'tell: &cYou''re missing Forging Material diamonds!'

Match by lore only, without restricting the material (useful for event items across materials):

- condition: 'hasItem.[lore=Event Token;amount=5]'
  allow:
    - 'tell: &aYou have 5 Event Tokens!'
  deny:
    - 'tell: &cYou do not have enough Event Tokens!'

Match by display name only, without restricting the material:

- condition: 'hasItem.[name=Legendary Sword;amount=1]'
  allow:
    - 'tell: &aYou own the Legendary Sword!'
  deny:
    - 'tell: &cYou do not own the Legendary Sword yet!'

Match by CustomModelData only, without restricting the material:

- condition: 'hasItem.[cmd=10086;amount=1]'

Check if player has 16 items with a custom model (e.g., Oraxen items):

- condition: 'hasItem.[mats=PAPER;amount=16;model=oraxen:mana_crystal]'
  allow:
    - 'tell: &aYou have enough Magic Crystals!'
  deny:
    - 'tell: &cYou need 16 Magic Crystals!'

Match an exact plugin item ID:

- condition: 'hasItem.[mats=itemsadder:my_pack:magic_sword;amount=1]'
- condition: 'hasItem.[mats=oraxen:magic_sword;amount=1]'
- condition: 'hasItem.[mats=craftengine:my_pack:magic_sword;amount=1]'

Check for paper with custom model ID 10001:

- condition: 'hasItem.[mats=PAPER;amount=1;custom_model_id=10001]'
  allow:
    - 'tell: &aFound the requested model item!'
  deny:
    - 'tell: &cThe requested model item was not found!'

Combine with item action:

actions:
  - condition: "hasItem.[mats=DIAMOND;amount=16]"
    allow:
      - 'item: type=take;mats=DIAMOND;amount=16'
      - 'tell: &aPurchase successful! 16 diamonds deducted'
    deny:
      - 'tell: &cInsufficient items! 16 diamonds required'

Reverse check (condition met when no items):

actions:
  - condition: "!hasItem.[mats=DIAMOND;amount=64]"
    allow:
      - 'tell: &aYou can continue mining diamonds!'
    deny:
      - 'tell: &cYour inventory is full!'

Notes#

  • Material names are case-insensitive, supporting multiple formats (see above)
  • mats accepts itemsadder:/ia:, oraxen:, craftengine:/ce:, and sxitem:/sx: prefixes; external items match by plugin item ID
  • mats may be omitted, in which case matching uses lore / name / model / cmd only; at least one of them is still required
  • lore check is an "includes" relationship, any matching string in description is sufficient
  • name check strips color codes before comparing, and is likewise an "includes" relationship
  • model format is namespace:key, such as:
    • minecraft:book (vanilla item model)
    • oraxen:mana_crystal (Oraxen custom items)
    • itemsadder:test_item (ItemsAdder custom items)
  • model is an exact comparison, not an "includes" one
  • Custom model IDs use integer matching and accept cmd, custom_model_data, or custom_model_id
  • model and custom_model_id may be combined; both must match
  • Supports reverse checks, e.g., !hasItem.[...] means condition is met when the item is absent
  • The check covers the main inventory, hotbar, armor slots, and offhand; no item is counted twice
  • The result counts total item amount (sum of amount across all matching stacks), not the number of stacks

hasStockItem - Saved Item Check#

Checks if the player inventory contains items with a specified name and quantity from the saved items.

Format#

hasStockItem.item_name;quantity

Parameters#

Parameter Description Required
Item name Saved item name ✅
Quantity Required quantity; falls back to 1 when it cannot be parsed as an integer ✅

Matching Rules#

  • Item must have been saved using /km item save command
  • Comparison ignores quantity differences and only checks whether the item's own properties are identical
  • Total quantity of all matching items must be greater than or equal to the specified quantity
  • If the saved item does not exist, the result is always unsatisfied (quantity counts as 0)

Examples#

Check if player has 16 Mystic Fruits:

- condition: "hasStockItem.MysticFruit;16"
  allow:
    - 'tell: &aYou have enough Mystic Fruits!'
  deny:
    - 'tell: &cYou need 16 Mystic Fruits!'

Check if player has 1 Sacred Sword:

- condition: "hasStockItem.SacredSword;1"
  allow:
    - 'tell: &aYou can purchase this item!'
  deny:
    - 'tell: &cYou need a Sacred Sword to purchase!'

Combine with stock-item action:

actions:
  - condition: "hasStockItem.MysticFruit;16"
    allow:
      - 'stock-item: type=take;name=MysticFruit;amount=16'
      - 'tell: &aPurchase successful!'
    deny:
      - 'tell: &cInsufficient items! 16 Mystic Fruits required'

Reverse check (condition met when no items):

actions:
  - condition: "!hasStockItem.SacredSword;1"
    allow:
      - 'tell: &aYou don''t have this weapon yet, you can purchase it!'
    deny:
      - 'tell: &cYou already have a Sacred Sword, you can''t purchase again!'

Using variables:

actions:
  # Read item name and quantity from data
  - condition: "hasStockItem.{data:purchase_item};{data:required_amount}"
    allow:
      - 'stock-item: type=take;name={data:purchase_item};amount={data:required_amount}'
      - 'tell: &aPurchase successful!'
    deny:
      - 'tell: &cInsufficient items!'

Notes#

  • Item must be saved using /km item save before use
  • Parameters are two positional arguments (name;quantity); the quantity cannot be omitted, and an unparsable quantity silently falls back to 1
  • Supports reverse checks, e.g., !hasStockItem.item_name;quantity
  • Comparison is a full item match (material, display name, lore, custom model data, item model, etc. must all be identical)
  • Consequently, if an item's lore or other properties were modified (for example /km item give replacing {player} in lore), hasStockItem can no longer match it; use hasItem with the lore dimension instead, or deduct with item: type=take;lore=...
  • The check covers the main inventory, hotbar, armor slots, and offhand; no item is counted twice

Complete Example: Shopping Menu#

Purchase Regular Items#

This demonstrates creating a menu to purchase diamonds at 100 coins each.

Title: '§6§lDiamond Shop'

Settings:
  need_placeholder:
    - 'math'
Body:
  diamond:
    type: 'item'
    text: '&a&lDiamond'
    material: DIAMOND
    lore:
      - '&7Price: 100 coins / each'
    description: 'Please use the slider below to select purchase quantity.'

Inputs:
  amount:
    type: 'slider'
    text: '&aPurchase Quantity'
    min: 1
    max: 64
    default: 1
    format: '%s: %seach'

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm Purchase ]'
    actions:
      # Purchase diamonds (use hasMoney to check if player has enough currency)
      - condition: "isIntNum.$(amount)"
        deny:
          - 'tell: &cPlease enter a valid number.'
          - 'return'
      - condition: "hasMoney.%math_0_100*$(amount)%"
        allow:
          - 'money: type=take;num=%math_0_100*$(amount)%'
          - 'item: type=give;mats=DIAMOND;amount=$(amount)'
          - 'tell: &aPurchase successful! Spent %math_0_100*$(amount)% coins, received %$(amount) diamonds'
        deny:
          - 'tell: &cInsufficient currency! Need %math_0_100*$(amount)% coins'
          - 'sound: block.note_block.bass'
  deny:
    text: '&c[ Cancel Purchase ]'
    actions:
      - 'actionbar: &cPurchase cancelled'
      - 'sound: block.note_block.bass'
      - 'close'

Purchase Stored Items#

Prerequisite: To use this example menu, you should first save an item named Magic Diamond Sword using /km item save Magic Diamond Sword.

Title: '§6§lMagic Diamond Sword Shop'

Settings:
  need_placeholder:
    - 'math'
Body:
  diamond_sword:
    type: 'item'
    text: '&a&lMagic Diamond Sword'
    material: DIAMOND_SWORD
    lore:
      - '&7Price: 10 diamonds'
    description: 'Please use the slider below to select redemption quantity.'

Inputs:
  amount:
    type: 'slider'
    text: '&aPurchase Quantity'
    min: 1
    max: 64
    default: 1
    format: '%s: %seach'

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ Confirm Purchase ]'
    actions:
      # Purchase diamond sword (use hasItem to check regular items)
      - condition: "hasItem.[mats=DIAMOND;amount=%math_0_10*$(amount)%]"
        allow:
          - 'item: type=take;mats=DIAMOND;amount=%math_0_10*$(amount)%'
          - 'stock-item: type=give;name=Magic Diamond Sword;amount={data:purchase_amount}'
          - 'tell: &aPurchase successful! Spent %math_0_10*$(amount)% diamonds, received Magic Diamond Sword x$(amount)'
        deny:
          - 'tell: &cInsufficient items! Need diamonds x%math_0_10*$(amount)%'
          - 'sound: block.note_block.bass'
  deny:
    text: '&c[ Cancel Purchase ]'
    actions:
      - 'actionbar: &cPurchase cancelled'
      - 'sound: block.note_block.bass'
      - 'close'

Differences Between the Two#

Feature hasItem hasStockItem
Scope Regular items Saved items
Parameter Format hasItem.[mats=...;amount=...] hasStockItem.item_name;quantity
Material Check Uses Minecraft native material ID or external plugin item ID Uses the saved item's complete properties
Item Matching Combines material / external ID / lore / name / model / cmd (AND) Full match of all item properties
Partial Matching Yes (e.g. match by lore only) No, the whole item must be identical
Quantity Parameter Optional, defaults to 1 Required
Pre-save Required No Yes, via /km item save
Use Case Check basic items (e.g., diamonds, iron ore) Check custom items (e.g., enchanted gear, special items)