Item reference

Every .yml under plugins/Sigil/items/<namespace>/ defines one item. The filename is the id, the folder is the namespace: items/aether/mythril.yml is aether:mythril.

Run /sigil reload to apply changes.

Identity

basematerialrequired: The vanilla material the item is built from, e.g. IRON_INGOT.
displayMiniMessage: Defaults to the id. If it carries no colour of its own it inherits the rarity's.
rarityrarity keydefault common: Must match a key under rarities in config.yml.
descriptionlist of MiniMessage: Lore lines, placed wherever <description> sits in the lore template.
categorystring: Free-form grouping. material marks the item as a crafting material.
tagslist of strings: Free-form, case-insensitive labels used by addons to select sets of items through api.itemsWithTag(...). Unlike category, an item can have several tags.
enabledbooleandefault true: false removes the item from the registry entirely.
permissionnode: Overrides the default sigil.item.<ns>.<id> node.
modelmodel key: Named item model. Requires 1.21.4+.
custom-model-dataintegerdefault -1: Integer fallback for servers below 1.21.4.

category: armour
tags: [frost, dungeon_reward]

display: "<gradient:#00b0ff:#9b00ff>Grappling Hook</gradient>"
base: TRIPWIRE_HOOK
rarity: rare
description:
  - "A handy device for reaching high places."

Uses

uses:
  type: limited # or: infinite
  max: 250
  delete-at-zero: true

delete-at-zero: false keeps the item as a spent husk that no longer activates.

Interaction rules

Each key is optional, and omitting one is not the same as setting it. An item that never expressed an opinion keeps following config.yml if that later changes.

rules:
  vanilla-recipes: false # can this be an ingredient in ordinary vanilla recipes?
  anvil-rename: false # can players rename it?
  anvil-combine: true # can two of them merge their remaining charges?
  enchanting: false # can it be enchanted at a table?

When anvil-rename is allowed, a name a player gives an item survives every later re-render: spending a charge, merging charges, a grindstone, or a /sigil reload that changed the item's configured name. Sigil stamps the name it wrote onto the stack and only overwrites a display name that still matches that stamp, so a name it did not write is left alone.

Items that forbid renaming keep the old behaviour and are reset to the configured name, which is the point of the rule rather than a side effect of it.

Grindstones always preserve a custom item's identity, lore and charges while still removing player-applied enchantments. That is not configurable, because the alternative is handing the player something that looks right and is silently broken.

Permissions

Deny-only. Everything works out of the box, and you take things away:

Node	Denies
`sigil.item.<ns>.<id>`	that item entirely
`sigil.ability.<ns>.<id>.<ability>`	one ability, leaving the rest of the item usable

In LuckPerms that means -sigil.item.aether.mythril, not a grant for everyone else.

A complete file

display: "<gradient:#00b0ff:#9b00ff>Grappling Hook</gradient>"
base: TRIPWIRE_HOOK
rarity: rare
category: tool
tags: [mobility, utility]
description:
  - "A handy device for reaching high places."

uses:
  type: limited
  max: 250
  delete-at-zero: false

rules:
  anvil-rename: true
  anvil-combine: true
  enchanting: false

abilities:
  - type: sigil:launch
    id: grapple
    name: "Grapple"
    trigger: right_click
    cooldown: 1s
    power: 1.8
    lift: 0.4

recipe:
  type: shaped
  shape:
    - " SI"
    - " SL"
    - "I  "
  keys:
    S: STRING
    L: LEAD
    I: sigil:aether_ingot

Run /sigil reload and then /sigil info <item> to check the resolved rarity, rules, abilities and recipes. Setting enabled: false removes the definition from the active registry after reload; it does not delete stacks already in inventories.