Action language

An ability is a list of steps under actions:, run top to bottom. Each step names an action and takes keys of its own:

actions:
  - action: target_radius
    radius: 6
  - action: require
    check: '%targets_found% >= 1'
    message: '${text.no_target}'
  - action: damage
    damage: 4
  - action: play
    at: targets
    effects:
      - '[SOUND] ENTITY_PLAYER_HURT;1;1'

Keys every step takes

A step may also name another plugin's ExyliaLib action by its full id. condition, permission and chance are only applied to this plugin's own steps.

Numbers and variables

Number keys accept placeholders and formulas: '%stacks%', '${radius} * 2'. Steps leave variables the next ones can read:

Targets and the anchor

A chain works on a target list and an anchor point.

• The target list starts as the hit player or entity (on HIT_PLAYER, HIT_ENTITY, PROJECTILE_HIT), the attacker (on TAKE_DAMAGE), or the user. Targeting steps replace it.
• The anchor starts where the projectile landed or the block that was clicked or broken, otherwise the user's position.

A player can be picked as a target only when they are not in spectator, the user can see them and they are not vanished, and WorldGuard allows PvP both where they stand and where the user stands. Mobs are always eligible.

target_self

The user.

target_victim

The hit player or entity, or the attacker on TAKE_DAMAGE. Empty if they are not eligible.

target_attacker

target_clear

Empties the list.

target_radius

Only entities in line of sight are taken.

target_look

Takes the entity the user looks at and moves the anchor to it. On a miss the anchor goes to the block hit, or to the end of the ray.

target_chain

From the current target, jumps to the nearest visible eligible entity not yet chained, again and again. Sets %chain_length%.

anchor

Combat

damage

Damage dealt by this step does not fire the item's own hit triggers again.

heal

amount (0) half hearts, or percent-of-max-health (0).

ignite

seconds (3). A longer fire already burning is kept.

Movement

push and pull

launch

up (1) and forward (0, along the target's facing).

teleport

Facing is kept. forward and to_source do not check WorldGuard.

Effects and states

potion_effect

- action: potion_effect
  potions:
    - 'SPEED|2|10'                 # Speed II for 10 seconds
    - 'STRENGTH|%stacks%|4|false'  # level from a variable, no particles

NAME|LEVEL|SECONDS|PARTICLES|ICON|AMBIENT. The level is the one players read (2 = II; 0 is I too). Seconds default to 10; infinite or -1 never ends; lengths like 1m30s work. Applies to mobs as well.

clear_effects

potions: a list of effect names. Empty clears every effect.

flag and unflag

- action: flag
  flag: NO_BUILD
  seconds: 10
  only: [COBWEB]

unflag takes flag and removes it. Both act on players only.

Items and inventory

repair

percent (1 = full) of each piece's damage, on armor (true) and the main hand (true). Sets %repaired%: the bundled Repair follows it with a require on %repaired% >= 1, so a use with nothing damaged is refunded.

refill

Two forms:

- action: refill        # fill empty slots with one item
  fill:
    material: POTION
    potion: {base_type: HEALING, upgraded: true}
  slots: inventory      # inventory | hotbar
  max: 0                # 0 = every empty slot
- action: refill        # top up to an amount
  items:
    - 'ENDER_PEARL|8'
    - 'GOLDEN_APPLE|8'

Both set %filled%. The first fills empty slots. The second gives what is missing to reach each amount (16 when omitted); what does not fit is not given.

give

item — a special item id or a material — and amount (1).

cooldown

Acts on the targets' cooldowns.

inventory

Acts on target players other than the user.

damage_armor

amount per piece, or when 0 percent (0.25) of each piece's durability, at least 1. break (true): a piece may break; false stops at 1 durability left.

World

blocks

- action: blocks
  mode: set
  material: IRON_BARS
  shape: wall
  radius: 2
  height: 4
  distance: 2
  seconds: 8

Placed blocks respect WorldGuard and other plugins' build checks, drop nothing, resist explosions and pistons, and are put back if the server stops first.

clear sets %cleared% and removes for good, with no drops, every block of materials in a sphere, block by block through the break checks. Without materials it removes a built-in debris list: cobblestone, stone, deepslate, dirt, gravel, sand, netherrack, end stone, obsidian, glass, ice, snow, cobweb, scaffolding, ladders, planks, magma, slime, honey and powder snow. That list includes natural terrain — write materials when that is not what you want.

projectile

A visual: it runs no steps when it lands.

Feedback

play

effects: — ExyliaLib effect lines ([SOUND], [PARTICLE], [CIRCLE], [RING_PULSE], [DISPLAY], [LIGHTNING], [DELAY]...). at: self (heard around the user), targets, anchor or only_self (only the user sees and hears it). radius: how far it is seen. follow: true makes the effect move with the player it is played on (each target, or the user), so a lingering cue stays on them.

bar

- action: bar
  seconds: 5
  until-potion: BLINDNESS
  victim:
    text: '${text.blinded_bar}'
    colour: YELLOW
  self:
    text: '${text.flashed_bar}'

A live boss bar for as long as the effect lasts. victim is shown to every player target, self to the user. With no targets, only self opens, as a bar the user alone sees.

A bar closes early when every target it names dies or leaves, or the user leaves.

unbar

Closes the bar of id (the item's id by default) for the user and the current targets.

flash

Blacks out each player target's screen at once (the end credits screen, closed with Escape). Purely visual: the Flashbang uses it.

message

text and to: self, targets or both. %player% is the user. With both a user who is also a target receives it twice.

command

command (%player% replaced), as console (default) or player, for self (default) or targets.

Flow

require

Stops the chain — and gives back the use and cooldown — unless every key it carries holds:

message is sent when it stops.

set_var

name, and value (a formula) or text.

stack

- action: stack
  id: fury
  add: 1
  max: 5
  seconds: 4

A counter on the user that decays: add (1), up to max (0 = no cap), forgotten seconds (0 = never) after the last add, reset to clear. Sets %stacks%, %stack_level% (stacks − 1) and %stack_full%. Cleared on death and quit.

repeat

times (1), every (10 ticks) and its own actions: list. The first pass runs at once, the rest on the timer; the steps after repeat do not wait for it.

stop

Ends the chain and gives back the use and cooldown.

Summons

- action: summon
  seconds: '${duration}'
  max-alive: 1
  body: {type: MANNEQUIN, fallback: ALLAY, name: '%owner%''s Bard', health: 20}
  move: {mode: FOLLOW, distance: 3}
  aura:
    every: 1
    range: 20
    potions: ['STRENGTH|3|3']

body:

Without a body section the summon is a decoy that is invulnerable and wears the owner's gear. With one, invulnerable defaults to false and equipment to NONE unless written.

move: mode STAY, FOLLOW (distance 3) or WANDER (radius 6, a new spot every every 4 seconds).

aura: every every (1) seconds, when the owner is within range (12), gives the owner potions and plays effects.

turret (not on decoys): shoots projectile (SNOWBALL) at speed 1.8 every every (1) seconds at the nearest enemy player in range (14) — survival or adventure, visible, PvP allowed — and at monsters with target-mobs: true. Each shot deals damage (3) with knockback (0.4) and plays trail, effects and impact.

effects: spawn, end and swap lines.

Summons vanish when their owner dies, changes world or leaves, and when the plugin stops. Mobs do not target the owner. Sets %summons%.

duel

Starts a duel between the user and the first target that is another player — so it follows a hit trigger or a targeting step.

The other player does not accept: they are taken. If the duel cannot start — no opponent, either player busy, no free arena — the chain stops and nothing is spent. See Duels.