Effects and sequences

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

Effects.play(config.onWin(), player);

EffectConfig

Six optional sections that nest inside your own config record like any other. An unwritten section does nothing.

combat-actionbar:
  action-bar:
    text: "{primary}⚔ {error}Combat {muted}%time%s"
    duration: 0
    countdown: 0
    time-style: tenths

Times are seconds with decimals — countdown: 3.3 is 3.3 real seconds. %time% belongs to the effect, never to the global placeholder registry: two countdowns on screen must not show the same number. time-style is a TimeFormats style name — auto, tenths, clock.

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

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").colours("#8a51c4").at(location).show();

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

A teleport already does this for you: onStart(effect) counts over the warmup it was given.

Times are seconds with decimals: countdown(3.3) is 3.3 real seconds and %time% shows 3.3. %time% belongs to the effect, never to the global registry — two countdowns on screen must not show the same number. timeStyle is a TimeFormats style name: auto, tenths, clock and the rest.

Timers

Timer is the clock behind a timed effect — a value, not a task.

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 and h suffixes.

Time styles

TimeFormats is what a timeStyle names, and what every duration in the ecosystem is written with:

FULL rolls into days rather than counting hours forever, so a five-day cooldown reads 5d and not 120h. COMPACT goes further — a month is thirty days and a year three hundred and sixty-five, which is the point: 2mo ago is not claiming to know which months. Everything these styles write, duration() input reads back: 30s, 1h30m, 2d, 1w, 2.5h.

Playing and stopping

A Display is the handle: text(...) rewrites what a bar says without restarting it, and stop() takes it down.

Sequences

A sequence is choreography written in configuration — shapes, sounds, delays, display entities and bodies, compiled once:

PluginSequences sequences = Sequences.of(this);
Sequence intro = sequences.compile(config.onCapture());
 
sequences.play(intro, SequenceTarget.at(location));

Twenty-five shapes, thirteen other tokens, and every shape drawable with particles or with display entities that move, spin and fall by themselves. 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 and the in-game editor are in Sequences.

Previews

Showing one player an effect against an empty sky and putting them back afterwards:

Previews.of(this).show(player, sequence);

It is what an editor uses so somebody choosing a kill effect can see it before saving, without firing it into a live arena.