Configuring

Abilities and hold effects

Right-click abilities, who they reach, what they cost, and the passive version that runs while an item is held.

Both systems are keyed by material. An ability is one right-click; a hold effect is what happens continuously while the same kind of item sits in the main hand.

Abilities

abilities:
  SUGAR:
    display-name: "<#ffd82b><bold>SPEED"
    type: TO_CLAN
    radius: 20
    effects:
      - SPEED|3|5
    cooldown: 7
    energy-cost: 35
    particles:
      enabled: true
      type: "CRIT|60|1|1|1|1"
    sound:
      enabled: true
      type: "BLOCK_NOTE_BLOCK_GUITAR|1|2"

Key	Default	What it does
`display-name`	the material	The name used in messages. Colours work.
`type`	`SELF`	Who the effects land on. See below.
`effects`	none	Effect lines, `NAME
`cooldown`	`30`	Seconds. `0` disables the cooldown entirely.
`energy-cost`	`0`	Energy spent. Requires an `energy` block on the class.
`radius`	`0`	Blocks, for the types that need one.
`particles`	off	Shown on every target, at their own location.
`sound`	off	Played to the caster only.

The map key is the material a player right-clicks. An unknown material is logged and skipped.

What happens on a right-click

The item is checked

The player must be in a class, and the item in hand must be one of that class's ability materials. Otherwise the click is left alone.

The interaction is cancelled

As soon as the item matches, the vanilla right-click is cancelled — an ability on a bow or a food item will not also shoot or eat.

Cooldown, then energy

Still on cooldown, or not enough energy, and the player is told and nothing else happens. The item is not spent.

Effects, particles, sound

The effects are applied to every target, particles are shown at each of them, the sound plays for the caster, and everyone hit other than the caster gets a message.

One item is consumed

Only after all of that. A stack loses one; a single item disappears from the main hand.

Cooldowns are per material, per player

Two abilities on the same material in different classes share the same cooldown slot, and the cooldown survives switching classes only until the class is removed — leaving the class clears every ability cooldown it declared.

Targeting

type decides who is hit, and radius is the reach for the types that leave the caster.

Type	Who it reaches
`SELF`	The caster. `radius` is ignored.
`TO_CLAN`	The caster, plus every online clan member inside `radius`, in the same world.
`TO_CLAN_AND_ALLY`	Identical to `TO_CLAN` today.
`TO_ENEMY`	Every player inside `radius` in the same world who is not in the caster's clan. The caster is excluded.
`TO_ALLY`	Nobody.

An unrecognised type falls back to SELF.

TO_ALLY reaches no one

It resolves to an empty target list, so an ability declared TO_ALLY still costs energy, still starts its cooldown and still consumes the item, and applies nothing. Use TO_CLAN until that changes.

Without a clan plugin

Clan membership is answered by ExyliaLib, which detects FactionsUUID, HuskTowns, ZelTeams, RunithClans, UltimateClans, Kingdoms, SimpleClans or ExyliaClans. With none of them installed:

TO_CLAN reaches only the caster.
TO_ENEMY reaches everyone in range, because nobody shares a clan with anybody.

That second one matters on a server without clans: a 25-block Sorcerer debuff hits allies too.

Messages to the people hit

Everyone but the caster is told what landed on them. TO_CLAN, TO_CLAN_AND_ALLY and TO_ALLY use the abilities.clan message; TO_ENEMY uses abilities.enemy. SELF sends nothing, because there is nobody else. Both are in messages.yml.

Hold effects

The same targeting, with no cost, no cooldown and no consumption — the price is holding the item instead of a weapon.

hold-effects:
  SUGAR:
    type: TO_CLAN
    radius: 20
    effects:
      - SPEED|2|5

Key	Default	What it does
`type`	`SELF`	The same five values as an ability.
`radius`	`0`	Blocks.
`effects`	none	Effect lines.

Every half second the plugin looks at the main hand of each player in a class with hold effects, and applies the matching entry's effects.

Give hold effects a long duration

The refresh is every ten ticks, so an effect written |5 is re-applied with four and a half seconds still on it and never blinks. A one-second duration would flicker, and the moment the player swaps items the effect runs out on its own — which is how a hold effect ends. Nothing removes it early.

The two together

The Bard ships with the same seven materials in both blocks: holding sugar gives the clan Speed II continuously, right-clicking it spends 35 energy for Speed III. That is the intended shape — a weak aura for free, a strong burst for a cost.

Something missing on this page? Tell us on Discord