Content generated with AI — it may contain mistakes.

ExyliaLib/Visuals

Effects and sequences

Titles, action bars, boss bars, sounds, particles, fireworks and potion effects — declared by the owner, played by the plugin.

Page 30 of 548 min read

The plugin says what happened. The server owner decides what that looks like.

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

SectionKeys
titletext, subtitle, fade-in, stay, fade-out, time-style
action-bartext, duration, time-style
boss-bartext, colour, overlay, count-up, progress, time-style
soundname, volume, pitch, category
particlename, count, spread, speed
fireworkcolours, fades, shape, flicker, trail
yaml
combat-actionbar:
  action-bar:
    text: "{primary}⚔ {error}Combat {muted}%time_precise%"
    duration: 0
    time-style: tenths

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

A duration of zero means stay

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:

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

PlaceholderReads 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:

java
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:

java
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 value

NAME|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#

java
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#

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

FactoryWhat 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:

StyleReads asFor
auto3.3, 47, 1:35Tenths under ten seconds, whole seconds to a minute, a clock past that. The default.
seconds3Whole seconds, rounded down.
tenths / hundredths3.3 / 3.34A number a player is reacting to.
clock1:35, 1:05:03Padded, past an hour.
full1h 5m 3s, 5dEvery part, days downwards, for a duration read once.
compact3d 4h, 59m 50s, 45sThe two largest units that say something, whole, up to years.
precise0.4s, 9.9s, 45s, 1m 30scompact 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:

java
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:

PartMeans
LEVELAs a player reads it — SPEED|2 is Speed II. Missing means I.
SECONDSinfinite or -1 never ends. Missing means 10. Also reads 90s, 1m30s.
PARTICLES, ICON, AMBIENTtrue/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#

java
Effects.ensureInfinite(player, zone.effects());   // on a timer while they stand there
Effects.removeInfinite(player, zone.effects());   // when they leave

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

java
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:

java
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