Sparks
Your own tags. Write a color, prefix, number or line once, then use it anywhere on the server.
Sparks are your own tags. Define your colors, prefix and common lines once, then use them in any plugin's config with <spark:name>. Change a spark later, and every message using it changes with it.
Where they live
Sparks live in plugins/Lightning/sparks/. Every top-level key in every file there becomes a spark, named after the key.
accent:
color: "#FFB347"
prefix:
text: "<spark:accent>DenizenMC</spark> <dark_gray>»</dark_gray>"Names can use letters, numbers, dots, dashes and underscores. Dots are handy for grouping, like ess.text and ess.accent for one plugin's palette. They're part of the name, never nesting.
Same name in two files
If two files define the same spark name, the first one loaded wins and the console tells you about the clash.
Run /lightning reload after editing, and /lightning sparks to see everything that loaded.
The eight kinds
A plain string, or text:. Read as MiniMessage when used.
divider: "<dark_gray><st> </st></dark_gray>"
prefix:
text: "<spark:name> <dark_gray>»</dark_gray>"Values
Any spark can take values after its name. They fill in wherever {0}, {1} and so on appear:
coins:
text: "<yellow>{0} ⛁</yellow>"<spark:coins:250> shows 250 ⛁. Values work in every kind of spark.
Sparks and placeholders
There are two ways to bring PlaceholderAPI into a spark, and each suits a different job.
Pass a placeholder as a value when the spark is a reusable shape and the number changes each time:
balance-line: "You have <spark:coins:'%vault_eco_balance%'>"
price-line: "This costs <spark:coins:'%shop_item_price%'>"Write the placeholder into the spark itself when it always means the same thing:
balance:
formula: "%vault_eco_balance%"
format: compactNow <spark:balance> works anywhere, and every player sees their own balance. This is the cleaner choice for things you show in many places, like balance, playtime or ping.
Quote placeholders you pass in
Wrap a placeholder in single quotes when passing it as a value, like <spark:coins:'%vault_eco_balance%'>. An answer containing : or > would otherwise break the tag.
Placeholders fill in before sparks run, so formulas get the real number. They always fill in for whoever is reading, so the result is never shared between players.
Number formats
format decides how a formula or scale result looks:
| Format | 1520000 becomes | Good for |
|---|---|---|
#,##0 | 1,520,000 | Money, counts |
#,##0.00 | 1,520,000.00 | Prices |
0.# | 1520000 | Ratios, one decimal at most |
compact | 1.5M | Balances, kills, blocks mined |
duration | 17d 14h (the number is read as seconds) | Playtime, cooldowns, uptime |
The pattern formats follow Java's DecimalFormat, so anything it supports works here.
Examples
| Goal | Spark |
|---|---|
Balance as 1.5M | formula: "%vault_eco_balance%", format: compact |
Playtime as 5h 12m | formula: "%statistic_time_played% / 20", format: duration |
| Health as a percent | formula: "%player_health% / 20 * 100", format: "0" |
| Sale price | formula: "{0} * 0.8", format: "#,##0.00" |
| Any plugin's seconds as readable time | formula: "{0}", format: duration |
| TPS in traffic-light colors | A scale on %server_tps_1%: red below 15, yellow below 19, green above |
A kill/death ratio, ready to copy:
kdr:
formula: "{0} / ({1} + 1)"
format: "0.00"Use it as <spark:kdr:'%statistic_player_kills%':'%statistic_deaths%'>. The + 1 stops a player with zero deaths from dividing by zero.
Sparks inside sparks
Sparks can use other sparks. Lightning stops after 64 sparks in one piece of text, so two sparks pointing at each other can never freeze anything.
Pulse
Cycles and <clock> change over time, but a line on screen only changes when it's sent again. Lots of scoreboard and tab plugins send a line once and then leave it alone, so a cycle in it would be stuck on its first frame.
Pulse fixes that. Whenever Lightning charges a line holding a cycle or clock, it remembers it, charges it again every pulse interval, and only sends the player a fresh copy if the result actually changed.
| Surface | What Pulse keeps moving |
|---|---|
tablist | Header and footer |
scoreboards | Sidebar title, team prefixes, suffixes and names, score lines |
bossbars | Boss bar titles |
entities | Holograms, text displays, name tags |
Chat, titles and action bars don't need it, since they're gone in a moment anyway.
Out of the way by design
Pulse runs off the main thread, never touches the server tick, and sends nothing while nothing changes. When a plugin removes a line, Pulse forgets it right away, so it can never bring a removed line back. Set pulse to 500ms for snappier clocks, or 0 to turn it off.
Last updated on
