Content generated with AI — it may contain mistakes.

ExyliaLib/Visuals

Sidebars, holograms, nametags and borders

Everything drawn on a player's screen, sent as packets and declared in configuration.

Page 36 of 546 min read

Modules with one thing in common: none of them creates real server state. No scoreboard team, no armour stand, no entity to leak, no change to the world's own border.

java
Scoreboards.show(this, player, config.ffa());

SidebarConfig nests in your own config record, so the sidebar lives in the owner's file:

yaml
scoreboard:
  enabled: true
  title:
    - "{primary}&lFFA"
  lines:
    - " {muted}❙ {letters}Kills: {success}%kills%"
    - " {muted}❙ {letters}KDR: {highlight}%kdr%"
  update:
    interval: 15
    smart: true
KeyWhat it does
enabledShow it at all — a section can stay written but off.
titleA list. Several entries animate: each refresh shows the next.
linesTop first. At most 15; extra lines are dropped.
update.intervalTicks between refreshes (20 by default). Also reads 1s.
update.smartSend only the lines that changed instead of the whole board.

Scoreboards.show returns a Board: refresh(), updateData(map), stop(), stopped(). Scoreboards.hide(player), get(player) and has(player) work from outside. Boards stack per player — showing one pauses the previous, and closing it brings the previous back. That is what lets an event's sidebar cover a hub's without either plugin knowing about the other.

A line that expands

A placeholder returning text with line breaks becomes several lines. It is how one %objectives% value can draw three rows without the file knowing how many there will be.

Other sidebars on the server

A visible board takes the sidebar slot back every three seconds, and at once after a teleport, a world change, a respawn or a join, so another plugin claiming it does not leave the player without ours. When TAB is installed it is asked to stand down instead: the first board shown to a player turns TAB's sidebar off for that player, and the last one taken down — or the player leaving — turns it back on. Only a player whose TAB sidebar was visible is touched.

Card layout and steady width#

Since 1.541.0 a board follows the parts of an item card: one tone, an optional dark subtitle, sections and stats, with no action lines. The title carries no icon; {icon:...} draws in lines (below 1.21.9 its glyph stands in). A client shows at most 15 lines.

yaml
title: '{primary}&lDUEL'
lines:
  - '{letters_black}Duel · %exyliaduels_mode%'
  - ''
  - '{primary}⚔ Opponent'
  - '  {letters_black}· {highlight}{icon:kills} {letters}Name{letters_black}: {highlight}%exyliaduels_opponent%'
  - ''
  - '{muted}{server-ip}'

Since 1.580.0 a sidebar no longer jumps when a value changes length: it is never narrower than its widest line with every placeholder left out, a longer value widens it at once and it narrows only after 10 seconds shorter (held by padding the first blank line). Start a line with <center> to centre it within that width.

Holograms#

java
Holograms.show(this, "trophy", location, config.trophy());
KeyWhat it does
enabledShow it at all.
typeTEXT, ITEM or BLOCK.
linesThe text, for TEXT. A line can start with tags that style it alone.
item / blockWhat floats, for the other two.
per-playerEvery viewer gets their own copy, so placeholders can differ per player.
view-distancePast this, nothing is sent.
offset-x/y/zWhere it sits relative to the location given.
propertiesHow it is drawn: billboard, scale, background and the rest.
config.update-intervalTicks between re-renders of the text.
click, pages, page-intervalWhat clicking it runs, and further pages each viewer turns through.

They are display-entity packets. Nothing exists server-side, so a hologram cannot be pushed by a piston, killed by a mob, or left behind when the plugin crashes.

Holograms.get(plugin, id), all(plugin), remove(plugin, id) and removeAll(plugin) manage them by id. isSupported() answers honestly when PacketEvents is absent. Line tags, clicks and pages are in Holograms.

Nametags#

java
PluginNametags tags = Nametags.of(this);
 
tags.paint(viewer, target, style);                 // how one player sees another
tags.paintEachOther(team, style);                  // a whole team, mutually
tags.reset(viewer, target);
tags.resetEverywhere(target);

The whole point is per viewer, not per player: the same player can be red to one person and blue to another, which is what a team game needs and what a scoreboard team cannot do without fighting every other plugin for the same team name.

NametagStyle.of(colour) sets the name colour; withGlow() outlines the player through walls, withCollision() lets them be pushed, and showingInvisible() draws them faintly while invisible. Vanilla clients are included — this is not a client mod feature.

Without PacketEvents, Nametags.isSupported() is false and every call does nothing rather than throwing.

World borders only some players see#

A border per arena, per match or per zone, in the same world, each with its own edge and clock:

java
VirtualBorder zone = Packets.of(this).worldBorders().create(arena.center(), 200);
match.players().forEach(zone::show);
zone.size(20, Duration.ofMinutes(2));
On a VirtualBorderWhat it does
show(viewer) / hide(viewer)Replaces the border they see, or gives them the world's own back.
size(size) / size(size, over)Resizes it; a timed resize is one packet and each client animates it.
center(x, z)Moves it.
warning(blocks, seconds)When the screen turns red. Vanilla's 5 blocks or 15 seconds by default.
damage(perBlock, buffer)Damage outside it. Vanilla's 0.2 per block past 5 by default; zero hurts nobody.
contains(location), size(), viewers()Reads, mid-resize included.
remove()Hides it from everyone.

worldBorders().seenBy(player) returns the border a player sees, or null while they see the world's.

The world's own border packets are dropped on their way to a viewer who sees a virtual one in that world, so a /worldborder elsewhere cannot overwrite it, and a respawn or world change resends the right one. The server hurts viewers outside it the way vanilla does, every ten ticks with the OUTSIDE_BORDER damage type — a modified client, a pearl or a vehicle does not ask the client first.

Limits

One border per player, across every plugin. Square only. The server's collision, block placement and portals still follow the world's own border. Without PacketEvents a border can be created and shaped but shows to nobody and hurts nobody.

Client waypoints and cooldowns#

For players on Lunar (through Apollo), Feather or SurvivalCore:

java
PluginClients clients = Clients.of(this);
 
clients.waypoints().show(player, Waypoint.at("koth", location).colour("#ff5555"));
clients.waypoints().remove(player, "koth");
clients.clear(player);   // only what this plugin drew

What a plugin sends through Clients.of(this) is keyed by that plugin, so a lobby's spawn marker and an event's spawn marker do not delete each other, clear(player) takes down only this plugin's, and disabling the plugin removes them. On Lunar a waypoint name is still one slot per player, so two plugins showing spawn there share one marker.

Client cooldowns, HUD timers, teammate markers, rallies, beams, zone borders and HUD bars work the same way. A player whose client supports none of it simply receives nothing; the caller never branches on which client somebody is using. The whole surface is in Client integration.

Something missing on this page? Tell us on Discord