Sequences
Choreographed effects written in configuration: every token, every shape, camera shots, and the parameters that move a display.
A sequence is choreography written as a list of strings — a ring of flame, a sound, a pause, an explosion, in that order. It is compiled once and played many times.
PluginSequences sequences = Sequences.of(this);
Sequence onKill = sequences.compile(config.getStringList("effects"), "ember_burst");
sequences.play(onKill, SequenceTarget.at(victim.getLocation()).by(killer));effects:
- '[CIRCLE] FLAME;radius:1.5;points:24'
- '[SOUND] ENTITY_BLAZE_DEATH;1.5;0.8'
- '[DELAY] 0.15'
- '[EXPLOSION]'Sequences or effects?#
| What you have | Use |
|---|---|
| One title, one sound, one particle, declared in a record | Effects |
| A list of things in order, with pauses, shapes and objects | this |
A menu's open sound is an EffectConfig. A hundred-line firework display is a Sequence.
The syntax#
Every line is a token in brackets, then a head, then parameters separated by ;:
- '[CIRCLE] NETHERITE_SWORD;as:item;radius:3;points:12;from:0,10,0;ease:in'(0,0,0) is the anchor the sequence was played at. Positive Y is up.
Tokens#
| Token | Arguments |
|---|---|
[DELAY] 0.15 | Seconds to wait before the next line, or written out: 1m30s. |
[PARTICLE] FLAME | count: offset:x,y,z speed: y: color: fade: size: block: — fade: is the colour a DUST_COLOR_TRANSITION fades to (white when absent). |
[SOUND] NAME;volume;pitch | Also volume: pitch:. A resource pack's own key works. |
[LIGHTNING] | volume: pitch: — flash, sparks and thunder. No strike, no fire, no damage. |
[EXPLOSION] | count: y: |
[FIREWORK] | color: fade: type: trail: flicker: power: — with PacketEvents it is a packet burst only the sequence's observers see; without it, a real rocket that deals no damage. |
[BLOCK_BREAK] STONE | count: offset: y: |
[POTION] speed;100;1 | Also duration: amplifier: particles: icon: ambient:. The duration is ticks (100 by default), or written out: 5s. |
[TITLE] title;subtitle;in;stay;out | Times in seconds (0.5, 3.5, 1 by default), or written out. who: as a last segment. |
[ACTION_BAR] text | who: as a last segment. |
[MESSAGE] text | A chat line. <center> works like anywhere else. who: as a last segment. |
[TOAST] icon;frame;text | An advancement toast — an item, TASK, GOAL or CHALLENGE, then the text. who: as a last segment. See Notices and toasts. |
[COMMAND] give {player} … | {player} {world} {x} {y} {z} |
[LID] open / [LID] close | Swings the lid of the chest, ender chest or shulker box at the anchor, for the observers only. y: shifts the block. |
[SHAKE] radius:10;times:2;every:0.08 | Tilts the camera of observers within radius blocks (10), the way taking a hit does — no damage, no sound. times: (1) tilts, every: (0.1 s) apart. |
[CAMERA] keys:0 close | 2 yaw=~360 | Shows the player their own animation from outside — see Camera shots. |
[DISPLAY] NETHERITE_SWORD | One display entity — see Displays and NPCs. |
[NPC] {victim} | A body where it happened — same page. |
[RAGDOLL] {victim} | That body coming apart into its pieces — same page. |
[FIREWORK], [EXPLOSION], [LIGHTNING], [SHAKE] and [CAMERA] name nothing positionally, so
their first segment is read as a parameter: [FIREWORK] color:red;fade:orange is red.
Who reads a text line
[TITLE], [ACTION_BAR], [MESSAGE] and [TOAST] take who: as the last ; segment, so a
semicolon inside the text stays text:
who: | Shown to |
|---|---|
source (default) | Whoever set the sequence off. |
target | Whoever it happened to, when that is a player. |
both | Both of them. |
nearby | The sequence's own observers: its radius and visibility rule. |
all | Every player online. |
- '[TITLE] {primary}JACKPOT;%reward%;0.2;3;0.5;who:nearby'Shapes#
Twenty-six, and every one of them can be drawn with particles or with displays:
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 PIXELS
| Shape | Its own 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 |
PIXELS | art word pixel pick depth |
CUBE says width and LINE says climb rather than size and rise, because on a display line
those two words already mean the model's own scale and where it ends up.
PIXELS draws a picture — heart heart_big broken_heart star crown skull bolt note
cloud trophy ufo moon guillotine blade grave portal eye clock rift flag — or
a word in a five-row block font, one piece per cell. pick: chooses which characters a line draws,
so a heart with a shine is two lines over one picture.
Every shape also takes y: scale: color: size: count: ticks: interval: rotate:
face:. ticks:1 draws the whole shape in one frame; anything higher draws it over time, which is
what makes a spiral look drawn rather than dropped. face:true turns the shape with whoever set it
off. SCATTER takes a seed, so its unplanned points are the same unplanned points every time.
One shape draws at most max-per-effect points (128 by default, in
plugins/ExyliaLib/displays.yml). A ring written with points:900 is cut there and the console says
so when the file is read, not as lag later.
color:{primary} follows colors.yml like everything else a player reads. #rrggbb and R,G,B
work too. A DUST particle with no colour is drawn white — visible and obviously wrong, rather than
silently invisible.
Drawn with something other than particles#
Any shape line becomes a shape of display entities by saying what it is made of:
- '[CIRCLE] NETHERITE_SWORD;as:item;radius:2.6;points:12;from:0,9,0;spin:2;axis:x;face_out:true'as: | The head of the line is |
|---|---|
item | An item name, NETHERITE_SWORD. |
block | A block name, or a full state like oak_stairs[facing=east]. |
head | A base64 texture, or {killer} / {victim} for a face. |
text | The line itself, in the usual formatting. |
The geometry, the animation, the rotation and who sees it are unchanged, because a shape never knew
what it was being drawn with. The movement parameters — life, from, to, ease, gravity,
spin, orbit, pull, size_to, roll, glow, light, follow and the rest — are in
Displays and NPCs.
Repeating a line on a beat#
repeat: and every: work on any line; a shape also takes turn_each:.
- '[CIRCLE] NETHERITE_SWORD;as:item;radius:3;points:6;repeat:5;every:0.1;turn_each:12'Five rings a tenth of a second apart, each twelve degrees further round — instead of five copies of a
line with four delays threaded between them. every: is 0.15 s when left out.
A repeated line also takes accel: and max_speed:: the gap is divided by accel: after every
beat and stops shortening at max_speed: times the original speed. That is how a sound keeps up with
a body that winds up.
One tempo per play
A [RAGDOLL] line with tempo:1-1.6 makes the whole play quicker or slower by a number rolled
once when the run starts. Every repeated line's gap is divided by that same tempo, so the sounds
keeping a dance's beat stay on it however the dance came out. SequenceRun.tempo() reads it back.
Custom shapes#
sequences.shape("heart", args -> {
List<Vector> points = new ArrayList<>();
double size = args.number("size", 1.0);
for (int i = 0; i < args.atLeastOne("points", 60); i++) {
double t = i / 60.0 * Math.PI * 2;
points.add(new Vector(size * Math.pow(Math.sin(t), 3),
size * (13 * Math.cos(t) - 5 * Math.cos(2 * t)) / 16, 0));
}
return points;
});A shape says where, never what. Colour, animation, rotation, scaling, as: and visibility
all come for free, which is why a new shape is a loop returning vectors rather than another copy of
the drawing code. It is called once, at compile time.
Camera shots#
A body that waves or dances is drawn for everybody around the player and for nobody inside it: the
one player it was made for is looking out of its eyes. [CAMERA] shows them the animation from
outside.
effects:
- '[CAMERA] keys:0 close | 2.4 yaw=~360 ease=in_out | 0.4 behind ease=out'
- '[SOUND] ENTITY_PLAYER_LEVELUP;0.7;1.4'keys: comes last because its value is full of spaces and bars. Frames are separated by |; each
starts with the seconds it takes to reach it and lists only what changes.
| Channel | What it moves |
|---|---|
distance= | How far the camera sits from the subject, in blocks (0.6–24). |
yaw= | Where it sits around them: 0 behind their back, 90 off their left shoulder, 180 facing them. |
pitch= | How far above the horizon it sits; positive looks down (±85). |
height= | What it aims at, in blocks above their feet. |
ease= | How the frame is reached: in_out (default), in, out, linear, back, anticipate, elastic, bounce, snap, smooth, hold. |
~90 adds to where the channel already is, so yaw=~360 is one more turn around them. A bare word
is a whole frame: behind, front, side, over, low, close, wide, top. smooth runs a
curve through the neighbouring frames instead of stopping at each. The camera always looks at the
subject; nothing in a shot says where it points.
| Parameter | |
|---|---|
who: | Whose eyes it takes: source (default), target or both. Never the audience — a line that took the eyes of everyone near a kill could not be written safely. |
loop:true | Plays the path again as it ends — for a body dancing on a loop. The path has to come back to where it started. |
The whole path is solved when the shot starts, from where the subject stands and which way they face, and walls pull the camera in rather than letting it render the inside of a block. While it plays the player is frozen and drawn as a spectator; both are undone at the end. A shot is at most 60 seconds and ends with the run that started it, or when the player leaves, dies or changes world. It is not protection: the player can still be hit, so a plugin that films somebody in the open cancels the run on damage. It needs PacketEvents.
In code, Cameras.of(this).play(player, CameraShot.parse(text, problem -> …)) plays the same shot
outside a sequence.
Played with SequenceTarget.of(player), a body drawn on the player faces the way they were looking,
so the body and the camera filming it agree.
Playing one#
SequenceRun run = sequences.play(sequence, SequenceTarget.at(location)
.by(killer)
.on(victim)
.within(20)
.visibleTo((observer, source) -> settings.seesEffects(observer)));
run.cancel();| On the target | What it sets |
|---|---|
at(location) / of(player) | The anchor. |
by(player) | Who caused it — what {killer}, face: and [COMMAND] read. |
on(entity) | Who it happened to — what {victim} reads. |
within(blocks) | How far it can be seen. 32 by default. |
onlyTo(player) | One viewer, which is how a preview is shown. |
visibleTo(predicate) | Who may perceive it, asked once per frame. |
values(values) / item(name, stack) | What this play fills in — see below. |
durationMillis() says how long a sequence lasts without playing it, animation included.
isEndless() is true for a sequence with a looping body or camera: it plays until its run is
cancelled.
Values known only when it plays#
What a crate rolled is not known when the file is read, so the target carries it:
sequences.play(reveal, SequenceTarget.at(crate.getLocation())
.by(opener)
.values(Values.of("reward", reward.displayName()).put("tier_color", "{highlight}"))
.item("reward", reward.icon()));- '[TITLE] {primary}&lYOU WON;%reward%;0.2;3;0.5'
- '[DISPLAY] {item:reward};from:0,0.5,0;to:0,1.6,0;life:3;ease:back_out;glow:%tier_color%'
- '[FIREWORK] color:%tier_color%;fade:#ffffff;type:star'%name% is filled in the text of [TITLE], [ACTION_BAR], [MESSAGE] and as:text lines, and in
color:, fade: and glow:. {item:name} as the head of an item line shows the stack the play
supplied; without it the line draws nothing. Everything else is still compiled once.
Effects that may or may not play#
A sequence says what happens. An EffectEntry says whether it happens, to whom and when:
EffectEntry crit = EffectEntry.of(List.of(
"[SOUND] ENTITY_PLAYER_ATTACK_CRIT;1;1.4",
"[PARTICLE] CRIT;count:20"))
.name("Critical hit")
.chance(25.0)
.condition("%player_level% >= 10")
.nearby(12.0)
.build();| Field | Means |
|---|---|
lines | What plays. |
name, icon | What an editor shows. |
chance | The percentage chance of playing at all. |
condition, permission | Who it may play for. |
priority | Higher plays first; equal priorities keep their written order. |
delayTicks | How long after the trigger this entry starts — the ones beside it still play on time. |
radius | 0 or less is the player it is about; a number is everyone within that many blocks; EffectEntry.WHOLE_WORLD is the whole world. |
Permission and condition run before the dice: who may see something does not depend on luck. Entries are compiled the first time they play and cached by their own lines, and a broken condition is reported once rather than once per play.
EffectCodec.encode / decode store them, and decode also reads ExyliaCommons rows, translating
their type into the line that plays the same thing.
Editing them in game#
sequences.editor(mine.breakEffects())
.title("{primary}&lBREAK EFFECTS")
.onSave(edited -> mines.save(mine, edited))
.open(player);Two levels of the editor screen: the entries, and inside one of them its lines as their own list. A line is added by picking what it plays, searching the server's own registry for which one, and filling in only the fields that token reads — a circle is asked for its radius, a pair of wings for its span. Blank fields are left out, so a line built by clicking is the same short line somebody would have written by hand.
The gating sits behind the WHEN IT PLAYS button, and both halves are saved or dropped together. A
token the library does not recognise is still drawn, still editable as text, and comes back exactly as
it was written.
Loose lines with no gating — a mob skill's impact lines — open the same lines screen on their own:
sequences.editLines(player, "{primary}&lIMPACT LINES", skill.effect())
.thenAccept(edited -> edited.ifPresent(lines -> save(skill.withEffect(lines))));Contracts#
| Compiled once | Names, numbers and trigonometry are resolved at compile time. Playing is arithmetic and packets. |
| A bad line costs its own line | It is reported through Debug naming the sequence; the rest still plays. |
| It never reaches the event | A kill effect cannot cancel a death. |
| Folia-correct | It runs on the thread that owns the location, through Tasks. |
| Instant sequences schedule nothing | No delays and no animation means it plays inline, in the calling tick. |
| Cancellable | play returns a SequenceRun; cancel() stops what has not run yet, camera shots included. |
| A run lets go when it is done | Once its last frame has run it is dropped, with its bodies and displays. |
| Nothing survives its plugin | Disabling a plugin cancels its runs before the scheduler is released. |
A renamed sound used to be handed on as a key that is not a key: nothing played and nothing said why. It now costs a console line naming the effect. A name with a dot or a colon in it is left alone, because a resource pack's own sound is legitimately not in the registry.
Previews#
PluginPreviews previews = Previews.of(this).using(() -> config.get().preview());
if (previews.available()) {
previews.show(player, sequence, () -> menu.open(player));
}Moves the player to a stage the server owner built, plays the sequence in front of them where only
they can see it, and puts them back exactly where they were — the callback runs however it ends. Until
a stage is set there is no preview: available() is false and show returns null without moving
anyone. An endless sequence is shown for six seconds, a few cycles of it, rather than forever.
PreviewSettings nests in the plugin's own config:
preview:
location: '' # server,world,x,y,z,yaw,pitch — empty means no previews
distance: 5.0 # how far in front of the player the effect plays
settle-ticks: 4 # wait after the teleport, so the client has the position
linger-ticks: 20 # how long to hold the stage after the effect ends
max-ticks: 600 # the safety netEach plugin gives its admins a setpreviewlocation command to fill location. Only the position is
used: a preview always faces north, so every effect is seen from the side it was drawn for —
build the room around that and leave the north side open. The player is held by flight, made
invulnerable and hidden from everyone else for the duration; their game mode is never changed.
sequences.preview(sequence, player) is the lighter form: it plays for that player alone, where they
stand, without a stage.
Something missing on this page? Tell us on Discord