Abilities

Each entry under abilities: names a registered ability type and configures it.

abilities:
  - type: sigil:projectile
    id: firebolt
    name: "Firebolt"
    description: "Launch a small fireball."
    trigger: right_click
    cooldown: 2s
    projectile: SMALL_FIREBALL
    speed: 1.6

Keys every type accepts

typenamespaced keyrequired: The registered ability type, e.g. sigil:projectile or yourplugin:freeze.
idstring: Stable and unique within the item. Defaults to the type's name. It is used for the cooldown key and the permission node, so renaming it resets both.
nameMiniMessage: Shown in lore. Defaults to the id.
descriptionMiniMessage: Shown in lore.
triggertrigger: What fires it. Defaults per type.
cooldowndurationdefault 0: 2s, 500ms, 1m, or a plain number of seconds.
cooldown-scopeplayer | stack | globaldefault player: Almost always player: it survives the item being dropped, re-picked-up or creative-cloned, none of which should refund an ability.
sneakingboolean: true requires sneaking, false forbids it. Omitted means either.
targetair | block | entity | anydefault any: What the player must be aiming at.

All types additionally accept sound, volume and pitch.

Triggers

left_click · right_click · block_break · block_place · damage_entity · take_damage · projectile_launch · projectile_hit · swap_hands · drop · consume_item · equip · unequip · tick

swap_hands is the F key, the conventional "activate" input for an ability item, because it does not collide with placing or attacking. equip and unequip fire for armour.

Built-in types

Type	Does	Notable keys
`sigil:launch`	throws the holder in their look direction	`power`, `lift`
`sigil:projectile`	fires a projectile	`projectile`, `speed`
`sigil:potion`	applies an effect	`effect`, `duration`, `amplifier`, `self`
`sigil:heal`	restores health	`amount`
`sigil:area_break`	breaks blocks around the one mined	`radius` (1-4)
`sigil:smite`	lightning and damage on the target	`damage`, `lightning`
`sigil:worn_effect`	grants an effect while worn, removes it when taken off	`effect`, `amplifier`

The built-in defaults are deliberately usable: launch uses power: 1.5 and lift: 0.4; projectile uses SNOWBALL at speed: 1.5; potion uses SPEED for 10 seconds at level 1 on the holder; heal restores 4 health; area break uses radius 1; and smite adds 4 damage with visual lightning. Potion duration is measured in seconds.

Why an ability never handles its own cooldown

Cooldowns, permissions, use consumption and event cancellation are enforced by the dispatcher. An ability only says what happened, and the dispatcher decides what that costs:

Result	Cooldown	Use spent	Meaning
`pass`	no	no	not interested; other abilities still get a look
`success`	yes	no	fired
`consume`	yes	yes	fired and spent a charge
`fail`	no	no	tried and couldn't: no target, no room, nothing to do

The fail / pass distinction is the point. A single boolean forces "I missed" and "I fired" into the same bucket, which is how an ability ends up on cooldown for having hit nothing. Missing with a grapple costs you nothing.

Several abilities on one item

Abilities are tried in order and each gets a look until one claims the interaction. Different triggers coexist happily on one item:

abilities:
  - type: sigil:launch
    id: grapple
    trigger: right_click
    target: block
    cooldown: 1s
    power: 1.8

  - type: sigil:potion
    id: brace
    trigger: swap_hands
    cooldown: 30s
    effect: DAMAGE_RESISTANCE
    duration: 100
    amplifier: 1
    self: true

Give each one a distinct id: it is the cooldown key and the permission node, so two abilities sharing an id would share a cooldown.

Custom types

Another plugin can register an ability type, which makes it available to every item on the server, including ones defined purely in config:

abilities:
  - type: yourplugin:freeze
    duration: 100

See the API for what registering one involves.

To verify configuration rather than guessing at it, reload and run /sigil info <item>. It prints the resolved ability ids, trigger bindings and cooldowns. Test with a fresh /sigil give copy when uses or per-stack cooldowns could affect the result.