Write your own effect steps
Add a hit effect of your own: the step syntax, the shapes, how to move a display and the budget to stay within.
A hit effect is a list of steps played in order on whoever was hit. Here you write a small one, try it and keep it inside the budget.
Before you start#
You need a preview stage so you can watch it: see Your first hit effect. The effect lives in your catalogue, see Edit the effect catalogue. The step syntax is the one shared by every Exylia plugin, documented in full in Sequences.
Steps#
Add the entry
In lang/<code>/effects.yml, add a new key under hit_effects with a category that exists, then an effects list.
Write the steps
Each step is a token in brackets, what it is drawn with, then parameters separated by ;. For example a sound and a ring of gold:
effects:
- '[SOUND] ENTITY_PLAYER_ATTACK_CRIT;0.7;1.4'
- '[CIRCLE] GOLD_BLOCK;as:block;radius:0.6;points:8;size:0.14;life:0.3;light:15'(0,0,0) is a block above the victim, so the effect lands on the body, and positive Y is up.
Reload and look
Run /hiteffectsadmin reload, then /hiteffect preview <id>. It plays on the preview stage and puts you back.
Grant it
Give exyliahiteffect.effect.<id in lowercase> or its category, see Permissions.
Check that it works#
The preview plays the sound and the shape in about a third of a second. A step that cannot be read is dropped and written to the console with the line that caused it (an unknown token, a particle that does not exist, a shape with no points, a parameter the token does not understand). The rest of the effect still plays, so one typo costs one line.
Going further#
Stay inside the budget#
A display is cheap to animate, but every line is a packet per viewer on every blow of every fight. The shipped effects are two to five lines and under six tenths of a second. Aim for ten displays at most, quiet, about a block wide.
The same syntax draws both, and it is tempting to paste a ten-second production. On a busy arena that plays on every blow, for every player, on every client in range.
Displays or particles#
A shape line draws displays when it carries as: (item, block, head or text) and particles when it does not. Moving a display is done with life, from, to, ease, spin, pull and size_to, and repeat, every and turn_each repeat any line. The tables below list them all.
Technical details
Displays or particles#
A shape line draws displays when it carries as:, and particles when it does not.
| Written | Drawn with |
|---|---|
as:item | An item model. |
as:block | A block model. |
as:head | A player head: a base64 texture, or {killer} / {victim} for a face. |
as:text | A line of text. |
| (nothing) | The particle named at the head of the line. |
- '[CIRCLE] FLAME;radius:2.0;points:32;color:255,80,0' # particles
- '[CIRCLE] DEEPSLATE;as:block;radius:3.4;points:12' # displaysShapes#
ExyliaLib's sequence engine draws 26 shapes, PIXELS being the one not detailed here (see Sequences). [DISPLAY] is a token of its own, not a shape.
CIRCLE SPHERE DOME CUBE LINE RIBBON SCATTER BEAM SPIRAL DOUBLE_HELIX TORNADO
STAR CAGE DISC VORTEX WAVE CROSS GALAXY TORUS BURST PYRAMID RING_PULSE WINGS
ARCH CLAW
Each has its own parameters:
| Shape | Parameters |
|---|---|
CIRCLE, SPHERE, DOME | radius points |
BEAM | height points |
SPIRAL | height radius turns points |
DOUBLE_HELIX | height radius turns points strands |
TORNADO | height radius top_radius turns points |
STAR | radius spikes inner points |
CAGE | radius height columns points |
DISC | radius rings points |
VORTEX | radius turns points |
WAVE | length amplitude frequency arms angle points |
CROSS | radius arms angle points |
GALAXY | radius turns arms points |
TORUS | radius tube segments tube_segments |
BURST | radius beams angle points |
PYRAMID | base height points |
RING_PULSE | radius rings spacing points |
WINGS | span arch depth dir points |
ARCH | radius arc dir points |
CLAW | radius claws spread curve dir drop points |
CUBE | width points edges |
LINE | length dir climb points |
RIBBON | radius points waves amplitude |
SCATTER | radius height points seed floor |
What every shape understands
y scale color size count ticks interval face rotate
| Parameter | What it does |
|---|---|
y | Lifts the whole shape. SPHERE and TORUS sit a block up by default; everything else at zero. |
scale | Grows or shrinks the geometry itself. |
ticks | 1 draws the whole shape in one frame; higher spreads it over time, so a spiral looks drawn rather than dropped. |
interval | Seconds between those frames. Defaults to 0.05. |
rotate | Turns the whole shape, in degrees. |
face | Turns it to face whoever landed the hit. |
color, size, count | Particle lines only: DUST takes color:255,80,0, size is the dot, count the particles per point. |
Moving a display#
Everything below works on any shape drawn with as:.
| Parameter | What it does |
|---|---|
life | Seconds it exists. |
from:x,y,z | Where it starts, relative to its point. |
to:x,y,z | Where it ends. rise: is shorthand for a vertical to. |
ease | in, out or in_out. ease:in aims a slam. |
gravity | Debris only. It is added to the movement rather than replacing it. |
spin | Turns, or x,y,z to tumble. axis picks the one axis. |
orbit | Turns carried around the anchor. |
pull | 1 reaches the centre; a negative number throws it outwards. |
size | One number, or x,y,z for a plate, a pillar or a blade. |
size_to | The size it ends at. |
vary | How much individual pieces differ from one another. |
roll, tilt, turn | Fixed rotation in degrees. |
face_out | Faces away from the centre. |
glow | An outline colour. |
light | 0 to 15. Use light:15 for anything that must read at night. |
model, billboard, hold | The display's own model, billboard mode and how long it is held. |
ease:in aims a slam and ease:out settles one. gravity: adds to a movement that already
descends, so a fall of eight blocks plus gravity goes through the floor — half of gravity times the
life squared is how far it drops. And roll: aims a blade, not tilt:: an item model is a flat plate
facing south with its tip up and to the right, so roll:135 points it down.
Repeating a line#
repeat every turn_each work on any step — a sound, a shape, a ring of blades:
- '[CIRCLE] NETHERITE_SWORD;as:item;radius:2;points:6;repeat:3;every:0.2;turn_each:15'| Parameter | What it does |
|---|---|
repeat | How many times the line plays. |
every | Seconds between plays. Defaults to 0.15. |
turn_each | Degrees added each time, so the copies fan out. |
The other tokens#
| Token | Parameters |
|---|---|
[DELAY] 0.15 | Seconds to wait before the next line. |
[PARTICLE] FLAME | count speed y color size offset:x,y,z block |
[SOUND] NAME;volume;pitch | Also volume: pitch: |
[LIGHTNING] | volume: pitch: — flash, sparks and thunder. No strike, no fire, no damage. |
[EXPLOSION] | count: y: |
[FIREWORK] | color: fade: type: trail: flicker: power: |
[BLOCK_BREAK] STONE | count: y: offset: |
[POTION] speed;100;1 | Also duration: amplifier: |
[TITLE] title;subtitle;in;stay;out | Times in seconds. |
[ACTION_BAR] text | |
[MESSAGE] text | A chat line. |
[COMMAND] give {player} … | {player} {world} {x} {y} {z} |
[NPC] {victim} | The body, below. |
[NPC] — a body#
- '[NPC] {victim};pose:lying;life:2.2;equip:true;face:false'| Parameter | What it does |
|---|---|
| (the head) | {victim}, {killer}, or a base64 texture. A player name is refused: it would need a lookup an effect cannot wait for. |
pose | lying by default. pose_to with after collapses into a second pose. |
life | Seconds it stays. Defaults to 5. |
equip | Whether it wears what the victim wore. On by default. |
face | Whether it turns to face. On by default. |
from, to, over, ease, gravity, turn | How it is thrown or how it falls. over defaults to 0.7 seconds. |
glow | An outline colour. |
hurt | Plays the damage flash. |
y | Lifts it. |
spin | Degrees a second it keeps turning, for its whole life — turn finishes, spin never does. |
bob, bob_every | Blocks it rises and falls on a loop, and how long one rise and fall takes. |
swing | Seconds between arm swings. |
scale | How big it is drawn, 1 being player-sized. Needs a 1.20.5 client. |
hold, offhand | A material put in each hand. |
pitch | Head pitch in degrees, negative being up. |
It is a display, not an entity: nothing can hit it, loot it or walk into it. None of the shipped hit effects uses it — a body left behind on every blow is a kill effect, not a hit effect — but the step is there if you want one.
When a line is wrong#
A step that cannot be read is dropped and reported to the console with the line that caused it — an unknown token, a particle that does not exist, a shape that produced no points, a parameter the token does not understand. The rest of the effect still plays, so one typo costs one line rather than the whole catalogue.
A display is cheap to animate — the client does it — but every line is still a packet per viewer, on every blow of every fight. The shipped effects are two to five lines and under six tenths of a second; that is the budget, not a coincidence.
Something missing on this page? Tell us on Discord