Content generated with AI — it may contain mistakes.

ExyliaHitEffect/How it worksUpdated in v1.6.1

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.

Page 9 of 219 min read
      - '[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' - '[CIRCLE] FLAME;radius:2.0;points:32;color:255,80,0'      # particles- '[CIRCLE] DEEPSLATE;as:block;radius:3.4;points:12'         # displays - '[CIRCLE] NETHERITE_SWORD;as:item;radius:2;points:6;repeat:3;every:0.2;turn_each:15' - '[NPC] {victim};pose:lying;life:2.2;equip:true;face:false'

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:

yaml
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.

A hit effect is not a kill effect

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.

WrittenDrawn with
as:itemAn item model.
as:blockA block model.
as:headA player head: a base64 texture, or {killer} / {victim} for a face.
as:textA line of text.
(nothing)The particle named at the head of the line.
yaml
- '[CIRCLE] FLAME;radius:2.0;points:32;color:255,80,0'      # particles
- '[CIRCLE] DEEPSLATE;as:block;radius:3.4;points:12'         # displays

Shapes#

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:

ShapeParameters
CIRCLE, SPHERE, DOMEradius points
BEAMheight points
SPIRALheight radius turns points
DOUBLE_HELIXheight radius turns points strands
TORNADOheight radius top_radius turns points
STARradius spikes inner points
CAGEradius height columns points
DISCradius rings points
VORTEXradius turns points
WAVElength amplitude frequency arms angle points
CROSSradius arms angle points
GALAXYradius turns arms points
TORUSradius tube segments tube_segments
BURSTradius beams angle points
PYRAMIDbase height points
RING_PULSEradius rings spacing points
WINGSspan arch depth dir points
ARCHradius arc dir points
CLAWradius claws spread curve dir drop points
CUBEwidth points edges
LINElength dir climb points
RIBBONradius points waves amplitude
SCATTERradius height points seed floor

What every shape understands

y scale color size count ticks interval face rotate

ParameterWhat it does
yLifts the whole shape. SPHERE and TORUS sit a block up by default; everything else at zero.
scaleGrows or shrinks the geometry itself.
ticks1 draws the whole shape in one frame; higher spreads it over time, so a spiral looks drawn rather than dropped.
intervalSeconds between those frames. Defaults to 0.05.
rotateTurns the whole shape, in degrees.
faceTurns it to face whoever landed the hit.
color, size, countParticle 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:.

ParameterWhat it does
lifeSeconds it exists.
from:x,y,zWhere it starts, relative to its point.
to:x,y,zWhere it ends. rise: is shorthand for a vertical to.
easein, out or in_out. ease:in aims a slam.
gravityDebris only. It is added to the movement rather than replacing it.
spinTurns, or x,y,z to tumble. axis picks the one axis.
orbitTurns carried around the anchor.
pull1 reaches the centre; a negative number throws it outwards.
sizeOne number, or x,y,z for a plate, a pillar or a blade.
size_toThe size it ends at.
varyHow much individual pieces differ from one another.
roll, tilt, turnFixed rotation in degrees.
face_outFaces away from the centre.
glowAn outline colour.
light0 to 15. Use light:15 for anything that must read at night.
model, billboard, holdThe display's own model, billboard mode and how long it is held.
Three rules that save an afternoon

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:

yaml
- '[CIRCLE] NETHERITE_SWORD;as:item;radius:2;points:6;repeat:3;every:0.2;turn_each:15'
ParameterWhat it does
repeatHow many times the line plays.
everySeconds between plays. Defaults to 0.15.
turn_eachDegrees added each time, so the copies fan out.

The other tokens#

TokenParameters
[DELAY] 0.15Seconds to wait before the next line.
[PARTICLE] FLAMEcount speed y color size offset:x,y,z block
[SOUND] NAME;volume;pitchAlso 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] STONEcount: y: offset:
[POTION] speed;100;1Also duration: amplifier:
[TITLE] title;subtitle;in;stay;outTimes in seconds.
[ACTION_BAR] text
[MESSAGE] textA chat line.
[COMMAND] give {player} …{player} {world} {x} {y} {z}
[NPC] {victim}The body, below.

[NPC] — a body#

yaml
- '[NPC] {victim};pose:lying;life:2.2;equip:true;face:false'
ParameterWhat 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.
poselying by default. pose_to with after collapses into a second pose.
lifeSeconds it stays. Defaults to 5.
equipWhether it wears what the victim wore. On by default.
faceWhether it turns to face. On by default.
from, to, over, ease, gravity, turnHow it is thrown or how it falls. over defaults to 0.7 seconds.
glowAn outline colour.
hurtPlays the damage flash.
yLifts it.
spinDegrees a second it keeps turning, for its whole life — turn finishes, spin never does.
bob, bob_everyBlocks it rises and falls on a loop, and how long one rise and fall takes.
swingSeconds between arm swings.
scaleHow big it is drawn, 1 being player-sized. Needs a 1.20.5 client.
hold, offhandA material put in each hand.
pitchHead 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.

Cost is per line, per hit — not per kill

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