Effects and sequences
Titles, action bars, boss bars, sounds, particles, fireworks and potion effects — declared by the owner, played by the plugin.
The plugin says what happened. The server owner decides what that looks like.
PluginEffects effects = Effects.of(this); // once, usually a field
effects.play(config.onWin(), player);Effects.of(plugin) stamps the owner on every display, so it ticks on that plugin's scheduler and
stops when that plugin disables. The static Effects.play(...) still works and works the owner out
when it can; when several plugins own effects and the caller cannot be identified, it asks for
Effects.of(plugin) instead of guessing.
EffectConfig#
Six optional sections that nest inside your own config record like any other. An unwritten section does nothing, and a section with nothing in it is not written to the file.
| Section | Keys |
|---|---|
title | text, subtitle, fade-in, stay, fade-out, time-style |
action-bar | text, duration, time-style |
boss-bar | text, colour, overlay, count-up, progress, time-style |
sound | name, volume, pitch, category |
particle | name, count, spread, speed |
firework | colours, fades, shape, flicker, trail |
combat-actionbar:
action-bar:
text: "{primary}⚔ {error}Combat {muted}%time_precise%"
duration: 0
time-style: tenthsTimes are seconds with decimals, and every time key also reads a duration written out:
stay: 1m30s is stay: 90. Titles default to no fade in (fade-in: 0, stay: 3, fade-out: 1): a
title reacting to something that just happened has to be on screen when it happens. Boss bars default
to PURPLE and PROGRESS; progress (0.0–1.0) is the fill when the bar is not counting.
It does not mean expire immediately. stay: 0 or duration: 0 keeps the title or bar up until
something stops it — what a combat tag driving its own remaining time wants.
The countdown belongs to the caller#
How long a timer runs is not a config key. A countdown is always the same number something else is already counting — the match, the warmup, the combat tag — so a key that could set it to anything else could only ever disagree with what is happening. The seconds come from the code, the look from the file:
effects.play(config.onCountdown(), player, matchSeconds); // a whole block, counting
Effects.title(text).countdown(matchSeconds).show(player); // or one display%time% and %time_precise% belong to the effect, never to the global placeholder registry: two
countdowns on screen must not show the same number.
| Placeholder | Reads as |
|---|---|
%time% | A bare number in the section's time-style: 3.3, 47, 1:35. |
%time_precise% | The same value with its unit, whatever the style says: 0.4s, 9.9s, 45s, 1m 30s. |
A text written %time%s reads 1:35s once the countdown passes a minute; %time_precise% is what new
defaults should use.
Teleport warmups#
A teleport does this for you: onStart(effect) counts over the warmup it was given, and whatever the
countdown put on screen — a boss bar, a title — is taken down the moment the teleport ends, arrived or
cancelled. onArrive and onCancel play after it.
One part, with values#
A plugin that keeps a single title or boss bar as its own config block plays it through the same path:
Display bar = effects.play(EffectConfig.of(config.resetBar()).filled(values), player, seconds);EffectConfig.of(Title | ActionBar | BossBar) is an effect holding only that part; filled(Values)
substitutes %name% into the text before it is parsed, so %time% and PlaceholderAPI still resolve.
A whole effect on one line#
Kit and class files often carry a sound or a particle in a single field, so callers do not have to split it themselves:
Effects.soundFrom("BLOCK_ANVIL_PLACE|1|1").show(player);
Effects.particleFrom("CLOUD|80|1.5|1.5|1.5|1.5").at(location).show(player);
Effects.particleFrom("FLAME|20|0.5").at(location).show(player); // one spread valueNAME|volume|pitch for sounds, NAME|count|dx|dy|dz|speed for particles, and a shorter
NAME|count|spread|speed is accepted too. Pipe is the only separator — a namespaced key like
minecraft:flame carries a colon that has to survive the split. Missing parts fall back to full
volume and pitch, count 1, no spread. A blank line plays nothing.
Builders#
Effects.title("{success}&lWIN").subtitle("{muted}%player%").show(player);
Effects.bossBar("{primary}Starting in {highlight}%time%").countdown(10).showAll();
Effects.firework().shape("BALL_LARGE").colour("#8a51c4").at(location).show();Fireworks the library sets off deal no damage.
Playing and stopping#
| Call | What it does |
|---|---|
effects.play(config, viewer) | Play it for one player, returning a Display. |
effects.play(config, viewer, seconds) | The same, counting over seconds. |
effects.playAll(config) | Every online viewer. |
Effects.stopFor(viewer) | Stop whatever is showing them. |
Effects.stopAll(pluginName) | Stop everything a plugin owns. |
A Display is the handle to everything one play put on screen: stop() takes every part of it down,
text(...) rewrites what a bar says without restarting it (the same text again is a no-op),
progress(float) sets the fill, addTime(seconds) extends it and onEnd(runnable) runs exactly once,
however it ends.
Timers#
Timer is the clock behind a timed effect — a value, not a task.
| Factory | What it is |
|---|---|
Timer.countdown(seconds) / countdownTicks(ticks) | Runs to zero. |
Timer.countUp() / countUp(total) | Elapsed-time displays. |
Timer.ofCooldown(player, key) | Reads a running cooldown instead of counting on its own. |
ofCooldown is the one worth knowing: the cooldown stays the truth — shared and persistent — and the
display just looks at it, finishing the moment the cooldown does. advance and extend do nothing on
such a timer; give the time through Cooldowns and the bar shows it.
Ticks converts: fromSeconds, toSeconds, fromMillis, toMillis, and parse(text, fallback)
understanding s, ms, t, m, h, d and w, combined as in 7d12h30m.
Time styles#
TimeFormats is what a time-style names, and what every duration in the ecosystem is written with:
| Style | Reads as | For |
|---|---|---|
auto | 3.3, 47, 1:35 | Tenths under ten seconds, whole seconds to a minute, a clock past that. The default. |
seconds | 3 | Whole seconds, rounded down. |
tenths / hundredths | 3.3 / 3.34 | A number a player is reacting to. |
clock | 1:35, 1:05:03 | Padded, past an hour. |
full | 1h 5m 3s, 5d | Every part, days downwards, for a duration read once. |
compact | 3d 4h, 59m 50s, 45s | The two largest units that say something, whole, up to years. |
precise | 0.4s, 9.9s, 45s, 1m 30s | compact with tenths under ten seconds, unit included. |
compact and precise round down: a countdown that rounds up tells a player they have time they
do not have, and compact never writes a decimal — 59m 50s, not 59.9m. A month is thirty days and
a year three hundred and sixty-five. full rolls into days, so a five-day cooldown reads 5d, not
120h. Decimals always use a dot, whatever the host's locale.
Potion effects#
A different Effects, in net.exylia.lib.util, applies potion effects written one per line:
Effects.apply(player, "SPEED|2|5"); // Speed II, 5 seconds
Effects.apply(player, "SPEED|2|5|false|false"); // the same, nothing on screen
Effects.applyInfinite(player, kit.passiveEffects()); // no end; the duration is ignored
Effects.remove(player, kit.passiveEffects());NAME|LEVEL|SECONDS|PARTICLES|ICON|AMBIENT:
| Part | Means |
|---|---|
LEVEL | As a player reads it — SPEED|2 is Speed II. Missing means I. |
SECONDS | infinite or -1 never ends. Missing means 10. Also reads 90s, 1m30s. |
PARTICLES, ICON, AMBIENT | true/false (or yes/no). Missing means what a potion normally does: particles and icon shown, not ambient. |
The same three flags are particles: icon: ambient: on a sequence's [POTION] line. A malformed
line is skipped, never fatal. clear(player) removes every effect — pair applyInfinite with
remove, not with clear, because the player's own potions are not yours to take.
Kept while inside#
Effects.ensureInfinite(player, zone.effects()); // on a timer while they stand there
Effects.removeInfinite(player, zone.effects()); // when they leaveensureInfinite applies only what is missing: milk, a death or a weaker potion took it away, and the
next check puts it back. An effect already there at the same level or higher is left alone and costs
no packet. removeInfinite removes only effects with no end, so a potion the player drank survives.
Kept through a totem#
A totem clears every effect — right for a potion, wrong for a kit buff the other side still has.
Effects.keepThroughTotem(this, player -> kits.effectsOf(player));
Effects.keepThroughTotem(this, "classes", player -> classes.passivesOf(player));The totem still clears everything; the next tick puts back the lines the rule names, at their written
level. Only effects the player had when the totem fired come back, never for longer than they had
left: milk that took a buff away is not undone, and a timed effect does not start over. One rule per
plugin, or per id for a plugin whose modules each keep their own; dropped when the plugin disables.
Lending effects for a while#
EffectSnapshot.of(player, List.of("SPEED", "STRENGTH")) holds those types, and restoreTo(player)
removes what is on now within that scope and puts back what was held — for a duel or arena that has to
hand back what the player came in with. EffectSnapshot.of(player) holds every type.
All of these touch the player, so call them from the thread that owns the player
(tasks.runAtEntity); parse is pure data and safe anywhere.
Sequences#
A sequence is choreography written in configuration — shapes, sounds, delays, display entities, bodies and camera shots, compiled once:
PluginSequences sequences = Sequences.of(this);
Sequence intro = sequences.compile(config.onCapture());
sequences.play(intro, SequenceTarget.at(location));Twenty-six shapes and every one drawable with particles or with display entities. Entries carry odds, conditions and an audience, so "one in five times, only if the player is crouching, seen by everyone within twenty blocks" is configuration rather than code. The whole syntax, the API, previews and the in-game editor are in Sequences.
Something missing on this page? Tell us on Discord