Getting started

Sigil requires Java 17 or newer and a Spigot-compatible 1.18-26.x server. Paper, Purpur, Pufferfish and Folia are supported; PlaceholderAPI is optional. No library plugin is required.

1. Drop the jar in and start the server

   There is no second plugin to install, because the framework is inside the jar. On first run Sigil writes a file per registered item under plugins/Sigil/items/<namespace>/, and never overwrites one once it exists.

2. Check what it thinks it is running on

   /sigil platform
   

   Prints the detected server, the compatibility tier it chose and which scheduler is in use. Worth reading once now so it is familiar when you need it in a bug report.

3. Look at the example

   items/sigil/ember_wand.yml is a complete item with an ability and a recipe, defined entirely in YAML. Open it, then browse everything registered:

   /sigil menu
   

   Click an item to see its recipe.

4. Write your own

   Create plugins/Sigil/items/aether/mythril.yml:

   display: "<#7fd4ff>Mythril Ingot"
   base: IRON_INGOT
   rarity: uncommon
   description:
     - "Refined under pressure."
   
   recipe:
     type: shaped
     shape: [ "NNN", "NNN", "NNN" ]
     keys:
       N: IRON_NUGGET

   The filename is the id and the folder is the namespace, so this is aether:mythril. Nothing else declares it.

5. Apply it

   /sigil reload
   /sigil give aether:mythril
   

   Items already in inventories update themselves the next time a player looks at them, so a reload after an edit is enough and nobody has to re-collect anything.

What ends up on disk

Two kinds of file end up in items/. One overrides an item registered in code, where the code supplies defaults and behaviour and the file retunes it. The other defines an item outright, naming ability types instead of writing Java. They use the same keys; a file simply supplies whatever it wants to change.

Commands you will use

/sigil menu                 browse every item, click one to see its recipe
/sigil give <item> [player] [amount]
/sigil list [rarity]
/sigil info <item>          abilities, triggers, cooldowns, rules, recipes
/sigil reload               re-read config, items and recipes
/sigil platform             what Sigil thinks it is running on

When a file is wrong

Sigil accumulates problems rather than stopping at the first, so one bad file reports everything wrong with it in a single startup block naming the file and the reason. There are three categories:

• error: that item or recipe will not work.
• warn: it loaded, but not as written.
• gate: the server version cannot do what was asked, and here is what happened instead.

A gate line is not a mistake. It is Sigil telling you a smithing recipe was skipped on 1.19.2, or an item model fell back to custom model data, so that correct-but-degraded behaviour is never indistinguishable from a bug.

After every first edit, use /sigil info <item> to verify the resolved definition and /sigil recipe <item> to verify what was actually registered. These inspect Sigil's loaded state, not just the YAML you intended it to read.