Sigil

Custom items, materials, abilities and recipes for Minecraft servers.

Minecraft

1.18-26.x

Servers

Spigot, Paper, Purpur, Pufferfish, Folia

Java

17+

Needs

Nothing else

Licence

LGPL-3.0

Choose your path

Sigil has one content type. What other plugins call a "material" is just an item with no abilities, which is what makes "a recipe whose ingredient is a custom item" work without a second parallel concept to keep in sync.

An item is a file

Any .yml under items/<namespace>/ is an item. The filename is its id and the folder is its namespace, so items/aether/mythril.yml is aether:mythril.

display: "<#7fd4ff>Mythril Ingot"
base: IRON_INGOT
rarity: uncommon
description:
  - "Refined under pressure."

recipe:
  type: shaped
  shape: ["NNN", "NNN", "NNN"]
  keys:
    N: IRON_NUGGET

That is a complete custom material. Copy it, rename it, and you have another. Give it a registered ability type and it does something:

abilities:
  - type: sigil:projectile
    id: firebolt
    name: "Firebolt"
    trigger: right_click
    cooldown: 2s
    projectile: SMALL_FIREBALL
    speed: 1.6

items/sigil/ember_wand.yml ships with the plugin as a worked example, and it has no Java behind it at all.

What makes it different

Items already in inventories update themselves

Every stack carries a revision stamp. Edit an item's name or lore, run /sigil reload, and existing copies re-render the next time a player looks at them, keeping their remaining uses and any data other plugins wrote.

A re-render will not take a player's name off an item

Sigil stamps the name it wrote and only overwrites a display name that still matches that stamp. That is what lets an item be both renameable and limited-use: without it, the anvil label a player gave a charged item would vanish the first time they spent a charge, because spending one re-renders the stack.

Abilities cannot forget their own plumbing

Cooldowns, permissions, use consumption and event cancellation are enforced by the dispatcher, not by each ability. An ability returns PASS, SUCCESS, CONSUME or FAIL, and the distinction matters: FAIL means "tried and couldn't", so missing with a grapple does not put it on cooldown.

Recipes are matched by identity

A custom ingredient is matched on its persistent id, so a renamed lookalike cannot satisfy it and a lore change cannot break it. Two recipes can share a shape and differ only in whether an ingredient is custom, which vanilla recipe registration cannot express.

Permissions are deny-only

Everything works out of the box. -sigil.item.aether.mythril in LuckPerms denies exactly that item; sigil.ability.<ns>.<id>.<ability> denies one ability while leaving the rest of the item usable.

Config is read once

Definitions are parsed at startup into immutable records and published behind a single volatile reference. Nothing re-reads a file at runtime, and a reload can never be observed half-applied.

Where to go next

• Getting started: install it and make your first item.
• Item reference: every key a file can contain.
• Abilities: triggers, cooldowns and the built-in types.
• Recipes: all six recipe kinds and how ingredients match.
• Server configuration: rarities, lore layout and interaction defaults.
• Compatibility: what degrades on older servers, and how you find out.
• Troubleshooting: item, ability, recipe and refresh diagnostics.